From 674d80a76ff5db54cfb03de20853fba6d739832a Mon Sep 17 00:00:00 2001 From: Francesco Montorsi Date: Thu, 25 Sep 2008 20:00:31 +0000 Subject: [PATCH] final f*h interface header reviews git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@55891 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775 --- docs/doxygen/overviews/xrc_format.h | 2 +- interface/wx/filepicker.h | 7 +++ interface/wx/font.h | 11 ++-- interface/wx/fontdlg.h | 6 +-- interface/wx/fontenum.h | 2 +- interface/wx/fontmap.h | 82 +++++++++++++++++++--------- interface/wx/fontpicker.h | 37 ++++++++----- interface/wx/frame.h | 84 ++++++++++++++++------------- 8 files changed, 145 insertions(+), 86 deletions(-) diff --git a/docs/doxygen/overviews/xrc_format.h b/docs/doxygen/overviews/xrc_format.h index ba71107d3d..18931c53af 100644 --- a/docs/doxygen/overviews/xrc_format.h +++ b/docs/doxygen/overviews/xrc_format.h @@ -362,7 +362,7 @@ In most cases, specifying @c stock_client is not needed. Examples of stock bitmaps usage: @code - @endcode Specifying the bitmap directly and using @c stock_id are mutually exclusive. diff --git a/interface/wx/filepicker.h b/interface/wx/filepicker.h index 9d57338383..6fdd64aa5c 100644 --- a/interface/wx/filepicker.h +++ b/interface/wx/filepicker.h @@ -262,6 +262,13 @@ public: This event class is used for the events generated by wxFilePickerCtrl and by wxDirPickerCtrl. + @beginEventTable{wxFileDirPickerEvent} + @event{EVT_FILEPICKER_CHANGED(id, func)} + Generated whenever the selected file changes. + @event{EVT_DIRPICKER_CHANGED(id, func)} + Generated whenever the selected directory changes. + @endEventTable + @library{wxcore} @category{events} diff --git a/interface/wx/font.h b/interface/wx/font.h index ca682bc9a3..012b2927fb 100644 --- a/interface/wx/font.h +++ b/interface/wx/font.h @@ -369,7 +369,7 @@ public: /** Destructor. - See @ref overview_refcountdestruct "reference-counted object destruction" + See @ref overview_refcount_destruct "reference-counted object destruction" for more info. @remarks Although all remaining fonts are deleted when the application @@ -466,8 +466,9 @@ public: //@{ /** - These functions take the same parameters as @ref ctor() wxFont - constructor and return a new font object allocated on the heap. + These functions take the same parameters as + @ref wxFont::wxFont "wxFont constructors" and return a new font + object allocated on the heap. Using @c New() is currently the only way to directly create a font with the given size in pixels on platforms other than wxMSW. @@ -610,7 +611,7 @@ public: /** Inequality operator. - See @ref overview_refcountequality "reference-counted object comparison" for + See @ref overview_refcount_equality "reference-counted object comparison" for more info. */ bool operator !=(const wxFont& font); @@ -618,7 +619,7 @@ public: /** Equality operator. - See @ref overview_refcountequality "reference-counted object comparison" for + See @ref overview_refcount_equality "reference-counted object comparison" for more info. */ bool operator ==(const wxFont& font); diff --git a/interface/wx/fontdlg.h b/interface/wx/fontdlg.h index 52389acde9..1fd6a06191 100644 --- a/interface/wx/fontdlg.h +++ b/interface/wx/fontdlg.h @@ -14,7 +14,7 @@ @library{wxcore} @category{cmndlg} - @see Overview(), wxFontData, wxGetFontFromUser() + @see overview_cmndlg_font, wxFontData, wxGetFontFromUser() */ class wxFontDialog : public wxDialog { @@ -32,7 +32,7 @@ public: /** Constructor. - Pass a parent window, and the @ref overview_wxfontdata "font data" object + Pass a parent window, and the @ref wxFontData "font data" object to be used to initialize the dialog controls. */ wxFontDialog(wxWindow* parent, const wxFontData& data); @@ -55,7 +55,7 @@ public: //@{ /** - Returns the @ref overview_wxfontdata "font data" associated with the + Returns the @ref wxFontData "font data" associated with the font dialog. */ const wxFontData& GetFontData() const; diff --git a/interface/wx/fontenum.h b/interface/wx/fontenum.h index 7ed8230d24..99327a7311 100644 --- a/interface/wx/fontenum.h +++ b/interface/wx/fontenum.h @@ -30,7 +30,7 @@ @library{wxcore} @category{gdi} - @see @ref overview_fontencoding, @ref sample_font, wxFont, wxFontMapper + @see @ref overview_fontencoding, @ref page_samples_font, wxFont, wxFontMapper */ class wxFontEnumerator { diff --git a/interface/wx/fontmap.h b/interface/wx/fontmap.h index 097fd17c37..790e551063 100644 --- a/interface/wx/fontmap.h +++ b/interface/wx/fontmap.h @@ -24,31 +24,60 @@ In case everything else fails (i.e. there is no record in config file and "interactive" is @false or user denied to choose any replacement), - the class queries wxEncodingConverter - for "equivalent" encodings (e.g. iso8859-2 and cp1250) and tries them. + the class queries wxEncodingConverter for "equivalent" encodings + (e.g. iso8859-2 and cp1250) and tries them. + + + @section fontmapper_mbconv Using wxFontMapper in conjunction with wxMBConv classes + + If you need to display text in encoding which is not available at host + system (see wxFontMapper::IsEncodingAvailable), you may use these two + classes to find font in some similar encoding (see wxFontMapper::GetAltForEncoding) + and convert the text to this encoding (wxMBConv classes). + Following code snippet demonstrates it: + + @code + if (!wxFontMapper::Get()->IsEncodingAvailable(enc, facename)) + { + wxFontEncoding alternative; + if (wxFontMapper::Get()->GetAltForEncoding(enc, &alternative, + facename, false)) + { + wxCSConv convFrom(wxFontMapper::Get()->GetEncodingName(enc)); + wxCSConv convTo(wxFontMapper::Get()->GetEncodingName(alternative)); + text = wxString(text.mb_str(convFrom), convTo); + } + else + ...failure (or we may try iso8859-1/7bit ASCII)... + } + ...display text... + @endcode @library{wxcore} @category{misc} - @see wxEncodingConverter, @ref overview_nonenglishoverview "Writing non-English - applications" + @see wxEncodingConverter, @ref overview_nonenglish "Writing non-English applications" */ class wxFontMapper { public: /** Default ctor. + + @note + The preferred way of creating a wxFontMapper instance is to call wxFontMapper::Get(). */ wxFontMapper(); /** - Virtual dtor for a base class. + Virtual dtor. */ - ~wxFontMapper(); + virtual ~wxFontMapper(); /** Returns the encoding for the given charset (in the form of RFC 2046) or @c wxFONTENCODING_SYSTEM if couldn't decode it. + Be careful when using this function with @a interactive set to @true (default value) as the function then may show a dialog box to the user which may lead to unexpected reentrancies and may also take a significantly longer @@ -60,17 +89,17 @@ public: bool interactive = true); /** - Get the current font mapper object. If there is no current object, creates - one. + Get the current font mapper object. If there is no current object, creates one. @see Set() */ static wxFontMapper* Get(); /** - Returns the array of all possible names for the given encoding. The array is - @NULL-terminated. IF it isn't empty, the first name in it is the canonical - encoding name, i.e. the same string as returned by + Returns the array of all possible names for the given encoding. + + The array is @NULL-terminated. IF it isn't empty, the first name in it is + the canonical encoding name, i.e. the same string as returned by GetEncodingName(). */ static const wxChar** GetAllEncodingNames(wxFontEncoding encoding); @@ -81,6 +110,7 @@ public: available on this system). If successful, return @true and fill info structure with the parameters required to create the font, otherwise return @false. + The first form is for wxWidgets' internal use while the second one is better suitable for general use -- it returns wxFontEncoding which can consequently be passed to wxFont constructor. @@ -96,9 +126,10 @@ public: //@} /** - Returns the @e n-th supported encoding. Together with - GetSupportedEncodingsCount() - this method may be used to get all supported encodings. + Returns the @e n-th supported encoding. + + Together with GetSupportedEncodingsCount() this method may be used + to get all supported encodings. */ static wxFontEncoding GetEncoding(size_t n); @@ -108,27 +139,26 @@ public: static wxString GetEncodingDescription(wxFontEncoding encoding); /** - Return the encoding corresponding to the given internal name. This function is - the inverse of GetEncodingName() and is - intentionally less general than - CharsetToEncoding(), i.e. it doesn't - try to make any guesses nor ever asks the user. It is meant just as a way of - restoring objects previously serialized using - GetEncodingName(). + Return the encoding corresponding to the given internal name. + + This function is the inverse of GetEncodingName() and is intentionally + less general than CharsetToEncoding(), i.e. it doesn't try to make any + guesses nor ever asks the user. It is meant just as a way of restoring + objects previously serialized using GetEncodingName(). */ static wxFontEncoding GetEncodingFromName(const wxString& encoding); /** Return internal string identifier for the encoding (see also - wxFontMapper::GetEncodingDescription) + wxFontMapper::GetEncodingDescription). @see GetEncodingFromName() */ static wxString GetEncodingName(wxFontEncoding encoding); /** - Returns the number of the font encodings supported by this class. Together with - GetEncoding() this method may be used to get + Returns the number of the font encodings supported by this class. + Together with GetEncoding() this method may be used to get all supported encodings. */ static size_t GetSupportedEncodingsCount(); @@ -152,8 +182,8 @@ public: /** Set the config object to use (may be @NULL to use default). By default, the global one (from wxConfigBase::Get() will be used) - and the default root path for the config settings is the string returned by - GetDefaultConfigPath(). + and the default root path for the config settings is the string returned + by GetDefaultConfigPath(). */ void SetConfig(wxConfigBase* config); diff --git a/interface/wx/fontpicker.h b/interface/wx/fontpicker.h index 4db0ae045c..7c067a78f8 100644 --- a/interface/wx/fontpicker.h +++ b/interface/wx/fontpicker.h @@ -12,14 +12,12 @@ This control allows the user to select a font. The generic implementation is a button which brings up a wxFontDialog when clicked. Native implementation may differ but this is usually a (small) widget which give access to the - font-chooser - dialog. + font-chooser dialog. It is only available if @c wxUSE_FONTPICKERCTRL is set to 1 (the default). @beginStyleTable @style{wxFNTP_DEFAULT_STYLE} - The default style: wxFNTP_FONTDESC_AS_LABEL | - wxFNTP_USEFONT_FOR_LABEL. + The default style: wxFNTP_FONTDESC_AS_LABEL | wxFNTP_USEFONT_FOR_LABEL. @style{wxFNTP_USE_TEXTCTRL} Creates a text control to the left of the picker button which is completely managed by the wxFontPickerCtrl and which can be used by @@ -35,6 +33,13 @@ Uses the currently selected font to draw the label of the button. @endStyleTable + @beginEventTable{wxFontPickerEvent} + @event{EVT_FONTPICKER_CHANGED(id, func)} + The user changed the font selected in the control either using the button + or using text control (see wxFNTP_USE_TEXTCTRL; note that in this case the + event is fired only if the user's input is valid, i.e. recognizable). + @endEventTable + @library{wxcore} @category{pickers} @@ -57,13 +62,15 @@ public: const wxString& name = "fontpickerctrl"); /** + Creates this widget with given parameters. + @param parent Parent window, must not be non-@NULL. @param id The identifier for the control. @param font - The initial font shown in the control. If wxNullFont - is given, the default font is used. + The initial font shown in the control. + If ::wxNullFont is given, the default font is used. @param pos Initial position. @param size @@ -99,13 +106,12 @@ public: /** Sets the maximum point size value allowed for the user-chosen font. + The default value is 100. Note that big fonts can require a lot of memory and - CPU time - both for creation and for rendering; thus, specially because the user has the - option to specify - the fontsize through a text control (see wxFNTP_USE_TEXTCTRL), it's a good idea - to put a limit - to the maximum font size when huge fonts do not make much sense. + CPU time both for creation and for rendering; thus, specially because the user + has the option to specify the fontsize through a text control + (see wxFNTP_USE_TEXTCTRL), it's a good idea to put a limit to the maximum + font size when huge fonts do not make much sense. */ void GetMaxPointSize(unsigned int max); @@ -124,8 +130,13 @@ public: This event class is used for the events generated by wxFontPickerCtrl. + @beginEventTable{wxFontPickerEvent} + @event{EVT_FONTPICKER_CHANGED(id, func)} + Generated whenever the selected font changes. + @endEventTable + @library{wxcore} - @category{FIXME} + @category{events} @see wxFontPickerCtrl */ diff --git a/interface/wx/frame.h b/interface/wx/frame.h index fd6c78c878..cf016028d8 100644 --- a/interface/wx/frame.h +++ b/interface/wx/frame.h @@ -24,7 +24,7 @@ data and subwindows can be cleaned up. - @section wxframe_defaultevent Default event processing + @section frame_defaultevent Default event processing wxFrame processes the following events: @@ -36,6 +36,10 @@ associated with the selected item in the first pane of the status bar, if there is one. + @section frame_styles + + wxFrame supports the following styles: + @beginStyleTable @style{wxDEFAULT_FRAME_STYLE} Defined as wxMINIMIZE_BOX | wxMAXIMIZE_BOX | wxRESIZE_BORDER | @@ -114,7 +118,11 @@ class wxFrame : public wxTopLevelWindow { public: - //@{ + /** + Default constructor. + */ + wxFrame(); + /** Constructor, creating the window. @@ -122,39 +130,33 @@ public: The window parent. This may be @NULL. If it is non-@NULL, the frame will always be displayed on top of the parent window on Windows. @param id - The window identifier. It may take a value of -1 to indicate a default - value. + The window identifier. It may take a value of -1 to indicate a default value. @param title The caption to be displayed on the frame's title bar. @param pos The window position. The value wxDefaultPosition indicates a default position, - chosen by - either the windowing system or wxWidgets, depending on platform. + chosen by either the windowing system or wxWidgets, depending on platform. @param size The window size. The value wxDefaultSize indicates a default size, chosen by either the windowing system or wxWidgets, depending on platform. @param style - The window style. See wxFrame. + The window style. See wxFrame class description. @param name - The name of the window. This parameter is used to associate a name with the - item, - allowing the application user to set Motif resource values for + The name of the window. This parameter is used to associate a name with + the item, allowing the application user to set Motif resource values for individual windows. @remarks For Motif, MWM (the Motif Window Manager) should be running for - any window styles to work (otherwise all styles take - effect). + any window styles to work (otherwise all styles take effect). @see Create() */ - wxFrame(); wxFrame(wxWindow* parent, wxWindowID id, const wxString& title, const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, long style = wxDEFAULT_FRAME_STYLE, const wxString& name = "frame"); - //@} /** Destructor. Destroys all child windows and menu bar if present. @@ -170,8 +172,8 @@ public: void Centre(int direction = wxBOTH); /** - Used in two-step frame construction. See wxFrame() - for further details. + Used in two-step frame construction. + See wxFrame() for further details. */ bool Create(wxWindow* parent, wxWindowID id, const wxString& title, @@ -187,16 +189,15 @@ public: The number of fields to create. Specify a value greater than 1 to create a multi-field status bar. @param style - The status bar style. See wxStatusBar for a list - of valid styles. + The status bar style. See wxStatusBar for a list of valid styles. @param id - The status bar window identifier. If -1, an identifier will be chosen by - wxWidgets. + The status bar window identifier. If -1, an identifier will be chosen + by wxWidgets. @param name The status bar window name. @return A pointer to the status bar if it was created successfully, @NULL - otherwise. + otherwise. @remarks The width of the status bar is the whole width of the frame (adjusted automatically when resizing), and the height @@ -213,32 +214,39 @@ public: Creates a toolbar at the top or left of the frame. @param style - The toolbar style. See wxToolBar for a list - of valid styles. + The toolbar style. See wxToolBar for a list of valid styles. @param id - The toolbar window identifier. If -1, an identifier will be chosen by - wxWidgets. + The toolbar window identifier. If -1, an identifier will be chosen + by wxWidgets. @param name The toolbar window name. @return A pointer to the toolbar if it was created successfully, @NULL - otherwise. + otherwise. @remarks By default, the toolbar is an instance of wxToolBar (which is defined to be a suitable toolbar class on each platform, such as wxToolBar95). To use a different class, override OnCreateToolBar(). + When a toolbar has been created with this function, or made + known to the frame with wxFrame::SetToolBar, the frame will + manage the toolbar position and adjust the return value from + wxWindow::GetClientSize to reflect the available space for + application windows. + Under Pocket PC, you should always use this function for creating + the toolbar to be managed by the frame, so that wxWidgets can + use a combined menubar and toolbar. + Where you manage your own toolbars, create a wxToolBar as usual. - @see CreateStatusBar(), OnCreateToolBar(), SetToolBar(), - GetToolBar() + @see CreateStatusBar(), OnCreateToolBar(), SetToolBar(), GetToolBar() */ virtual wxToolBar* CreateToolBar(long style = wxBORDER_NONE | wxTB_HORIZONTAL, wxWindowID id = -1, const wxString& name = "toolBar"); /** - Returns the origin of the frame client area (in client coordinates). It may be - different from (0, 0) if the frame has a toolbar. + Returns the origin of the frame client area (in client coordinates). + It may be different from (0, 0) if the frame has a toolbar. */ wxPoint GetClientAreaOrigin() const; @@ -250,8 +258,8 @@ public: wxMenuBar* GetMenuBar() const; /** - Returns a pointer to the status bar currently associated with the frame (if - any). + Returns a pointer to the status bar currently associated with the frame + (if any). @see CreateStatusBar(), wxStatusBar */ @@ -338,6 +346,10 @@ public: destroyed also, so do not delete the menu bar explicitly (except by resetting the frame's menu bar to another frame or @NULL). + Under Windows, a size event is generated, so be sure to + initialize data members properly before calling SetMenuBar(). + Note that on some platforms, it is not possible to call this + function twice for the same frame object. @see GetMenuBar(), wxMenuBar, wxMenu. */ @@ -379,14 +391,12 @@ public: @param widths Must contain an array of n integers, each of which is a status field width in pixels. A value of -1 indicates that the field is variable width; at - least one - field must be -1. You should delete this array after calling - SetStatusWidths. + least one field must be -1. You should delete this array after calling + SetStatusWidths(). @remarks The widths of the variable fields are calculated from the total width of all fields, minus the sum of widths of the - non-variable fields, divided by the number of variable - fields. + non-variable fields, divided by the number of variable fields. */ virtual void SetStatusWidths(int n, int* widths);