From 74bf4e6430a42c20491d13e1bb9805e1ee614a95 Mon Sep 17 00:00:00 2001 From: Francesco Montorsi Date: Sun, 6 Apr 2008 12:52:58 +0000 Subject: [PATCH] revisions contributed by Utensil Candel git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@53041 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775 --- interface/odcombo.h | 52 ++++++--- interface/palette.h | 41 ++++--- interface/panel.h | 35 +++--- interface/pen.h | 110 +++++++++-------- interface/pickerbase.h | 38 +++--- interface/platinfo.h | 260 +++++++++++++++++++++++++++++++++-------- 6 files changed, 370 insertions(+), 166 deletions(-) diff --git a/interface/odcombo.h b/interface/odcombo.h index ecd545f67a..5eb7f5bbda 100644 --- a/interface/odcombo.h +++ b/interface/odcombo.h @@ -11,14 +11,12 @@ @wxheader{odcombo.h} wxOwnerDrawnComboBox is a combobox with owner-drawn list items. - In essence, it is a wxComboCtrl with - wxVListBox popup and wxControlWithItems + In essence, it is a wxComboCtrl with wxVListBox popup and wxControlWithItems interface. Implementing item drawing and measuring is similar to wxVListBox. Application needs to subclass wxOwnerDrawnComboBox and implement - wxOwnerDrawnComboBox::OnDrawItem, wxOwnerDrawnComboBox::OnMeasureItem - and wxOwnerDrawnComboBox::OnMeasureItemWidth. + OnDrawItem(), OnMeasureItem() and OnMeasureItemWidth(). @beginStyleTable @style{wxODCB_DCLICK_CYCLES}: @@ -27,16 +25,18 @@ @style{wxODCB_STD_CONTROL_PAINT}: Control itself is not custom painted using OnDrawItem. Even if this style is not used, writable wxOwnerDrawnComboBox is never custom - painted unless SetCustomPaintWidth is called. + painted unless SetCustomPaintWidth() is called. @endStyleTable @beginEventTable{wxCommandEvent} @event{EVT_COMBOBOX(id, func)}: Process a wxEVT_COMMAND_COMBOBOX_SELECTED event, when an item on - the list is selected. Note that calling GetValue returns the new + the list is selected. Note that calling GetValue() returns the new value of selection. @endEventTable + @see Events emitted by wxComboCtrl. + @library{wxadv} @category{ctrl} @appearance{ownerdrawncombobox.png} @@ -46,6 +46,11 @@ class wxOwnerDrawnComboBox : public wxComboCtrl { public: + + /** + Default constructor. + */ + wxOwnerDrawnComboBox(); //@{ /** Constructor, creating and showing a owner-drawn combobox. @@ -53,13 +58,13 @@ public: @param parent Parent window. Must not be @NULL. @param id - Window identifier. The value wxID_ANY indicates a default value. + Window identifier. The value @c wxID_ANY indicates a default value. @param value Initial selection string. An empty string indicates no selection. @param pos Window position. @param size - Window size. If wxDefaultSize is specified then the window is + Window size. If @c wxDefaultSize is specified then the window is sized appropriately. @param n @@ -75,13 +80,12 @@ public: @see Create(), wxValidator */ - wxOwnerDrawnComboBox(); wxOwnerDrawnComboBox(wxWindow* parent, wxWindowID id, const wxString& value = "", const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, int n = 0, - const wxString choices[] = NULL, + const wxString[] choices = NULL, long style = 0, const wxValidator& validator = wxDefaultValidator, const wxString& name = "comboBox"); @@ -102,10 +106,10 @@ public: //@{ /** - Creates the combobox for two-step construction. Derived classes - should call or replace this function. See - wxOwnerDrawnComboBox() - for further details. + Creates the combobox for two-step construction. + See wxOwnerDrawnComboBox() for further details. + + @remarks Derived classes should call or replace this function. */ bool Create(wxWindow* parent, wxWindowID id, const wxString& value = "", @@ -137,19 +141,22 @@ public: /** This method is used to draw the items background and, maybe, a border around it. + The base class version implements a reasonable default behaviour which consists in drawing the selected item with the standard background colour and drawing a border around the item if it is either selected or current. - @remarks flags has the same meaning as with OnDrawItem. + @remarks flags has the same meaning as with OnDrawItem(). */ void OnDrawBackground(wxDC& dc, const wxRect& rect, int item, int flags) const; /** The derived class may implement this function to actually draw the item - with the given index on the provided DC. If function is not implemented, - the item text is simply drawn, as if the control was a normal combobox. + with the given index on the provided DC. + + If function is not implemented, the item text is simply drawn, as if the control + was a normal combobox. @param dc The device context to use for drawing @@ -160,6 +167,15 @@ public: The index of the item to be drawn @param flags Combines any of the following flag values: + + @beginStyleTable + @style{wxODCB_PAINTING_CONTROL}: + Combo control is being painted, instead of a list item. + Argument item may be @c wxNOT_FOUND in this case. + @style{wxODCB_PAINTING_SELECTED}: + An item with selection background is being painted. + DC text colour should already be correct. + @endStyleTable */ void OnDrawItem(wxDC& dc, const wxRect& rect, int item, int flags) const; @@ -167,6 +183,7 @@ public: /** The derived class may implement this method to return the height of the specified item (in pixels). + The default implementation returns text height, as if this control was a normal combobox. */ @@ -176,6 +193,7 @@ public: The derived class may implement this method to return the width of the specified item (in pixels). If -1 is returned, then the item text width is used. + The default implementation returns -1. */ wxCoord OnMeasureItemWidth(size_t item) const; diff --git a/interface/palette.h b/interface/palette.h index 6c8d61c460..6a5663e169 100644 --- a/interface/palette.h +++ b/interface/palette.h @@ -27,17 +27,25 @@ @category{gdi} @stdobjects - ::Objects:, ::wxNullPalette, + ::wxNullPalette - @see wxDC::SetPalette, wxBitmap + @see wxDC::SetPalette(), wxBitmap */ class wxPalette : public wxGDIObject { public: - //@{ + + /** + Default constructor. + */ + wxPalette(); + /** + Copy constructor, uses @ref overview_refcount. + */ + wxPalette(const wxPalette& palette); /** - Creates a palette from arrays of size @e n, one for each - red, blue or green component. + Creates a palette from arrays of size @e n, one for each red, blue or + green component. @param palette A pointer or reference to the palette to copy. @@ -52,23 +60,20 @@ public: @see Create() */ - wxPalette(); - wxPalette(const wxPalette& palette); wxPalette(int n, const unsigned char* red, const unsigned char* green, const unsigned char* blue); - //@} /** Destructor. - See @ref overview_refcountdestruct "reference-counted object destruction" for - more info. + + @see @ref overview_refcount_destruct "reference-counted object destruction" */ ~wxPalette(); /** - Creates a palette from arrays of size @e n, one for each - red, blue or green component. + Creates a palette from arrays of size @e n, one for each red, blue or + green component. @param n The number of indices in the palette. @@ -102,7 +107,7 @@ public: @param blue Blue value. - @returns The nearest palette index or wxNOT_FOUND for unexpected errors. + @returns The nearest palette index or @c wxNOT_FOUND for unexpected errors. @see GetRGB() */ @@ -135,18 +140,12 @@ public: bool IsOk() const; /** - Assignment operator, using @ref overview_trefcount "reference counting". + Assignment operator, using @ref overview_refcount. */ - wxPalette operator =(const wxPalette& palette); + wxPalette& operator =(const wxPalette& palette); }; -/** - FIXME -*/ -wxPalette Objects: -; - /** FIXME */ diff --git a/interface/panel.h b/interface/panel.h index 571a17ac1d..46b64f19ed 100644 --- a/interface/panel.h +++ b/interface/panel.h @@ -18,11 +18,11 @@ @e Note: Tab traversal is implemented through an otherwise undocumented intermediate wxControlContainer class from which any class can derive - in addition to the normal wxWindow base class. Please see wx/containr.h - and wx/panel.h to find out how this is achieved. + in addition to the normal wxWindow base class. Please see @e wx/containr.h + and @e wx/panel.h to find out how this is achieved. @e Note: if not all characters are being intercepted by your OnKeyDown or - OnChar handler, it may be because you are using the wxTAB_TRAVERSAL style, + OnChar handler, it may be because you are using the @c wxTAB_TRAVERSAL style, which grabs some keypresses for use by child controls. @library{wxbase} @@ -33,20 +33,24 @@ class wxPanel : public wxWindow { public: - //@{ + + /** + Default constructor. + */ + wxPanel(); /** Constructor. @param parent The parent window. @param id - An identifier for the panel. A value of -1 is taken to mean a default. + An identifier for the panel. @c wxID_ANY is taken to mean a default. @param pos - The panel position. The value wxDefaultPosition indicates a default position, + The panel position. The value @c wxDefaultPosition indicates a default position, chosen by either the windowing system or wxWidgets, depending on platform. @param size - The panel size. The value wxDefaultSize indicates a default size, chosen by + The panel size. The value @c wxDefaultSize indicates a default size, chosen by either the windowing system or wxWidgets, depending on platform. @param style The window style. See wxPanel. @@ -57,13 +61,11 @@ public: @see Create() */ - wxPanel(); wxPanel(wxWindow* parent, wxWindowID id = wxID_ANY, const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, long style = wxTAB_TRAVERSAL, const wxString& name = "panel"); - //@} /** Destructor. Deletes any child windows before deleting the physical window. @@ -71,7 +73,7 @@ public: ~wxPanel(); /** - This method is overridden from wxWindow::AcceptsFocus + This method is overridden from wxWindow::AcceptsFocus() and returns @true only if there is no child window in the panel which can accept the focus. This is reevaluated each time a child window is added or removed from the panel. @@ -79,8 +81,7 @@ public: bool AcceptsFocus() const; /** - Used for two-step panel construction. See wxPanel() - for details. + Used for two-step panel construction. See wxPanel() for details. */ bool Create(wxWindow* parent, wxWindowID id = wxID_ANY, const wxPoint& pos = wxDefaultPosition, @@ -89,8 +90,8 @@ public: const wxString& name = "panel"); /** - Sends a wxInitDialogEvent, which - in turn transfers data to the dialog via validators. + Sends a wxInitDialogEvent, which in turn transfers data to the dialog via + validators. @see wxInitDialogEvent */ @@ -106,7 +107,7 @@ public: (Windows only). Add an event table entry for your panel class if you wish the behaviour to be different (such as keeping a user-defined background colour). If you do - override this function, call wxEvent::Skip to propagate + override this function, call wxEvent::Skip() to propagate the notification to child windows and controls. @see wxSysColourChangedEvent @@ -114,13 +115,13 @@ public: void OnSysColourChanged(wxSysColourChangedEvent& event); /** - Overrides wxWindow::SetFocus. This method + Overrides wxWindow::SetFocus(). This method uses the (undocumented) mix-in class wxControlContainer which manages the focus and TAB logic for controls which usually have child controls. In practice, if you call this method and the control has at least one child window, the focus will be given to the child window. - @see wxFocusEvent, wxWindow::SetFocus + @see wxFocusEvent, wxWindow::SetFocus() */ virtual void SetFocus(); diff --git a/interface/pen.h b/interface/pen.h index a8877df3e2..7192429d16 100644 --- a/interface/pen.h +++ b/interface/pen.h @@ -104,22 +104,24 @@ enum wxPenCap lines and painting the outline of rectangles, ellipses, etc. It has a colour, a width and a style. + @remarks + On a monochrome display, wxWidgets shows all non-white pens as black. Do not initialize objects on the stack before the program commences, since other required structures may not have been set up yet. - Instead, define global pointers to objects and create them in wxApp::OnInit + Instead, define global pointers to objects and create them in wxApp::OnInit() or when required. An application may wish to dynamically create pens with different characteristics, and there is the consequent danger that a large number of duplicate pens will be created. Therefore an application may wish to get a pointer to a pen by using - the global list of pens wxThePenList, and calling the member function + the global list of pens ::wxThePenList, and calling the member function wxPenList::FindOrCreatePen(). See the entry for wxPenList. - This class uses reference counting and copy-on-write internally so that - assignments between two instances of this class are very cheap. + This class uses @ref overview_refcount "reference counting and copy-on-write" internally + so that assignments between two instances of this class are very cheap. You can therefore use actual objects instead of pointers without efficiency problems. If an instance of this class is changed it will create its own data internally so that other instances, which previously shared the data using the reference @@ -129,44 +131,30 @@ enum wxPenCap @category{gdi} @stdobjects - ::wxNullPen, ::wxRED_PEN, ::wxCYAN_PEN, ::wxGREEN_PEN, ::wxBLACK_PEN, - ::wxWHITE_PEN, ::wxTRANSPARENT_PEN, ::wxBLACK_DASHED_PEN, ::wxGREY_PEN, - ::wxMEDIUM_GREY_PEN, ::wxLIGHT_GREY_PEN + ::wxNullPen + + Predefined pointers: ::wxRED_PEN, ::wxCYAN_PEN, ::wxGREEN_PEN, + ::wxBLACK_PEN, ::wxWHITE_PEN, ::wxTRANSPARENT_PEN, ::wxBLACK_DASHED_PEN, + ::wxGREY_PEN, ::wxMEDIUM_GREY_PEN, ::wxLIGHT_GREY_PEN - @see wxPenList, wxDC, wxDC::SetPen + @see wxPenList, wxDC, wxDC::SetPen() */ class wxPen : public wxGDIObject { public: /** - Default constructor. The pen will be uninitialised, and wxPen:IsOk will return @false. + Default constructor. The pen will be uninitialised, and IsOk() will return @false. */ wxPen(); /** Constructs a pen from a colour object, pen width and style. - */ - wxPen(const wxColour& colour, int width = 1, wxPenStyle style = wxPENSTYLE_SOLID); - - /** - Constructs a stippled pen from a stipple bitmap and a width. - */ - wxPen(const wxBitmap& stipple, int width); - - /** - Copy constructor, uses @ref overview_refcount "reference counting". @param colour A colour object. - @param colourName - A colour name. @param width Pen width. Under Windows, the pen width cannot be greater than 1 if - the style is wxDOT, wxLONG_DASH, wxSHORT_DASH, wxDOT_DASH, or wxUSER_DASH. - @param stipple - A stipple bitmap. - @param pen - A pointer or reference to a pen to copy. + the style is @c wxDOT, @c wxLONG_DASH, @c wxSHORT_DASH, @c wxDOT_DASH, or @c wxUSER_DASH. @param style The style may be one of the ::wxPenStyle values. @@ -175,14 +163,34 @@ public: above - there is no similarity even between Windows95 and Windows98 - so handle with care. - @see SetStyle(), SetColour(), SetWidth(), SetStipple() + @see SetStyle(), SetColour(), SetWidth() + */ + wxPen(const wxColour& colour, int width = 1, wxPenStyle style = wxPENSTYLE_SOLID); + + /** + Constructs a stippled pen from a stipple bitmap and a width. + + @param width + Pen width. Under Windows, the pen width cannot be greater than 1 if + the style is @c wxDOT, @c wxLONG_DASH, @c wxSHORT_DASH, @c wxDOT_DASH, or @c wxUSER_DASH. + @param stipple + A stipple bitmap. + + @see SetWidth(), SetStipple() + */ + wxPen(const wxBitmap& stipple, int width); + + /** + Copy constructor, uses @ref overview_refcount. + + @param pen + A pointer or reference to a pen to copy. */ wxPen(const wxPen& pen); /** Destructor. - See @ref overview_refcountdestruct "reference-counted object destruction" for - more info. + @see @ref overview_refcount_destruct "reference-counted object destruction" @remarks Although all remaining pens are deleted when the application exits, the application should try to clean up all pens @@ -193,9 +201,10 @@ public: ~wxPen(); /** - Returns the pen cap style, which may be one of @b wxCAP_ROUND, @b - wxCAP_PROJECTING and - @b wxCAP_BUTT. The default is @b wxCAP_ROUND. + Returns the pen cap style, which may be one of @c wxCAP_ROUND, @c + wxCAP_PROJECTING and @c wxCAP_BUTT. + + The default is @c wxCAP_ROUND. @see SetCap() */ @@ -212,16 +221,18 @@ public: Gets an array of dashes (defined as char in X, DWORD under Windows). @a dashes is a pointer to the internal array. Do not deallocate or store this pointer. - The function returns the number of dashes associated with this pen. + + @return The number of dashes associated with this pen. @see SetDashes() */ virtual int GetDashes(wxDash** dashes) const; /** - Returns the pen join style, which may be one of @b wxJOIN_BEVEL, @b - wxJOIN_ROUND and - @b wxJOIN_MITER. The default is @b wxJOIN_ROUND. + Returns the pen join style, which may be one of @c wxJOIN_BEVEL, @c + wxJOIN_ROUND and @c wxJOIN_MITER. + + The default is @c wxJOIN_ROUND. @see SetJoin() */ @@ -254,9 +265,8 @@ public: bool IsOk() const; /** - Sets the pen cap style, which may be one of @b wxCAP_ROUND, @b wxCAP_PROJECTING - and - @b wxCAP_BUTT. The default is @b wxCAP_ROUND. + Sets the pen cap style, which may be one of @c wxCAP_ROUND, @c wxCAP_PROJECTING + and @c wxCAP_BUTT. The default is @c wxCAP_ROUND. @see GetCap() */ @@ -274,19 +284,21 @@ public: /** Associates an array of pointers to dashes (defined as char in X, DWORD under - Windows) - with the pen. The array is not deallocated by wxPen, but neither must it be - deallocated by the calling application until the pen is deleted or this - function is called with a @NULL array. + Windows) with the pen. + + The array is not deallocated by wxPen, but neither must it be deallocated by + the calling application until the pen is deleted or this function is called + with a @NULL array. @see GetDashes() */ virtual void SetDashes(int n, wxDash* dashes); /** - Sets the pen join style, which may be one of @b wxJOIN_BEVEL, @b wxJOIN_ROUND - and - @b wxJOIN_MITER. The default is @b wxJOIN_ROUND. + Sets the pen join style, which may be one of @c wxJOIN_BEVEL, @c wxJOIN_ROUND + and @c wxJOIN_MITER. + + The default is @c wxJOIN_ROUND. @see GetJoin() */ @@ -315,19 +327,19 @@ 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 wxPen& pen); /** - Assignment operator, using @ref overview_trefcount "reference counting". + Assignment operator, using @ref overview_refcount. */ wxPen operator =(const wxPen& pen); /** 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 wxPen& pen); diff --git a/interface/pickerbase.h b/interface/pickerbase.h index 94792952fc..cfadac7b1f 100644 --- a/interface/pickerbase.h +++ b/interface/pickerbase.h @@ -11,13 +11,13 @@ @wxheader{pickerbase.h} Base abstract class for all pickers which support an auxiliary text control. + This class handles all positioning and sizing of the text control like a - an horizontal wxBoxSizer would do, with the text control on - the left of the picker button. - The proportion (see wxSizer documentation for more info about - proportion values) of the picker control defaults to 1 when there isn't a text - control - associated (see @c wxPB_USE_TEXTCTRL style) and to 0 otherwise. + an horizontal wxBoxSizer would do, with the text control on the left of the + picker button. + The proportion (see wxSizer documentation for more info about proportion values) + of the picker control defaults to 1 when there isn't a text control associated + (see @c wxPB_USE_TEXTCTRL style) and to 0 otherwise. @beginStyleTable @style{wxPB_USE_TEXTCTRL}: @@ -26,7 +26,7 @@ @endStyleTable @library{wxcore} - @category{FIXME} + @category{pickers} @see wxColourPickerCtrl */ @@ -35,6 +35,7 @@ class wxPickerBase : public wxControl public: /** Returns the margin (in pixel) between the picker and the text control. + This function can be used only when HasTextCtrl() returns @true. */ int GetInternalMargin() const; @@ -46,22 +47,28 @@ public: /** Returns a pointer to the text control handled by this window or @NULL if the - @b wxPB_USE_TEXTCTRL style was not specified when this control was created. - Very important: the contents of the text control could be containing an invalid - representation of the entity which can be chosen through the picker (e.g. the user entered an invalid colour syntax because of a typo). Thus you should never parse the content of the textctrl to get the user's input; rather use the derived-class getter (e.g. wxColourPickerCtrl::GetColour, wxFilePickerCtrl::GetPath, etc). + @c wxPB_USE_TEXTCTRL style was not specified when this control was created. + + @remarks + The contents of the text control could be containing an invalid + representation of the entity which can be chosen through the picker + (e.g. the user entered an invalid colour syntax because of a typo). + Thus you should never parse the content of the textctrl to get the + user's input; rather use the derived-class getter + (e.g. wxColourPickerCtrl::GetColour(), wxFilePickerCtrl::GetPath(), etc). */ wxTextCtrl* GetTextCtrl(); /** Returns the proportion value of the text control. + This function can be used only when HasTextCtrl() returns @true. */ int GetTextCtrlProportion() const; /** - Returns @true if this window has a valid text control (i.e. if the @b - wxPB_USE_TEXTCTRL style was - given when creating this control). + Returns @true if this window has a valid text control (i.e. if the @c + wxPB_USE_TEXTCTRL style was given when creating this control). */ bool HasTextCtrl() const; @@ -72,12 +79,14 @@ public: /** Returns @true if the text control is growable. + This function can be used only when HasTextCtrl() returns @true. */ bool IsTextCtrlGrowable() const; /** Sets the margin (in pixel) between the picker and the text control. + This function can be used only when HasTextCtrl() returns @true. */ void SetInternalMargin(int margin); @@ -89,18 +98,21 @@ public: /** Sets the proportion value of the picker. + Look at the overview of wxPickerBase for more details about this. */ void SetPickerCtrlProportion(int prop); /** Sets the text control as growable when @c grow is @true. + This function can be used only when HasTextCtrl() returns @true. */ void SetTextCtrlGrowable(bool grow = true); /** Sets the proportion value of the text control. + Look at the overview of wxPickerBase for more details about this. This function can be used only when HasTextCtrl() returns @true. */ diff --git a/interface/platinfo.h b/interface/platinfo.h index 17101b23c4..ef63705453 100644 --- a/interface/platinfo.h +++ b/interface/platinfo.h @@ -11,24 +11,146 @@ @wxheader{platinfo.h} This class holds informations about the operating system and the toolkit that - the application - is running under and some basic architecture info of the machine where it's - running. + the application is running under and some basic architecture info of the machine + where it's running. @library{wxbase} - @category{FIXME} + @category{misc} - @see wxGetOSVersion(), wxIsPlatformLittleEndian(), wxIsPlatform64Bit(), + @see ::wxGetOsVersion(), wxIsPlatformLittleEndian(), wxIsPlatform64Bit(), wxAppTraits + + Data structures: + + The following are the operating systems which are recognized by wxWidgets and + whose version can be detected at run-time. + The values of the constants are chosen so that they can be combined as flags; + this allows to check for operating system families like + e.g. wxOS_MAC and wxOS_UNIX. + + @code + + enum wxOperatingSystemId + { + wxOS_UNKNOWN = 0, // returned on error + + wxOS_MAC_OS = 1 << 0, // Apple Mac OS 8/9/X with Mac paths + wxOS_MAC_OSX_DARWIN = 1 << 1, // Apple Mac OS X with Unix paths + wxOS_MAC = wxOS_MAC_OS|wxOS_MAC_OSX_DARWIN, + + wxOS_WINDOWS_9X = 1 << 2, // Windows 9x family (95/98/ME) + wxOS_WINDOWS_NT = 1 << 3, // Windows NT family (NT/2000/XP) + wxOS_WINDOWS_MICRO = 1 << 4, // MicroWindows + wxOS_WINDOWS_CE = 1 << 5, // Windows CE (Window Mobile) + wxOS_WINDOWS = wxOS_WINDOWS_9X | + wxOS_WINDOWS_NT | + wxOS_WINDOWS_MICRO | + wxOS_WINDOWS_CE, + + wxOS_UNIX_LINUX = 1 << 6, // Linux + wxOS_UNIX_FREEBSD = 1 << 7, // FreeBSD + wxOS_UNIX_OPENBSD = 1 << 8, // OpenBSD + wxOS_UNIX_NETBSD = 1 << 9, // NetBSD + wxOS_UNIX_SOLARIS = 1 << 10, // SunOS + wxOS_UNIX_AIX = 1 << 11, // AIX + wxOS_UNIX_HPUX = 1 << 12, // HP/UX + wxOS_UNIX = wxOS_UNIX_LINUX | + wxOS_UNIX_FREEBSD | + wxOS_UNIX_OPENBSD | + wxOS_UNIX_NETBSD | + wxOS_UNIX_SOLARIS | + wxOS_UNIX_AIX | + wxOS_UNIX_HPUX, + + wxOS_DOS = 1 << 15, // Microsoft DOS + wxOS_OS2 = 1 << 16 // OS/2 + }; + + @endcode + + The list of wxWidgets ports. + Some of them can be used with more than a single (native) toolkit; + e.g. wxWinCE port sources can be used with smartphones, pocket PCs + and handheld devices SDKs. + + @code + + enum wxPortId + { + wxPORT_UNKNOWN = 0, // returned on error + + wxPORT_BASE = 1 << 0, // wxBase, no native toolkit used + + wxPORT_MSW = 1 << 1, // wxMSW, native toolkit is Windows API + wxPORT_MOTIF = 1 << 2, // wxMotif, using [Open]Motif or Lesstif + wxPORT_GTK = 1 << 3, // wxGTK, using GTK+ 1.x, 2.x, GPE or Maemo + wxPORT_MGL = 1 << 4, // wxMGL, using wxUniversal + wxPORT_X11 = 1 << 5, // wxX11, using wxUniversal + wxPORT_OS2 = 1 << 6, // wxOS2, using OS/2 Presentation Manager + wxPORT_MAC = 1 << 7, // wxMac, using Carbon or Classic Mac API + wxPORT_COCOA = 1 << 8, // wxCocoa, using Cocoa NextStep/Mac API + wxPORT_WINCE = 1 << 9, // wxWinCE, toolkit is WinCE SDK API + wxPORT_PALMOS = 1 << 10, // wxPalmOS, toolkit is PalmOS API + wxPORT_DFB = 1 << 11 // wxDFB, using wxUniversal + }; + + @endcode + + The architecture of the operating system + (regardless of the build environment of wxWidgets library + - see wxIsPlatform64bit documentation for more info). + + @code + + enum wxArchitecture + { + wxARCH_INVALID = -1, // returned on error + + wxARCH_32, // 32 bit + wxARCH_64, + + wxARCH_MAX + } + + @endcode + + The endian-ness of the machine. + + @code + + enum wxEndianness + { + wxENDIAN_INVALID = -1, // returned on error + + wxENDIAN_BIG, // 4321 + wxENDIAN_LITTLE, // 1234 + wxENDIAN_PDP, // 3412 + + wxENDIAN_MAX + } + + @endcode + + */ class wxPlatformInfo : public wxObject { public: - //@{ + /** - Initializes the object using given values. + Initializes the instance with the values corresponding to the currently + running platform. + + This is a fast operation because it only requires to copy the values + internally cached for the currently running platform. + + @see Get() */ wxPlatformInfo(); + + /** + Initializes the object using given values. + */ wxPlatformInfo(wxPortId pid = wxPORT_UNKNOWN, int tkMajor = -1, int tkMinor = -1, @@ -37,7 +159,7 @@ public: int osMinor = -1, wxArchitecture arch = wxARCH_INVALID, wxEndianness endian = wxENDIAN_INVALID); - //@} + /** Returns @true if the OS version is at least @c major.minor. @@ -56,124 +178,162 @@ public: bool CheckToolkitVersion(int major, int minor) const; /** - Returns the global wxPlatformInfo object, initialized with the values for the - currently running platform. + Returns the global wxPlatformInfo object, initialized with the values + for the currently running platform. */ static const wxPlatformInfo Get(); /** Converts the given string to a wxArchitecture enum value or to - wxARCH_INVALID if the given string is not a valid architecture string + @c wxARCH_INVALID if the given string is not a valid architecture string (i.e. does not contain nor @c 32 nor @c 64 strings). */ static wxArchitecture GetArch(const wxString& arch); - //@{ /** - Returns the name for the architecture of this wxPlatformInfo instance. + Returns the name for the given wxArchitecture enumeration value. */ static wxString GetArchName(wxArchitecture arch) const; + + /** + Returns the name for the architecture of this wxPlatformInfo instance. + */ wxString GetArchName() const; - //@} /** Returns the architecture ID of this wxPlatformInfo instance. */ wxArchitecture GetArchitecture() const; - //@{ /** - Returns the endianness ID of this wxPlatformInfo instance. + Converts the given string to a wxEndianness enum value or to + @c wxENDIAN_INVALID if the given string is not a valid endianness + string (i.e. does not contain nor little nor big strings). */ static wxEndianness GetEndianness(const wxString& end) const; + + /** + Returns the endianness ID of this wxPlatformInfo instance. + */ wxEndianness GetEndianness() const; - //@} - //@{ /** - Returns the name for the endianness of this wxPlatformInfo instance. + Returns name for the given wxEndianness enumeration value. */ static wxString GetEndiannessName(wxEndianness end) const; + + /** + Returns the name for the endianness of this wxPlatformInfo instance. + */ wxString GetEndiannessName() const; - //@} /** Returns the run-time major version of the OS associated with this wxPlatformInfo instance. - See wxGetOsVersion() for more info. - @see CheckOSVersion() + @see ::wxGetOsVersion(), CheckOSVersion() */ int GetOSMajorVersion() const; /** Returns the run-time minor version of the OS associated with this wxPlatformInfo instance. - See wxGetOsVersion() for more info. - @see CheckOSVersion() + @see ::wxGetOsVersion(), CheckOSVersion() */ int GetOSMinorVersion() const; - //@{ + /** + Returns the operating system family name for the given wxOperatingSystemId + enumeration value: @c Unix for @c wxOS_UNIX, @c Macintosh for @c wxOS_MAC, + @c Windows for @c wxOS_WINDOWS, @c DOS for @c wxOS_DOS, @c OS/2 for @c wxOS_OS2. + */ + static wxString GetOperatingSystemFamilyName(wxOperatingSystemId os) const; + /** Returns the operating system family name of the OS associated with this wxPlatformInfo instance. */ - static wxString GetOperatingSystemFamilyName(wxOperatingSystemId os) const; wxString GetOperatingSystemFamilyName() const; - //@} - //@{ /** - Returns the operating system ID of this wxPlatformInfo instance. + Converts the given string to a wxOperatingSystemId enum value or to @c + wxOS_UNKNOWN if the given string is not a valid operating system name. */ static wxOperatingSystemId GetOperatingSystemId(const wxString& name) const; + + /** + Returns the operating system ID of this wxPlatformInfo instance. + */ wxOperatingSystemId GetOperatingSystemId() const; - //@} - //@{ + /** + Returns the name for the given operating system ID value. + + This can be a long name (e.g. Microsoft Windows NT); + use GetOperatingSystemFamilyName() to retrieve a short, generic name. + */ + static wxString GetOperatingSystemIdName(wxOperatingSystemId os) const; + /** Returns the operating system name of the OS associated with this wxPlatformInfo instance. */ - static wxString GetOperatingSystemIdName(wxOperatingSystemId os) const; wxString GetOperatingSystemIdName() const; - //@} - //@{ + /** - Returns the wxWidgets port ID associated with this wxPlatformInfo instance. + Converts the given string to a wxWidgets port ID value or to @c wxPORT_UNKNOWN + if the given string does not match any of the wxWidgets canonical name ports + ("wxGTK", "wxMSW", etc) nor any of the short wxWidgets name ports ("gtk", "msw", etc). */ static wxPortId GetPortId(const wxString& portname) const; + + /** + Returns the wxWidgets port ID associated with this wxPlatformInfo instance. + */ wxPortId GetPortId() const; - //@} - //@{ + /** + Returns the name of the given wxWidgets port ID value. + The @a usingUniversal argument specifies whether the port is in its native + or wxUniversal variant. + + The returned string always starts with the "wx" prefix and is a mixed-case string. + */ + static wxString GetPortIdName(wxPortId port, bool usingUniversal) const; + /** Returns the name of the wxWidgets port ID associated with this wxPlatformInfo instance. */ - static wxString GetPortIdName(wxPortId port, bool usingUniversal) const; wxString GetPortIdName() const; - //@} - //@{ /** - Returns the short name of the wxWidgets port ID associated with this - wxPlatformInfo instance. + Returns the short name of the given wxWidgets port ID value. + The @a usingUniversal argument specifies whether the port is in its native + or wxUniversal variant. + + The returned string does not start with the "wx" prefix and is always lower + case. */ static wxString GetPortIdShortName(wxPortId port, bool usingUniversal) const; + + /** + Returns the short name of the wxWidgets port ID associated with this + wxPlatformInfo instance. + */ wxString GetPortIdShortName() const; - //@} /** Returns the run-time major version of the toolkit associated with this wxPlatformInfo instance. - Note that if GetPortId() returns wxPORT_BASE, then this value is zero (unless - externally modified with wxPlatformInfo::SetToolkitVersion); that is, no native toolkit is in use. - See wxAppTraits::GetToolkitVersion for more info. + + Note that if GetPortId() returns @c wxPORT_BASE, then this value is zero + (unless externally modified with SetToolkitVersion()); that is, no native + toolkit is in use. + See wxAppTraits::GetToolkitVersion() for more info. @see CheckToolkitVersion() */ @@ -182,9 +342,11 @@ public: /** Returns the run-time minor version of the toolkit associated with this wxPlatformInfo instance. - Note that if GetPortId() returns wxPORT_BASE, then this value is zero (unless - externally modified with wxPlatformInfo::SetToolkitVersion); that is, no native toolkit is in use. - See wxAppTraits::GetToolkitVersion for more info. + + Note that if GetPortId() returns @c wxPORT_BASE, then this value is zero + (unless externally modified with SetToolkitVersion()); that is, no native + toolkit is in use. + See wxAppTraits::GetToolkitVersion() for more info. @see CheckToolkitVersion() */ -- 2.45.2