From: Bryan Petty Date: Fri, 27 Jun 2008 16:22:58 +0000 (+0000) Subject: Moved all interface headers into a 'wx' subdirectory for proper use of Doxygen path... X-Git-Url: https://git.saurik.com/wxWidgets.git/commitdiff_plain/ae3c17b4013e80b99976c750c19fca47729517f6 Moved all interface headers into a 'wx' subdirectory for proper use of Doxygen path settings. git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@54385 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775 --- diff --git a/interface/aboutdlg.h b/interface/aboutdlg.h deleted file mode 100644 index 1688a5a45c..0000000000 --- a/interface/aboutdlg.h +++ /dev/null @@ -1,224 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: aboutdlg.h -// Purpose: interface of wxAboutDialogInfo -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxAboutDialogInfo - @wxheader{aboutdlg.h} - - wxAboutDialogInfo contains information shown in the standard @e About - dialog displayed by the wxAboutBox() function. - - This class contains the general information about the program, such as its - name, version, copyright and so on, as well as lists of the program developers, - documentation writers, artists and translators. The simple properties from the - former group are represented as a string with the exception of the program icon - and the program web site, while the lists from the latter group are stored as - wxArrayString and can be either set entirely at once using - wxAboutDialogInfo::SetDevelopers and similar functions or built one by one using - wxAboutDialogInfo::AddDeveloper etc. - - Please also notice that while all the main platforms have the native - implementation of the about dialog, they are often more limited than the - generic version provided by wxWidgets and so the generic version is used if - wxAboutDialogInfo has any fields not supported by the native version. Currently - GTK+ version supports all the possible fields natively but MSW and Mac versions - don't support URLs, licence text nor custom icons in the about dialog and if - either of those is used, wxAboutBox() will automatically use the generic version - so you should avoid specifying these fields to achieve more native look and feel. - - @library{wxadv} - @category{misc} - - @see wxAboutDialogInfo::SetArtists -*/ -class wxAboutDialogInfo -{ -public: - /** - Default constructor leaves all fields are initially uninitialized, in general - you should call at least SetVersion(), SetCopyright() and SetDescription(). - */ - wxAboutDialogInfo(); - - /** - Adds an artist name to be shown in the program credits. - - @see SetArtists() - */ - void AddArtist(const wxString& artist); - - /** - Adds a developer name to be shown in the program credits. - - @see SetDevelopers() - */ - void AddDeveloper(const wxString& developer); - - /** - Adds a documentation writer name to be shown in the program credits. - - @see SetDocWriters() - */ - void AddDocWriter(const wxString& docwriter); - - /** - Adds a translator name to be shown in the program credits. Notice that if no - translator names are specified explicitely, wxAboutBox() will try to use the - translation of the string @c translator-credits from the currently used message - catalog -- this can be used to show just the name of the translator of the - program in the current language. - - @see SetTranslators() - */ - void AddTranslator(const wxString& translator); - - /** - Sets the the list of artists to be shown in the program credits. - - @see AddArtist() - */ - void SetArtists(const wxArrayString& artists); - - /** - Set the short string containing the program copyright information. Notice that - any occurrences of @c "(C)" in @a copyright will be replaced by the - copyright symbol (circled C) automatically, which means that you can avoid - using this symbol in the program source code which can be problematic, - */ - void SetCopyright(const wxString& copyright); - - /** - Set brief, but possibly multiline, description of the program. - */ - void SetDescription(const wxString& desc); - - /** - Set the list of developers of the program. - - @see AddDeveloper() - */ - void SetDevelopers(const wxArrayString& developers); - - /** - Set the list of documentation writers. - - @see AddDocWriter() - */ - void SetDocWriters(const wxArrayString& docwriters); - - /** - Set the icon to be shown in the dialog. By default the icon of the main frame - will be shown if the native about dialog supports custom icons. If it doesn't - but a valid icon is specified using this method, the generic about dialog is - used instead so you should avoid calling this function for maximally native - look and feel. - */ - void SetIcon(const wxIcon& icon); - - /** - Set the long, multiline string containing the text of the program licence. - - Only GTK+ version supports showing the licence text in the native about dialog - currently so the generic version will be used under all the other platforms if - this method is called. To preserve the native look and feel it is advised that - you do not call this method but provide a separate menu item in the - @c "Help" menu for displaying the text of your program licence. - */ - void SetLicence(const wxString& licence); - - /** - This is the same as SetLicence(). - */ - void SetLicense(const wxString& licence); - - /** - Set the name of the program. If this method is not called, the string returned - by wxApp::GetAppName will be shown in the dialog. - */ - void SetName(const wxString& name); - - /** - Set the list of translators. Please see AddTranslator() for additional - discussion. - */ - void SetTranslators(const wxArrayString& translators); - - /** - Set the version of the program. The version is in free format, i.e. not - necessarily in the @c x.y.z form but it shouldn't contain the "version" word. - */ - void SetVersion(const wxString& version); - - /** - Set the web site for the program and its description (which defaults to @a url - itself if empty). - - Please notice that only GTK+ version currently supports showing the link in the - native about dialog so if this method is called, the generic version will be - used under all the other platforms. - */ - void SetWebSite(const wxString& url, - const wxString& desc = wxEmptyString); -}; - - -// ============================================================================ -// Global functions/macros -// ============================================================================ - -/** @ingroup group_funcmacro_dialog */ -//@{ - -/** - This function shows the standard about dialog containing the information - specified in @a info. If the current platform has a native about dialog - which is capable of showing all the fields in @a info, the native dialog is - used, otherwise the function falls back to the generic wxWidgets version of - the dialog, i.e. does the same thing as wxGenericAboutBox. - - Here is an example of how this function may be used: - - @code - void MyFrame::ShowSimpleAboutDialog(wxCommandEvent& WXUNUSED(event)) - { - wxAboutDialogInfo info; - info.SetName(_("My Program")); - info.SetVersion(_("1.2.3 Beta")); - info.SetDescription(_("This program does something great.")); - info.SetCopyright(_T("(C) 2007 Me ")); - - wxAboutBox(info); - } - @endcode - - Please see the @ref page_samples_dialogs for more examples of using this - function and wxAboutDialogInfo for the description of the information which - can be shown in the about dialog. - - @header{wx/aboutdlg.h} -*/ -void wxAboutBox(const wxAboutDialogInfo& info); - -/** - This function does the same thing as wxAboutBox() except that it always uses - the generic wxWidgets version of the dialog instead of the native one. - - This is mainly useful if you need to customize the dialog by e.g. adding - custom controls to it (customizing the native dialog is not currently - supported). - - See the @ref page_samples_dialogs for an example of about dialog - customization. - - @see wxAboutDialogInfo - - @header{wx/aboutdlg.h} -*/ -void wxGenericAboutBox(const wxAboutDialogInfo& info); - -//@} diff --git a/interface/accel.h b/interface/accel.h deleted file mode 100644 index 616f2b047a..0000000000 --- a/interface/accel.h +++ /dev/null @@ -1,216 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: accel.h -// Purpose: interface of wxAccelerator* classes -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - - -/** wxAcceleratorEntry flags */ -enum wxAcceleratorEntryFlags -{ - /** no modifiers */ - wxACCEL_NORMAL, - - /** hold Alt key down */ - wxACCEL_ALT, - - /** hold Ctrl key down */ - wxACCEL_CTRL, - - /** hold Shift key down */ - wxACCEL_SHIFT, - - /** Command key on OS X; identic to wxACCEL_CTRL on other platforms. */ - wxACCEL_CMD -}; - - -/** - @class wxAcceleratorEntry - @wxheader{accel.h} - - An object used by an application wishing to create an accelerator table - (see wxAcceleratorTable). - - @library{wxcore} - @category{misc} - - @see wxAcceleratorTable, wxWindow::SetAcceleratorTable -*/ -class wxAcceleratorEntry -{ -public: - /** - Constructor. - - @param flags - A combination of the wxAcceleratorEntryFlags values, which - indicates which modifier keys are held down. - @param keyCode - The keycode to be detected. See @ref page_keycodes for a full list of keycodes. - @param cmd - The menu or control command identifier (ID). - @param item - The menu item associated with this accelerator. - */ - wxAcceleratorEntry(int flags = 0, int keyCode = 0, int cmd = 0, - wxMenuItem *item = NULL); - - /** - Copy ctor. - */ - wxAcceleratorEntry(const wxAcceleratorEntry& entry); - - /** - Returns the command identifier for the accelerator table entry. - */ - int GetCommand() const; - - /** - Returns the flags for the accelerator table entry. - */ - int GetFlags() const; - - /** - Returns the keycode for the accelerator table entry. - */ - int GetKeyCode() const; - - /** - Returns the menu item associated with this accelerator entry. - */ - wxMenuItem *GetMenuItem() const; - - /** - Sets the accelerator entry parameters. - - @param flags - A combination of the wxAcceleratorEntryFlags values, which - indicates which modifier keys are held down. - @param keyCode - The keycode to be detected. See @ref page_keycodes for a full list of keycodes. - @param cmd - The menu or control command identifier (ID). - @param item - The menu item associated with this accelerator. - */ - void Set(int flags, int keyCode, int cmd, wxMenuItem *item = NULL); - - /** - Returns @true if this object is correctly initialized. - */ - bool IsOk() const; - - /** - Returns a wxString for this accelerator. - This function formats it using the @c "flags-keycode" format - where @c flags maybe a hyphen-separed list of @c "shift|alt|ctrl". - */ - wxString ToString() const; - - /** - Parses the given string and sets the accelerator accordingly. - - @param str - Should be a string in the form "flags-keycode" - - @return @true if the given string correctly initialized this object - (i.e. if IsOk() returns true after this call) - */ - bool FromString(const wxString& str); - - - wxAcceleratorEntry& operator=(const wxAcceleratorEntry& entry); - bool operator==(const wxAcceleratorEntry& entry) const; - bool operator!=(const wxAcceleratorEntry& entry) const; -}; - - -/** - @class wxAcceleratorTable - @wxheader{accel.h} - - An accelerator table allows the application to specify a table of keyboard - shortcuts for menu or button commands. - - The object ::wxNullAcceleratorTable is defined to be a table with no data, and - is the initial accelerator table for a window. - - Example: - - @code - wxAcceleratorEntry entries[4]; - entries[0].Set(wxACCEL_CTRL, (int) 'N', ID_NEW_WINDOW); - entries[1].Set(wxACCEL_CTRL, (int) 'X', wxID_EXIT); - entries[2].Set(wxACCEL_SHIFT, (int) 'A', ID_ABOUT); - entries[3].Set(wxACCEL_NORMAL, WXK_DELETE, wxID_CUT); - - wxAcceleratorTable accel(4, entries); - frame->SetAcceleratorTable(accel); - @endcode - - @remarks - An accelerator takes precedence over normal processing and can be a convenient - way to program some event handling. For example, you can use an accelerator table - to enable a dialog with a multi-line text control to accept CTRL-Enter as meaning - 'OK'. - - @library{wxcore} - @category{misc} - - @stdobjects - ::wxNullAcceleratorTable - - @see wxAcceleratorEntry, wxWindow::SetAcceleratorTable -*/ -class wxAcceleratorTable : public wxObject -{ -public: - /** - Default ctor. - */ - wxAcceleratorTable(); - - /** - Initializes the accelerator table from an array of wxAcceleratorEntry. - - @param n - Number of accelerator entries. - @param entries - The array of entries. - */ - wxAcceleratorTable(int n, const wxAcceleratorEntry entries[]); - - /** - Loads the accelerator table from a Windows resource (Windows only). - - @onlyfor{wxmsw} - - @param resource - Name of a Windows accelerator. - */ - wxAcceleratorTable(const wxString& resource); - - /** - Destroys the wxAcceleratorTable object. - See @ref overview_refcount_destruct for more info. - */ - virtual ~wxAcceleratorTable(); - - /** - Returns @true if the accelerator table is valid. - */ - bool IsOk() const; -}; - - -// ============================================================================ -// Global functions/macros -// ============================================================================ - -/** - An empty accelerator table. -*/ -wxAcceleratorTable wxNullAcceleratorTable; diff --git a/interface/access.h b/interface/access.h deleted file mode 100644 index 9218d85226..0000000000 --- a/interface/access.h +++ /dev/null @@ -1,421 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: access.h -// Purpose: interface of wxAccessible -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - - -/** - wxAccessible functions return a wxAccStatus error code, - which may be one of this enum's values. -*/ -typedef enum -{ - wxACC_FAIL, //!< The function failed. - wxACC_FALSE, //!< The function returned false. - wxACC_OK, //!< The function completed successfully. - wxACC_NOT_IMPLEMENTED, //!< The function is not implemented. - wxACC_NOT_SUPPORTED //!< The function is not supported. -} wxAccStatus; - - -/** - Directions of navigation are represented by this enum. -*/ -typedef enum -{ - wxNAVDIR_DOWN, - wxNAVDIR_FIRSTCHILD, - wxNAVDIR_LASTCHILD, - wxNAVDIR_LEFT, - wxNAVDIR_NEXT, - wxNAVDIR_PREVIOUS, - wxNAVDIR_RIGHT, - wxNAVDIR_UP -} wxNavDir; - - -/** - The role of a user interface element is represented by the values of this enum. -*/ -typedef enum { - wxROLE_NONE, - wxROLE_SYSTEM_ALERT, - wxROLE_SYSTEM_ANIMATION, - wxROLE_SYSTEM_APPLICATION, - wxROLE_SYSTEM_BORDER, - wxROLE_SYSTEM_BUTTONDROPDOWN, - wxROLE_SYSTEM_BUTTONDROPDOWNGRID, - wxROLE_SYSTEM_BUTTONMENU, - wxROLE_SYSTEM_CARET, - wxROLE_SYSTEM_CELL, - wxROLE_SYSTEM_CHARACTER, - wxROLE_SYSTEM_CHART, - wxROLE_SYSTEM_CHECKBUTTON, - wxROLE_SYSTEM_CLIENT, - wxROLE_SYSTEM_CLOCK, - wxROLE_SYSTEM_COLUMN, - wxROLE_SYSTEM_COLUMNHEADER, - wxROLE_SYSTEM_COMBOBOX, - wxROLE_SYSTEM_CURSOR, - wxROLE_SYSTEM_DIAGRAM, - wxROLE_SYSTEM_DIAL, - wxROLE_SYSTEM_DIALOG, - wxROLE_SYSTEM_DOCUMENT, - wxROLE_SYSTEM_DROPLIST, - wxROLE_SYSTEM_EQUATION, - wxROLE_SYSTEM_GRAPHIC, - wxROLE_SYSTEM_GRIP, - wxROLE_SYSTEM_GROUPING, - wxROLE_SYSTEM_HELPBALLOON, - wxROLE_SYSTEM_HOTKEYFIELD, - wxROLE_SYSTEM_INDICATOR, - wxROLE_SYSTEM_LINK, - wxROLE_SYSTEM_LIST, - wxROLE_SYSTEM_LISTITEM, - wxROLE_SYSTEM_MENUBAR, - wxROLE_SYSTEM_MENUITEM, - wxROLE_SYSTEM_MENUPOPUP, - wxROLE_SYSTEM_OUTLINE, - wxROLE_SYSTEM_OUTLINEITEM, - wxROLE_SYSTEM_PAGETAB, - wxROLE_SYSTEM_PAGETABLIST, - wxROLE_SYSTEM_PANE, - wxROLE_SYSTEM_PROGRESSBAR, - wxROLE_SYSTEM_PROPERTYPAGE, - wxROLE_SYSTEM_PUSHBUTTON, - wxROLE_SYSTEM_RADIOBUTTON, - wxROLE_SYSTEM_ROW, - wxROLE_SYSTEM_ROWHEADER, - wxROLE_SYSTEM_SCROLLBAR, - wxROLE_SYSTEM_SEPARATOR, - wxROLE_SYSTEM_SLIDER, - wxROLE_SYSTEM_SOUND, - wxROLE_SYSTEM_SPINBUTTON, - wxROLE_SYSTEM_STATICTEXT, - wxROLE_SYSTEM_STATUSBAR, - wxROLE_SYSTEM_TABLE, - wxROLE_SYSTEM_TEXT, - wxROLE_SYSTEM_TITLEBAR, - wxROLE_SYSTEM_TOOLBAR, - wxROLE_SYSTEM_TOOLTIP, - wxROLE_SYSTEM_WHITESPACE, - wxROLE_SYSTEM_WINDOW -} wxAccRole; - -/** - Objects are represented by a wxAccObject enum value. -*/ -typedef enum { - wxOBJID_WINDOW = 0x00000000, - wxOBJID_SYSMENU = 0xFFFFFFFF, - wxOBJID_TITLEBAR = 0xFFFFFFFE, - wxOBJID_MENU = 0xFFFFFFFD, - wxOBJID_CLIENT = 0xFFFFFFFC, - wxOBJID_VSCROLL = 0xFFFFFFFB, - wxOBJID_HSCROLL = 0xFFFFFFFA, - wxOBJID_SIZEGRIP = 0xFFFFFFF9, - wxOBJID_CARET = 0xFFFFFFF8, - wxOBJID_CURSOR = 0xFFFFFFF7, - wxOBJID_ALERT = 0xFFFFFFF6, - wxOBJID_SOUND = 0xFFFFFFF5 -} wxAccObject; - - -/** - Selection actions are identified by the wxAccSelectionFlags values. -*/ -typedef enum -{ - wxACC_SEL_NONE = 0, - wxACC_SEL_TAKEFOCUS = 1, - wxACC_SEL_TAKESELECTION = 2, - wxACC_SEL_EXTENDSELECTION = 4, - wxACC_SEL_ADDSELECTION = 8, - wxACC_SEL_REMOVESELECTION = 16 -} wxAccSelectionFlags; - -//@{ -/** - Represents a status of the system. -*/ -#define wxACC_STATE_SYSTEM_ALERT_HIGH 0x00000001 -#define wxACC_STATE_SYSTEM_ALERT_MEDIUM 0x00000002 -#define wxACC_STATE_SYSTEM_ALERT_LOW 0x00000004 -#define wxACC_STATE_SYSTEM_ANIMATED 0x00000008 -#define wxACC_STATE_SYSTEM_BUSY 0x00000010 -#define wxACC_STATE_SYSTEM_CHECKED 0x00000020 -#define wxACC_STATE_SYSTEM_COLLAPSED 0x00000040 -#define wxACC_STATE_SYSTEM_DEFAULT 0x00000080 -#define wxACC_STATE_SYSTEM_EXPANDED 0x00000100 -#define wxACC_STATE_SYSTEM_EXTSELECTABLE 0x00000200 -#define wxACC_STATE_SYSTEM_FLOATING 0x00000400 -#define wxACC_STATE_SYSTEM_FOCUSABLE 0x00000800 -#define wxACC_STATE_SYSTEM_FOCUSED 0x00001000 -#define wxACC_STATE_SYSTEM_HOTTRACKED 0x00002000 -#define wxACC_STATE_SYSTEM_INVISIBLE 0x00004000 -#define wxACC_STATE_SYSTEM_MARQUEED 0x00008000 -#define wxACC_STATE_SYSTEM_MIXED 0x00010000 -#define wxACC_STATE_SYSTEM_MULTISELECTABLE 0x00020000 -#define wxACC_STATE_SYSTEM_OFFSCREEN 0x00040000 -#define wxACC_STATE_SYSTEM_PRESSED 0x00080000 -#define wxACC_STATE_SYSTEM_PROTECTED 0x00100000 -#define wxACC_STATE_SYSTEM_READONLY 0x00200000 -#define wxACC_STATE_SYSTEM_SELECTABLE 0x00400000 -#define wxACC_STATE_SYSTEM_SELECTED 0x00800000 -#define wxACC_STATE_SYSTEM_SELFVOICING 0x01000000 -#define wxACC_STATE_SYSTEM_UNAVAILABLE 0x02000000 -//@} - -//@{ -/** - An event identifier that can be sent via wxAccessible::NotifyEvent. -*/ -#define wxACC_EVENT_SYSTEM_SOUND 0x0001 -#define wxACC_EVENT_SYSTEM_ALERT 0x0002 -#define wxACC_EVENT_SYSTEM_FOREGROUND 0x0003 -#define wxACC_EVENT_SYSTEM_MENUSTART 0x0004 -#define wxACC_EVENT_SYSTEM_MENUEND 0x0005 -#define wxACC_EVENT_SYSTEM_MENUPOPUPSTART 0x0006 -#define wxACC_EVENT_SYSTEM_MENUPOPUPEND 0x0007 -#define wxACC_EVENT_SYSTEM_CAPTURESTART 0x0008 -#define wxACC_EVENT_SYSTEM_CAPTUREEND 0x0009 -#define wxACC_EVENT_SYSTEM_MOVESIZESTART 0x000A -#define wxACC_EVENT_SYSTEM_MOVESIZEEND 0x000B -#define wxACC_EVENT_SYSTEM_CONTEXTHELPSTART 0x000C -#define wxACC_EVENT_SYSTEM_CONTEXTHELPEND 0x000D -#define wxACC_EVENT_SYSTEM_DRAGDROPSTART 0x000E -#define wxACC_EVENT_SYSTEM_DRAGDROPEND 0x000F -#define wxACC_EVENT_SYSTEM_DIALOGSTART 0x0010 -#define wxACC_EVENT_SYSTEM_DIALOGEND 0x0011 -#define wxACC_EVENT_SYSTEM_SCROLLINGSTART 0x0012 -#define wxACC_EVENT_SYSTEM_SCROLLINGEND 0x0013 -#define wxACC_EVENT_SYSTEM_SWITCHSTART 0x0014 -#define wxACC_EVENT_SYSTEM_SWITCHEND 0x0015 -#define wxACC_EVENT_SYSTEM_MINIMIZESTART 0x0016 -#define wxACC_EVENT_SYSTEM_MINIMIZEEND 0x0017 -#define wxACC_EVENT_OBJECT_CREATE 0x8000 -#define wxACC_EVENT_OBJECT_DESTROY 0x8001 -#define wxACC_EVENT_OBJECT_SHOW 0x8002 -#define wxACC_EVENT_OBJECT_HIDE 0x8003 -#define wxACC_EVENT_OBJECT_REORDER 0x8004 -#define wxACC_EVENT_OBJECT_FOCUS 0x8005 -#define wxACC_EVENT_OBJECT_SELECTION 0x8006 -#define wxACC_EVENT_OBJECT_SELECTIONADD 0x8007 -#define wxACC_EVENT_OBJECT_SELECTIONREMOVE 0x8008 -#define wxACC_EVENT_OBJECT_SELECTIONWITHIN 0x8009 -#define wxACC_EVENT_OBJECT_STATECHANGE 0x800A -#define wxACC_EVENT_OBJECT_LOCATIONCHANGE 0x800B -#define wxACC_EVENT_OBJECT_NAMECHANGE 0x800C -#define wxACC_EVENT_OBJECT_DESCRIPTIONCHANGE 0x800D -#define wxACC_EVENT_OBJECT_VALUECHANGE 0x800E -#define wxACC_EVENT_OBJECT_PARENTCHANGE 0x800F -#define wxACC_EVENT_OBJECT_HELPCHANGE 0x8010 -#define wxACC_EVENT_OBJECT_DEFACTIONCHANGE 0x8011 -#define wxACC_EVENT_OBJECT_ACCELERATORCHANGE 0x8012 -//@} - -/** - @class wxAccessible - @wxheader{access.h} - - The wxAccessible class allows wxWidgets applications, and wxWidgets itself, - to return extended information about user interface elements to client - applications such as screen readers. This is the main way in which wxWidgets - implements accessibility features. - - At present, only Microsoft Active Accessibility is supported by this class. - - To use this class, derive from wxAccessible, implement appropriate - functions, and associate an object of the class with a window using - wxWindow::SetAccessible. - - All functions return an indication of success, failure, or not implemented - using values of the wxAccStatus enum type. - - If you return @c wxACC_NOT_IMPLEMENTED from any function, the system will try - to implement the appropriate functionality. However this will not work with - all functions. - - Most functions work with an object @e id, which can be zero to refer to - 'this' UI element, or greater than zero to refer to the nth child element. - This allows you to specify elements that don't have a corresponding wxWindow or - wxAccessible; for example, the sash of a splitter window. - - For details on the semantics of functions and types, please refer to the - Microsoft Active Accessibility 1.2 documentation. - - This class is compiled into wxWidgets only if the wxUSE_ACCESSIBILITY setup - symbol is set to 1. - - @onlyfor{wxmsw} - - @library{wxcore} - @category{misc} - - @see @sample{access} -*/ -class wxAccessible : public wxObject -{ -public: - /** - Constructor, taking an optional window. The object can be associated with - a window later. - */ - wxAccessible(wxWindow* win = NULL); - - /** - Destructor. - */ - ~wxAccessible(); - - /** - Performs the default action for the object. - @a childId is 0 (the action for this object) or greater than 0 (the action - for a child). - - @return wxACC_NOT_SUPPORTED if there is no default action for this - window (e.g. an edit control). - */ - virtual wxAccStatus DoDefaultAction(int childId); - - /** - Gets the specified child (starting from 1). If @a child is @NULL and the return - value is wxACC_OK, this means that the child is a simple element and not an - accessible object. - */ - virtual wxAccStatus GetChild(int childId, wxAccessible** child); - - /** - Returns the number of children in @a childCount. - */ - virtual wxAccStatus GetChildCount(int* childCount); - - /** - Gets the default action for this object (0) or a child (greater than 0). - - Return wxACC_OK even if there is no action. @a actionName is the action, or the - empty string if there is no action. The retrieved string describes the action that is - performed on an object, not what the object does as a result. For example, a toolbar - button that prints a document has a default action of "Press" rather than "Prints - the current document." - */ - virtual wxAccStatus GetDefaultAction(int childId, - wxString* actionName); - - /** - Returns the description for this object or a child. - */ - virtual wxAccStatus GetDescription(int childId, - wxString* description); - - /** - Gets the window with the keyboard focus. If childId is 0 and child is @NULL, no - object in this subhierarchy has the focus. If this object has the focus, child - should be 'this'. - */ - virtual wxAccStatus GetFocus(int* childId, wxAccessible** child); - - /** - Returns help text for this object or a child, similar to tooltip text. - */ - virtual wxAccStatus GetHelpText(int childId, wxString* helpText); - - /** - Returns the keyboard shortcut for this object or child. - Returns e.g. ALT+K. - */ - virtual wxAccStatus GetKeyboardShortcut(int childId, - wxString* shortcut); - - /** - Returns the rectangle for this object (id is 0) or a child element (id is - greater than 0). - @a rect is in screen coordinates. - */ - virtual wxAccStatus GetLocation(wxRect& rect, int elementId); - - /** - Gets the name of the specified object. - */ - virtual wxAccStatus GetName(int childId, wxString* name); - - /** - Returns the parent of this object, or @NULL. - */ - virtual wxAccStatus GetParent(wxAccessible** parent); - - /** - Returns a role constant describing this object. See wxAccRole for a list - of these roles. - */ - virtual wxAccStatus GetRole(int childId, wxAccRole* role); - - /** - Gets a variant representing the selected children of this object. - - Acceptable values are: - @li a null variant (IsNull() returns @true) - @li a list variant (GetType() == wxT("list")) - @li an integer representing the selected child element, - or 0 if this object is selected (GetType() == wxT("long")) - @li a "void*" pointer to a wxAccessible child object - */ - virtual wxAccStatus GetSelections(wxVariant* selections); - - /** - Returns a state constant. See wxAccStatus for a list of these states. - */ - virtual wxAccStatus GetState(int childId, long* state); - - /** - Returns a localized string representing the value for the object - or child. - */ - virtual wxAccStatus GetValue(int childId, wxString* strValue); - - /** - Returns the window associated with this object. - */ - wxWindow* GetWindow(); - - /** - Returns a status value and object id to indicate whether the given point - was on this or a child object. Can return either a child object, or an - integer representing the child element, starting from 1. - - @a pt is in screen coordinates. - */ - virtual wxAccStatus HitTest(const wxPoint& pt, int* childId, - wxAccessible** childObject); - - /** - Navigates from @a fromId to @a toId or to @a toObject. - */ - virtual wxAccStatus Navigate(wxNavDir navDir, int fromId, - int* toId, - wxAccessible** toObject); - - /** - Allows the application to send an event when something changes in - an accessible object. - */ - virtual static void NotifyEvent(int eventType, wxWindow* window, - wxAccObject objectType, - int objectType); - - /** - Selects the object or child. See wxAccSelectionFlags for a list - of the selection actions. - */ - virtual wxAccStatus Select(int childId, - wxAccSelectionFlags selectFlags); - - /** - Sets the window associated with this object. - */ - void SetWindow(wxWindow* window); -}; - diff --git a/interface/animate.h b/interface/animate.h deleted file mode 100644 index 62e2ab5a8f..0000000000 --- a/interface/animate.h +++ /dev/null @@ -1,290 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: animate.h -// Purpose: interface of wxAnimation* classes -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - Supported animation types. -*/ -enum wxAnimationType -{ - wxANIMATION_TYPE_INVALID, - - /** represents an animated GIF file. */ - wxANIMATION_TYPE_GIF, - - /** represents an ANI file. */ - wxANIMATION_TYPE_ANI, - - /** autodetect the filetype. */ - wxANIMATION_TYPE_ANY -}; - -/** - @class wxAnimationCtrl - @wxheader{animate.h} - - This is a static control which displays an animation. - wxAnimationCtrl API is as simple as possible and won't give you full control - on the animation; if you need it then use wxMediaCtrl. - - This control is useful to display a (small) animation while doing a long task - (e.g. a "throbber"). - - It is only available if @c wxUSE_ANIMATIONCTRL is set to 1 (the default). - - @beginStyleTable - @style{wxAC_DEFAULT_STYLE} - The default style: wxBORDER_NONE. - @style{wxAC_NO_AUTORESIZE} - By default, the control will adjust its size to exactly fit to the - size of the animation when SetAnimation is called. If this style - flag is given, the control will not change its size - @endStyleTable - - @library{wxadv} - @category{ctrl} - - @nativeimpl{wxgtk,wxmsw} - - - - @see wxAnimation, @sample{animate} -*/ -class wxAnimationCtrl : public wxControl -{ -public: - /** - Initializes the object and calls Create() with - all the parameters. - */ - wxAnimationCtrl(wxWindow* parent, wxWindowID id, - const wxAnimation& anim = wxNullAnimation, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = wxAC_DEFAULT_STYLE, - const wxString& name = wxAnimationCtrlNameStr); - - /** - Creates the control with the given @a anim animation. - - After control creation you must explicitely call Play() to start to play - the animation. Until that function won't be called, the first frame - of the animation is displayed. - - @param parent - Parent window, must be non-@NULL. - @param id - The identifier for the control. - @param anim - The initial animation shown in the control. - @param pos - Initial position. - @param size - Initial size. - @param style - The window style, see wxAC_* flags. - @param name - Control name. - - @return @true if the control was successfully created or @false if - creation failed. - */ - bool Create(wxWindow* parent, wxWindowID id, - const wxAnimation& anim = wxNullAnimation, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = wxAC_DEFAULT_STYLE, - const wxString& name = wxAnimationCtrlNameStr); - - /** - Returns the animation associated with this control. - */ - virtual wxAnimation GetAnimation() const; - - /** - Returns the inactive bitmap shown in this control when the; - see SetInactiveBitmap() for more info. - */ - wxBitmap GetInactiveBitmap() const; - - /** - Returns @true if the animation is being played. - */ - virtual bool IsPlaying() const; - - /** - Loads the animation from the given file and calls SetAnimation(). - See wxAnimation::LoadFile for more info. - */ - virtual bool LoadFile(const wxString& file, - wxAnimationType animType = wxANIMATION_TYPE_ANY); - - /** - Loads the animation from the given stream and calls SetAnimation(). - See wxAnimation::Load() for more info. - */ - virtual bool Load(wxInputStream& file, - wxAnimationType animType = wxANIMATION_TYPE_ANY); - - /** - Starts playing the animation. - - The animation is always played in loop mode (unless the last frame of the - animation has an infinite delay time) and always start from the first frame - even if you @ref Stop "stopped" it while some other frame was displayed. - */ - virtual bool Play(); - - /** - Sets the animation to play in this control. - - If the previous animation is being played, it's @ref Stop() stopped. - Until Play() isn't called, a static image, the first frame of the given - animation or the background colour will be shown - (see SetInactiveBitmap() for more info). - */ - virtual void SetAnimation(const wxAnimation& anim); - - /** - Sets the bitmap to show on the control when it's not playing an animation. - - If you set as inactive bitmap ::wxNullBitmap (which is the default), then the - first frame of the animation is instead shown when the control is inactive; - in this case, if there's no valid animation associated with the control - (see SetAnimation()), then the background colour of the window is shown. - - If the control is not playing the animation, the given bitmap will be - immediately shown, otherwise it will be shown as soon as Stop() is called. - - Note that the inactive bitmap, if smaller than the control's size, will be - centered in the control; if bigger, it will be stretched to fit it. - */ - virtual void SetInactiveBitmap(const wxBitmap& bmp); - - /** - Stops playing the animation. - The control will show the first frame of the animation, a custom static image or - the window's background colour as specified by the last SetInactiveBitmap() call. - */ - virtual void Stop(); -}; - - - -/** - @class wxAnimation - @wxheader{animate.h} - - This class encapsulates the concept of a platform-dependent animation. - An animation is a sequence of frames of the same size. - Sound is not supported by wxAnimation. - - @library{wxadv} - @category{gdi} - - @stdobjects - ::wxNullAnimation - - @see wxAnimationCtrl, @sample{animate} -*/ -class wxAnimation : public wxGDIObject -{ -public: - /** - Copy ctor. - */ - wxAnimation(const wxAnimation& anim); - - /** - Loads an animation from a file. - - @param name - The name of the file to load. - @param type - See LoadFile for more info. - */ - wxAnimation(const wxString& name, - wxAnimationType type = wxANIMATION_TYPE_ANY); - - /** - Destructor. - See @ref overview_refcount_destruct for more info. - */ - virtual ~wxAnimation(); - - /** - Returns the delay for the i-th frame in milliseconds. - If @c -1 is returned the frame is to be displayed forever. - */ - virtual int GetDelay(unsigned int i) const; - - /** - Returns the i-th frame as a wxImage. - */ - virtual wxImage GetFrame(unsigned int i) const; - - /** - Returns the number of frames for this animation. - */ - virtual unsigned int GetFrameCount() const; - - /** - Returns the size of the animation. - */ - virtual wxSize GetSize() const; - - /** - Returns @true if animation data is present. - */ - virtual bool IsOk() const; - - /** - Loads an animation from the given stream. - - @param stream - The stream to use to load the animation. - @param type - One of the following values: - @li wxANIMATION_TYPE_GIF: loads an animated GIF file; - @li wxANIMATION_TYPE_ANI: load an ANI file; - @li wxANIMATION_TYPE_ANY: tries to autodetect the filetype. - - @return @true if the operation succeeded, @false otherwise. - */ - virtual bool Load(wxInputStream& stream, - wxAnimationType type = wxANIMATION_TYPE_ANY); - - /** - Loads an animation from a file. - - @param name - A filename. - @param type - One of the wxAnimationType values; wxANIMATION_TYPE_ANY - means that the function should try to autodetect the filetype. - - @return @true if the operation succeeded, @false otherwise. - */ - virtual bool LoadFile(const wxString& name, - wxAnimationType type = wxANIMATION_TYPE_ANY); - - /** - Assignment operator, using @ref overview_refcount "reference counting". - */ - wxAnimation& operator =(const wxAnimation& brush); -}; - - -// ============================================================================ -// Global functions/macros -// ============================================================================ - -/** - An empty animation object. -*/ -wxAnimation wxNullAnimation; - diff --git a/interface/app.h b/interface/app.h deleted file mode 100644 index cf79e46a12..0000000000 --- a/interface/app.h +++ /dev/null @@ -1,865 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: app.h -// Purpose: interface of wxApp -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - - -/** - @class wxAppConsole - @wxheader{app.h} - - This class is essential for writing console-only or hybrid apps without - having to define wxUSE_GUI=0. - - @todo MORE INFO - - @library{wxbase} - @category{appmanagement} - - @see @ref overview_app -*/ -class wxAppConsole : public wxEvtHandler -{ -protected: - /** - Creates the wxAppTraits object when GetTraits() needs it for the first time. - - @see wxAppTraits - */ - virtual wxAppTraits* CreateTraits(); - -public: - - /** - Destructor. - */ - virtual ~wxAppConsole(); - - /** - Dispatches the next event in the windowing system event queue. - Blocks until an event appears if there are none currently - (use Pending() if this is not wanted). - - This can be used for programming event loops, e.g. - - @code - while (app.Pending()) - Dispatch(); - @endcode - - @return @false if the event loop should stop and @true otherwise. - - @see Pending() - */ - virtual bool Dispatch(); - - /** - Call this to explicitly exit the main message (event) loop. - You should normally exit the main loop (and the application) by deleting - the top window. - */ - virtual void ExitMainLoop(); - - /** - This function is called before processing any event and allows the application - to preempt the processing of some events. - - If this method returns -1 the event is processed normally, otherwise either - @true or @false should be returned and the event processing stops immediately - considering that the event had been already processed (for the former return - value) or that it is not going to be processed at all (for the latter one). - */ - virtual int FilterEvent(wxEvent& event); - - /** - Returns the user-readable application name. - - The difference between this string and the one returned by GetAppName() is that - this one is meant to be shown to the user and so should be used for the window - titles, page headers and so on while the other one should be only used internally, - e.g. for the file names or configuration file keys. - By default, returns the same string as GetAppName(). - - @since 2.9.0 - */ - wxString GetAppDisplayName() const; - - /** - Returns the application name. - - @remarks wxWidgets sets this to a reasonable default before calling - OnInit(), but the application can reset it at will. - - @see GetAppDisplayName() - */ - wxString GetAppName() const; - - /** - Gets the class name of the application. The class name may be used in a - platform specific manner to refer to the application. - - @see SetClassName() - */ - wxString GetClassName() const; - - /** - Returns the one and only global application object. - Usually ::wxTheApp is usead instead. - - @see SetInstance() - */ - static wxAppConsole* GetInstance(); - - /** - Returns a pointer to the wxAppTraits object for the application. - If you want to customize the wxAppTraits object, you must override the - CreateTraits() function. - */ - wxAppTraits* GetTraits(); - - /** - Returns the user-readable vendor name. The difference between this string - and the one returned by GetVendorName() is that this one is meant to be shown - to the user and so should be used for the window titles, page headers and so on - while the other one should be only used internally, e.g. for the file names or - configuration file keys. - - By default, returns the same string as GetVendorName(). - - @since 2.9.0 - */ - const wxString& GetVendorDisplayName() const; - - /** - Returns the application's vendor name. - */ - const wxString& GetVendorName() const; - - /** - This function simply invokes the given method @a func of the specified - event handler @a handler with the @a event as parameter. It exists solely - to allow to catch the C++ exceptions which could be thrown by all event - handlers in the application in one place: if you want to do this, override - this function in your wxApp-derived class and add try/catch clause(s) to it. - */ - virtual void HandleEvent(wxEvtHandler* handler, - wxEventFunction func, - wxEvent& event) const; - - /** - Returns @true if the main event loop is currently running, i.e. if the - application is inside OnRun(). - - This can be useful to test whether events can be dispatched. For example, - if this function returns @false, non-blocking sockets cannot be used because - the events from them would never be processed. - */ - static bool IsMainLoopRunning(); - - /** - Called in response of an "open-application" Apple event. - Override this to create a new document in your app. - - @onlyfor{wxmac} - */ - virtual void MacNewFile(); - - /** - Called in response of an "open-document" Apple event. - - You need to override this method in order to open a document file after the - user double clicked on it or if the document file was dropped on either the - running application or the application icon in Finder. - - @onlyfor{wxmac} - */ - virtual void MacOpenFile(const wxString& fileName); - - /** - Called in response of a "get-url" Apple event. - - @onlyfor{wxmac} - */ - virtual void MacOpenURL(const wxString& url); - - /** - Called in response of a "print-document" Apple event. - - @onlyfor{wxmac} - */ - virtual void MacPrintFile(const wxString& fileName); - - /** - Called in response of a "reopen-application" Apple event. - - @onlyfor{wxmac} - */ - virtual void MacReopenApp(); - - /** - Called by wxWidgets on creation of the application. Override this if you wish - to provide your own (environment-dependent) main loop. - - @return 0 under X, and the wParam of the WM_QUIT message under Windows. - */ - virtual int MainLoop(); - - /** - This function is called when an assert failure occurs, i.e. the condition - specified in wxASSERT() macro evaluated to @false. - - It is only called in debug mode (when @c __WXDEBUG__ is defined) as - asserts are not left in the release code at all. - The base class version shows the default assert failure dialog box proposing to - the user to stop the program, continue or ignore all subsequent asserts. - - @param file - the name of the source file where the assert occurred - @param line - the line number in this file where the assert occurred - @param func - the name of the function where the assert occurred, may be - empty if the compiler doesn't support C99 __FUNCTION__ - @param cond - the condition of the failed assert in text form - @param msg - the message specified as argument to wxASSERT_MSG or wxFAIL_MSG, will - be @NULL if just wxASSERT or wxFAIL was used - */ - virtual void OnAssertFailure(const wxChar *file, - int line, - const wxChar *func, - const wxChar *cond, - const wxChar *msg); - - /** - Called when command line parsing fails (i.e. an incorrect command line option - was specified by the user). The default behaviour is to show the program usage - text and abort the program. - - Return @true to continue normal execution or @false to return - @false from OnInit() thus terminating the program. - - @see OnInitCmdLine() - */ - virtual bool OnCmdLineError(wxCmdLineParser& parser); - - /** - Called when the help option (@c --help) was specified on the command line. - The default behaviour is to show the program usage text and abort the program. - - Return @true to continue normal execution or @false to return - @false from OnInit() thus terminating the program. - - @see OnInitCmdLine() - */ - virtual bool OnCmdLineHelp(wxCmdLineParser& parser); - - /** - Called after the command line had been successfully parsed. You may override - this method to test for the values of the various parameters which could be - set from the command line. - - Don't forget to call the base class version unless you want to suppress - processing of the standard command line options. - Return @true to continue normal execution or @false to return @false from - OnInit() thus terminating the program. - - @see OnInitCmdLine() - */ - virtual bool OnCmdLineParsed(wxCmdLineParser& parser); - - /** - This function is called if an unhandled exception occurs inside the main - application event loop. It can return @true to ignore the exception and to - continue running the loop or @false to exit the loop and terminate the - program. In the latter case it can also use C++ @c throw keyword to - rethrow the current exception. - - The default behaviour of this function is the latter in all ports except under - Windows where a dialog is shown to the user which allows him to choose between - the different options. You may override this function in your class to do - something more appropriate. - - Finally note that if the exception is rethrown from here, it can be caught in - OnUnhandledException(). - */ - virtual bool OnExceptionInMainLoop(); - - /** - Override this member function for any processing which needs to be - done as the application is about to exit. OnExit is called after - destroying all application windows and controls, but before - wxWidgets cleanup. Note that it is not called at all if - OnInit() failed. - - The return value of this function is currently ignored, return the same - value as returned by the base class method if you override it. - */ - virtual int OnExit(); - - /** - This function may be called if something fatal happens: an unhandled - exception under Win32 or a a fatal signal under Unix, for example. However, - this will not happen by default: you have to explicitly call - wxHandleFatalExceptions() to enable this. - - Generally speaking, this function should only show a message to the user and - return. You may attempt to save unsaved data but this is not guaranteed to - work and, in fact, probably won't. - - @see wxHandleFatalExceptions() - */ - virtual void OnFatalException(); - - /** - This must be provided by the application, and will usually create the - application's main window, optionally calling SetTopWindow(). - - You may use OnExit() to clean up anything initialized here, provided - that the function returns @true. - - Notice that if you want to to use the command line processing provided by - wxWidgets you have to call the base class version in the derived class - OnInit(). - - Return @true to continue processing, @false to exit the application - immediately. - */ - virtual bool OnInit(); - - /** - Called from OnInit() and may be used to initialize the parser with the - command line options for this application. The base class versions adds - support for a few standard options only. - */ - virtual void OnInitCmdLine(wxCmdLineParser& parser); - - /** - This virtual function is where the execution of a program written in wxWidgets - starts. The default implementation just enters the main loop and starts - handling the events until it terminates, either because ExitMainLoop() has - been explicitly called or because the last frame has been deleted and - GetExitOnFrameDelete() flag is @true (this is the default). - - The return value of this function becomes the exit code of the program, so it - should return 0 in case of successful termination. - */ - virtual int OnRun(); - - /** - This function is called when an unhandled C++ exception occurs inside - OnRun() (the exceptions which occur during the program startup and shutdown - might not be caught at all). Notice that by now the main event loop has been - terminated and the program will exit, if you want to prevent this from happening - (i.e. continue running after catching an exception) you need to override - OnExceptionInMainLoop(). - - The default implementation shows information about the exception in debug build - but does nothing in the release build. - */ - virtual void OnUnhandledException(); - - /** - Returns @true if unprocessed events are in the window system event queue. - - @see Dispatch() - */ - virtual bool Pending(); - - /** - Set the application name to be used in the user-visible places such as window - titles. See GetAppDisplayName() for more about the differences between the - display name and name. - */ - void SetAppDisplayName(const wxString& name); - - /** - Sets the name of the application. This name should be used for file names, - configuration file entries and other internal strings. For the user-visible - strings, such as the window titles, the application display name set by - SetAppDisplayName() is used instead. - - By default the application name is set to the name of its executable file. - - @see GetAppName() - */ - void SetAppName(const wxString& name); - - /** - Sets the class name of the application. This may be used in a platform specific - manner to refer to the application. - - @see GetClassName() - */ - void SetClassName(const wxString& name); - - /** - Allows external code to modify global ::wxTheApp, but you should really - know what you're doing if you call it. - - @param app - Replacement for the global application object. - - @see GetInstance() - */ - static void SetInstance(wxAppConsole* app); - - /** - Set the vendor name to be used in the user-visible places. - See GetVendorDisplayName() for more about the differences between the - display name and name. - */ - void SetVendorDisplayName(const wxString& name); - - /** - Sets the name of application's vendor. The name will be used - in registry access. A default name is set by wxWidgets. - - @see GetVendorName() - */ - void SetVendorName(const wxString& name); - - /** - Yields control to pending messages in the windowing system. - - This can be useful, for example, when a time-consuming process writes to a - text window. Without an occasional yield, the text window will not be updated - properly, and on systems with cooperative multitasking, such as Windows 3.1 - other processes will not respond. - - Caution should be exercised, however, since yielding may allow the - user to perform actions which are not compatible with the current task. - Disabling menu items or whole menus during processing can avoid unwanted - reentrance of code: see ::wxSafeYield for a better function. - - Note that Yield() will not flush the message logs. This is intentional as - calling Yield() is usually done to quickly update the screen and popping up - a message box dialog may be undesirable. If you do wish to flush the log - messages immediately (otherwise it will be done during the next idle loop - iteration), call wxLog::FlushActive. - - Calling Yield() recursively is normally an error and an assert failure is - raised in debug build if such situation is detected. However if the - @a onlyIfNeeded parameter is @true, the method will just silently - return @false instead. - */ - virtual bool Yield(bool onlyIfNeeded = false); - - /** - Number of command line arguments (after environment-specific processing). - */ - int argc; - - /** - Command line arguments (after environment-specific processing). - - Under Windows and Linux/Unix, you should parse the command line - arguments and check for files to be opened when starting your - application. Under OS X, you need to override MacOpenFile() - since command line arguments are used differently there. - - You may use the wxCmdLineParser to parse command line arguments. - */ - wxChar** argv; -}; - - - - -/** - @class wxApp - @wxheader{app.h} - - The wxApp class represents the application itself. It is used to: - - @li set and get application-wide properties; - @li implement the windowing system message or event loop; - @li initiate application processing via wxApp::OnInit; - @li allow default processing of events not handled by other - objects in the application. - - You should use the macro IMPLEMENT_APP(appClass) in your application - implementation file to tell wxWidgets how to create an instance of your - application class. - - Use DECLARE_APP(appClass) in a header file if you want the wxGetApp function - (which returns a reference to your application object) to be visible to other - files. - - @library{wxbase} - @category{appmanagement} - - @see @ref overview_app -*/ -class wxApp : public wxAppConsole -{ -public: - /** - Constructor. Called implicitly with a definition of a wxApp object. - */ - wxApp(); - - /** - Destructor. Will be called implicitly on program exit if the wxApp - object is created on the stack. - */ - virtual ~wxApp(); - - /** - Returns @true if the application will exit when the top-level frame is deleted. - - @see SetExitOnFrameDelete() - */ - bool GetExitOnFrameDelete() const; - - /** - Returns @true if the application will use the best visual on systems that support - different visuals, @false otherwise. - - @see SetUseBestVisual() - */ - bool GetUseBestVisual() const; - - /** - Returns a pointer to the top window. - - @remarks If the top window hasn't been set using SetTopWindow(), - this function will find the first top-level window - (frame or dialog) and return that. - - @see SetTopWindow() - */ - virtual wxWindow* GetTopWindow() const; - - /** - Returns @true if the application is active, i.e. if one of its windows is - currently in the foreground. - - If this function returns @false and you need to attract users attention to - the application, you may use wxTopLevelWindow::RequestUserAttention to do it. - */ - virtual bool IsActive() const; - - /** - Windows-only function for processing a message. This function is called - from the main message loop, checking for windows that may wish to process it. - - The function returns @true if the message was processed, @false otherwise. - If you use wxWidgets with another class library with its own message loop, - you should make sure that this function is called to allow wxWidgets to - receive messages. For example, to allow co-existence with the Microsoft - Foundation Classes, override the PreTranslateMessage function: - - @code - // Provide wxWidgets message loop compatibility - BOOL CTheApp::PreTranslateMessage(MSG *msg) - { - if (wxTheApp && wxTheApp->ProcessMessage((WXMSW *)msg)) - return true; - else - return CWinApp::PreTranslateMessage(msg); - } - @endcode - - @onlyfor{wxmsw} - */ - bool ProcessMessage(WXMSG* msg); - - /** - Sends idle events to a window and its children. - Please note that this function is internal to wxWidgets and shouldn't be used - by user code. - - @remarks These functions poll the top-level windows, and their children, - for idle event processing. If @true is returned, more OnIdle - processing is requested by one or more window. - - @see wxIdleEvent - */ - virtual bool SendIdleEvents(wxWindow* win, wxIdleEvent& event); - - /** - Allows the programmer to specify whether the application will exit when the - top-level frame is deleted. - - @param flag - If @true (the default), the application will exit when the top-level frame - is deleted. If @false, the application will continue to run. - - @see GetExitOnFrameDelete(), @ref overview_app_shutdown - */ - void SetExitOnFrameDelete(bool flag); - - /** - Allows external code to modify global ::wxTheApp, but you should really - know what you're doing if you call it. - - @param app - Replacement for the global application object. - - @see GetInstance() - */ - static void SetInstance(wxAppConsole* app); - - /** - Allows runtime switching of the UI environment theme. - - Currently implemented for wxGTK2-only. - Return @true if theme was successfully changed. - - @param theme - The name of the new theme or an absolute path to a gtkrc-theme-file - */ - virtual bool SetNativeTheme(const wxString& theme); - - /** - Sets the 'top' window. You can call this from within OnInit() to let wxWidgets - know which is the main window. You don't have to set the top window; - it is only a convenience so that (for example) certain dialogs without parents - can use a specific window as the top window. If no top window is specified by the - application, wxWidgets just uses the first frame or dialog in its top-level window - list, when it needs to use the top window. - - @param window - The new top window. - - @see GetTopWindow(), OnInit() - */ - void SetTopWindow(wxWindow* window); - - /** - Allows the programmer to specify whether the application will use the best - visual on systems that support several visual on the same display. This is typically - the case under Solaris and IRIX, where the default visual is only 8-bit whereas - certain applications are supposed to run in TrueColour mode. - - Note that this function has to be called in the constructor of the wxApp - instance and won't have any effect when called later on. - This function currently only has effect under GTK. - - @param flag - If @true, the app will use the best visual. - @param forceTrueColour - If @true then the application will try to force using a TrueColour - visual and abort the app if none is found. - */ - void SetUseBestVisual(bool flag, bool forceTrueColour = false); -}; - - - -// ============================================================================ -// Global functions/macros -// ============================================================================ - - -/** @ingroup group_funcmacro_rtti */ -//@{ - -/** - This is used in headers to create a forward declaration of the wxGetApp() - function implemented by IMPLEMENT_APP(). - - It creates the declaration className& wxGetApp(). - - @header{wx/app.h} - - Example: - - @code - DECLARE_APP(MyApp) - @endcode -*/ -#define DECLARE_APP( className ) - -/** - This is used in the application class implementation file to make the - application class known to wxWidgets for dynamic construction. - - @header{wx/app.h} - - Example: - - @code - IMPLEMENT_APP(MyApp) - @endcode - - @see DECLARE_APP(). -*/ -#define IMPLEMENT_APP( className ) - -//@} - - - -/** - The global pointer to the singleton wxApp object. - - @see wxApp::GetInstance() -*/ -wxApp *wxTheApp; - - - -/** @ingroup group_funcmacro_appinitterm */ -//@{ - -/** - This function doesn't exist in wxWidgets but it is created by using the - IMPLEMENT_APP() macro. - - Thus, before using it anywhere but in the same module where this macro is - used, you must make it available using DECLARE_APP(). - - The advantage of using this function compared to directly using the global - ::wxTheApp pointer is that the latter is of type wxApp* and so wouldn't - allow you to access the functions specific to your application class but - not present in wxApp while wxGetApp() returns the object of the right type. - - @header{wx/app.h} -*/ -wxAppDerivedClass& wxGetApp(); - -/** - If @a doIt is @true, the fatal exceptions (also known as general protection - faults under Windows or segmentation violations in the Unix world) will be - caught and passed to wxApp::OnFatalException. - - By default, i.e. before this function is called, they will be handled in - the normal way which usually just means that the application will be - terminated. Calling wxHandleFatalExceptions() with @a doIt equal to @false - will restore this default behaviour. - - Notice that this function is only available if @c wxUSE_ON_FATAL_EXCEPTION - is 1 and under Windows platform this requires a compiler with support for - SEH (structured exception handling) which currently means only Microsoft - Visual C++ or a recent Borland C++ version. - - @header{wx/app.h} -*/ -bool wxHandleFatalExceptions(bool doIt = true); - -/** - This function is used in wxBase only and only if you don't create - wxApp object at all. In this case you must call it from your - @c main() function before calling any other wxWidgets functions. - - If the function returns @false the initialization could not be performed, - in this case the library cannot be used and wxUninitialize() shouldn't be - called neither. - - This function may be called several times but wxUninitialize() must be - called for each successful call to this function. - - @header{wx/app.h} -*/ -bool wxInitialize(); - -/** - This function is for use in console (wxBase) programs only. It must be called - once for each previous successful call to wxInitialize(). - - @header{wx/app.h} -*/ -void wxUninitialize(); - -/** - This function wakes up the (internal and platform dependent) idle system, - i.e. it will force the system to send an idle event even if the system - currently @e is idle and thus would not send any idle event until after - some other event would get sent. This is also useful for sending events - between two threads and is used by the corresponding functions - wxPostEvent() and wxEvtHandler::AddPendingEvent(). - - @header{wx/app.h} -*/ -void wxWakeUpIdle(); - -/** - Calls wxApp::Yield. - - @deprecated - This function is kept only for backwards compatibility. Please use - the wxApp::Yield method instead in any new code. - - @header{wx/app.h} -*/ -bool wxYield(); - -/** - This function is similar to wxYield, except that it disables the user input to - all program windows before calling wxYield and re-enables it again - afterwards. If @a win is not @NULL, this window will remain enabled, - allowing the implementation of some limited user interaction. - Returns the result of the call to ::wxYield. - - @header{wx/app.h} -*/ -bool wxSafeYield(wxWindow* win = NULL, bool onlyIfNeeded = false); - -/** - This function initializes wxWidgets in a platform-dependent way. Use this if you - are not using the default wxWidgets entry code (e.g. main or WinMain). - - For example, you can initialize wxWidgets from an Microsoft Foundation Classes - (MFC) application using this function. - - @note This overload of wxEntry is available under all platforms. - - @see wxEntryStart() - - @header{wx/app.h} -*/ -int wxEntry(int& argc, wxChar** argv); - -/** - See wxEntry(int&,wxChar**) for more info about this function. - - Notice that under Windows CE platform, and only there, the type of @a pCmdLine - is @c wchar_t *, otherwise it is @c char *, even in Unicode build. - - @remarks To clean up wxWidgets, call wxApp::OnExit followed by the static - function wxApp::CleanUp. For example, if exiting from an MFC application - that also uses wxWidgets: - @code - int CTheApp::ExitInstance() - { - // OnExit isn't called by CleanUp so must be called explicitly. - wxTheApp->OnExit(); - wxApp::CleanUp(); - - return CWinApp::ExitInstance(); - } - @endcode - - @header{wx/app.h} -*/ -int wxEntry(HINSTANCE hInstance, - HINSTANCE hPrevInstance = NULL, - char* pCmdLine = NULL, - int nCmdShow = SW_SHOWNORMAL); - -//@} - - - -/** @ingroup group_funcmacro_procctrl */ -//@{ - -/** - Exits application after calling wxApp::OnExit. - - Should only be used in an emergency: normally the top-level frame - should be deleted (after deleting all other frames) to terminate the - application. See wxCloseEvent and wxApp. - - @header{wx/app.h} -*/ -void wxExit(); - -//@} - diff --git a/interface/apptrait.h b/interface/apptrait.h deleted file mode 100644 index 7da10c02b9..0000000000 --- a/interface/apptrait.h +++ /dev/null @@ -1,125 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: apptrait.h -// Purpose: interface of wxAppTraits -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxAppTraits - @wxheader{apptrait.h} - - The wxAppTraits class defines various configurable aspects of a wxApp. - You can access it using wxApp::GetTraits() function and you can create your - own wxAppTraits overriding the wxApp::CreateTraits() function. - - Note that wxAppTraits is an abstract class since it contains many - pure virtual functions. - In fact, by default, wxWidgets creates a @c wxConsoleAppTraits object for - console applications (i.e. those applications linked against wxBase library - only - see the @ref page_libs page) and a @c wxGUIAppTraits object for GUI - applications. - Both these classes are derived by wxAppTraits and represent concrete - implementation of the wxAppTraits interface. - - @library{wxbase} - @category{appmanagement} - - @see @ref overview_app, wxApp -*/ -class wxAppTraits -{ -public: - /** - Called by wxWidgets to create the default configuration object for the - application. The default version creates a registry-based wxRegConfig - class under MSW and wxFileConfig under all other platforms. - - The wxApp::GetAppName and wxApp::GetVendorName methods are used to - determine the registry key or file name. - */ - virtual wxConfigBase* CreateConfig(); - - /** - Creates the global font mapper object used for encodings/charset mapping. - */ - virtual wxFontMapper* CreateFontMapper() = 0; - - /** - Creates a wxLog class for the application to use for logging errors. - The default implementation returns a new wxLogGui class. - - @see wxLog - */ - virtual wxLog* CreateLogTarget() = 0; - - /** - Creates the global object used for printing out messages. - */ - virtual wxMessageOutput* CreateMessageOutput() = 0; - - /** - Returns the renderer to use for drawing the generic controls (return - value may be @NULL in which case the default renderer for the current - platform is used); this is used in GUI mode only and always returns @NULL - in console. - - @note the returned pointer needs to be deleted by the caller. - */ - virtual wxRendererNative* CreateRenderer() = 0; - - /** - This method returns the name of the desktop environment currently - running in a Unix desktop. Currently only "KDE" or "GNOME" are - supported and the code uses the X11 session protocol vendor name - to figure out, which desktop environment is running. The method - returns an empty string otherwise and on all other platforms. - */ - virtual wxString GetDesktopEnvironment() const = 0; - - /** - Returns the wxStandardPaths object for the application. - It's normally the same for wxBase and wxGUI except in the case of wxMac - and wxCocoa. - - @todo the real function returns a reference to wxStandardPathsBase; - user looking at these docs will write code: - wxStandardPaths &ref = ...->GetStandardPaths(); - which won't compile... - */ - virtual wxStandardPaths& GetStandardPaths(); - - /** - Returns the wxWidgets port ID used by the running program and eventually - fills the given pointers with the values of the major and minor digits - of the native toolkit currently used. - - The version numbers returned are thus detected at run-time and not compile-time - (except when this is not possible e.g. wxMotif). - - E.g. if your program is using wxGTK port this function will return wxPORT_GTK - and put in given pointers the versions of the GTK library in use. - See wxPlatformInfo for more details. - */ - virtual wxPortId GetToolkitVersion(int* major = NULL, int* minor = NULL) const = 0; - - /** - Returns @true if @c fprintf(stderr) goes somewhere, @false otherwise. - */ - virtual bool HasStderr() = 0; - - /** - Returns @true if the library was built as wxUniversal. - Always returns @false for wxBase-only apps. - */ - virtual bool IsUsingUniversalWidgets() const = 0; - - /** - Shows the assert dialog with the specified message in GUI mode or just prints - the string to stderr in console mode. - Returns @true to suppress subsequent asserts, @false to continue as before. - */ - virtual bool ShowAssertDialog(const wxString& msg) = 0; -}; - diff --git a/interface/archive.h b/interface/archive.h deleted file mode 100644 index cb2069dc60..0000000000 --- a/interface/archive.h +++ /dev/null @@ -1,638 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: archive.h -// Purpose: interface of wxArchive* classes -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxArchiveInputStream - @wxheader{archive.h} - - This is an abstract base class which serves as a common interface to - archive input streams such as wxZipInputStream. - - wxArchiveInputStream::GetNextEntry returns an wxArchiveEntry object containing - the meta-data for the next entry in the archive (and gives away ownership). - - Reading from the wxArchiveInputStream then returns the entry's data. Eof() - becomes @true after an attempt has been made to read past the end of the - entry's data. - - When there are no more entries, GetNextEntry() returns @NULL and sets Eof(). - - @library{wxbase} - @category{archive} - - @see @ref overview_archive, wxArchiveEntry, wxArchiveOutputStream -*/ -class wxArchiveInputStream : public wxFilterInputStream -{ -public: - /** - Closes the current entry. On a non-seekable stream reads to the end of - the current entry first. - */ - virtual bool CloseEntry() = 0; - - /** - Closes the current entry if one is open, then reads the meta-data for - the next entry and returns it in a wxArchiveEntry object, giving away - ownership. Reading this wxArchiveInputStream then returns the entry's data. - */ - wxArchiveEntry* GetNextEntry(); - - /** - Closes the current entry if one is open, then opens the entry specified - by the wxArchiveEntry object. - - @a entry must be from the same archive file that this wxArchiveInputStream - is reading, and it must be reading it from a seekable stream. - */ - virtual bool OpenEntry(wxArchiveEntry& entry) = 0; -}; - - - -/** - @class wxArchiveOutputStream - @wxheader{archive.h} - - This is an abstract base class which serves as a common interface to - archive output streams such as wxZipOutputStream. - - wxArchiveOutputStream::PutNextEntry is used to create a new entry in the - output archive, then the entry's data is written to the wxArchiveOutputStream. - Another call to PutNextEntry() closes the current entry and begins the next. - - @library{wxbase} - @category{archive} - - @see @ref overview_archive, wxArchiveEntry, wxArchiveInputStream -*/ -class wxArchiveOutputStream : public wxFilterOutputStream -{ -public: - /** - Calls Close() if it has not already been called. - */ - virtual ~wxArchiveOutputStream(); - - /** - Closes the archive, returning @true if it was successfully written. - Called by the destructor if not called explicitly. - - @see wxOutputStream::Close() - */ - virtual bool Close(); - - /** - Close the current entry. - It is called implicitly whenever another new entry is created with CopyEntry() - or PutNextEntry(), or when the archive is closed. - */ - virtual bool CloseEntry() = 0; - - /** - Some archive formats have additional meta-data that applies to the archive - as a whole. - For example in the case of zip there is a comment, which is stored at the end - of the zip file. CopyArchiveMetaData() can be used to transfer such information - when writing a modified copy of an archive. - - Since the position of the meta-data can vary between the various archive - formats, it is best to call CopyArchiveMetaData() before transferring - the entries. The wxArchiveOutputStream will then hold on to the meta-data - and write it at the correct point in the output file. - - When the input archive is being read from a non-seekable stream, the - meta-data may not be available when CopyArchiveMetaData() is called, - in which case the two streams set up a link and transfer the data - when it becomes available. - */ - virtual bool CopyArchiveMetaData(wxArchiveInputStream& stream) = 0; - - /** - Takes ownership of @a entry and uses it to create a new entry in the - archive. @a entry is then opened in the input stream @a stream - and its contents copied to this stream. - - For archive types which compress entry data, CopyEntry() is likely to be - much more efficient than transferring the data using Read() and Write() - since it will copy them without decompressing and recompressing them. - - @a entry must be from the same archive file that @a stream is - accessing. For non-seekable streams, @a entry must also be the last - thing read from @a stream. - */ - virtual bool CopyEntry(wxArchiveEntry* entry, - wxArchiveInputStream& stream) = 0; - - /** - Create a new directory entry (see wxArchiveEntry::IsDir) with the given - name and timestamp. - - PutNextEntry() can also be used to create directory entries, by supplying - a name with a trailing path separator. - */ - virtual bool PutNextDirEntry(const wxString& name, - const wxDateTime& dt = wxDateTime::Now()) = 0; - - /** - Takes ownership of entry and uses it to create a new entry in the archive. - The entry's data can then be written by writing to this wxArchiveOutputStream. - */ - virtual bool PutNextEntry(wxArchiveEntry* entry) = 0; - - /** - Create a new entry with the given name, timestamp and size. The entry's - data can then be written by writing to this wxArchiveOutputStream. - */ - virtual bool PutNextEntry(const wxString& name, - const wxDateTime& dt = wxDateTime::Now(), - wxFileOffset size = wxInvalidOffset) = 0; -}; - - - -/** - @class wxArchiveEntry - @wxheader{archive.h} - - This is an abstract base class which serves as a common interface to - archive entry classes such as wxZipEntry. - These hold the meta-data (filename, timestamp, etc.), for entries - in archive files such as zips and tars. - - @section wxarchiveentry_nonseekable About non-seekable streams - - This information applies only when reading archives from non-seekable streams. - When the stream is seekable GetNextEntry() returns a fully populated wxArchiveEntry. - See @ref overview_archive_noseek for more information. - - For generic programming, when the worst case must be assumed, you can rely on - all the fields of wxArchiveEntry being fully populated when - wxArchiveInputStream::GetNextEntry() returns, with the the following exceptions: - - @li GetSize(): guaranteed to be available after the entry has been read to Eof(), - or CloseEntry() has been called; - @li IsReadOnly(): guaranteed to be available after the end of the archive has - been reached, i.e. after GetNextEntry() returns NULL and Eof() is true. - - @library{wxbase} - @category{archive} - - @see @ref overview_archive, @ref overview_archive_generic, - wxArchiveInputStream, wxArchiveOutputStream, wxArchiveNotifier -*/ -class wxArchiveEntry : public wxObject -{ -public: - /** - Returns a copy of this entry object. - */ - wxArchiveEntry* Clone() const; - - /** - Gets the entry's timestamp. - */ - virtual wxDateTime GetDateTime() const = 0; - - /** - Sets the entry's timestamp. - */ - virtual void SetDateTime(const wxDateTime& dt) = 0; - - /** - Returns the entry's name, by default in the native format. - The name can include directory components, i.e. it can be a full path. - - If this is a directory entry, (i.e. if IsDir() is @true) then the - returned string is the name with a trailing path separator. - */ - virtual wxString GetName(wxPathFormat format = wxPATH_NATIVE) const = 0; - - /** - Sets the entry's name. - Setting a name with a trailing path separator sets IsDir(). - - @see GetName() - */ - virtual void SetName(const wxString& name, - wxPathFormat format = wxPATH_NATIVE) = 0; - - /** - Returns the size of the entry's data in bytes. - */ - virtual wxFileOffset GetSize() const = 0; - - /** - Sets the size of the entry's data in bytes. - */ - virtual void SetSize(wxFileOffset size) = 0; - - /** - Returns the path format used internally within the archive to store - filenames. - */ - virtual wxPathFormat GetInternalFormat() const = 0; - - /** - Returns the entry's filename in the internal format used within the - archive. The name can include directory components, i.e. it can be a - full path. - - The names of directory entries are returned without any trailing path - separator. This gives a canonical name that can be used in comparisons. - - @see @ref overview_archive_byname - */ - virtual wxString GetInternalName() const = 0; - - /** - Returns a numeric value unique to the entry within the archive. - */ - virtual wxFileOffset GetOffset() const = 0; - - /** - Returns @true if this is a directory entry. - - Directory entries are entries with no data, which are used to store - the meta-data of directories. They also make it possible for completely - empty directories to be stored. - - @note - The names of entries within an archive can be complete paths, and - unarchivers typically create whatever directories are necessary as they - restore files, even if the archive contains no explicit directory entries. - */ - virtual bool IsDir() const = 0; - - /** - Marks this entry as a directory if @a isDir is @true. See IsDir() for more info. - */ - virtual void SetIsDir(bool isDir = true) = 0; - - /** - Returns @true if the entry is a read-only file. - */ - virtual bool IsReadOnly() const = 0; - - /** - Sets this entry as a read-only file. - */ - virtual void SetIsReadOnly(bool isReadOnly = true) = 0; - - /** - Sets the notifier (see wxArchiveNotifier) for this entry. - - Whenever the wxArchiveInputStream updates this entry, it will then invoke - the associated notifier's wxArchiveNotifier::OnEntryUpdated method. - - Setting a notifier is not usually necessary. It is used to handle - certain cases when modifying an archive in a pipeline (i.e. between - non-seekable streams). - */ - void SetNotifier(wxArchiveNotifier& notifier); - - /** - Unsets the notifier eventually attached to this entry. - */ - virtual void UnsetNotifier(); -}; - - -/** - Type of stream enumeration; used by wxArchiveClassFactory methods. -*/ -enum wxStreamProtocolType -{ - wxSTREAM_PROTOCOL, //!< wxFileSystem protocol (should be only one) - wxSTREAM_MIMETYPE, //!< MIME types the stream handles - wxSTREAM_ENCODING, //!< Not used for archives - wxSTREAM_FILEEXT //!< File extensions the stream handles -}; - -/** - @class wxArchiveClassFactory - @wxheader{archive.h} - - Allows the creation of streams to handle archive formats such as zip and tar. - - For example, given a filename you can search for a factory that will - handle it and create a stream to read it: - - @code - factory = wxArchiveClassFactory::Find(filename, wxSTREAM_FILEEXT); - if (factory) - stream = factory->NewStream(new wxFFileInputStream(filename)); - @endcode - - wxArchiveClassFactory::Find can also search for a factory by MIME type - or wxFileSystem protocol. - - The available factories can be enumerated using - wxArchiveClassFactory::GetFirst() and wxArchiveClassFactory::GetNext(). - - @library{wxbase} - @category{archive} - - @see @ref overview_archive, @ref overview_archive_generic, wxArchiveEntry, - wxArchiveInputStream, wxArchiveOutputStream, wxFilterClassFactory -*/ -class wxArchiveClassFactory : public wxObject -{ -public: - /** - Returns @true if this factory can handle the given protocol, MIME type - or file extension. - - When using wxSTREAM_FILEEXT for the second parameter, the first parameter - can be a complete filename rather than just an extension. - */ - bool CanHandle(const wxChar* protocol, - wxStreamProtocolType type = wxSTREAM_PROTOCOL) const; - - /** - A static member that finds a factory that can handle a given protocol, MIME - type or file extension. Returns a pointer to the class factory if found, or - @NULL otherwise. It does not give away ownership of the factory. - - When using wxSTREAM_FILEEXT for the second parameter, the first parameter - can be a complete filename rather than just an extension. - */ - static const wxArchiveClassFactory* Find(const wxChar* protocol, - wxStreamProtocolType type = wxSTREAM_PROTOCOL); - - /** - Returns the wxMBConv object that the created streams will use when - translating meta-data. The initial default, set by the constructor, - is wxConvLocal. - */ - wxMBConv GetConv() const; - - /** - Sets the wxMBConv object that the created streams will use when - translating meta-data. - */ - void SetConv(wxMBConv& conv); - - //@{ - /** - GetFirst and GetNext can be used to enumerate the available factories. - For example, to list them: - - @code - wxString list; - const wxArchiveClassFactory *factory = wxArchiveClassFactory::GetFirst(); - - while (factory) { - list << factory->GetProtocol() << _T("\n"); - factory = factory->GetNext(); - } - @endcode - - GetFirst() and GetNext() return a pointer to a factory or @NULL if no more - are available. They do not give away ownership of the factory. - */ - static const wxArchiveClassFactory* GetFirst() const; - const wxArchiveClassFactory* GetNext() const; - //@} - - /** - Calls the static GetInternalName() function for the archive entry type, - for example wxZipEntry::GetInternalName. - */ - wxString GetInternalName(const wxString& name, - wxPathFormat format = wxPATH_NATIVE) const; - - /** - Returns the wxFileSystem protocol supported by this factory. - Equivalent to @code wxString(*GetProtocols()) @endcode. - */ - wxString GetProtocol() const; - - /** - Returns the protocols, MIME types or file extensions supported by this - factory, as an array of null terminated strings. - - It does not give away ownership of the array or strings. - For example, to list the file extensions a factory supports: - - @code - wxString list; - const wxChar *const *p; - - for (p = factory->GetProtocols(wxSTREAM_FILEEXT); *p; p++) - list << *p << _T("\n"); - @encode - */ - const wxChar* const* GetProtocols(wxStreamProtocolType type = wxSTREAM_PROTOCOL) const; - - /** - Create a new wxArchiveEntry object of the appropriate type. - */ - wxArchiveEntry* NewEntry() const; - - //@{ - /** - Create a new input or output stream to read or write an archive. - - If the parent stream is passed as a pointer then the new archive stream - takes ownership of it. If it is passed by reference then it does not. - */ - wxArchiveInputStream* NewStream(wxInputStream& stream) const; - wxArchiveOutputStream* NewStream(wxOutputStream& stream) const; - wxArchiveInputStream* NewStream(wxInputStream* stream) const; - wxArchiveOutputStream* NewStream(wxOutputStream* stream) const; - //@} - - /** - Adds this class factory to the list returned by GetFirst() or GetNext(). - - It is not necessary to do this to use the archive streams. It is usually - used when implementing streams, typically the implementation will - add a static instance of its factory class. - - It can also be used to change the order of a factory already in the list, - bringing it to the front. This isn't a thread safe operation - so can't be done when other threads are running that will be using the list. - The list does not take ownership of the factory. - */ - void PushFront(); - - /** - Removes this class factory from the list returned by GetFirst() and GetNext(). - - Removing from the list isn't a thread safe operation so can't be done when - other threads are running that will be using the list. - The list does not own the factories, so removing a factory does not delete it. - */ - void Remove(); -}; - - - -/** - @class wxArchiveNotifier - @wxheader{archive.h} - - If you need to know when a wxArchiveInputStream updates a wxArchiveEntry - object, you can create a notifier by deriving from this abstract base class, - overriding wxArchiveNotifier::OnEntryUpdated. - - An instance of your notifier class can then be assigned to the wxArchiveEntry - object using wxArchiveEntry::SetNotifier. - Your OnEntryUpdated() method will then be invoked whenever the input - stream updates the entry. - - Setting a notifier is not usually necessary. It is used to handle - certain cases when modifying an archive in a pipeline (i.e. between - non-seekable streams). - See @ref overview_archive_noseek. - - @library{wxbase} - @category{archive} - - @see @ref overview_archive_noseek, wxArchiveEntry, wxArchiveInputStream, - wxArchiveOutputStream -*/ -class wxArchiveNotifier -{ -public: - /** - This method must be overridden in your derived class. - */ - void OnEntryUpdated(class wxArchiveEntry& entry); -}; - - - -/** - @class wxArchiveIterator - @wxheader{archive.h} - - An input iterator template class that can be used to transfer an archive's - catalogue to a container. It is only available if wxUSE_STL is set to 1 - in setup.h, and the uses for it outlined below require a compiler which - supports member templates. - - @code - template class Arc, class T = typename Arc::entry_type* - class wxArchiveIterator - { - // this constructor creates an 'end of sequence' object - wxArchiveIterator(); - - // template parameter 'Arc' should be the type of an archive input stream - wxArchiveIterator(Arc& arc) { - // ... - } - }; - @endcode - - The first template parameter should be the type of archive input stream - (e.g. wxArchiveInputStream) and the second can either be a pointer to an entry - (e.g. wxArchiveEntry*), or a string/pointer pair (e.g. std::pairwxString, - wxArchiveEntry*). - - The @c wx/archive.h header defines the following typedefs: - - @code - typedef wxArchiveIterator wxArchiveIter; - - typedef wxArchiveIterator > wxArchivePairIter; - @endcode - - The header for any implementation of this interface should define similar - typedefs for its types, for example in @c wx/zipstrm.h there is: - - @code - typedef wxArchiveIterator wxZipIter; - - typedef wxArchiveIterator > wxZipPairIter; - @endcode - - Transferring the catalogue of an archive @e arc to a vector @e cat, - can then be done something like this: - - @code - std::vector cat((wxArchiveIter)arc, wxArchiveIter()); - @endcode - - When the iterator is dereferenced, it gives away ownership of an entry - object. So in the above example, when you have finished with @e cat - you must delete the pointers it contains. - - If you have smart pointers with normal copy semantics (i.e. not auto_ptr - or wxScopedPtr), then you can create an iterator which uses them instead. - - For example, with a smart pointer class for zip entries @e ZipEntryPtr: - - @code - typedef std::vector ZipCatalog; - typedef wxArchiveIterator ZipIter; - ZipCatalog cat((ZipIter)zip, ZipIter()); - @endcode - - Iterators that return std::pair objects can be used to populate a std::multimap, - to allow entries to be looked up by name. - The string is initialised using the wxArchiveEntry object's - wxArchiveEntry::GetInternalName function. - - @code - typedef std::multimap ZipCatalog; - ZipCatalog cat((wxZipPairIter)zip, wxZipPairIter()); - @endcode - - Note that this iterator also gives away ownership of an entry - object each time it is dereferenced. So in the above example, when - you have finished with @e cat you must delete the pointers it contains. - - Or if you have them, a pair containing a smart pointer can be used - (again @e ZipEntryPtr), no worries about ownership: - - @code - typedef std::multimap ZipCatalog; - typedef wxArchiveIterator > ZipPairIter; - ZipCatalog cat((ZipPairIter)zip, ZipPairIter()); - @endcode - - @library{wxbase} - @category{archive} - - @see wxArchiveEntry, wxArchiveInputStream, wxArchiveOutputStream -*/ -class wxArchiveIterator -{ -public: - /** - Default constructor. - */ - wxArchiveIterator(); - - /** - Construct the iterator that returns all the entries in the archive input - stream @a arc. - */ - wxArchiveIterator(Arc& arc); - - /** - Returns an entry object from the archive input stream, giving away - ownership. - */ - const T operator*() const; - - //@{ - /** - Position the input iterator at the next entry in the archive input stream. - */ - wxArchiveIterator operator++(); - wxArchiveIterator operator++(int); - //@} -}; - diff --git a/interface/arrstr.h b/interface/arrstr.h deleted file mode 100644 index 34652fe144..0000000000 --- a/interface/arrstr.h +++ /dev/null @@ -1,376 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: arrstr.h -// Purpose: interface of wxArrayString -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @todo - the following functions are not documented; do they need to be? - WXDLLIMPEXP_BASE int wxCMPFUNC_CONV wxStringSortAscending(wxString*, wxString*); - WXDLLIMPEXP_BASE int wxCMPFUNC_CONV wxStringSortDescending(wxString*, wxString*); -*/ - -/** - @class wxArrayString - @wxheader{arrstr.h} - - wxArrayString is an efficient container for storing wxString objects. - - It has the same features as all wxArray classes, i.e. it dynamically expands - when new items are added to it (so it is as easy to use as a linked list), - but the access time to the elements is constant, instead of being linear in - number of elements as in the case of linked lists. It is also very size - efficient and doesn't take more space than a C array @e wxString[] type - (wxArrayString uses its knowledge of internals of wxString class to achieve this). - - This class is used in the same way as other dynamic arrays(), except that no - ::WX_DEFINE_ARRAY declaration is needed for it. - When a string is added or inserted in the array, a copy of the string is created, - so the original string may be safely deleted (e.g. if it was a @e wxChar * - pointer the memory it was using can be freed immediately after this). - In general, there is no need to worry about string memory deallocation when using - this class - it will always free the memory it uses itself. - - The references returned by wxArrayString::Item, wxArrayString::Last or - wxArrayString::operator[] are not constant, so the array elements may - be modified in place like this: - - @code - array.Last().MakeUpper(); - @endcode - - @note none of the methods of wxArrayString is virtual including its - destructor, so this class should not be used as a base class. - - Although this is not true strictly speaking, this class may be considered as - a specialization of wxArray class for the wxString member data: it is not - implemented like this, but it does have all of the wxArray functions. - - @todo what about stl? how does it integrate? - - @library{wxbase} - @category{containers} - - @see wxArray, wxString, @ref overview_string -*/ -class wxArrayString : public wxArray -{ -public: - /** - Default constructor. - */ - wxArrayString(); - - /** - Copy constructor. - */ - wxArrayString(const wxArrayString& array); - - //@{ - /** - Constructor from a C string array. Pass a size @a sz and an array @a arr. - **/ - wxArrayString(size_t sz, const char** arr); - wxArrayString(size_t sz, const wchar_t** arr); - //@} - - /** - Constructor from a wxString array. Pass a size @a sz and array @a arr. - */ - wxArrayString(size_t sz, const wxString* arr); - - /** - Destructor frees memory occupied by the array strings. For performance - reasons it is not virtual, so this class should not be derived from. - */ - ~wxArrayString(); - - /** - Appends the given number of @a copies of the new item @a str to the - array and returns the index of the first new item in the array. - - @see Insert() - */ - size_t Add(const wxString& str, size_t copies = 1); - - /** - Preallocates enough memory to store @a nCount items. This function may be - used to improve array class performance before adding a known number of items - consecutively. - - @todo FIX THIS LINK - - @see @ref wxArray::memorymanagement "Dynamic array memory management" - */ - void Alloc(size_t nCount); - - /** - Clears the array contents and frees memory. - - @see Empty() - */ - void Clear(); - - /** - Empties the array: after a call to this function GetCount() will return 0. - However, this function does not free the memory used by the array and so - should be used when the array is going to be reused for storing other strings. - Otherwise, you should use Clear() to empty the array and free memory. - */ - void Empty(); - - /** - Returns the number of items in the array. - */ - size_t GetCount() const; - - /** - Search the element in the array, starting from the beginning if @a bFromEnd - is @false or from end otherwise. If @a bCase, comparison is case sensitive - (default), otherwise the case is ignored. - - This function uses linear search for wxArrayString. - Returns index of the first item matched or @c wxNOT_FOUND if there is no match. - */ - int Index(const wxString& sz, bool bCase = true, bool bFromEnd = false) const; - - /** - Insert the given number of @a copies of the new element in the array before the - position @a nIndex. Thus, for example, to insert the string in the beginning of - the array you would write: - - @code - Insert("foo", 0); - @endcode - - If @a nIndex is equal to GetCount() this function behaves as Add(). - */ - void Insert(const wxString& str, size_t nIndex, - size_t copies = 1); - - /** - Returns @true if the array is empty, @false otherwise. This function returns the - same result as GetCount() == 0 but is probably easier to read. - */ - bool IsEmpty() const; - - /** - Return the array element at position @a nIndex. An assert failure will - result from an attempt to access an element beyond the end of array in debug - mode, but no check is done in release mode. - - @see operator[] for the operator version. - */ - wxString& Item(size_t nIndex) const; - - /** - Returns the last element of the array. Attempt to access the last element of - an empty array will result in assert failure in debug build, however no checks - are done in release mode. - */ - wxString& Last() const; - - /** - Removes the first item matching this value. An assert failure is provoked by - an attempt to remove an element which does not exist in debug build. - - @see Index() - */ - void Remove(const wxString& sz); - - /** - Removes @a count items starting at position @a nIndex from the array. - */ - void RemoveAt(size_t nIndex, size_t count = 1); - - /** - Releases the extra memory allocated by the array. This function is useful to - minimize the array memory consumption. - - @todo FIX THIS LINK - - @see Alloc(), @ref wxArray::memorymanagement "Dynamic array memory - management" - */ - void Shrink(); - - /** - Sorts the array in alphabetical order or in reverse alphabetical order if - @a reverseOrder is @true. The sort is case-sensitive. - */ - void Sort(bool reverseOrder = false); - - /** - Sorts the array using the specified @a compareFunction for item comparison. - @a CompareFunction is defined as a function taking two @e const wxString - parameters and returning an @e int value less than, equal to or greater - than 0 if the first string is less than, equal to or greater than the - second one. - - Example: - The following example sorts strings by their length. - - @code - static int CompareStringLen(const wxString& first, const wxString& second) - { - return first.length() - second.length(); - } - - ... - - wxArrayString array; - - array.Add("one"); - array.Add("two"); - array.Add("three"); - array.Add("four"); - - array.Sort(CompareStringLen); - @endcode - */ - void Sort(CompareFunction compareFunction); - - /** - Compares 2 arrays respecting the case. Returns @true if the arrays have - different number of elements or if the elements don't match pairwise. - */ - bool operator !=(const wxArrayString& array) const; - - /** - Assignment operator. - */ - wxArrayString& operator=(const wxArrayString&); - - /** - Compares 2 arrays respecting the case. Returns @true only if the arrays have - the same number of elements and the same strings in the same order. - */ - bool operator ==(const wxArrayString& array) const; - - /** - Return the array element at position @a nIndex. An assert failure will - result from an attempt to access an element beyond the end of array in - debug mode, but no check is done in release mode. - - This is the operator version of the Item() method. - */ - wxString& operator[](size_t nIndex) const; -}; - - -/** - @class wxSortedArrayString - @wxheader{arrstr.h} - - wxSortedArrayString is an efficient container for storing wxString objects - which always keeps the string in alphabetical order. - - wxSortedArrayString uses binary search in its wxArrayString::Index() function - (instead of linear search for wxArrayString::Index()) which makes it much more - efficient if you add strings to the array rarely (because, of course, you have - to pay for Index() efficiency by having Add() be slower) but search for them - often. Several methods should not be used with sorted array (basically, all - those which break the order of items) which is mentioned in their description. - - @todo what about STL? who does it integrates? - - @library{wxbase} - @category{containers} - - @see wxArray, wxString, @ref overview_string -*/ -class wxSortedArrayString : public wxArrayString -{ -public: - - /** - Copy constructor. Note that when an array is assigned to a sorted array, - its contents is automatically sorted during construction. - */ - wxArrayString(const wxArrayString& array); - - /** - @copydoc wxArrayString::Add() - - @warning - For sorted arrays, the index of the inserted item will not be, in general, - equal to GetCount() - 1 because the item is inserted at the correct position - to keep the array sorted and not appended. - */ - size_t Add(const wxString& str, size_t copies = 1); - - - /** - @copydoc wxArrayString::Index() - - This function uses binary search for wxSortedArrayString, but it ignores - the @a bCase and @a bFromEnd parameters. - */ - int Index(const wxString& sz, bool bCase = true, - bool bFromEnd = false); - - /** - @warning this function should not be used with sorted arrays because it - could break the order of items and, for example, subsequent calls - to Index() would then not work! - */ - void Insert(const wxString& str, size_t nIndex, - size_t copies = 1); - - //@{ - /** - @warning this function should not be used with sorted array because it could - break the order of items and, for example, subsequent calls to Index() - would then not work! Also, sorting a wxSortedArrayString doesn't make - sense because its elements are always already sorted. - */ - void Sort(bool reverseOrder = false); - void Sort(CompareFunction compareFunction); - //@} -}; - - -// ============================================================================ -// Global functions/macros -// ============================================================================ - -/** @ingroup group_funcmacro_string */ -//@{ - -/** - Splits the given wxString object using the separator @a sep and returns the - result as a wxArrayString. - - If the @a escape character is non-@NULL, then the occurrences of @a sep - immediately prefixed with @a escape are not considered as separators. - Note that empty tokens will be generated if there are two or more adjacent - separators. - - @see wxJoin() - - @header{wx/arrstr.h} -*/ -wxArrayString wxSplit(const wxString& str, const wxChar sep, - const wxChar escape = '\\'); - -/** - Concatenate all lines of the given wxArrayString object using the separator - @a sep and returns the result as a wxString. - - If the @a escape character is non-@NULL, then it's used as prefix for each - occurrence of @a sep in the strings contained in @a arr before joining them - which is necessary in order to be able to recover the original array - contents from the string later using wxSplit(). - - @see wxSplit() - - @header{wx/arrstr.h} -*/ -wxString wxJoin(const wxArrayString& arr, const wxChar sep, - const wxChar escape = '\\'); - -//@} - diff --git a/interface/artprov.h b/interface/artprov.h deleted file mode 100644 index fc50474b81..0000000000 --- a/interface/artprov.h +++ /dev/null @@ -1,283 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: artprov.h -// Purpose: interface of wxArtProvider -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxArtProvider - @wxheader{artprov.h} - - wxArtProvider class is used to customize the look of wxWidgets application. - - When wxWidgets needs to display an icon or a bitmap (e.g. in the standard file - dialog), it does not use a hard-coded resource but asks wxArtProvider for it - instead. This way users can plug in their own wxArtProvider class and easily - replace standard art with their own version. - - All that is needed is to derive a class from wxArtProvider, override either its - wxArtProvider::CreateBitmap() and/or its wxArtProvider::CreateIconBundle() methods - and register the provider with wxArtProvider::Push(): - - @code - class MyProvider : public wxArtProvider - { - protected: - wxBitmap CreateBitmap(const wxArtID& id, - const wxArtClient& client, - const wxSize size) - - // optionally override this one as well - wxIconBundle CreateIconBundle(const wxArtID& id, - const wxArtClient& client) - { ... } - }; - ... - wxArtProvider::Push(new MyProvider); - @endcode - - If you need bitmap images (of the same artwork) that should be displayed at - different sizes you should probably consider overriding wxArtProvider::CreateIconBundle - and supplying icon bundles that contain different bitmap sizes. - - There's another way of taking advantage of this class: you can use it in your - code and use platform native icons as provided by wxArtProvider::GetBitmap or - wxArtProvider::GetIcon. - - @todo IS THIS NB TRUE? - (@note this is not yet really possible as of wxWidgets 2.3.3, the set of wxArtProvider - bitmaps is too small). - - @section wxartprovider_identify Identifying art resources - - Every bitmap and icon bundle are known to wxArtProvider under an unique ID that - is used when requesting a resource from it. The ID is represented by wxArtID type - and can have one of these predefined values (you can see bitmaps represented by these - constants in the @ref page_samples_artprovider): - - - -
- @li wxART_ERROR - @li wxART_QUESTION - @li wxART_WARNING - @li wxART_INFORMATION - @li wxART_ADD_BOOKMARK - @li wxART_DEL_BOOKMARK - @li wxART_HELP_SIDE_PANEL - @li wxART_HELP_SETTINGS - @li wxART_HELP_BOOK - @li wxART_HELP_FOLDER - @li wxART_HELP_PAGE - @li wxART_GO_BACK - @li wxART_GO_FORWARD - @li wxART_GO_UP - - @li wxART_GO_DOWN - @li wxART_GO_TO_PARENT - @li wxART_GO_HOME - @li wxART_PRINT - @li wxART_HELP - @li wxART_TIP - @li wxART_REPORT_VIEW - @li wxART_LIST_VIEW - @li wxART_NEW_DIR - @li wxART_FOLDER - @li wxART_FOLDER_OPEN - @li wxART_GO_DIR_UP - @li wxART_EXECUTABLE_FILE - @li wxART_NORMAL_FILE - @li wxART_TICK_MARK - @li wxART_CROSS_MARK - - @li wxART_MISSING_IMAGE - @li wxART_NEW - @li wxART_FILE_OPEN - @li wxART_FILE_SAVE - @li wxART_FILE_SAVE_AS - @li wxART_DELETE - @li wxART_COPY - @li wxART_CUT - @li wxART_PASTE - @li wxART_UNDO - @li wxART_REDO - @li wxART_QUIT - @li wxART_FIND - @li wxART_FIND_AND_REPLACE - @li wxART_HARDDISK - @li wxART_FLOPPY - @li wxART_CDROM - @li wxART_REMOVABLE -
- - Additionally, any string recognized by custom art providers registered using - wxArtProvider::Push may be used. - - @note - When running under GTK+ 2, GTK+ stock item IDs (e.g. @c "gtk-cdrom") may be used - as well. Additionally, if wxGTK was compiled against GTK+ >= 2.4, then it is also - possible to load icons from current icon theme by specifying their name (without - extension and directory components). - Icon themes recognized by GTK+ follow the freedesktop.org Icon Themes specification - (see http://freedesktop.org/Standards/icon-theme-spec). - Note that themes are not guaranteed to contain all icons, so wxArtProvider may - return ::wxNullBitmap or ::wxNullIcon. - The default theme is typically installed in @c /usr/share/icons/hicolor. - - - @section wxartprovider_clients Clients - - Client is the entity that calls wxArtProvider's GetBitmap or GetIcon function. - It is represented by wxClientID type and can have one of these values: - - @li wxART_TOOLBAR - @li wxART_MENU - @li wxART_BUTTON - @li wxART_FRAME_ICON - @li wxART_CMN_DIALOG - @li wxART_HELP_BROWSER - @li wxART_MESSAGE_BOX - @li wxART_OTHER (used for all requests that don't fit into any of the - categories above) - - Client ID servers as a hint to wxArtProvider that is supposed to help it to - choose the best looking bitmap. For example it is often desirable to use - slightly different icons in menus and toolbars even though they represent - the same action (e.g. wxART_FILE_OPEN). Remember that this is really only a - hint for wxArtProvider -- it is common that wxArtProvider::GetBitmap returns - identical bitmap for different client values! - - @library{wxcore} - @category{misc,data} - - @see the @ref page_samples_artprovider for an example of wxArtProvider usage. -*/ -class wxArtProvider : public wxObject -{ -public: - /** - The destructor automatically removes the provider from the provider stack used - by GetBitmap(). - */ - virtual ~wxArtProvider(); - - /** - Delete the given @a provider. - */ - static bool Delete(wxArtProvider* provider); - - /** - Query registered providers for bitmap with given ID. - - @param id - wxArtID unique identifier of the bitmap. - @param client - wxArtClient identifier of the client (i.e. who is asking for the bitmap). - @param size - Size of the returned bitmap or wxDefaultSize if size doesn't matter. - - @return The bitmap if one of registered providers recognizes the ID or - wxNullBitmap otherwise. - */ - static wxBitmap GetBitmap(const wxArtID& id, - const wxArtClient& client = wxART_OTHER, - const wxSize& size = wxDefaultSize); - - /** - Same as wxArtProvider::GetBitmap, but return a wxIcon object - (or ::wxNullIcon on failure). - */ - static wxIcon GetIcon(const wxArtID& id, - const wxArtClient& client = wxART_OTHER, - const wxSize& size = wxDefaultSize); - - /** - Returns a suitable size hint for the given @e wxArtClient. If - @a platform_default is @true, return a size based on the current platform, - otherwise return the size from the topmost wxArtProvider. @e wxDefaultSize may - be returned if the client doesn't have a specified size, like wxART_OTHER for - example. - */ - static wxSize GetSizeHint(const wxArtClient& client, - bool platform_default = false); - - /** - Query registered providers for icon bundle with given ID. - - @param id - wxArtID unique identifier of the icon bundle. - @param client - wxArtClient identifier of the client (i.e. who is asking for the icon - bundle). - - @return The icon bundle if one of registered providers recognizes the ID - or wxNullIconBundle otherwise. - */ - static wxIconBundle GetIconBundle(const wxArtID& id, - const wxArtClient& client = wxART_OTHER); - - /** - Register new art provider and add it to the bottom of providers stack - (i.e. it will be queried as the last one). - - @see Push() - */ - static void Insert(wxArtProvider* provider); - - /** - Remove latest added provider and delete it. - */ - static bool Pop(); - - /** - Register new art provider and add it to the top of providers stack - (i.e. it will be queried as the first provider). - - @see Insert() - */ - static void Push(wxArtProvider* provider); - - /** - Remove a provider from the stack if it is on it. The provider is not - deleted, unlike when using Delete(). - */ - static bool Remove(wxArtProvider* provider); - -protected: - - /** - Derived art provider classes must override this method to create requested art - resource. Note that returned bitmaps are cached by wxArtProvider and it is - therefore not necessary to optimize CreateBitmap() for speed (e.g. you may - create wxBitmap objects from XPMs here). - - @param id - wxArtID unique identifier of the bitmap. - @param client - wxArtClient identifier of the client (i.e. who is asking for the bitmap). - This only servers as a hint. - @param size - Preferred size of the bitmap. The function may return a bitmap of different - dimensions, it will be automatically rescaled to meet client's request. - - @note - This is not part of wxArtProvider's public API, use wxArtProvider::GetBitmap - or wxArtProvider::GetIconBundle or wxArtProvider::GetIcon to query wxArtProvider - for a resource. - - @see CreateIconBundle() - */ - virtual wxBitmap CreateBitmap(const wxArtID& id, - const wxArtClient& client, - const wxSize& size); - - /** - This method is similar to CreateBitmap() but can be used when a bitmap - (or an icon) exists in several sizes. - */ - virtual wxIconBundle CreateIconBundle(const wxArtID& id, - const wxArtClient& client); -}; - diff --git a/interface/atomic.h b/interface/atomic.h deleted file mode 100644 index 3767cd7f0b..0000000000 --- a/interface/atomic.h +++ /dev/null @@ -1,43 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: atomic.h -// Purpose: interface of global functions -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - - -// ============================================================================ -// Global functions/macros -// ============================================================================ - -/** @ingroup group_funcmacro_atomic */ -//@{ - -/** - This function increments @a value in an atomic manner. - - Whenever possible wxWidgets provides an efficient, CPU-specific, - implementation of this function. If such implementation is available, the - symbol wxHAS_ATOMIC_OPS is defined. Otherwise this function still exists - but is implemented in a generic way using a critical section which can be - prohibitively expensive for use in performance-sensitive code. - - @header{wx/atomic.h} -*/ -void wxAtomicInc(wxAtomicInt& value); - -/** - This function decrements value in an atomic manner. - - Returns 0 if value is 0 after decrement or any non-zero value (not - necessarily equal to the value of the variable) otherwise. - - @see wxAtomicInc - - @header{wx/atomic.h} -*/ -wxInt32 wxAtomicDec(wxAtomicInt& value); - -//@} - diff --git a/interface/aui/auibook.h b/interface/aui/auibook.h deleted file mode 100644 index b4d933eab3..0000000000 --- a/interface/aui/auibook.h +++ /dev/null @@ -1,325 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: aui/auibook.h -// Purpose: interface of wxAuiNotebook -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxAuiNotebook - @headerfile auibook.h wx/aui/auibook.h - - wxAuiNotebook is part of the wxAUI class framework. - See also @ref overview_aui. - - wxAuiNotebook is a notebook control which implements many features common in - applications with dockable panes. - Specifically, wxAuiNotebook implements functionality which allows the user to - rearrange tab order via drag-and-drop, split the tab window into many different - splitter configurations, and toggle through different themes to customize - the control's look and feel. - - An effort has been made to try to maintain an API as similar to that of - wxNotebook. - - The default theme that is used is wxAuiDefaultTabArt, which provides a modern, - glossy look and feel. - The theme can be changed by calling wxAuiNotebook::SetArtProvider. - - @beginStyleTable - @style{wxAUI_NB_DEFAULT_STYLE} - Defined as wxAUI_NB_TOP | wxAUI_NB_TAB_SPLIT | wxAUI_NB_TAB_MOVE | - wxAUI_NB_SCROLL_BUTTONS | wxAUI_NB_CLOSE_ON_ACTIVE_TAB. - @style{wxAUI_NB_TAB_SPLIT} - Allows the tab control to be split by dragging a tab. - @style{wxAUI_NB_TAB_MOVE} - Allows a tab to be moved horizontally by dragging. - @style{wxAUI_NB_TAB_EXTERNAL_MOVE} - Allows a tab to be moved to another tab control. - @style{wxAUI_NB_TAB_FIXED_WIDTH} - With this style, all tabs have the same width. - @style{wxAUI_NB_SCROLL_BUTTONS} - With this style, left and right scroll buttons are displayed. - @style{wxAUI_NB_WINDOWLIST_BUTTON} - With this style, a drop-down list of windows is available. - @style{wxAUI_NB_CLOSE_BUTTON} - With this style, a close button is available on the tab bar. - @style{wxAUI_NB_CLOSE_ON_ACTIVE_TAB} - With this style, the close button is visible on the active tab. - @style{wxAUI_NB_CLOSE_ON_ALL_TABS} - With this style, the close button is visible on all tabs. - @style{wxAUI_NB_TOP} - With this style, tabs are drawn along the top of the notebook. - @style{wxAUI_NB_BOTTOM} - With this style, tabs are drawn along the bottom of the notebook. - @endStyleTable - - @library{wxaui} - @category{aui} -*/ -class wxAuiNotebook : public wxControl -{ -public: - wxAuiNotebook(); - - /** - Constructor. Creates a wxAuiNotebok control. - */ - wxAuiNotebook(wxWindow* parent, wxWindowID id = wxID_ANY, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = wxAUI_NB_DEFAULT_STYLE); - - /** - Adds a page. - If the @a select parameter is @true, calling this will generate a page change event. - */ - bool AddPage(wxWindow* page, const wxString& caption, - bool select = false, - const wxBitmap& bitmap = wxNullBitmap); - - /** - Sets the selection to the next or previous page. - */ - void AdvanceSelection(bool forward = true); - - /** - Creates the notebook window. - */ - bool Create(wxWindow* parent, wxWindowID id = wxID_ANY, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = 0); - - /** - Deletes a page at the given index. - Calling this method will generate a page change event. - */ - bool DeletePage(size_t page); - - /** - Returns the associated art provider. - */ - wxAuiTabArt* GetArtProvider() const; - - /** - Returns the desired height of the notebook for the given page height. - Use this to fit the notebook to a given page size. - */ - int GetHeightForPageHeight(int pageHeight); - - /** - Returns the page specified by the given index. - */ - wxWindow* GetPage(size_t page_idx) const; - - /** - Returns the tab bitmap for the page. - */ - wxBitmap GetPageBitmap(size_t page) const; - - /** - Returns the number of pages in the notebook. - */ - size_t GetPageCount() const; - - /** - Returns the page index for the specified window. - If the window is not found in the notebook, wxNOT_FOUND is returned. - */ - int GetPageIndex(wxWindow* page_wnd) const; - - /** - Returns the tab label for the page. - */ - wxString GetPageText(size_t page) const; - - /** - Returns the currently selected page. - */ - int GetSelection() const; - - /** - Returns the height of the tab control. - */ - int GetTabCtrlHeight() const; - - /** - InsertPage() is similar to AddPage, but allows the ability to specify the - insert location. - If the @a select parameter is @true, calling this will generate a page change - event. - */ - bool InsertPage(size_t page_idx, wxWindow* page, - const wxString& caption, - bool select = false, - const wxBitmap& bitmap = wxNullBitmap); - - /** - Removes a page, without deleting the window pointer. - */ - bool RemovePage(size_t page); - - /** - Sets the art provider to be used by the notebook. - */ - void SetArtProvider(wxAuiTabArt* art); - - /** - Sets the font for drawing the tab labels, using a bold version of the font for - selected tab labels. - */ - virtual bool SetFont(const wxFont& font); - - /** - Sets the font for measuring tab labels. - */ - void SetMeasuringFont(const wxFont& font); - - /** - Sets the font for drawing unselected tab labels. - */ - void SetNormalFont(const wxFont& font); - - /** - Sets the bitmap for the page. To remove a bitmap from the tab caption, pass - wxNullBitmap. - */ - bool SetPageBitmap(size_t page, const wxBitmap& bitmap); - - /** - Sets the tab label for the page. - */ - bool SetPageText(size_t page, const wxString& text); - - /** - Sets the font for drawing selected tab labels. - */ - void SetSelectedFont(const wxFont& font); - - /** - Sets the page selection. Calling this method will generate a page change event. - */ - size_t SetSelection(size_t new_page); - - /** - Sets the tab height. By default, the tab control height is calculated - by measuring the text height and bitmap sizes on the tab captions. Calling this - method will override that calculation and set the tab control to the specified - height parameter. A call to this method will override any call to - SetUniformBitmapSize(). - - Specifying -1 as the height will return the control to its default auto-sizing - behaviour. - */ - virtual void SetTabCtrlHeight(int height); - - //@{ - /** - Split performs a split operation programmatically. The argument @a page - indicates the page that will be split off. This page will also become the - active page after the split. - - The @a direction argument specifies where the pane should go, it should be one - of the following: wxTOP, wxBOTTOM, wxLEFT, or wxRIGHT. - */ - void SetUniformBitmapSize(const wxSize& size); - void Split(size_t page, int direction); - //@} - - /** - Shows the window menu for the active tab control associated with this notebook, - and returns @true if a selection was made. - */ - bool ShowWindowMenu(); -}; - - - -/** - @class wxAuiTabArt - @headerfile auibook.h wx/aui/auibook.h - - Tab art class. - - @todo BETTER DESCRIPTION NEEDED - - @library{wxaui} - @category{aui} -*/ -class wxAuiTabArt -{ -public: - /** - Constructor. - */ - wxAuiTabArt(); - - /** - Clones the art object. - */ - virtual wxAuiTabArt* Clone() = 0; - - /** - Draws a background on the given area. - */ - virtual void DrawBackground(wxDC& dc, wxWindow* wnd, const wxRect& rect) = 0; - - /** - Draws a button. - */ - virtual void DrawButton(wxDC& dc, wxWindow* wnd, const wxRect& in_rect, - int bitmap_id, int button_state, int orientation, - wxRect* out_rect) = 0; - - /** - Draws a tab. - */ - virtual void DrawTab(wxDC& dc, wxWindow* wnd, const wxAuiNotebookPage& page, - const wxRect& rect, int close_button_state, - wxRect* out_tab_rect, wxRect* out_button_rect, int* x_extent) = 0; - - /** - Returns the tab control size. - */ - virtual int GetBestTabCtrlSize(wxWindow*, const wxAuiNotebookPageArray&, const wxSize&) = 0; - - /** - Returns the indent size. - */ - virtual int GetIndentSize() = 0; - - /** - Returns the tab size for the given caption, bitmap and state. - */ - virtual wxSize GetTabSize(wxDC& dc, wxWindow* wnd, const wxString& caption, - const wxBitmap& bitmap, bool active, - int close_button_state, int* x_extent) = 0; - - /** - Sets flags. - */ - virtual void SetFlags(unsigned int flags) = 0; - - /** - Sets the font used for calculating measurements. - */ - virtual void SetMeasuringFont(const wxFont& font) = 0; - - /** - Sets the normal font for drawing labels. - */ - virtual void SetNormalFont(const wxFont& font) = 0; - - /** - Sets the font for drawing text for selected UI elements. - */ - virtual void SetSelectedFont(const wxFont& font) = 0; - - /** - Sets sizing information. - */ - virtual void SetSizingInfo(const wxSize& tab_ctrl_size, size_t tab_count) = 0; -}; - diff --git a/interface/aui/dockart.h b/interface/aui/dockart.h deleted file mode 100644 index 34ae018422..0000000000 --- a/interface/aui/dockart.h +++ /dev/null @@ -1,180 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: aui/dockart.h -// Purpose: interface of wxAuiDockArt -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - - -/** - @todo TOWRITE -*/ -enum wxAuiPaneDockArtSetting -{ - wxAUI_DOCKART_SASH_SIZE = 0, - wxAUI_DOCKART_CAPTION_SIZE = 1, - wxAUI_DOCKART_GRIPPER_SIZE = 2, - wxAUI_DOCKART_PANE_BORDER_SIZE = 3, - wxAUI_DOCKART_PANE_BUTTON_SIZE = 4, - wxAUI_DOCKART_BACKGROUND_COLOUR = 5, - wxAUI_DOCKART_SASH_COLOUR = 6, - wxAUI_DOCKART_ACTIVE_CAPTION_COLOUR = 7, - wxAUI_DOCKART_ACTIVE_CAPTION_GRADIENT_COLOUR = 8, - wxAUI_DOCKART_INACTIVE_CAPTION_COLOUR = 9, - wxAUI_DOCKART_INACTIVE_CAPTION_GRADIENT_COLOUR = 10, - wxAUI_DOCKART_ACTIVE_CAPTION_TEXT_COLOUR = 11, - wxAUI_DOCKART_INACTIVE_CAPTION_TEXT_COLOUR = 12, - wxAUI_DOCKART_BORDER_COLOUR = 13, - wxAUI_DOCKART_GRIPPER_COLOUR = 14, - wxAUI_DOCKART_CAPTION_FONT = 15, - wxAUI_DOCKART_GRADIENT_TYPE = 16 -}; - -/** - @todo TOWRITE -*/ -enum wxAuiPaneDockArtGradients -{ - wxAUI_GRADIENT_NONE = 0, - wxAUI_GRADIENT_VERTICAL = 1, - wxAUI_GRADIENT_HORIZONTAL = 2 -}; - -/** - @todo TOWRITE -*/ -enum wxAuiPaneButtonState -{ - wxAUI_BUTTON_STATE_NORMAL = 0, - wxAUI_BUTTON_STATE_HOVER = 1, - wxAUI_BUTTON_STATE_PRESSED = 2 -}; - -/** - @todo TOWRITE -*/ -enum wxAuiButtonId -{ - wxAUI_BUTTON_CLOSE = 101, - wxAUI_BUTTON_MAXIMIZE_RESTORE = 102, - wxAUI_BUTTON_MINIMIZE = 103, - wxAUI_BUTTON_PIN = 104, - wxAUI_BUTTON_OPTIONS = 105, - wxAUI_BUTTON_WINDOWLIST = 106, - wxAUI_BUTTON_LEFT = 107, - wxAUI_BUTTON_RIGHT = 108, - wxAUI_BUTTON_UP = 109, - wxAUI_BUTTON_DOWN = 110, - wxAUI_BUTTON_CUSTOM1 = 201, - wxAUI_BUTTON_CUSTOM2 = 202, - wxAUI_BUTTON_CUSTOM3 = 203 -}; - -/** - @class wxAuiDockArt - @headerfile dockart.h wx/aui/dockart.h - - wxAuiDockArt is part of the wxAUI class framework. - See also @ref overview_aui. - - wxAuiDockArt is the art provider: provides all drawing functionality to the - wxAui dock manager. This allows the dock manager to have a plugable look-and-feel. - - By default, a wxAuiManager uses an instance of this class called - wxAuiDefaultDockArt which provides bitmap art and a colour scheme that is - adapted to the major platforms' look. You can either derive from that class - to alter its behaviour or write a completely new dock art class. - Call wxAuiManager::SetArtProvider to force wxAUI to use your new dock art provider. - - @library{wxaui} - @category{aui} - - @see wxAuiManager, wxAuiPaneInfo -*/ -class wxAuiDockArt -{ -public: - /** - Constructor. - */ - wxAuiDockArt(); - - /** - Destructor. - */ - virtual ~wxAuiDockArt(); - - /** - Draws a background. - */ - virtual void DrawBackground(wxDC& dc, wxWindow* window, int orientation, - const wxRect& rect) = 0; - - /** - Draws a border. - */ - virtual void DrawBorder(wxDC& dc, wxWindow* window, const wxRect& rect, - wxAuiPaneInfo& pane) = 0; - - /** - Draws a caption. - */ - virtual void DrawCaption(wxDC& dc, wxWindow* window, const wxString& text, - const wxRect& rect, wxAuiPaneInfo& pane) = 0; - - /** - Draws a gripper. - */ - virtual void DrawGripper(wxDC& dc, wxWindow* window, const wxRect& rect, - wxAuiPaneInfo& pane) = 0; - - /** - Draws a button in the pane's title bar. - @a button can be one of the values of @b wxAuiButtonId. - @a button_state can be one of the values of @b wxAuiPaneButtonState. - */ - virtual void DrawPaneButton(wxDC& dc, wxWindow* window, int button, - int button_state, const wxRect& rect, - wxAuiPaneInfo& pane) = 0; - - /** - Draws a sash between two windows. - */ - virtual void DrawSash(wxDC& dc, wxWindow* window, int orientation, - const wxRect& rect) = 0; - /** - Get the colour of a certain setting. - @a id can be one of the colour values of @b wxAuiPaneDockArtSetting. - */ - virtual wxColour GetColour(int id) = 0; - - /** - Get a font setting. - */ - virtual wxFont GetFont(int id) = 0; - - /** - Get the value of a certain setting. - @a id can be one of the size values of @b wxAuiPaneDockArtSetting. - */ - virtual int GetMetric(int id) = 0; - - /** - Set a certain setting with the value @e colour. - @a id can be one of the colour values of @b wxAuiPaneDockArtSetting. - */ - virtual void SetColour(int id, const wxColour& colour) = 0; - - /** - Set a font setting. - */ - virtual void SetFont(int id, const wxFont& font) = 0; - - /** - Set a certain setting with the value @e new_val. - @a id can be one of the size values of @b wxAuiPaneDockArtSetting. - */ - virtual void SetMetric(int id, int new_val) = 0; -}; - diff --git a/interface/aui/framemanager.h b/interface/aui/framemanager.h deleted file mode 100644 index b95708e143..0000000000 --- a/interface/aui/framemanager.h +++ /dev/null @@ -1,771 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: aui/aui.h -// Purpose: interface of wxAuiManager -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - - -/** - @todo TOWRITE -*/ -enum wxAuiManagerDock -{ - wxAUI_DOCK_NONE = 0, - wxAUI_DOCK_TOP = 1, - wxAUI_DOCK_RIGHT = 2, - wxAUI_DOCK_BOTTOM = 3, - wxAUI_DOCK_LEFT = 4, - wxAUI_DOCK_CENTER = 5, - wxAUI_DOCK_CENTRE = wxAUI_DOCK_CENTER -}; - - -/** - @todo TOWRITE -*/ -enum wxAuiManagerOption -{ - wxAUI_MGR_ALLOW_FLOATING = 1 << 0, - wxAUI_MGR_ALLOW_ACTIVE_PANE = 1 << 1, - wxAUI_MGR_TRANSPARENT_DRAG = 1 << 2, - wxAUI_MGR_TRANSPARENT_HINT = 1 << 3, - wxAUI_MGR_VENETIAN_BLINDS_HINT = 1 << 4, - wxAUI_MGR_RECTANGLE_HINT = 1 << 5, - wxAUI_MGR_HINT_FADE = 1 << 6, - wxAUI_MGR_NO_VENETIAN_BLINDS_FADE = 1 << 7, - - wxAUI_MGR_DEFAULT = wxAUI_MGR_ALLOW_FLOATING | - wxAUI_MGR_TRANSPARENT_HINT | - wxAUI_MGR_HINT_FADE | - wxAUI_MGR_NO_VENETIAN_BLINDS_FADE -}; - -/** - @class wxAuiManager - @headerfile aui.h wx/aui/aui.h - - wxAuiManager is the central class of the wxAUI class framework. - See also @ref overview_aui. - - wxAuiManager manages the panes associated with it for a particular wxFrame, - using a pane's wxAuiPaneInfo information to determine each pane's docking - and floating behavior. - - wxAuiManager uses wxWidgets' sizer mechanism to plan the layout of each frame. - It uses a replaceable dock art class to do all drawing, so all drawing is - localized in one area, and may be customized depending on an application's - specific needs. - - wxAuiManager works as follows: the programmer adds panes to the class, - or makes changes to existing pane properties (dock position, floating - state, show state, etc.). To apply these changes, wxAuiManager's - Update() function is called. This batch processing can be used to avoid - flicker, by modifying more than one pane at a time, and then "committing" - all of the changes at once by calling Update(). - - Panes can be added quite easily: - - @code - wxTextCtrl* text1 = new wxTextCtrl(this, -1); - wxTextCtrl* text2 = new wxTextCtrl(this, -1); - m_mgr.AddPane(text1, wxLEFT, wxT("Pane Caption")); - m_mgr.AddPane(text2, wxBOTTOM, wxT("Pane Caption")); - m_mgr.Update(); - @endcode - - Later on, the positions can be modified easily. The following will float - an existing pane in a tool window: - - @code - m_mgr.GetPane(text1).Float(); - @endcode - - - @section wxauimanager_layers Layers, Rows and Directions, Positions - - Inside wxAUI, the docking layout is figured out by checking several pane - parameters. Four of these are important for determining where a pane will end up: - - @li Direction: Each docked pane has a direction, Top, Bottom, Left, Right, or Center. - This is fairly self-explanatory. The pane will be placed in the location specified - by this variable. - @li Position: More than one pane can be placed inside of a dock. Imagine two panes - being docked on the left side of a window. One pane can be placed over another. - In proportionally managed docks, the pane position indicates its sequential position, - starting with zero. So, in our scenario with two panes docked on the left side, - the top pane in the dock would have position 0, and the second one would occupy - position 1. - @li Row: A row can allow for two docks to be placed next to each other. One of the - most common places for this to happen is in the toolbar. Multiple toolbar rows - are allowed, the first row being row 0, and the second row 1. Rows can also be - used on vertically docked panes. - @li Layer: A layer is akin to an onion. Layer 0 is the very center of the managed pane. - Thus, if a pane is in layer 0, it will be closest to the center window (also - sometimes known as the "content window"). Increasing layers "swallow up" all - layers of a lower value. This can look very similar to multiple rows, but is - different because all panes in a lower level yield to panes in higher levels. - The best way to understand layers is by running the wxAUI sample. - - - @library{wxbase} - @category{aui} - - @see wxAuiPaneInfo, wxAuiDockArt -*/ -class wxAuiManager : public wxEvtHandler -{ -public: - /** - Constructor. @a managed_wnd specifies the wxFrame which should be managed. - @a flags specifies options which allow the frame management behavior - to be modified. - */ - wxAuiManager(wxWindow* managed_wnd = NULL, - unsigned int flags = wxAUI_MGR_DEFAULT); - - /** - Dtor. - */ - virtual ~wxAuiManager(); - - //@{ - /** - AddPane() tells the frame manager to start managing a child window. - There are several versions of this function. The first version allows - the full spectrum of pane parameter possibilities. The second version is - used for simpler user interfaces which do not require as much configuration. - The last version allows a drop position to be specified, which will determine - where the pane will be added. - */ - bool AddPane(wxWindow* window, const wxAuiPaneInfo& pane_info); - bool AddPane(wxWindow* window, int direction = wxLEFT, - const wxString& caption = wxEmptyString); - bool AddPane(wxWindow* window, - const wxAuiPaneInfo& pane_info, - const wxPoint& drop_pos); - //@} - - /** - Tells the wxAuiManager to stop managing the pane specified by window. - The window, if in a floated frame, is reparented to the frame managed - by wxAuiManager. - */ - bool DetachPane(wxWindow* window); - - /** - Returns an array of all panes managed by the frame manager. - */ - wxAuiPaneInfoArray& GetAllPanes(); - - /** - Returns the current art provider being used. - @see wxAuiDockArt. - */ - wxAuiDockArt* GetArtProvider() const; - - /** - Returns the current dock constraint values. - See SetDockSizeConstraint() for more information. - */ - void GetDockSizeConstraint(double* widthpct, double* heightpct) const; - - /** - Returns the current manager's flags. - */ - unsigned int GetFlags() const; - - /** - Returns the frame currently being managed by wxAuiManager. - */ - wxWindow* GetManagedWindow() const; - - /** - Calling this method will return the wxAuiManager for a given window. - The @a window parameter should specify any child window or sub-child - window of the frame or window managed by wxAuiManager. - - The @a window parameter need not be managed by the manager itself, nor does it - even need to be a child or sub-child of a managed window. It must however - be inside the window hierarchy underneath the managed window. - */ - static wxAuiManager* GetManager(wxWindow* window); - - //@{ - /** - GetPane() is used to lookup a wxAuiPaneInfo object either by window pointer - or by pane name, which acts as a unique id for a window pane. - - The returned wxAuiPaneInfo object may then be modified to change a pane's - look, state or position. After one or more modifications to wxAuiPaneInfo, - wxAuiManager::Update() should be called to commit the changes to the user - interface. If the lookup failed (meaning the pane could not be found in the - manager), a call to the returned wxAuiPaneInfo's IsOk() method will return @false. - */ - wxAuiPaneInfo GetPane(wxWindow* window); - wxAuiPaneInfo GetPane(const wxString& name); - //@} - - /** - HideHint() hides any docking hint that may be visible. - */ - virtual void HideHint(); - - /** - This method is used to insert either a previously unmanaged pane window - into the frame manager, or to insert a currently managed pane somewhere - else. InsertPane() will push all panes, rows, or docks aside and - insert the window into the position specified by @a insert_location. - - Because @a insert_location can specify either a pane, dock row, or dock - layer, the @a insert_level parameter is used to disambiguate this. - The parameter @a insert_level can take a value of wxAUI_INSERT_PANE, - wxAUI_INSERT_ROW or wxAUI_INSERT_DOCK. - */ - bool InsertPane(wxWindow* window, - const wxAuiPaneInfo& insert_location, - int insert_level = wxAUI_INSERT_PANE); - - /** - LoadPaneInfo() is similar to to LoadPerspective, with the exception that it - only loads information about a single pane. It is used in combination with - SavePaneInfo(). - */ - void LoadPaneInfo(wxString pane_part, wxAuiPaneInfo& pane); - - /** - Loads a saved perspective. If update is @true, wxAuiManager::Update() - is automatically invoked, thus realizing the saved perspective on screen. - */ - bool LoadPerspective(const wxString& perspective, - bool update = true); - - /** - SavePaneInfo() is similar to SavePerspective, with the exception that it only - saves information about a single pane. It is used in combination with - LoadPaneInfo(). - */ - wxString SavePaneInfo(wxAuiPaneInfo& pane); - - /** - Saves the entire user interface layout into an encoded wxString, which - can then be stored by the application (probably using wxConfig). - - When a perspective is restored using LoadPerspective(), the entire user - interface will return to the state it was when the perspective was saved. - */ - wxString SavePerspective(); - - /** - Instructs wxAuiManager to use art provider specified by parameter - @a art_provider for all drawing calls. - This allows plugable look-and-feel features. The previous art provider object, - if any, will be deleted by wxAuiManager. - - @see wxAuiDockArt. - */ - void SetArtProvider(wxAuiDockArt* art_provider); - - /** - When a user creates a new dock by dragging a window into a docked position, - often times the large size of the window will create a dock that is unwieldly - large. wxAuiManager by default limits the size of any new dock to 1/3 of the - window size. For horizontal docks, this would be 1/3 of the window height. - For vertical docks, 1/3 of the width. - - Calling this function will adjust this constraint value. The numbers must be - between 0.0 and 1.0. For instance, calling SetDockSizeContraint with - 0.5, 0.5 will cause new docks to be limited to half of the size of the - entire managed window. - */ - void SetDockSizeConstraint(double widthpct, double heightpct); - - /** - This method is used to specify wxAuiManager's settings flags. @a flags - specifies options which allow the frame management behavior to be modified. - */ - void SetFlags(unsigned int flags); - - /** - Called to specify the frame or window which is to be managed by wxAuiManager. - Frame management is not restricted to just frames. Child windows or custom - controls are also allowed. - */ - void SetManagedWindow(wxWindow* managed_wnd); - - /** - This function is used by controls to explicitly show a hint window at the - specified rectangle. It is rarely called, and is mostly used by controls - implementing custom pane drag/drop behaviour. - The specified rectangle should be in screen coordinates. - */ - virtual void ShowHint(const wxRect& rect); - - /** - Uninitializes the framework and should be called before a managed frame or - window is destroyed. UnInit() is usually called in the managed wxFrame's - destructor. It is necessary to call this function before the managed frame - or window is destroyed, otherwise the manager cannot remove its custom event - handlers from a window. - */ - void UnInit(); - - /** - This method is called after any number of changes are - made to any of the managed panes. Update() must be invoked after - AddPane() or InsertPane() are called in order to "realize" or "commit" - the changes. In addition, any number of changes may be made to - wxAuiPaneInfo structures (retrieved with wxAuiManager::GetPane), but to - realize the changes, Update() must be called. This construction allows - pane flicker to be avoided by updating the whole layout at one time. - */ - void Update(); - -protected: - - /** - ProcessDockResult() is a protected member of the wxAUI layout manager. - It can be overridden by derived classes to provide custom docking calculations. - */ - virtual bool ProcessDockResult(wxAuiPaneInfo& target, - const wxAuiPaneInfo& new_pos); -}; - - - -/** - @class wxAuiPaneInfo - @headerfile aui.h wx/aui/aui.h - - wxAuiPaneInfo is part of the wxAUI class framework. - See also @ref overview_aui. - - wxAuiPaneInfo specifies all the parameters for a pane. - These parameters specify where the pane is on the screen, whether it is docked - or floating, or hidden. - In addition, these parameters specify the pane's docked position, floating - position, preferred size, minimum size, caption text among many other parameters. - - @library{wxbase} - @category{aui} - - @see wxAuiManager, wxAuiDockArt -*/ -class wxAuiPaneInfo -{ -public: - wxAuiPaneInfo(); - - /** - Copy constructor. - */ - wxAuiPaneInfo(const wxAuiPaneInfo& c); - - //@{ - /** - BestSize() sets the ideal size for the pane. The docking manager will attempt - to use this size as much as possible when docking or floating the pane. - */ - wxAuiPaneInfo BestSize(const wxSize& size); - wxAuiPaneInfo BestSize(int x, int y); - //@} - - /** - Bottom() sets the pane dock position to the bottom side of the frame. This is - the same thing as calling Direction(wxAUI_DOCK_BOTTOM). - */ - wxAuiPaneInfo& Bottom(); - - /** - BottomDockable() indicates whether a pane can be docked at the bottom of the - frame. - */ - wxAuiPaneInfo& BottomDockable(bool b = true); - - /** - Caption() sets the caption of the pane. - */ - wxAuiPaneInfo& Caption(const wxString& c); - - /** - CaptionVisible indicates that a pane caption should be visible. If @false, no - pane caption is drawn. - */ - wxAuiPaneInfo& CaptionVisible(bool visible = true); - - //@{ - /** - Center() sets the pane dock position to the left side of the frame. - The centre pane is the space in the middle after all border panes (left, top, - right, bottom) are subtracted from the layout. - This is the same thing as calling Direction(wxAUI_DOCK_CENTRE). - */ - wxAuiPaneInfo Centre(); - wxAuiPaneInfo Center(); - //@} - - //@{ - /** - CentrePane() specifies that the pane should adopt the default center pane - settings. Centre panes usually do not have caption bars. - This function provides an easy way of preparing a pane to be displayed in - the center dock position. - */ - wxAuiPaneInfo CentrePane(); - wxAuiPaneInfo CenterPane(); - //@} - - /** - CloseButton() indicates that a close button should be drawn for the pane. - */ - wxAuiPaneInfo& CloseButton(bool visible = true); - - /** - DefaultPane() specifies that the pane should adopt the default pane settings. - */ - wxAuiPaneInfo& DefaultPane(); - - /** - DestroyOnClose() indicates whether a pane should be detroyed when it is closed. - Normally a pane is simply hidden when the close button is clicked. - Setting DestroyOnClose to @true will cause the window to be destroyed when - the user clicks the pane's close button. - */ - wxAuiPaneInfo& DestroyOnClose(bool b = true); - - /** - Direction() determines the direction of the docked pane. It is functionally the - same as calling Left(), Right(), Top() or Bottom(), except that docking direction - may be specified programmatically via the parameter. - */ - wxAuiPaneInfo& Direction(int direction); - - /** - Dock() indicates that a pane should be docked. It is the opposite of Float(). - */ - wxAuiPaneInfo& Dock(); - - /** - DockFixed() causes the containing dock to have no resize sash. This is useful - for creating panes that span the entire width or height of a dock, but should - not be resizable in the other direction. - */ - wxAuiPaneInfo& DockFixed(bool b = true); - - /** - Dockable() specifies whether a frame can be docked or not. It is the same as - specifying TopDockable(b).BottomDockable(b).LeftDockable(b).RightDockable(b). - */ - wxAuiPaneInfo& Dockable(bool b = true); - - /** - Fixed() forces a pane to be fixed size so that it cannot be resized. After - calling Fixed(), IsFixed() will return @true. - */ - wxAuiPaneInfo& Fixed(); - - /** - Float() indicates that a pane should be floated. It is the opposite of Dock(). - */ - wxAuiPaneInfo& Float(); - - /** - Floatable() sets whether the user will be able to undock a pane and turn it - into a floating window. - */ - wxAuiPaneInfo& Floatable(bool b = true); - - //@{ - /** - FloatingPosition() sets the position of the floating pane. - */ - wxAuiPaneInfo FloatingPosition(const wxPoint& pos); - wxAuiPaneInfo FloatingPosition(int x, int y); - //@} - - //@{ - /** - FloatingSize() sets the size of the floating pane. - */ - wxAuiPaneInfo FloatingSize(const wxSize& size); - wxAuiPaneInfo FloatingSize(int x, int y); - //@} - - /** - Gripper() indicates that a gripper should be drawn for the pane. - */ - wxAuiPaneInfo& Gripper(bool visible = true); - - /** - GripperTop() indicates that a gripper should be drawn at the top of the pane. - */ - wxAuiPaneInfo& GripperTop(bool attop = true); - - /** - HasBorder() returns @true if the pane displays a border. - */ - bool HasBorder() const; - - /** - HasCaption() returns @true if the pane displays a caption. - */ - bool HasCaption() const; - - /** - HasCloseButton() returns @true if the pane displays a button to close the pane. - */ - bool HasCloseButton() const; - - /** - HasFlag() returns @true if the the property specified by flag is active for the - pane. - */ - bool HasFlag(unsigned int flag) const; - - /** - HasGripper() returns @true if the pane displays a gripper. - */ - bool HasGripper() const; - - /** - HasGripper() returns @true if the pane displays a gripper at the top. - */ - bool HasGripperTop() const; - - /** - HasMaximizeButton() returns @true if the pane displays a button to maximize the - pane. - */ - bool HasMaximizeButton() const; - - /** - HasMinimizeButton() returns @true if the pane displays a button to minimize the - pane. - */ - bool HasMinimizeButton() const; - - /** - HasPinButton() returns @true if the pane displays a button to float the pane. - */ - bool HasPinButton() const; - - /** - Hide() indicates that a pane should be hidden. - */ - wxAuiPaneInfo& Hide(); - - /** - IsBottomDockable() returns @true if the pane can be docked at the bottom of the - managed frame. - */ - bool IsBottomDockable() const; - - /** - IsDocked() returns @true if the pane is docked. - */ - bool IsDocked() const; - - /** - IsFixed() returns @true if the pane cannot be resized. - */ - bool IsFixed() const; - - /** - IsFloatable() returns @true if the pane can be undocked and displayed as a - floating window. - */ - bool IsFloatable() const; - - /** - IsFloating() returns @true if the pane is floating. - */ - bool IsFloating() const; - - /** - IsLeftDockable() returns @true if the pane can be docked on the left of the - managed frame. - */ - bool IsLeftDockable() const; - - /** - IsMoveable() returns @true if the docked frame can be undocked or moved to - another dock position. - */ - bool IsMovable() const; - - /** - IsOk() returns @true if the wxAuiPaneInfo structure is valid. A pane structure - is valid if it has an associated window. - */ - bool IsOk() const; - - /** - IsResizable() returns @true if the pane can be resized. - */ - bool IsResizable() const; - - /** - IsRightDockable() returns @true if the pane can be docked on the right of the - managed frame. - */ - bool IsRightDockable() const; - - /** - IsShown() returns @true if the pane is currently shown. - */ - bool IsShown() const; - - /** - IsToolbar() returns @true if the pane contains a toolbar. - */ - bool IsToolbar() const; - - /** - IsTopDockable() returns @true if the pane can be docked at the top of the - managed frame. - */ - bool IsTopDockable() const; - - /** - Layer() determines the layer of the docked pane. The dock layer is similar to - an onion, the inner-most layer being layer 0. Each shell moving in the outward - direction has a higher layer number. This allows for more complex docking layout - formation. - */ - wxAuiPaneInfo& Layer(int layer); - - /** - Left() sets the pane dock position to the left side of the frame. This is the - same thing as calling Direction(wxAUI_DOCK_LEFT). - */ - wxAuiPaneInfo& Left(); - - /** - LeftDockable() indicates whether a pane can be docked on the left of the frame. - */ - wxAuiPaneInfo& LeftDockable(bool b = true); - - //@{ - /** - MaxSize() sets the maximum size of the pane. - */ - wxAuiPaneInfo MaxSize(const wxSize& size); - wxAuiPaneInfo MaxSize(int x, int y); - //@} - - /** - MaximizeButton() indicates that a maximize button should be drawn for the pane. - */ - wxAuiPaneInfo& MaximizeButton(bool visible = true); - - //@{ - /** - MinSize() sets the minimum size of the pane. Please note that this is only - partially supported as of this writing. - */ - wxAuiPaneInfo MinSize(const wxSize& size); - wxAuiPaneInfo MinSize(int x, int y); - //@} - - /** - MinimizeButton() indicates that a minimize button should be drawn for the pane. - */ - wxAuiPaneInfo& MinimizeButton(bool visible = true); - - /** - Movable indicates whether a frame can be moved. - */ - wxAuiPaneInfo& Movable(bool b = true); - - /** - Name() sets the name of the pane so it can be referenced in lookup functions. - If a name is not specified by the user, a random name is assigned to the pane - when it is added to the manager. - */ - wxAuiPaneInfo& Name(const wxString& n); - - /** - PaneBorder indicates that a border should be drawn for the pane. - */ - wxAuiPaneInfo& PaneBorder(bool visible = true); - - /** - PinButton() indicates that a pin button should be drawn for the pane. - */ - wxAuiPaneInfo& PinButton(bool visible = true); - - /** - Position() determines the position of the docked pane. - */ - wxAuiPaneInfo& Position(int pos); - - /** - Resizable() allows a pane to be resized if the parameter is @true, and forces it - to be a fixed size if the parameter is @false. This is simply an antonym for Fixed(). - */ - wxAuiPaneInfo& Resizable(bool resizable = true); - - /** - Right() sets the pane dock position to the right side of the frame. - */ - wxAuiPaneInfo& Right(); - - /** - RightDockable() indicates whether a pane can be docked on the right of the - frame. - */ - wxAuiPaneInfo& RightDockable(bool b = true); - - /** - Row() determines the row of the docked pane. - */ - wxAuiPaneInfo& Row(int row); - - /** - Write the safe parts of a newly loaded PaneInfo structure "source" into "this" - used on loading perspectives etc. - */ - void SafeSet(wxAuiPaneInfo source); - - /** - SetFlag() turns the property given by flag on or off with the option_state - parameter. - */ - wxAuiPaneInfo& SetFlag(unsigned int flag, bool option_state); - - /** - Show() indicates that a pane should be shown. - */ - wxAuiPaneInfo& Show(bool show = true); - - /** - ToolbarPane() specifies that the pane should adopt the default toolbar pane - settings. - */ - wxAuiPaneInfo& ToolbarPane(); - - /** - Top() sets the pane dock position to the top of the frame. - */ - wxAuiPaneInfo& Top(); - - /** - TopDockable() indicates whether a pane can be docked at the top of the frame. - */ - wxAuiPaneInfo& TopDockable(bool b = true); - - /** - Window() assigns the window pointer that the wxAuiPaneInfo should use. - This normally does not need to be specified, as the window pointer is - automatically assigned to the wxAuiPaneInfo structure as soon as it is added - to the manager. - */ - wxAuiPaneInfo& Window(wxWindow* w); - - /** - Makes a copy of the wxAuiPaneInfo object. - */ - wxAuiPaneInfo& operator=(const wxAuiPaneInfo& c); -}; - diff --git a/interface/base64.h b/interface/base64.h deleted file mode 100644 index 3967d697b9..0000000000 --- a/interface/base64.h +++ /dev/null @@ -1,166 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: base64.h -// Purpose: interface of global functions -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - - -// ============================================================================ -// Global functions/macros -// ============================================================================ - -/** @ingroup group_funcmacro_misc */ -//@{ - -/** - This function encodes the given data using base64. - - To allocate the buffer of the correct size, use wxBase64EncodedSize() or - call this function with @a dst set to @NULL -- it will then return the - necessary buffer size. - - This raw encoding function overload writes the output string into the - provided buffer; the other overloads return it as a wxString. - - @param dst - The output buffer, may be @NULL to retrieve the needed buffer size. - @param dstLen - The output buffer size, ignored if dst is @NULL. - @param src - The input buffer, must not be @NULL. - @param srcLen - The length of the input data. - - @return @c wxCONV_FAILED if the output buffer is too small. - - @header{wx/base64.h} -*/ -size_t wxBase64Encode(char* dst, size_t dstLen, - const void* src, - size_t srcLen); - -/** - This function encodes the given data using base64 and returns the output as - a wxString. - - There is no error return. - - To allocate the buffer of the correct size, use wxBase64EncodedSize() or - call this function with @a dst set to @NULL -- it will then return the - necessary buffer size. - - @param src - The input buffer, must not be @NULL. - @param srcLen - The length of the input data. - - @header{wx/base64.h} -*/ -wxString wxBase64Encode(const void* src, size_t srcLen); - -/** - This function encodes the given data using base64 and returns the output as - a wxString. - - There is no error return. - - @header{wx/base64.h} -*/ -wxString wxBase64Encode(const wxMemoryBuffer& buf); - - -/** - Returns the size of the buffer necessary to contain the data encoded in a - base64 string of length @e srcLen. This can be useful for allocating a - buffer to be passed to wxBase64Decode(). - - @header{wx/base64.h} -*/ -size_t wxBase64DecodedSize(size_t srcLen); - -/** - Returns the length of the string with base64 representation of a buffer of - specified size @e len. This can be useful for allocating the buffer passed - to wxBase64Encode(). - - @header{wx/base64.h} -*/ -size_t wxBase64EncodedSize(size_t len); - -/** - This function decodes a Base64-encoded string. - - This overload is a raw decoding function and decodes the data into the - provided buffer @a dst of the given size @e dstLen. An error is returned if - the buffer is not large enough -- that is not at least - wxBase64DecodedSize(srcLen) bytes. - - This overload returns the number of bytes written to the buffer or the - necessary buffer size if @a dst was @NULL or @c wxCONV_FAILED on error, - e.g. if the output buffer is too small or invalid characters were - encountered in the input string. - - @param dst - Pointer to output buffer, may be @NULL to just compute the necessary - buffer size. - @param dstLen - The size of the output buffer, ignored if dst is @NULL. - @param src - The input string, must not be @NULL. For the version using wxString, - the input string should contain only ASCII characters. - @param srcLen - The length of the input string or special value wxNO_LEN if the string - is @NULL-terminated and the length should be computed by this function - itself. - @param mode - This parameter specifies the function behaviour when invalid characters - are encountered in input. By default, any such character stops the - decoding with error. If the mode is wxBase64DecodeMode_SkipWS, then the - white space characters are silently skipped instead. And if it is - wxBase64DecodeMode_Relaxed, then all invalid characters are skipped. - @param posErr - If this pointer is non-@NULL and an error occurs during decoding, it is - filled with the index of the invalid character. - - @header{wx/base64.h} -*/ -size_t wxBase64Decode(void* dst, size_t dstLen, - const char* src, - size_t srcLen = wxNO_LEN, - wxBase64DecodeMode mode = wxBase64DecodeMode_Strict, - size_t posErr = NULL); - -/** - See the wxBase64Decode(void*,size_t,const char*,size_t,wxBase64DecodeMode,size_t) - overload for more info about the parameters of this function. - - This overload allocates memory internally and returns it as wxMemoryBuffer - and is recommended for normal use. - - This overload returns a buffer with the base64 decoded binary equivalent - of the input string. In neither case is the buffer @NULL-terminated. - - @header{wx/base64.h} -*/ -wxMemoryBuffer wxBase64Decode(const char* src, - size_t srcLen = wxNO_LEN, - wxBase64DecodeMode mode = wxBase64DecodeMode_Strict, - size_t posErr = NULL); - -/** - See the wxBase64Decode(void*,size_t,const char*,size_t,wxBase64DecodeMode,size_t) - overload for more info about the parameters of this function. - - This overload takes as input a wxString and returns the internally-allocated - memory as a wxMemoryBuffer, containing the base64 decoded data. - - @header{wx/base64.h} -*/ -wxMemoryBuffer wxBase64Decode(const wxString& src, - wxBase64DecodeMode mode = wxBase64DecodeMode_Strict, - size_t posErr = NULL); - -//@} - diff --git a/interface/bitmap.h b/interface/bitmap.h deleted file mode 100644 index 1bcf959e19..0000000000 --- a/interface/bitmap.h +++ /dev/null @@ -1,687 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: bitmap.h -// Purpose: interface of wxBitmap* classes -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - - -/** - In wxBitmap and wxBitmapHandler context this value means: "use the screen depth". -*/ -#define wxBITMAP_SCREEN_DEPTH (-1) - -/** - @class wxBitmapHandler - @wxheader{bitmap.h} - - This is the base class for implementing bitmap file loading/saving, and - bitmap creation from data. - It is used within wxBitmap and is not normally seen by the application. - - If you wish to extend the capabilities of wxBitmap, derive a class from - wxBitmapHandler and add the handler using wxBitmap::AddHandler() in your - application initialisation. - - @library{wxcore} - @category{misc} - - @see @ref overview_bitmap, wxBitmap, wxIcon, wxCursor -*/ -class wxBitmapHandler : public wxObject -{ -public: - /** - Default constructor. - - In your own default constructor, initialise the members m_name, - m_extension and m_type. - */ - wxBitmapHandler(); - - /** - Destroys the wxBitmapHandler object. - */ - virtual ~wxBitmapHandler(); - - /** - Creates a bitmap from the given data, which can be of arbitrary type. - The wxBitmap object @a bitmap is manipulated by this function. - - @param bitmap - The wxBitmap object. - @param width - The width of the bitmap in pixels. - @param height - The height of the bitmap in pixels. - @param depth - The depth of the bitmap in pixels. - If this is ::wxBITMAP_SCREEN_DEPTH, the screen depth is used. - @param data - Data whose type depends on the value of type. - @param type - A bitmap type identifier - see ::wxBitmapType for a list - of possible values. - - @return @true if the call succeeded, @false otherwise (the default). - */ - virtual bool Create(wxBitmap* bitmap, const void* data, wxBitmapType type, - int width, int height, int depth = 1); - - /** - Gets the file extension associated with this handler. - */ - const wxString& GetExtension() const; - - /** - Gets the name of this handler. - */ - const wxString& GetName() const; - - /** - Gets the bitmap type associated with this handler. - */ - wxBitmapType GetType() const; - - /** - Loads a bitmap from a file or resource, putting the resulting data into - @a bitmap. - - @param bitmap - The bitmap object which is to be affected by this operation. - @param name - Either a filename or a Windows resource name. - The meaning of name is determined by the type parameter. - @param type - See ::wxBitmapType for values this can take. - @param desiredWidth - The desired width for the loaded bitmap. - @param desiredHeight - The desired height for the loaded bitmap. - - @return @true if the operation succeeded, @false otherwise. - - @see wxBitmap::LoadFile, wxBitmap::SaveFile, SaveFile() - */ - virtual bool LoadFile(wxBitmap* bitmap, const wxString& name, wxBitmapType type, - int desiredWidth, int desiredHeight); - - /** - Saves a bitmap in the named file. - - @param bitmap - The bitmap object which is to be affected by this operation. - @param name - A filename. The meaning of name is determined by the type parameter. - @param type - See ::wxBitmapType for values this can take. - @param palette - An optional palette used for saving the bitmap. - - @return @true if the operation succeeded, @false otherwise. - - @see wxBitmap::LoadFile, wxBitmap::SaveFile, LoadFile() - */ - virtual bool SaveFile(const wxBitmap* bitmap, const wxString& name, wxBitmapType type, - const wxPalette* palette = NULL) const; - - /** - Sets the handler extension. - - @param extension - Handler extension. - */ - void SetExtension(const wxString& extension); - - /** - Sets the handler name. - - @param name - Handler name. - */ - void SetName(const wxString& name); - - /** - Sets the handler type. - - @param type - Handler type. - */ - void SetType(wxBitmapType type); -}; - - -/** - @class wxBitmap - @wxheader{bitmap.h} - - This class encapsulates the concept of a platform-dependent bitmap, - either monochrome or colour or colour with alpha channel support. - - If you need direct access the bitmap data instead going through - drawing to it using wxMemoryDC you need to use the wxPixelData - class (either wxNativePixelData for RGB bitmaps or wxAlphaPixelData - for bitmaps with an additionaly alpha channel). - - @note - Many wxBitmap functions take a @e type parameter, which is a value of the - ::wxBitmapType enumeration. - The validity of those values depends however on the platform where your program - is running and from the wxWidgets configuration. - If all possible wxWidgets settings are used, the Windows platform supports BMP file, - BMP resource, XPM data, and XPM. - Under wxGTK, the available formats are BMP file, XPM data, XPM file, and PNG file. - Under wxMotif, the available formats are XBM data, XBM file, XPM data, XPM file. - In addition, wxBitmap can load and save all formats that wxImage; see wxImage for - more info. Of course, you must have wxImage handlers loaded. - - @library{wxcore} - @category{gdi} - - @stdobjects - ::wxNullBitmap - - @see @ref overview_bitmap, @ref overview_bitmap_supportedformats, - wxDC::Blit, wxIcon, wxCursor, wxMemoryDC, wxImage, wxPixelData -*/ -class wxBitmap : public wxGDIObject -{ -public: - /** - Default constructor. - - Constructs a bitmap object with no data; an assignment or another member - function such as Create() or LoadFile() must be called subsequently. - */ - wxBitmap(); - - /** - Copy constructor, uses @ref overview_refcount "reference counting". - To make a real copy, you can use: - - @code - wxBitmap newBitmap = oldBitmap.GetSubBitmap( - wxRect(0, 0, oldBitmap.GetWidth(), oldBitmap.GetHeight())); - @endcode - */ - wxBitmap(const wxBitmap& bitmap); - - - /* - Creates a bitmap from the given @a data which is interpreted in - platform-dependent manner. - - @param data - Specifies the bitmap data in a platform-dependent format. - @param type - May be one of the ::wxBitmapType values and indicates which type of - bitmap does @a data contains. See the note in the class - detailed description. - @param width - Specifies the width of the bitmap. - @param height - Specifies the height of the bitmap. - @param depth - Specifies the depth of the bitmap. - If this is omitted, the display depth of the screen is used. - wxBitmap(const void* data, int type, int width, int height, int depth = -1); - - - NOTE: this ctor is not implemented by all ports, is somewhat useless - without further description of the "data" supported formats and - uses 'int type' instead of wxBitmapType, so don't document it. - */ - - /** - Creates a bitmap from the given array @a bits. - You should only use this function for monochrome bitmaps (depth 1) in - portable programs: in this case the bits parameter should contain an XBM image. - - For other bit depths, the behaviour is platform dependent: under Windows, - the data is passed without any changes to the underlying CreateBitmap() API. - Under other platforms, only monochrome bitmaps may be created using this - constructor and wxImage should be used for creating colour bitmaps from - static data. - - @param bits - Specifies an array of pixel values. - @param width - Specifies the width of the bitmap. - @param height - Specifies the height of the bitmap. - @param depth - Specifies the depth of the bitmap. - If this is omitted, then a value of 1 (monochrome bitmap) is used. - */ - wxBitmap(const char bits[], int width, int height, int depth = 1); - - /** - Creates a new bitmap. A depth of ::wxBITMAP_SCREEN_DEPTH indicates the - depth of the current screen or visual. - - Some platforms only support 1 for monochrome and ::wxBITMAP_SCREEN_DEPTH for - the current colour setting. - - A depth of 32 including an alpha channel is supported under MSW, Mac and GTK+. - */ - wxBitmap(int width, int height, int depth = wxBITMAP_SCREEN_DEPTH); - - /** - Creates a bitmap from XPM data. - */ - wxBitmap(const char* const* bits); - - /** - Loads a bitmap from a file or resource. - - @param name - This can refer to a resource name or a filename under MS Windows and X. - Its meaning is determined by the @a type parameter. - @param type - May be one of the ::wxBitmapType values and indicates which type of - bitmap should be loaded. See the note in the class detailed description. - - @see LoadFile() - */ - wxBitmap(const wxString& name, wxBitmapType type = wxBITMAP_TYPE_XPM); - - /** - Creates this bitmap object from the given image. - This has to be done to actually display an image as you cannot draw an - image directly on a window. - - The resulting bitmap will use the provided colour depth (or that of the - current system if depth is ::wxBITMAP_SCREEN_DEPTH) which entails that a - colour reduction may take place. - - When in 8-bit mode (PseudoColour mode), the GTK port will use a color cube - created on program start-up to look up colors. This ensures a very fast conversion, - but the image quality won't be perfect (and could be better for photo images using - more sophisticated dithering algorithms). - - On Windows, if there is a palette present (set with SetPalette), it will be - used when creating the wxBitmap (most useful in 8-bit display mode). - On other platforms, the palette is currently ignored. - - @param img - Platform-independent wxImage object. - @param depth - Specifies the depth of the bitmap. - If this is omitted, the display depth of the screen is used. - */ - wxBitmap(const wxImage& img, int depth = wxBITMAP_SCREEN_DEPTH); - - /** - Destructor. - See @ref overview_refcount_destruct for more info. - - If the application omits to delete the bitmap explicitly, the bitmap will be - destroyed automatically by wxWidgets when the application exits. - - @warning - Do not delete a bitmap that is selected into a memory device context. - */ - virtual ~wxBitmap(); - - /** - Adds a handler to the end of the static list of format handlers. - - @param handler - A new bitmap format handler object. There is usually only one instance - of a given handler class in an application session. - - @see wxBitmapHandler - */ - static void AddHandler(wxBitmapHandler* handler); - - /** - Deletes all bitmap handlers. - This function is called by wxWidgets on exit. - */ - static void CleanUpHandlers(); - - /** - Creates an image from a platform-dependent bitmap. This preserves - mask information so that bitmaps and images can be converted back - and forth without loss in that respect. - */ - virtual wxImage ConvertToImage() const; - - /** - Creates the bitmap from an icon. - */ - virtual bool CopyFromIcon(const wxIcon& icon); - - /** - Creates a fresh bitmap. - If the final argument is omitted, the display depth of the screen is used. - - This overload works on all platforms. - */ - virtual bool Create(int width, int height, int depth = wxBITMAP_SCREEN_DEPTH); - - /* - Creates a bitmap from the given data, which can be of arbitrary type. - - @param data - Data whose type depends on the value of type. - @param type - A bitmap type identifier; see ::wxBitmapType for the list of values. - See the note in the class detailed description for more info. - @param width - The width of the bitmap in pixels. - @param height - The height of the bitmap in pixels. - @param depth - The depth of the bitmap in pixels. If this is -1, the screen depth is used. - - @return @true if the call succeeded, @false otherwise. - - This overload depends on the @a type of data. - - virtual bool Create(const void* data, int type, int width, - int height, int depth = -1); - - NOTE: leave this undoc for the same reason of the relative ctor. - */ - - /** - Finds the handler with the given @a name. - - @return A pointer to the handler if found, @NULL otherwise. - */ - static wxBitmapHandler* FindHandler(const wxString& name); - - /** - Finds the handler associated with the given @a extension and @a type. - - @param extension - The file extension, such as "bmp" (without the dot). - @param bitmapType - The bitmap type managed by the handler, see ::wxBitmapType. - - @return A pointer to the handler if found, @NULL otherwise. - */ - static wxBitmapHandler* FindHandler(const wxString& extension, - wxBitmapType bitmapType); - - /** - Finds the handler associated with the given bitmap type. - - @param bitmapType - The bitmap type managed by the handler, see ::wxBitmapType. - - @return A pointer to the handler if found, @NULL otherwise. - - @see wxBitmapHandler - */ - - static wxBitmapHandler* FindHandler(wxBitmapType bitmapType); - - /** - Gets the colour depth of the bitmap. - A value of 1 indicates a monochrome bitmap. - */ - virtual int GetDepth() const; - - /** - Returns the static list of bitmap format handlers. - - @see wxBitmapHandler - */ - static wxList GetHandlers(); - - /** - Gets the height of the bitmap in pixels. - */ - virtual int GetHeight() const; - - /** - Gets the associated mask (if any) which may have been loaded from a file - or set for the bitmap. - - @see SetMask(), wxMask - */ - virtual wxMask* GetMask() const; - - /** - Gets the associated palette (if any) which may have been loaded from a file - or set for the bitmap. - - @see wxPalette - */ - virtual wxPalette* GetPalette() const; - - /** - Returns a sub bitmap of the current one as long as the rect belongs entirely to - the bitmap. This function preserves bit depth and mask information. - */ - virtual wxBitmap GetSubBitmap(const wxRect& rect) const; - - /** - Gets the width of the bitmap in pixels. - - @see GetHeight() - */ - virtual int GetWidth() const; - - /** - Adds the standard bitmap format handlers, which, depending on wxWidgets - configuration, can be handlers for Windows bitmap, Windows bitmap resource, - and XPM. - - This function is called by wxWidgets on startup. - - @see wxBitmapHandler - */ - static void InitStandardHandlers(); - - /** - Adds a handler at the start of the static list of format handlers. - - @param handler - A new bitmap format handler object. There is usually only one instance - of a given handler class in an application session. - - @see wxBitmapHandler - */ - static void InsertHandler(wxBitmapHandler* handler); - - /** - Returns @true if bitmap data is present. - */ - bool IsOk() const; - - /** - Loads a bitmap from a file or resource. - - @param name - Either a filename or a Windows resource name. - The meaning of name is determined by the @a type parameter. - @param type - One of the ::wxBitmapType values; see the note in the class - detailed description. - - @return @true if the operation succeeded, @false otherwise. - - @remarks A palette may be associated with the bitmap if one exists - (especially for colour Windows bitmaps), and if the - code supports it. You can check if one has been created - by using the GetPalette() member. - - @see SaveFile() - */ - virtual bool LoadFile(const wxString& name, wxBitmapType type); - - /** - Finds the handler with the given name, and removes it. - The handler is not deleted. - - @param name - The handler name. - - @return @true if the handler was found and removed, @false otherwise. - - @see wxBitmapHandler - */ - static bool RemoveHandler(const wxString& name); - - /** - Saves a bitmap in the named file. - - @param name - A filename. The meaning of name is determined by the type parameter. - @param type - One of the ::wxBitmapType values; see the note in the class - detailed description. - @param palette - An optional palette used for saving the bitmap. - - @return @true if the operation succeeded, @false otherwise. - - @remarks Depending on how wxWidgets has been configured, not all formats - may be available. - - @see LoadFile() - */ - virtual bool SaveFile(const wxString& name, wxBitmapType type, - const wxPalette* palette = NULL) const; - - /** - Sets the depth member (does not affect the bitmap data). - - @todo since these functions do not affect the bitmap data, - why they exist?? - - @param depth - Bitmap depth. - */ - virtual void SetDepth(int depth); - - /** - Sets the height member (does not affect the bitmap data). - - @param height - Bitmap height in pixels. - */ - virtual void SetHeight(int height); - - /** - Sets the mask for this bitmap. - - @remarks The bitmap object owns the mask once this has been called. - - @see GetMask(), wxMask - */ - virtual void SetMask(wxMask* mask); - - /** - Sets the associated palette. (Not implemented under GTK+). - - @param palette - The palette to set. - - @see wxPalette - */ - virtual void SetPalette(const wxPalette& palette); - - /** - Sets the width member (does not affect the bitmap data). - - @param width - Bitmap width in pixels. - */ - virtual void SetWidth(int width); -}; - -/** - An empty wxBitmap object. -*/ -wxBitmap wxNullBitmap; - - - - -/** - @class wxMask - @wxheader{bitmap.h} - - This class encapsulates a monochrome mask bitmap, where the masked area is - black and the unmasked area is white. - - When associated with a bitmap and drawn in a device context, the unmasked - area of the bitmap will be drawn, and the masked area will not be drawn. - - @library{wxcore} - @category{gdi} - - @see wxBitmap, wxDC::Blit, wxMemoryDC -*/ -class wxMask : public wxObject -{ -public: - - /** - Default constructor. - */ - wxMask(); - - /** - Constructs a mask from a bitmap and a palette index that indicates the - background. - Not yet implemented for GTK. - - @param bitmap - A valid bitmap. - @param index - Index into a palette, specifying the transparency colour. - */ - wxMask(const wxBitmap& bitmap, int index); - - /** - Constructs a mask from a monochrome bitmap. - - @beginWxPythonOnly - This is the default constructor for wxMask in wxPython. - @endWxPythonOnly - */ - wxMask(const wxBitmap& bitmap); - - /** - Constructs a mask from a bitmap and a colour that indicates the background. - - @beginWxPythonOnly - wxPython has an alternate wxMask constructor matching this form called wxMaskColour. - @endWxPythonOnly - */ - wxMask(const wxBitmap& bitmap, const wxColour& colour); - - /** - Destroys the wxMask object and the underlying bitmap data. - */ - virtual ~wxMask(); - - /** - Constructs a mask from a bitmap and a palette index that indicates the - background. - Not yet implemented for GTK. - - @param bitmap - A valid bitmap. - @param index - Index into a palette, specifying the transparency colour. - */ - bool Create(const wxBitmap& bitmap, int index); - - /** - Constructs a mask from a monochrome bitmap. - */ - bool Create(const wxBitmap& bitmap); - - /** - Constructs a mask from a bitmap and a colour that indicates the background. - */ - bool Create(const wxBitmap& bitmap, const wxColour& colour); -}; - diff --git a/interface/bmpbuttn.h b/interface/bmpbuttn.h deleted file mode 100644 index 89dcca9677..0000000000 --- a/interface/bmpbuttn.h +++ /dev/null @@ -1,239 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: bmpbuttn.h -// Purpose: interface of wxBitmapButton -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxBitmapButton - @wxheader{bmpbuttn.h} - - A bitmap button is a control that contains a bitmap. - It may be placed on a wxDialog or a wxPanel, or indeed almost any other window. - - @remarks - A bitmap button can be supplied with a single bitmap, and wxWidgets will draw - all button states using this bitmap. If the application needs more control, - additional bitmaps for the selected state, unpressed focused state, and greyed-out - state may be supplied. - - @section wxbitmapbutton_states Button states - This class supports bitmaps for several different states: - - @li @b normal: this is the bitmap shown in the default state, it must be always - valid while all the other bitmaps are optional and don't have to be set. - @li @b disabled: bitmap shown when the button is disabled. - @li @b selected: bitmap shown when the button is pushed (e.g. while the user - keeps the mouse button pressed on it) - @li @b focus: bitmap shown when the button has keyboard focus but is not pressed. - @li @b hover: bitmap shown when the mouse is over the button (but it is not pressed). - Notice that if hover bitmap is not specified but the current platform UI uses - hover images for the buttons (such as Windows XP or GTK+), then the focus bitmap - is used for hover state as well. This makes it possible to set focus bitmap only - to get reasonably good behaviour on all platforms. - - @beginStyleTable - @style{wxBU_AUTODRAW} - If this is specified, the button will be drawn automatically using - the label bitmap only, providing a 3D-look border. If this style is - not specified, the button will be drawn without borders and using - all provided bitmaps. Has effect only under MS Windows. - @style{wxBU_LEFT} - Left-justifies the bitmap label. Has effect only under MS Windows. - @style{wxBU_TOP} - Aligns the bitmap label to the top of the button. - Has effect only under MS Windows. - @style{wxBU_RIGHT} - Right-justifies the bitmap label. Has effect only under MS Windows. - @style{wxBU_BOTTOM} - Aligns the bitmap label to the bottom of the button. - Has effect only under MS Windows. - @endStyleTable - - Note that the wxBU_EXACTFIT style supported by wxButton is not used by this - class as bitmap buttons don't have any minimal standard size by default. - - @beginEventTable{wxCommandEvent} - @event{EVT_BUTTON(id, func)} - Process a wxEVT_COMMAND_BUTTON_CLICKED event, when the button is clicked. - @endEventTable - - @library{wxcore} - @category{ctrl} - - - @see wxButton -*/ -class wxBitmapButton : public wxButton -{ -public: - /** - Default ctor. - */ - wxBitmapButton(); - - /** - Constructor, creating and showing a button. - - @param parent - Parent window. Must not be @NULL. - @param id - Button identifier. The value wxID_ANY indicates a default value. - @param bitmap - Bitmap to be displayed. - @param pos - Button position. - @param size - Button size. If wxDefaultSize is specified then the button is sized - appropriately for the bitmap. - @param style - Window style. See wxBitmapButton. - @param validator - Window validator. - @param name - Window name. - - @remarks The bitmap parameter is normally the only bitmap you need to provide, - and wxWidgets will draw the button correctly in its different states. - If you want more control, call any of the functions SetBitmapSelected(), - SetBitmapFocus(), SetBitmapDisabled(). - - @see Create(), wxValidator - */ - wxBitmapButton(wxWindow* parent, wxWindowID id, - const wxBitmap& bitmap, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = wxBU_AUTODRAW, - const wxValidator& validator = wxDefaultValidator, - const wxString& name = wxButtonNameStr); - - /** - Destructor, destroying the button. - */ - virtual ~wxBitmapButton(); - - /** - Button creation function for two-step creation. - For more details, see wxBitmapButton(). - */ - bool Create(wxWindow* parent, wxWindowID id, - const wxBitmap& bitmap, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = wxBU_AUTODRAW, - const wxValidator& validator = wxDefaultValidator, - const wxString& name = wxButtonNameStr); - - //@{ - /** - Returns the bitmap for the disabled state, which may be invalid. - - @return A reference to the disabled state bitmap. - - @see SetBitmapDisabled() - */ - const wxBitmap& GetBitmapDisabled() const; - wxBitmap& GetBitmapDisabled(); - //@} - - //@{ - /** - Returns the bitmap for the focused state, which may be invalid. - - @return A reference to the focused state bitmap. - - @see SetBitmapFocus() - */ - const wxBitmap& GetBitmapFocus() const; - wxBitmap& GetBitmapFocus(); - //@} - - //@{ - /** - Returns the bitmap used when the mouse is over the button, which may be invalid. - - @see SetBitmapHover() - */ - const wxBitmap& GetBitmapHover(); - wxBitmap& GetBitmapHover(); - //@} - - //@{ - /** - Returns the label bitmap (the one passed to the constructor), always valid. - - @return A reference to the button's label bitmap. - - @see SetBitmapLabel() - */ - const wxBitmap& GetBitmapLabel(); - wxBitmap& GetBitmapLabel(); - //@} - - /** - Returns the bitmap for the selected state. - - @return A reference to the selected state bitmap. - - @see SetBitmapSelected() - */ - const wxBitmap& GetBitmapSelected() const; - - /** - Sets the bitmap for the disabled button appearance. - - @param bitmap - The bitmap to set. - - @see GetBitmapDisabled(), SetBitmapLabel(), - SetBitmapSelected(), SetBitmapFocus() - */ - virtual void SetBitmapDisabled(const wxBitmap& bitmap); - - /** - Sets the bitmap for the button appearance when it has the keyboard focus. - - @param bitmap - The bitmap to set. - - @see GetBitmapFocus(), SetBitmapLabel(), - SetBitmapSelected(), SetBitmapDisabled() - */ - virtual void SetBitmapFocus(const wxBitmap& bitmap); - - /** - Sets the bitmap to be shown when the mouse is over the button. - - @since 2.7.0 - - The hover bitmap is currently only supported in wxMSW. - - @see GetBitmapHover() - */ - virtual void SetBitmapHover(const wxBitmap& bitmap); - - /** - Sets the bitmap label for the button. - - @param bitmap - The bitmap label to set. - - @remarks This is the bitmap used for the unselected state, and for all - other states if no other bitmaps are provided. - - @see GetBitmapLabel() - */ - virtual void SetBitmapLabel(const wxBitmap& bitmap); - - /** - Sets the bitmap for the selected (depressed) button appearance. - - @param bitmap - The bitmap to set. - */ - virtual void SetBitmapSelected(const wxBitmap& bitmap); -}; - diff --git a/interface/bmpcbox.h b/interface/bmpcbox.h deleted file mode 100644 index 3e7b6d87e1..0000000000 --- a/interface/bmpcbox.h +++ /dev/null @@ -1,203 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: bmpcbox.h -// Purpose: interface of wxBitmapComboBox -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxBitmapComboBox - @wxheader{bmpcbox.h} - - A combobox that displays bitmap in front of the list items. - It currently only allows using bitmaps of one size, and resizes itself - so that a bitmap can be shown next to the text field. - - @remarks - While wxBitmapComboBox contains the wxComboBox API, but it might not actually - be derived from that class. In fact, if the platform does not have a native - implementation, wxBitmapComboBox will inherit from wxOwnerDrawnComboBox. - You can determine if the implementation is generic by checking whether - @c wxGENERIC_BITMAPCOMBOBOX is defined. Currently wxBitmapComboBox is - implemented natively for MSW and GTK+. - - @beginStyleTable - @style{wxCB_READONLY} - Creates a combobox without a text editor. On some platforms the - control may appear very different when this style is used. - @style{wxCB_SORT} - Sorts the entries in the list alphabetically. - @style{wxTE_PROCESS_ENTER} - The control will generate the event wxEVT_COMMAND_TEXT_ENTER - (otherwise pressing Enter key is either processed internally by the - control or used for navigation between dialog controls). - Windows only. - @endStyleTable - - @todo create wxCB_PROCESS_ENTER rather than reusing wxTE_PROCESS_ENTER! - - @beginEventTable{wxCommandEvent} - @event{EVT_COMBOBOX(id, func)} - Process a wxEVT_COMMAND_COMBOBOX_SELECTED event, when an item on - the list is selected. - @event{EVT_TEXT(id, func)} - Process a wxEVT_COMMAND_TEXT_UPDATED event, when the combobox text changes. - @event{EVT_TEXT_ENTER(id, func)} - Process a wxEVT_COMMAND_TEXT_ENTER event, when RETURN is pressed in - the combobox. - @endEventTable - - @library{wxadv} - @category{ctrl} - - - @see wxComboBox, wxChoice, wxOwnerDrawnComboBox, wxCommandEvent -*/ -class wxBitmapComboBox : public wxComboBox -{ -public: - /** - Default ctor. - */ - wxBitmapComboBox(); - - /** - Constructor, creating and showing a combobox. - - @param parent - Parent window. Must not be @NULL. - @param id - Window identifier. The value wxID_ANY indicates a default value. - @param value - Initial selection string. An empty string indicates no selection. - @param n - Number of strings with which to initialise the control. - @param choices - An array of strings with which to initialise the control. - - @see Create(), wxValidator - */ - wxBitmapComboBox(wxWindow* parent, wxWindowID id, - const wxString& value = "", - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - int n = 0, - const wxString choices[] = NULL, - long style = 0, - const wxValidator& validator = wxDefaultValidator, - const wxString& name = "comboBox"); - - /** - Constructor, creating and showing a combobox. - - @param parent - Parent window. Must not be @NULL. - @param id - Window identifier. The value wxID_ANY indicates a default value. - @param value - Initial selection string. An empty string indicates no selection. - @param choices - An wxArrayString with which to initialise the control. - - @see Create(), wxValidator - */ - wxBitmapComboBox(wxWindow* parent, wxWindowID id, - const wxString& value, - const wxPoint& pos, - const wxSize& size, - const wxArrayString& choices, - long style = 0, - const wxValidator& validator = wxDefaultValidator, - const wxString& name = "comboBox"); - - /** - Destructor, destroying the combobox. - */ - virtual ~wxBitmapComboBox(); - - /** - Adds the item to the end of the combo box. - */ - int Append(const wxString& item, - const wxBitmap& bitmap = wxNullBitmap); - - /** - Adds the item to the end of the combo box, associating the given - untyped, client data pointer @a clientData with the item. - */ - int Append(const wxString& item, const wxBitmap& bitmap, - void* clientData); - - /** - Adds the item to the end of the combo box, associating the given typed - client data pointer @a clientData with the item. - */ - int Append(const wxString& item, const wxBitmap& bitmap, - wxClientData* clientData); - - /** - Creates the combobox for two-step construction. - */ - bool Create(wxWindow* parent, wxWindowID id, - const wxString& value = "", - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - int n, const wxString choices[], - long style = 0, - const wxValidator& validator = wxDefaultValidator, - const wxString& name = "comboBox"); - - /** - Creates the combobox for two-step construction. - */ - bool Create(wxWindow* parent, wxWindowID id, - const wxString& value, - const wxPoint& pos, - const wxSize& size, - const wxArrayString& choices, - long style = 0, - const wxValidator& validator = wxDefaultValidator, - const wxString& name = "comboBox"); - - /** - Returns size of bitmaps used in the list. - */ - virtual wxSize GetBitmapSize() const; - - /** - Returns the bitmap of the item with the given index. - */ - virtual wxBitmap GetItemBitmap(unsigned int n) const; - - /** - Inserts the item into the list before @a pos. - Not valid for @c wxCB_SORT style, use Append() instead. - */ - int Insert(const wxString& item, const wxBitmap& bitmap, - unsigned int pos); - - /** - Inserts the item into the list before pos, associating the given - untyped, client data pointer with the item. - Not valid for @c wxCB_SORT style, use Append() instead. - */ - int Insert(const wxString& item, const wxBitmap& bitmap, - unsigned int pos, - void* clientData); - - /** - Inserts the item into the list before pos, associating the given typed - client data pointer with the item. - Not valid for @c wxCB_SORT style, use Append() instead. - */ - int Insert(const wxString& item, const wxBitmap& bitmap, - unsigned int pos, - wxClientData* clientData); - - /** - Sets the bitmap for the given item. - */ - virtual void SetItemBitmap(unsigned int n, const wxBitmap& bitmap); -}; - diff --git a/interface/bookctrl.h b/interface/bookctrl.h deleted file mode 100644 index c4d68d7bdf..0000000000 --- a/interface/bookctrl.h +++ /dev/null @@ -1,25 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: bookctrl.h -// Purpose: interface of wxBookCtrlBase -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxBookCtrlBase - @wxheader{bookctrl.h} - - @todo Document this class. - - @library{wxcore} - @category{miscwnd} - - @see @ref overview_bookctrl -*/ -class wxBookCtrlBase : public wxControl -{ -public: - -}; - diff --git a/interface/brush.h b/interface/brush.h deleted file mode 100644 index f98b98525f..0000000000 --- a/interface/brush.h +++ /dev/null @@ -1,308 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: brush.h -// Purpose: interface of wxBrush -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - The possible brush styles. -*/ -enum wxBrushStyle -{ - wxBRUSHSTYLE_INVALID = -1, - - wxBRUSHSTYLE_SOLID = wxSOLID, - /**< Solid. */ - - wxBRUSHSTYLE_TRANSPARENT = wxTRANSPARENT, - /**< Transparent (no fill). */ - - wxBRUSHSTYLE_STIPPLE_MASK_OPAQUE = wxSTIPPLE_MASK_OPAQUE, - /**< @todo WHAT's THIS?? */ - - wxBRUSHSTYLE_STIPPLE_MASK = wxSTIPPLE_MASK, - /**< @todo WHAT's THIS?? */ - - wxBRUSHSTYLE_STIPPLE = wxSTIPPLE, - /**< Uses a bitmap as a stipple. */ - - wxBRUSHSTYLE_BDIAGONAL_HATCH = wxBDIAGONAL_HATCH, - /**< Backward diagonal hatch. */ - - wxBRUSHSTYLE_CROSSDIAG_HATCH = wxCROSSDIAG_HATCH, - /**< Cross-diagonal hatch. */ - - wxBRUSHSTYLE_FDIAGONAL_HATCH = wxFDIAGONAL_HATCH, - /**< Forward diagonal hatch. */ - - wxBRUSHSTYLE_CROSS_HATCH = wxCROSS_HATCH, - /**< Cross hatch. */ - - wxBRUSHSTYLE_HORIZONTAL_HATCH = wxHORIZONTAL_HATCH, - /**< Horizontal hatch. */ - - wxBRUSHSTYLE_VERTICAL_HATCH = wxVERTICAL_HATCH, - /**< Vertical hatch. */ - - wxBRUSHSTYLE_FIRST_HATCH = wxFIRST_HATCH, - wxBRUSHSTYLE_LAST_HATCH = wxLAST_HATCH, -}; - - - -/** - @class wxBrush - @wxheader{brush.h} - - A brush is a drawing tool for filling in areas. It is used for painting - the background of rectangles, ellipses, etc. It has a colour and a style. - - On a monochrome display, wxWidgets shows all brushes as white unless the - colour is really 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 or when required. - - An application may wish to create brushes with different characteristics - dynamically, and there is the consequent danger that a large number of - duplicate brushes will be created. Therefore an application may wish to - get a pointer to a brush by using the global list of brushes ::wxTheBrushList, - and calling the member function wxBrushList::FindOrCreateBrush(). - - This class uses 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 - counting, are not affected. - - @library{wxcore} - @category{gdi} - - @stdobjects - ::wxNullBrush, ::wxBLUE_BRUSH, ::wxGREEN_BRUSH, ::wxWHITE_BRUSH, - ::wxBLACK_BRUSH, ::wxGREY_BRUSH, ::wxMEDIUM_GREY_BRUSH, ::wxLIGHT_GREY_BRUSH, - ::wxTRANSPARENT_BRUSH, ::wxCYAN_BRUSH, ::wxRED_BRUSH - - @see wxBrushList, wxDC, wxDC::SetBrush -*/ -class wxBrush : public wxGDIObject -{ -public: - /** - Default constructor. - The brush will be uninitialised, and wxBrush:IsOk() will return @false. - */ - wxBrush(); - - /** - Constructs a brush from a colour object and @a style. - - @param colour - Colour object. - @param style - One of the ::wxBrushStyle enumeration values. - */ - wxBrush(const wxColour& colour, wxBrushStyle style = wxBRUSHSTYLE_SOLID); - - /** - Constructs a stippled brush using a bitmap. - The brush style will be set to wxBRUSHSTYLE_STIPPLE. - */ - wxBrush(const wxBitmap& stippleBitmap); - - /** - Copy constructor, uses @ref overview_refcount "reference counting". - */ - wxBrush(const wxBrush& brush); - - /** - Destructor. - - See @ref overview_refcount_destruct for more info. - - @remarks Although all remaining brushes are deleted when the application - exits, the application should try to clean up all brushes itself. - This is because wxWidgets cannot know if a pointer to the brush - object is stored in an application data structure, and there is - a risk of double deletion. - */ - virtual ~wxBrush(); - - /** - Returns a reference to the brush colour. - - @see SetColour() - */ - virtual wxColour GetColour() const; - - /** - Gets a pointer to the stipple bitmap. If the brush does not have a wxBRUSHSTYLE_STIPPLE - style, this bitmap may be non-@NULL but uninitialised (i.e. wxBitmap:IsOk() returns @false). - - @see SetStipple() - */ - virtual wxBitmap* GetStipple() const; - - /** - Returns the brush style, one of the ::wxBrushStyle values. - - @see SetStyle(), SetColour(), SetStipple() - */ - virtual wxBrushStyle GetStyle() const; - - /** - Returns @true if the style of the brush is any of hatched fills. - - @see GetStyle() - */ - virtual bool IsHatch() const; - - /** - Returns @true if the brush is initialised. It will return @false if the default - constructor has been used (for example, the brush is a member of a class, or - @NULL has been assigned to it). - */ - bool IsOk() const; - - //@{ - /** - Sets the brush colour using red, green and blue values. - - @see GetColour() - */ - virtual void SetColour(wxColour& colour); - virtual void SetColour(unsigned char red, unsigned char green, unsigned char blue); - //@} - - /** - Sets the stipple bitmap. - - @param bitmap - The bitmap to use for stippling. - - @remarks The style will be set to wxBRUSHSTYLE_STIPPLE, unless the bitmap - has a mask associated to it, in which case the style will be set - to wxBRUSHSTYLE_STIPPLE_MASK_OPAQUE. - - @see wxBitmap - */ - virtual void SetStipple(const wxBitmap& bitmap); - - /** - Sets the brush style. - - @param style - One of the ::wxBrushStyle values. - - @see GetStyle() - */ - virtual void SetStyle(wxBrushStyle style); - - /** - Inequality operator. - See @ref overview_refcount_equality for more info. - */ - bool operator !=(const wxBrush& brush) const; - - /** - Equality operator. - See @ref overview_refcount_equality for more info. - */ - bool operator ==(const wxBrush& brush) const; -}; - -/** - An empty brush. -*/ -wxBrush wxNullBrush; - -/** - Blue brush. -*/ -wxBrush* wxBLUE_BRUSH; - -/** - Green brush. -*/ -wxBrush* wxGREEN_BRUSH; - -/** - White brush. -*/ -wxBrush* wxWHITE_BRUSH; - -/** - Black brush. -*/ -wxBrush* wxBLACK_BRUSH; - -/** - Grey brush. -*/ -wxBrush* wxGREY_BRUSH; - -/** - Medium grey brush. -*/ -wxBrush* wxMEDIUM_GREY_BRUSH; - -/** - Light grey brush. -*/ -wxBrush* wxLIGHT_GREY_BRUSH; - -/** - Transparent brush. -*/ -wxBrush* wxTRANSPARENT_BRUSH; - -/** - Cyan brush. -*/ -wxBrush* wxCYAN_BRUSH; - -/** - Red brush. -*/ -wxBrush* wxRED_BRUSH; - - - -/** - @class wxBrushList - @wxheader{gdicmn.h} - - A brush list is a list containing all brushes which have been created. - - The application should not construct its own brush list: it should use the - object pointer ::wxTheBrushList. - - @library{wxcore} - @category{gdi} - - @see wxBrush -*/ -class wxBrushList : public wxList -{ -public: - /** - Finds a brush with the specified attributes and returns it, else creates a new - brush, adds it to the brush list, and returns it. - - @param colour - Colour object. - @param style - Brush style. See ::wxBrushStyle for a list of styles. - */ - wxBrush* FindOrCreateBrush(const wxColour& colour, - wxBrushStyle style = wxBRUSHSTYLE_SOLID); -}; - -/** - The global wxBrushList instance. -*/ -wxBrushList* wxTheBrushList; diff --git a/interface/buffer.h b/interface/buffer.h deleted file mode 100644 index 6de1c83f15..0000000000 --- a/interface/buffer.h +++ /dev/null @@ -1,117 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: buffer.h -// Purpose: interface of wxMemoryBuffer -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxMemoryBuffer - @wxheader{buffer.h} - - A @b wxMemoryBuffer is a useful data structure for storing arbitrary sized - blocks of memory. wxMemoryBuffer guarantees deletion of the memory block when - the object is destroyed. - - @library{wxbase} - @category{data} -*/ -class wxMemoryBuffer -{ -public: - /** - Copy constructor, refcounting is used for performance, but wxMemoryBuffer - is not a copy-on-write structure so changes made to one buffer effect all - copies made from it. - - @see @ref overview_refcount - */ - wxMemoryBuffer(const wxMemoryBuffer& src); - - /** - Create a new buffer. - - @param size - size of the new buffer. - */ - wxMemoryBuffer(size_t size); - - /** - Append a single byte to the buffer. - - @param data - New byte to append to the buffer. - */ - void AppendByte(char data); - - /** - Ensure that the buffer is big enough and return a pointer to the start - of the empty space in the buffer. This pointer can be used to directly - write data into the buffer, this new data will be appended to the - existing data. - - @param sizeNeeded - Amount of extra space required in the buffer for - the append operation - */ - void* GetAppendBuf(size_t sizeNeeded); - - /** - Returns the size of the buffer. - */ - size_t GetBufSize() const; - - /** - Return a pointer to the data in the buffer. - */ - void* GetData() const; - - /** - Returns the length of the valid data in the buffer. - */ - size_t GetDataLen() const; - - /** - Ensure the buffer is big enough and return a pointer to the - buffer which can be used to directly write into the buffer - up to @a sizeNeeded bytes. - */ - void* GetWriteBuf(size_t sizeNeeded); - - /** - Ensures the buffer has at least @a size bytes available. - */ - void SetBufSize(size_t size); - - /** - Sets the length of the data stored in the buffer. - Mainly useful for truncating existing data. - - @param size - New length of the valid data in the buffer. This is - distinct from the allocated size - */ - void SetDataLen(size_t size); - - /** - Update the length after completing a direct append, which - you must have used GetAppendBuf() to initialise. - - @param sizeUsed - This is the amount of new data that has been - appended. - */ - void UngetAppendBuf(size_t sizeUsed); - - /** - Update the buffer after completing a direct write, which - you must have used GetWriteBuf() to initialise. - - @param sizeUsed - The amount of data written in to buffer - by the direct write - */ - void UngetWriteBuf(size_t sizeUsed); -}; - diff --git a/interface/busyinfo.h b/interface/busyinfo.h deleted file mode 100644 index 88c88810e3..0000000000 --- a/interface/busyinfo.h +++ /dev/null @@ -1,72 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: busyinfo.h -// Purpose: interface of wxBusyInfo -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxBusyInfo - @wxheader{busyinfo.h} - - This class makes it easy to tell your user that the program is temporarily busy. - Just create a wxBusyInfo object on the stack, and within the current scope, - a message window will be shown. - - For example: - - @code - wxBusyInfo wait("Please wait, working..."); - - for (int i = 0; i < 100000; i++) - { - DoACalculation(); - } - @endcode - - It works by creating a window in the constructor, and deleting it - in the destructor. - - You may also want to call wxTheApp-Yield() to refresh the window - periodically (in case it had been obscured by other windows, for - example) like this: - - @code - wxWindowDisabler disableAll; - - wxBusyInfo wait("Please wait, working..."); - - for (int i = 0; i < 100000; i++) - { - DoACalculation(); - - if ( !(i % 1000) ) - wxTheApp-Yield(); - } - @endcode - - but take care to not cause undesirable reentrancies when doing it (see - wxApp::Yield for more details). The simplest way to do it is to use - wxWindowDisabler class as illustrated in the above example. - - @library{wxcore} - @category{cmndlg} -*/ -class wxBusyInfo -{ -public: - /** - Constructs a busy info window as child of @a parent and displays @e msg in it. - - @note If @a parent is not @NULL you must ensure that it is not - closed while the busy info is shown. - */ - wxBusyInfo(const wxString& msg, wxWindow* parent = NULL); - - /** - Hides and closes the window containing the information text. - */ - virtual ~wxBusyInfo(); -}; - diff --git a/interface/button.h b/interface/button.h deleted file mode 100644 index 67e13cc77f..0000000000 --- a/interface/button.h +++ /dev/null @@ -1,146 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: button.h -// Purpose: interface of wxButton -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxButton - @wxheader{button.h} - - A button is a control that contains a text string, and is one of the most - common elements of a GUI. - - It may be placed on a @ref wxDialog "dialog box" or on a @ref wxPanel panel, - or indeed on almost any other window. - - @beginStyleTable - @style{wxBU_LEFT} - Left-justifies the label. Windows and GTK+ only. - @style{wxBU_TOP} - Aligns the label to the top of the button. Windows and GTK+ only. - @style{wxBU_RIGHT} - Right-justifies the bitmap label. Windows and GTK+ only. - @style{wxBU_BOTTOM} - Aligns the label to the bottom of the button. Windows and GTK+ only. - @style{wxBU_EXACTFIT} - Creates the button as small as possible instead of making it of the - standard size (which is the default behaviour ). - @style{wxBORDER_NONE} - Creates a flat button. Windows and GTK+ only. - @endStyleTable - - @beginEventTable{wxCommandEvent} - @event{EVT_BUTTON(id, func)} - Process a wxEVT_COMMAND_BUTTON_CLICKED event, when the button is clicked. - @endEventTable - - @library{wxcore} - @category{ctrl} - - - @see wxBitmapButton -*/ -class wxButton : public wxControl -{ -public: - /** - Default ctor. - */ - wxButton(); - - /** - Constructor, creating and showing a button. - - The preferred way to create standard buttons is to use default value of - @a label. If no label is supplied and @a id is one of standard IDs from - @ref page_stockitems "this list", a standard label will be used. - - In addition to that, the button will be decorated with stock icons under GTK+ 2. - - @param parent - Parent window. Must not be @NULL. - @param id - Button identifier. A value of wxID_ANY indicates a default value. - @param label - Text to be displayed on the button. - @param pos - Button position. - @param size - Button size. If the default size is specified then the button is sized - appropriately for the text. - @param style - Window style. See wxButton class description. - @param validator - Window validator. - @param name - Window name. - - @see Create(), wxValidator - */ - wxButton(wxWindow* parent, wxWindowID id, - const wxString& label = wxEmptyString, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = 0, - const wxValidator& validator = wxDefaultValidator, - const wxString& name = wxButtonNameStr); - - /** - Destructor, destroying the button. - */ - virtual ~wxButton(); - - /** - Button creation function for two-step creation. - For more details, see wxButton(). - */ - bool Create(wxWindow* parent, wxWindowID id, - const wxString& label = wxEmptyString, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = 0, - const wxValidator& validator = wxDefaultValidator, - const wxString& name = wxButtonNameStr); - - /** - Returns the default size for the buttons. It is advised to make all the dialog - buttons of the same size and this function allows to retrieve the (platform and - current font dependent size) which should be the best suited for this. - */ - static wxSize GetDefaultSize(); - - /** - Returns the string label for the button. - - @see SetLabel() - */ - wxString GetLabel() const; - - /** - This sets the button to be the default item in its top-level window - (e.g. the panel or the dialog box containing it). - - As normal, pressing return causes the default button to be depressed when - the return key is pressed. - - See also wxWindow::SetFocus() which sets the keyboard focus for windows - and text panel items, and wxTopLevelWindow::SetDefaultItem(). - - @remarks Under Windows, only dialog box buttons respond to this function. - - @return the old default item (possibly NULL) - */ - virtual wxWindow* SetDefault(); - - /** - Sets the string label for the button. - - @param label - The label to set. - */ - void SetLabel(const wxString& label); -}; - diff --git a/interface/calctrl.h b/interface/calctrl.h deleted file mode 100644 index 397b4760ef..0000000000 --- a/interface/calctrl.h +++ /dev/null @@ -1,529 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: calctrl.h -// Purpose: interface of wxCalendarCtrl -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxCalendarEvent - @wxheader{calctrl.h} - - The wxCalendarEvent class is used together with wxCalendarCtrl. - - @library{wxadv} - @category{events} - - @see wxCalendarCtrl -*/ -class wxCalendarEvent : public wxDateEvent -{ -public: - /** - Returns the week day on which the user clicked in - @c EVT_CALENDAR_WEEKDAY_CLICKED handler. It doesn't make sense to call - this function in other handlers. - */ - wxDateTime::WeekDay GetWeekDay() const; - - /** - Sets the week day carried by the event, normally only used by the - library internally. - */ - void SetWeekDay(wxDateTime::WeekDay day); -}; - - - -/** - Possible kinds of borders which may be used to decorate a date using - wxCalendarDateAttr. -*/ -enum wxCalendarDateBorder -{ - wxCAL_BORDER_NONE, ///< No Border (Default) - wxCAL_BORDER_SQUARE, ///< Rectangular Border - wxCAL_BORDER_ROUND ///< Round Border -}; - -/** - @class wxCalendarDateAttr - @wxheader{calctrl.h} - - wxCalendarDateAttr is a custom attributes for a calendar date. The objects - of this class are used with wxCalendarCtrl. - - @library{wxadv} - @category{misc} - - @see wxCalendarCtrl -*/ -class wxCalendarDateAttr -{ -public: - /** - Default constructor. - */ - wxCalendarDateAttr(); - - /** - Constructor for specifying all wxCalendarDateAttr properties. - */ - wxCalendarDateAttr(const wxColour& colText, - const wxColour& colBack = wxNullColour, - const wxColour& colBorder = wxNullColour, - const wxFont& font = wxNullFont, - wxCalendarDateBorder border = wxCAL_BORDER_NONE); - - /** - Constructor using default properties except the given border. - */ - wxCalendarDateAttr(wxCalendarDateBorder border, - const wxColour& colBorder = wxNullColour); - - /** - Returns the background colour set for the calendar date. - */ - const wxColour GetBackgroundColour() const; - - /** - Returns the border set for the calendar date. - */ - wxCalendarDateBorder GetBorder() const; - - /** - Returns the border colour set for the calendar date. - */ - const wxColour GetBorderColour() const; - - /** - Returns the font set for the calendar date. - */ - const wxFont GetFont() const; - - /** - Returns the text colour set for the calendar date. - */ - const wxColour GetTextColour() const; - - /** - Returns @true if a non-default text background colour is set. - */ - bool HasBackgroundColour() const; - - /** - Returns @true if a non-default (i.e. any) border is set. - */ - bool HasBorder() const; - - /** - Returns @true if a non-default border colour is set. - */ - bool HasBorderColour() const; - - /** - Returns @true if a non-default font is set. - */ - bool HasFont() const; - - /** - Returns @true if a non-default text foreground colour is set. - */ - bool HasTextColour() const; - - /** - Returns @true if this calendar day is displayed as a holiday. - */ - bool IsHoliday() const; - - /** - Sets the text background colour to use. - */ - void SetBackgroundColour(const wxColour& colBack); - - /** - Sets the border to use. - */ - void SetBorder(wxCalendarDateBorder border); - - /** - Sets the border colour to use. - */ - void SetBorderColour(const wxColour& col); - - /** - Sets the font to use. - */ - void SetFont(const wxFont& font); - - /** - If @a holiday is @true, this calendar day will be displayed as a - holiday. - */ - void SetHoliday(bool holiday); - - /** - Sets the text (foreground) colour to use. - */ - void SetTextColour(const wxColour& colText); - - /** - Used (internally) by the generic wxCalendarCtrl::Mark(). - */ - static const wxCalendarDateAttr& GetMark(); - - /** - Set the attributes that will be used to Mark() days on the generic - wxCalendarCtrl. - */ - static void SetMark(wxCalendarDateAttr const& m); -}; - - - -/** - Possible return values from wxCalendarCtrl::HitTest(). -*/ -enum wxCalendarHitTestResult -{ - wxCAL_HITTEST_NOWHERE, ///< Hit outside of anything. - wxCAL_HITTEST_HEADER, ///< Hit on the header (weekdays). - wxCAL_HITTEST_DAY ///< Hit on a day in the calendar. -}; - -/** - @class wxCalendarCtrl - @wxheader{calctrl.h} - - The calendar control allows the user to pick a date. The user can move the - current selection using the keyboard and select the date (generating - @c EVT_CALENDAR event) by pressing @c @ or double clicking it. - - Generic calendar has advanced possibilities for the customization of its - display, described below. If you want to use these possibilities on every - platform, use wxGenericCalendarCtrl instead of wxCalendarCtrl. - - All global settings (such as colours and fonts used) can, of course, be - changed. But also, the display style for each day in the month can be set - independently using wxCalendarDateAttr class. - - An item without custom attributes is drawn with the default colours and - font and without border, but setting custom attributes with SetAttr() - allows to modify its appearance. Just create a custom attribute object and - set it for the day you want to be displayed specially (note that the - control will take ownership of the pointer, i.e. it will delete it itself). - A day may be marked as being a holiday, even if it is not recognized as - one by wxDateTime using the wxCalendarDateAttr::SetHoliday() method. - - As the attributes are specified for each day, they may change when the - month is changed, so you will often want to update them in - @c EVT_CALENDAR_PAGE_CHANGED event handler. - - @beginStyleTable - @style{wxCAL_SUNDAY_FIRST} - Show Sunday as the first day in the week (not in wxGTK) - @style{wxCAL_MONDAY_FIRST} - Show Monday as the first day in the week (not in wxGTK) - @style{wxCAL_SHOW_HOLIDAYS} - Highlight holidays in the calendar (only generic) - @style{wxCAL_NO_YEAR_CHANGE} - Disable the year changing (deprecated, only generic) - @style{wxCAL_NO_MONTH_CHANGE} - Disable the month (and, implicitly, the year) changing - @style{wxCAL_SHOW_SURROUNDING_WEEKS} - Show the neighbouring weeks in the previous and next months - (only generic, always on for the native controls) - @style{wxCAL_SEQUENTIAL_MONTH_SELECTION} - Use alternative, more compact, style for the month and year - selection controls. (only generic) - @style{wxCAL_SHOW_WEEK_NUMBERS} - Show week numbers on the left side of the calendar. (not in generic) - @endStyleTable - - @beginEventTable{wxCalendarEvent} - @event{EVT_CALENDAR(id, func)} - A day was double clicked in the calendar. - @event{EVT_CALENDAR_SEL_CHANGED(id, func)} - The selected date changed. - @event{EVT_CALENDAR_PAGE_CHANGED(id, func)} - The selected month (and/or year) changed. - @event{EVT_CALENDAR_WEEKDAY_CLICKED(id, func)} - User clicked on the week day header (only generic). - @endEventTable - - @note Changing the selected date will trigger an EVT_CALENDAR_DAY, MONTH or - YEAR event as well as an EVT_CALENDAR_SEL_CHANGED event. - - @library{wxadv} - @category{ctrl} - - - @nativeimpl{wxgtk,wxmsw} - - @see @ref page_samples_calendar, wxCalendarDateAttr, wxCalendarEvent, - wxDatePickerCtrl -*/ -class wxCalendarCtrl : public wxControl -{ -public: - /** - Default constructor. - */ - wxCalendarCtrl(); - - /** - Does the same as Create() method. - */ - wxCalendarCtrl(wxWindow* parent, wxWindowID id, - const wxDateTime& date = wxDefaultDateTime, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = wxCAL_SHOW_HOLIDAYS, - const wxString& name = wxCalendarNameStr); - - /** - Destroys the control. - */ - ~wxCalendarCtrl(); - - /** - Creates the control. See wxWindow::wxWindow() for the meaning of the - parameters and the control overview for the possible styles. - */ - bool Create(wxWindow* parent, wxWindowID id, - const wxDateTime& date = wxDefaultDateTime, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = wxCAL_SHOW_HOLIDAYS, - const wxString& name = wxCalendarNameStr); - - /** - This function should be used instead of changing @c wxCAL_SHOW_HOLIDAYS - style bit directly. It enables or disables the special highlighting of - the holidays. - */ - void EnableHolidayDisplay(bool display = true); - - /** - This function should be used instead of changing - @c wxCAL_NO_MONTH_CHANGE style bit. It allows or disallows the user to - change the month interactively. Note that if the month can not be - changed, the year can not be changed neither. - - @return @true if the value of this option really changed or @false if - it was already set to the requested value. - */ - bool EnableMonthChange(bool enable = true); - - /** - @deprecated - - This function should be used instead of changing - @c wxCAL_NO_YEAR_CHANGE style bit directly. It allows or disallows the - user to change the year interactively. Only in generic wxCalendarCtrl. - */ - void EnableYearChange(bool enable = true); - - /** - Returns the attribute for the given date (should be in the range - 1...31). The returned pointer may be @NULL. Only in generic - wxCalendarCtrl. - */ - wxCalendarDateAttr* GetAttr(size_t day) const; - - /** - Gets the currently selected date. - */ - const wxDateTime GetDate() const; - - /** - Gets the background colour of the header part of the calendar window. - - This method is currently only implemented in generic wxCalendarCtrl and - always returns @c wxNullColour in the native versions. - - @see SetHeaderColours() - */ - const wxColour GetHeaderColourBg() const; - - /** - Gets the foreground colour of the header part of the calendar window. - - This method is currently only implemented in generic wxCalendarCtrl and - always returns @c wxNullColour in the native versions. - - @see SetHeaderColours() - */ - const wxColour GetHeaderColourFg() const; - - /** - Gets the background highlight colour. Only in generic wxCalendarCtrl. - - This method is currently only implemented in generic wxCalendarCtrl and - always returns @c wxNullColour in the native versions. - - @see SetHighlightColours() - */ - const wxColour GetHighlightColourBg() const; - - /** - Gets the foreground highlight colour. Only in generic wxCalendarCtrl. - - This method is currently only implemented in generic wxCalendarCtrl and - always returns @c wxNullColour in the native versions. - - @see SetHighlightColours() - */ - const wxColour GetHighlightColourFg() const; - - /** - Return the background colour currently used for holiday highlighting. - - Only useful with generic wxCalendarCtrl as native versions currently - don't support holidays display at all and always return - @c wxNullColour. - - @see SetHolidayColours() - */ - const wxColour GetHolidayColourBg() const; - - /** - Return the foreground colour currently used for holiday highlighting. - - Only useful with generic wxCalendarCtrl as native versions currently - don't support holidays display at all and always return - @c wxNullColour. - - @see SetHolidayColours() - */ - const wxColour GetHolidayColourFg() const; - - /** - Returns one of wxCalendarHitTestResult constants and fills either - @a date or @a wd pointer with the corresponding value depending on the - hit test code. - - Not implemented in wxGTK currently. - */ - wxCalendarHitTestResult HitTest(const wxPoint& pos, - wxDateTime* date = NULL, - wxDateTime::WeekDay* wd = NULL); - - /** - Clears any attributes associated with the given day (in the range - 1...31). Only in generic wxCalendarCtrl. - */ - void ResetAttr(size_t day); - - /** - Associates the attribute with the specified date (in the range 1...31). - If the pointer is @NULL, the items attribute is cleared. Only in - generic wxCalendarCtrl. - */ - void SetAttr(size_t day, wxCalendarDateAttr* attr); - - /** - Sets the current date. - - The @a date parameter must be valid. - */ - void SetDate(const wxDateTime& date); - - /** - Set the colours used for painting the weekdays at the top of the - control. - - This method is currently only implemented in generic wxCalendarCtrl and - does nothing in the native versions. - */ - void SetHeaderColours(const wxColour& colFg, - const wxColour& colBg); - - /** - Set the colours to be used for highlighting the currently selected - date. - - This method is currently only implemented in generic wxCalendarCtrl and - does nothing in the native versions. - */ - void SetHighlightColours(const wxColour& colFg, - const wxColour& colBg); - - /** - Marks the specified day as being a holiday in the current month. - - This method is only implemented in the generic version of the control - and does nothing in the native ones. - */ - void SetHoliday(size_t day); - - /** - Sets the colours to be used for the holidays highlighting. - - This method is only implemented in the generic version of the control - and does nothing in the native ones. It should also only be called if - the window style includes @c wxCAL_SHOW_HOLIDAYS flag or - EnableHolidayDisplay() had been called. - - */ - void SetHolidayColours(const wxColour& colFg, - const wxColour& colBg); - - /** - Mark or unmark the day. This day of month will be marked in every - month. In generic wxCalendarCtrl, - */ - void Mark(size_t day, bool mark); - - /** - @name Date Range Functions - - The functions in this section are currently implemented in the generic - and MSW versions and do nothing in the native GTK implementation. - */ - //@{ - - /** - Restrict the dates shown by the control to the specified range. - - If either date is set, the corresponding limit will be enforced and - @true returned. If none are set, the existing restrictions are removed - and @false is returned. - - @see GetDateRange() - - @param lowerdate - The low limit for the dates shown by the control or - @c wxDefaultDateTime. - @param highlighting - The high limit for the dates shown by the control or - @c wxDefaultDateTime. - @return - @true if either limit is valid, @false otherwise - */ - virtual bool SetDateRange(const wxDateTime& lowerdate = wxDefaultDateTime, - const wxDateTime& upperdate = wxDefaultDateTime); - - /** - Returns the limits currently being used. - - @see SetDateRange() - - @param lowerdate - If non-@NULL, the value of the low limit for the dates shown by the - control is returned (which may be @c wxDefaultDateTime if no limit - is set). - @param upperdate - If non-@NULL, the value of the upper limit for the dates shown by - the control is returned (which may be @c wxDefaultDateTime if no - limit is set). - @return - @true if either limit is set, @false otherwise - */ - virtual bool GetDateRange(wxDateTime *lowerdate, - wxDateTime *upperdate) const; - - //@} -}; - diff --git a/interface/caret.h b/interface/caret.h deleted file mode 100644 index 4182c41f60..0000000000 --- a/interface/caret.h +++ /dev/null @@ -1,132 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: caret.h -// Purpose: interface of wxCaret -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxCaret - @wxheader{caret.h} - - A caret is a blinking cursor showing the position where the typed text will - appear. Text controls usually have their own caret but wxCaret provides a - way to use a caret in other windows. - - Currently, the caret appears as a rectangle of the given size. In the - future, it will be possible to specify a bitmap to be used for the caret - shape. - - A caret is always associated with a window and the current caret can be - retrieved using wxWindow::GetCaret(). The same caret can't be reused in two - different windows. - - @library{wxcore} - @category{misc} -*/ -class wxCaret -{ -public: - /** - Default constructor. - */ - wxCaret(); - - //@{ - /** - Creates a caret with the given size (in pixels) and associates it with - the @a window. - */ - wxCaret(wxWindow* window, int width, int height); - wxCaret(wxWindowBase* window, const wxSize& size); - //@} - - //@{ - /** - Creates a caret with the given size (in pixels) and associates it with - the @a window (same as the equivalent constructors). - */ - bool Create(wxWindowBase* window, int width, int height); - bool Create(wxWindowBase* window, const wxSize& size); - //@} - - /** - Returns the blink time which is measured in milliseconds and is the - time elapsed between 2 inversions of the caret (blink time of the caret - is the same for all carets, so this functions is static). - */ - static int GetBlinkTime(); - - //@{ - /** - Get the caret position (in pixels). - */ - void GetPosition(int* x, int* y) const; - const wxPoint GetPosition() const; - //@} - - //@{ - /** - Get the caret size. - */ - void GetSize(int* width, int* height) const; - const wxSize GetSize() const; - //@} - - /** - Get the window the caret is associated with. - */ - wxWindow* GetWindow() const; - - /** - Hides the caret, same as Show(@false). - */ - void Hide(); - - /** - Returns @true if the caret was created successfully. - */ - bool IsOk() const; - - /** - Returns @true if the caret is visible and @false if it is permanently - hidden (if it is is blinking and not shown currently but will be after - the next blink, this method still returns @true). - */ - bool IsVisible() const; - - //@{ - /** - Move the caret to given position (in logical coordinates). - */ - void Move(int x, int y); - void Move(const wxPoint& pt); - //@} - - /** - Sets the blink time for all the carets. - - @warning Under Windows, this function will change the blink time for - all carets permanently (until the next time it is called), - even for carets in other applications. - - @see GetBlinkTime() - */ - static void SetBlinkTime(int milliseconds); - - //@{ - /** - Changes the size of the caret. - */ - void SetSize(int width, int height); - void SetSize(const wxSize& size); - //@} - - /** - Shows or hides the caret. Notice that if the caret was hidden N times, - it must be shown N times as well to reappear on the screen. - */ - void Show(bool show = true); -}; - diff --git a/interface/chartype.h b/interface/chartype.h deleted file mode 100644 index af71092399..0000000000 --- a/interface/chartype.h +++ /dev/null @@ -1,59 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: chartype.h -// Purpose: interface of global functions -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** @ingroup group_funcmacro_string */ -//@{ - -/** - This macro can be used with character and string literals (in other words, - @c 'x' or @c "foo") to automatically convert them to Unicode in Unicode - builds of wxWidgets. This macro is simply returns the value passed to it - without changes in ASCII build. In fact, its definition is: - -@code -#ifdef UNICODE -# define wxT(x) L ## x -#else // !Unicode -# define wxT(x) x -#endif -@endcode - - @see @ref overview_unicode - - @header{wx/chartype.h} -*/ -#define wxT(string) - -/** - wxS is macro which can be used with character and string literals to either - convert them to wide characters or strings in @c wchar_t-based Unicode - builds or keep them unchanged in UTF-8 builds. The use of this macro is - optional as the translation will always be done at run-time even if there - is a mismatch between the kind of the literal used and string or character - type used in the current build, but using it can be beneficial in - performance-sensitive code to do the conversion at compile-time instead. - - @see wxT() - - @header{wx/chartype.h} -*/ -#define wxS(string) - -/** - This macro is exactly the same as wxT() and is defined in wxWidgets simply - because it may be more intuitive for Windows programmers as the standard - Win32 headers also define it (as well as yet another name for the same - macro which is _TEXT()). - - Don't confuse this macro with _()! - - @header{wx/chartype.h} -*/ -#define _T(string) - -//@} diff --git a/interface/checkbox.h b/interface/checkbox.h deleted file mode 100644 index e0f584b3b6..0000000000 --- a/interface/checkbox.h +++ /dev/null @@ -1,170 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: checkbox.h -// Purpose: interface of wxCheckBox -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - The possible states of a 3-state wxCheckBox (Compatible with the 2-state - wxCheckBox). -*/ -enum wxCheckBoxState -{ - wxCHK_UNCHECKED, - wxCHK_CHECKED, - wxCHK_UNDETERMINED ///< 3-state checkbox only -}; - -/** - @class wxCheckBox - @wxheader{checkbox.h} - - A checkbox is a labelled box which by default is either on (checkmark is - visible) or off (no checkmark). Optionally (when the wxCHK_3STATE style - flag is set) it can have a third state, called the mixed or undetermined - state. Often this is used as a "Does Not Apply" state. - - @beginStyleTable - @style{wxCHK_2STATE} - Create a 2-state checkbox. This is the default. - @style{wxCHK_3STATE} - Create a 3-state checkbox. Not implemented in wxMGL, wxOS2 and - wxGTK built against GTK+ 1.2. - @style{wxCHK_ALLOW_3RD_STATE_FOR_USER} - By default a user can't set a 3-state checkbox to the third state. - It can only be done from code. Using this flags allows the user to - set the checkbox to the third state by clicking. - @style{wxALIGN_RIGHT} - Makes the text appear on the left of the checkbox. - @endStyleTable - - @beginEventTable{wxCommandEvent} - @event{EVT_CHECKBOX(id, func)} - Process a wxEVT_COMMAND_CHECKBOX_CLICKED event, when the checkbox - is clicked. - @endEventTable - - @library{wxcore} - @category{ctrl} - - - @see wxRadioButton, wxCommandEvent -*/ -class wxCheckBox : public wxControl -{ -public: - /** - Default constructor. - - @see Create(), wxValidator - */ - wxCheckBox(); - - /** - Constructor, creating and showing a checkbox. - - @param parent - Parent window. Must not be @NULL. - @param id - Checkbox identifier. The value wxID_ANY indicates a default value. - @param label - Text to be displayed next to the checkbox. - @param pos - Checkbox position. If wxDefaultPosition is specified then a default - position is chosen. - @param size - Checkbox size. If wxDefaultSize is specified then a default size is - chosen. - @param style - Window style. See wxCheckBox. - @param validator - Window validator. - @param name - Window name. - - @see Create(), wxValidator - */ - wxCheckBox(wxWindow* parent, wxWindowID id, - const wxString& label, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = 0, - const wxValidator& val = wxDefaultValidator, - const wxString& name = "checkBox"); - - /** - Destructor, destroying the checkbox. - */ - ~wxCheckBox(); - - /** - Creates the checkbox for two-step construction. See wxCheckBox() - for details. - */ - bool Create(wxWindow* parent, wxWindowID id, - const wxString& label, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = 0, - const wxValidator& val = wxDefaultValidator, - const wxString& name = "checkBox"); - - /** - Gets the state of a 2-state checkbox. - - @return Returns @true if it is checked, @false otherwise. - */ - bool GetValue() const; - - /** - Gets the state of a 3-state checkbox. Asserts when the function is used - with a 2-state checkbox. - */ - wxCheckBoxState Get3StateValue() const; - - /** - Returns whether or not the checkbox is a 3-state checkbox. - - @return @true if this checkbox is a 3-state checkbox, @false if it's - a 2-state checkbox. - */ - bool Is3State() const; - - /** - Returns whether or not the user can set the checkbox to the third - state. - - @return @true if the user can set the third state of this checkbox, - @false if it can only be set programmatically or if it's a - 2-state checkbox. - */ - bool Is3rdStateAllowedForUser() const; - - /** - This is just a maybe more readable synonym for GetValue(): just as the - latter, it returns @true if the checkbox is checked and @false - otherwise. - */ - bool IsChecked() const; - - /** - Sets the checkbox to the given state. This does not cause a - wxEVT_COMMAND_CHECKBOX_CLICKED event to get emitted. - - @param state - If @true, the check is on, otherwise it is off. - */ - void SetValue(bool state); - - /** - Sets the checkbox to the given state. This does not cause a - wxEVT_COMMAND_CHECKBOX_CLICKED event to get emitted. - - Asserts when the checkbox is a 2-state checkbox and setting the state - to wxCHK_UNDETERMINED. - */ - void Set3StateValue(const wxCheckBoxState state); -}; - diff --git a/interface/checklst.h b/interface/checklst.h deleted file mode 100644 index c8a6ee6073..0000000000 --- a/interface/checklst.h +++ /dev/null @@ -1,109 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: checklst.h -// Purpose: interface of wxCheckListBox -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxCheckListBox - @wxheader{checklst.h} - - A wxCheckListBox is like a wxListBox, but allows items to be checked or - unchecked. - - When using this class under Windows wxWidgets must be compiled with - wxUSE_OWNER_DRAWN set to 1. - - Only the new functions for this class are documented; see also wxListBox. - - Please note that wxCheckListBox uses client data in its implementation, - and therefore this is not available to the application. - - @beginEventTable{wxCommandEvent} - @event{EVT_CHECKLISTBOX(id, func)} - Process a wxEVT_COMMAND_CHECKLISTBOX_TOGGLED event, when an item in - the check list box is checked or unchecked. - @endEventTable - - @library{wxcore} - @category{ctrl} - - - @see wxListBox, wxChoice, wxComboBox, wxListCtrl, wxCommandEvent -*/ -class wxCheckListBox : public wxListBox -{ -public: - /** - Default constructor. - */ - wxCheckListBox(); - - //@{ - /** - Constructor, creating and showing a list box. - - @param parent - Parent window. Must not be @NULL. - @param id - Window identifier. The value wxID_ANY indicates a default value. - @param pos - Window position. - @param size - Window size. If wxDefaultSize is specified then the window is sized - appropriately. - @param n - Number of strings with which to initialise the control. - @param choices - An array of strings with which to initialise the control. - @param style - Window style. See wxCheckListBox. - @param validator - Window validator. - @param name - Window name. - */ - wxCheckListBox(wxWindow* parent, wxWindowID id, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - int n, - const wxString choices[] = NULL, - long style = 0, - const wxValidator& validator = wxDefaultValidator, - const wxString& name = "listBox"); - wxCheckListBox(wxWindow* parent, wxWindowID id, - const wxPoint& pos, - const wxSize& size, - const wxArrayString& choices, - long style = 0, - const wxValidator& validator = wxDefaultValidator, - const wxString& name = "listBox"); - //@} - - /** - Destructor, destroying the list box. - */ - ~wxCheckListBox(); - - /** - Checks the given item. Note that calling this method does not result in - a wxEVT_COMMAND_CHECKLISTBOX_TOGGLE event being emitted. - - @param item - Index of item to check. - @param check - @true if the item is to be checked, @false otherwise. - */ - void Check(int item, bool check = true); - - /** - Returns @true if the given item is checked, @false otherwise. - - @param item - Index of item whose check status is to be returned. - */ - bool IsChecked(unsigned int item) const; -}; - diff --git a/interface/choicdlg.h b/interface/choicdlg.h deleted file mode 100644 index 734cecc83c..0000000000 --- a/interface/choicdlg.h +++ /dev/null @@ -1,353 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: choicdlg.h -// Purpose: interface of wx[Multi|Single]ChoiceDialog -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxMultiChoiceDialog - @wxheader{choicdlg.h} - - This class represents a dialog that shows a list of strings, and allows the - user to select one or more. - - @library{wxbase} - @category{cmndlg} - - @see @ref overview_cmndlg_multichoice, wxSingleChoiceDialog -*/ -class wxMultiChoiceDialog : public wxDialog -{ -public: - //@{ - /** - Constructor taking an array of wxString choices. - - @param parent - Parent window. - @param message - Message to show on the dialog. - @param caption - The dialog caption. - @param n - The number of choices. - @param choices - An array of strings, or a string list, containing the choices. - @param style - A dialog style (bitlist) containing flags chosen from standard - dialog style and the ones listed below. The default value is - equivalent to wxDEFAULT_DIALOG_STYLE | wxRESIZE_BORDER | wxOK | - wxCANCEL | wxCENTRE. - @param pos - Dialog position. Not Windows. - - @beginStyleTable - @style{wxOK} - Show an OK button. - @style{wxCANCEL} - Show a Cancel button. - @style{wxCENTRE} - Centre the message. Not Windows. - @endStyleTable - - @remarks Use ShowModal() to show the dialog. - - @beginWxPythonOnly - - For Python the two parameters @a n and @a choices are collapsed into a - multi parameter @a choices which is expected to be a Python list of - strings. - - @endWxPythonOnly - */ - wxMultiChoiceDialog(wxWindow* parent, const wxString& message, - const wxString& caption, - int n, const wxString* choices, - long style = wxCHOICEDLG_STYLE, - const wxPoint& pos = wxDefaultPosition); - wxMultiChoiceDialog(wxWindow* parent, - const wxString& message, - const wxString& caption, - const wxArrayString& choices, - long style = wxCHOICEDLG_STYLE, - const wxPoint& pos = wxDefaultPosition); - //@} - - /** - Returns array with indexes of selected items. - */ - wxArrayInt GetSelection() const; - - /** - Sets selected items from the array of selected items' indexes. - */ - void SetSelections(const wxArrayInt& selections) const; - - /** - Shows the dialog, returning either wxID_OK or wxID_CANCEL. - */ - int ShowModal(); -}; - - - -/** - @class wxSingleChoiceDialog - @wxheader{choicdlg.h} - - This class represents a dialog that shows a list of strings, and allows the - user to select one. Double-clicking on a list item is equivalent to - single-clicking and then pressing OK. - - @library{wxbase} - @category{cmndlg} - - @see @ref overview_cmndlg_singlechoice, wxMultiChoiceDialog -*/ -class wxSingleChoiceDialog : public wxDialog -{ -public: - //@{ - /** - Constructor, taking an array of wxString choices and optional client - data. - - @param parent - Parent window. - @param message - Message to show on the dialog. - @param caption - The dialog caption. - @param n - The number of choices. - @param choices - An array of strings, or a string list, containing the choices. - @param clientData - An array of client data to be associated with the items. See - GetSelectionClientData(). - @param style - A dialog style (bitlist) containing flags chosen from standard - dialog styles and the ones listed below. The default value is - equivalent to wxDEFAULT_DIALOG_STYLE | wxRESIZE_BORDER | wxOK | - wxCANCEL | wxCENTRE. - @param pos - Dialog position. Not Windows. - - @beginStyleTable - @style{wxOK} - Show an OK button. - @style{wxCANCEL} - Show a Cancel button. - @style{wxCENTRE} - Centre the message. Not Windows. - @endStyleTable - - @remarks Use ShowModal() to show the dialog. - - @beginWxPythonOnly - - For Python the two parameters @a n and @a choices are collapsed into a - multi parameter @a choices which is expected to be a Python list of - strings. - - @endWxPythonOnly - */ - wxSingleChoiceDialog(wxWindow* parent, const wxString& message, - const wxString& caption, - int n, const wxString* choices, - void** clientData = NULL, - long style = wxCHOICEDLG_STYLE, - const wxPoint& pos = wxDefaultPosition); - wxSingleChoiceDialog(wxWindow* parent, - const wxString& message, - const wxString& caption, - const wxArrayString& choices, - void** clientData = NULL, - long style = wxCHOICEDLG_STYLE, - const wxPoint& pos = wxDefaultPosition); - //@} - - /** - Returns the index of selected item. - */ - int GetSelection() const; - - /** - Returns the client data associated with the selection. - */ - char* GetSelectionClientData() const; - - /** - Returns the selected string. - */ - wxString GetStringSelection() const; - - /** - Sets the index of the initially selected item. - */ - void SetSelection(int selection) const; - - /** - Shows the dialog, returning either wxID_OK or wxID_CANCEL. - */ - int ShowModal(); -}; - - - -// ============================================================================ -// Global functions/macros -// ============================================================================ - -/** @ingroup group_funcmacro_dialog */ -//@{ - -/** - Same as wxGetSingleChoice() but returns the index representing the - selected string. If the user pressed cancel, -1 is returned. - - @header{wx/choicdlg.h} -*/ -int wxGetSingleChoiceIndex(const wxString& message, - const wxString& caption, - const wxArrayString& aChoices, - wxWindow* parent = NULL, - int x = -1, - int y = -1, - bool centre = true, - int width = 150, - int height = 200); -int wxGetSingleChoiceIndex(const wxString& message, - const wxString& caption, - int n, - const wxString& choices[], - wxWindow* parent = NULL, - int x = -1, - int y = -1, - bool centre = true, - int width = 150, - int height = 200); - -//@} - -/** @ingroup group_funcmacro_dialog */ -//@{ - -/** - Pops up a dialog box containing a message, OK/Cancel buttons and a - single-selection listbox. The user may choose an item and press OK to - return a string or Cancel to return the empty string. Use - wxGetSingleChoiceIndex() if empty string is a valid choice and if you want - to be able to detect pressing Cancel reliably. - - You may pass the list of strings to choose from either using @c choices - which is an array of @a n strings for the listbox or by using a single - @c aChoices parameter of type wxArrayString. - - If @c centre is @true, the message text (which may include new line - characters) is centred; if @false, the message is left-justified. - - @header{wx/choicdlg.h} -*/ -wxString wxGetSingleChoice(const wxString& message, - const wxString& caption, - const wxArrayString& aChoices, - wxWindow* parent = NULL, - int x = -1, - int y = -1, - bool centre = true, - int width = 150, - int height = 200); -wxString wxGetSingleChoice(const wxString& message, - const wxString& caption, - int n, - const wxString& choices[], - wxWindow* parent = NULL, - int x = -1, - int y = -1, - bool centre = true, - int width = 150, - int height = 200); - -//@} - -/** @ingroup group_funcmacro_dialog */ -//@{ - -/** - Same as wxGetSingleChoice but takes an array of client data pointers - corresponding to the strings, and returns one of these pointers or @NULL - if Cancel was pressed. The @c client_data array must have the same number - of elements as @c choices or @c aChoices! - - @header{wx/choicdlg.h} -*/ -wxString wxGetSingleChoiceData(const wxString& message, - const wxString& caption, - const wxArrayString& aChoices, - const wxString& client_data[], - wxWindow* parent = NULL, - int x = -1, - int y = -1, - bool centre = true, - int width = 150, - int height = 200); -wxString wxGetSingleChoiceData(const wxString& message, - const wxString& caption, - int n, - const wxString& choices[], - const wxString& client_data[], - wxWindow* parent = NULL, - int x = -1, - int y = -1, - bool centre = true, - int width = 150, - int height = 200); - -//@} - -/** @ingroup group_funcmacro_dialog */ -//@{ - -/** - Pops up a dialog box containing a message, OK/Cancel buttons and a - multiple-selection listbox. The user may choose an arbitrary (including 0) - number of items in the listbox whose indices will be returned in - @c selections array. The initial contents of this array will be used to - select the items when the dialog is shown. - - You may pass the list of strings to choose from either using @c choices - which is an array of @a n strings for the listbox or by using a single - @c aChoices parameter of type wxArrayString. - - If @c centre is @true, the message text (which may include new line - characters) is centred; if @false, the message is left-justified. - - @header{wx/choicdlg.h} -*/ -size_t wxGetMultipleChoices(wxArrayInt& selections, - const wxString& message, - const wxString& caption, - const wxArrayString& aChoices, - wxWindow* parent = NULL, - int x = -1, - int y = -1, - bool centre = true, - int width = 150, - int height = 200); -size_t wxGetMultipleChoices(wxArrayInt& selections, - const wxString& message, - const wxString& caption, - int n, - const wxString& choices[], - wxWindow* parent = NULL, - int x = -1, - int y = -1, - bool centre = true, - int width = 150, - int height = 200); - -//@} - diff --git a/interface/choice.h b/interface/choice.h deleted file mode 100644 index acb6033101..0000000000 --- a/interface/choice.h +++ /dev/null @@ -1,150 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: choice.h -// Purpose: interface of wxChoice -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxChoice - @wxheader{choice.h} - - A choice item is used to select one of a list of strings. Unlike a - wxListBox, only the selection is visible until the user pulls down the - menu of choices. - - @beginStyleTable - @style{wxCB_SORT} - Sorts the entries alphabetically. - @endStyleTable - - @beginEventTable{wxCommandEvent} - @event{EVT_CHOICE(id, func)} - Process a wxEVT_COMMAND_CHOICE_SELECTED event, when an item on the - list is selected. - @endEventTable - - @library{wxcore} - @category{ctrl} - - - @see wxListBox, wxComboBox, wxCommandEvent -*/ -class wxChoice : public wxControlWithItems -{ -public: - /** - Default constructor. - - @see Create(), wxValidator - */ - wxChoice(); - - //@{ - /** - Constructor, creating and showing a choice. - - @param parent - Parent window. Must not be @NULL. - @param id - Window identifier. The value wxID_ANY indicates a default value. - @param pos - Window position. - @param size - Window size. If wxDefaultSize is specified then the choice is sized - appropriately. - @param n - Number of strings with which to initialise the choice control. - @param choices - An array of strings with which to initialise the choice control. - @param style - Window style. See wxChoice. - @param validator - Window validator. - @param name - Window name. - - @see Create(), wxValidator - - @beginWxPythonOnly - - The wxChoice constructor in wxPython reduces the @a n and @a choices - arguments to a single argument, which is a list of strings. - - @endWxPythonOnly - */ - wxChoice(wxWindow* parent, wxWindowID id, - const wxPoint& pos, - const wxSize& size, int n, - const wxString choices[], - long style = 0, - const wxValidator& validator = wxDefaultValidator, - const wxString& name = "choice"); - wxChoice(wxWindow* parent, wxWindowID id, - const wxPoint& pos, - const wxSize& size, - const wxArrayString& choices, - long style = 0, - const wxValidator& validator = wxDefaultValidator, - const wxString& name = "choice"); - //@} - - /** - Destructor, destroying the choice item. - */ - ~wxChoice(); - - //@{ - /** - Creates the choice for two-step construction. See wxChoice(). - */ - bool Create(wxWindow* parent, wxWindowID id, const wxPoint& pos, - const wxSize& size, int n, - const wxString choices[], - long style = 0, - const wxValidator& validator = wxDefaultValidator, - const wxString& name = "choice"); - bool Create(wxWindow* parent, wxWindowID id, - const wxPoint& pos, - const wxSize& size, - const wxArrayString& choices, - long style = 0, - const wxValidator& validator = wxDefaultValidator, - const wxString& name = "choice"); - //@} - - /** - Gets the number of columns in this choice item. - - @remarks This is implemented for GTK and Motif only and always - returns 1 for the other platforms. - */ - int GetColumns() const; - - /** - Unlike wxControlWithItems::GetSelection() which only returns the - accepted selection value, i.e. the selection in the control once the - user closes the dropdown list, this function returns the current - selection. That is, while the dropdown list is shown, it returns the - currently selected item in it. When it is not shown, its result is the - same as for the other function. - - @since 2.6.2. - In older versions, wxControlWithItems::GetSelection() itself - behaved like this. - */ - int GetCurrentSelection() const; - - /** - Sets the number of columns in this choice item. - - @param n - Number of columns. - - @remarks This is implemented for GTK and Motif only and doesn’t do - anything under other platforms. - */ - void SetColumns(int n = 1); -}; - diff --git a/interface/choicebk.h b/interface/choicebk.h deleted file mode 100644 index 879e4e024d..0000000000 --- a/interface/choicebk.h +++ /dev/null @@ -1,78 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: choicebk.h -// Purpose: interface of wxChoicebook -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxChoicebook - @wxheader{choicebk.h} - - wxChoicebook is a class similar to wxNotebook, but uses a wxChoice control - to show the labels instead of the tabs. - - There is no documentation for this class yet but its usage is identical to - wxNotebook (except for the features clearly related to tabs only), so - please refer to that class documentation for now. You can also use the - @ref page_samples_notebook to see wxChoicebook in action. - - wxChoicebook allows the use of wxBookCtrlBase::GetControlSizer(), allowing - a program to add other controls next to the choice control. This is - particularly useful when screen space is restricted, as it often is when - wxChoicebook is being employed. - - @beginStyleTable - @style{wxCHB_DEFAULT} - Choose the default location for the labels depending on the current - platform (left everywhere except Mac where it is top). - @style{wxCHB_TOP} - Place labels above the page area. - @style{wxCHB_LEFT} - Place labels on the left side. - @style{wxCHB_RIGHT} - Place labels on the right side. - @style{wxCHB_BOTTOM} - Place labels below the page area. - @endStyleTable - - @beginEventTable{wxChoicebookEvent} - @event{EVT_CHOICEBOOK_PAGE_CHANGED(id, func)} - The page selection was changed. Processes a - wxEVT_COMMAND_LISTBOOK_PAGE_CHANGED event. - @event{EVT_CHOICEBOOK_PAGE_CHANGING(id, func)} - The page selection is about to be changed. Processes a - wxEVT_COMMAND_CHOICEBOOK_PAGE_CHANGING event. This event can be - vetoed (using wxNotifyEvent::Veto()). - @endEventTable - - @library{wxcore} - @category{miscwnd} - - @see @ref overview_bookctrl, wxNotebook, @ref page_samples_notebook - - @todo Write up wxBookCtrlBase documentation, where most of this class' - functionality comes from. -*/ -class wxChoicebook : public wxBookCtrlBase -{ -public: - //@{ - /** - Constructs a choicebook control. - */ - wxChoicebook(); - wxChoicebook(wxWindow* parent, wxWindowID id, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = 0, - const wxString& name = wxEmptyStr); - //@} - - /** - Returns the wxChoice associated with the control. - */ - wxChoice * GetChoiceCtrl() const; -}; - diff --git a/interface/clipbrd.h b/interface/clipbrd.h deleted file mode 100644 index 307793295c..0000000000 --- a/interface/clipbrd.h +++ /dev/null @@ -1,179 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: clipbrd.h -// Purpose: interface of wxClipboard -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - The backwards compatible access macro that returns the global clipboard - object pointer. -*/ -#define wxTheClipboard - -/** - @class wxClipboard - @wxheader{clipbrd.h} - - A class for manipulating the clipboard. - - To use the clipboard, you call member functions of the global - ::wxTheClipboard object. - - See the @ref overview_dataobject for further information. - - Call wxClipboard::Open() to get ownership of the clipboard. If this - operation returns @true, you now own the clipboard. Call - wxClipboard::SetData() to put data on the clipboard, or - wxClipboard::GetData() to retrieve data from the clipboard. Call - wxClipboard::Close() to close the clipboard and relinquish ownership. You - should keep the clipboard open only momentarily. - - For example: - - @code - // Write some text to the clipboard - if (wxTheClipboard->Open()) - { - // This data objects are held by the clipboard, - // so do not delete them in the app. - wxTheClipboard->SetData( new wxTextDataObject("Some text") ); - wxTheClipboard->Close(); - } - - // Read some text - if (wxTheClipboard->Open()) - { - if (wxTheClipboard->IsSupported( wxDF_TEXT )) - { - wxTextDataObject data; - wxTheClipboard->GetData( data ); - wxMessageBox( data.GetText() ); - } - wxTheClipboard->Close(); - } - @endcode - - @library{wxcore} - @category{dnd} - - @see @ref overview_dnd, @ref overview_dataobject, wxDataObject -*/ -class wxClipboard : public wxObject -{ -public: - /** - Default constructor. - */ - wxClipboard(); - - /** - Destructor. - */ - ~wxClipboard(); - - /** - Call this function to add the data object to the clipboard. You may - call this function repeatedly after having cleared the clipboard using - Clear(). - - After this function has been called, the clipboard owns the data, so do - not delete the data explicitly. - - @see SetData() - */ - bool AddData(wxDataObject* data); - - /** - Clears the global clipboard object and the system's clipboard if - possible. - */ - void Clear(); - - /** - Call this function to close the clipboard, having opened it with - Open(). - */ - void Close(); - - /** - Flushes the clipboard: this means that the data which is currently on - clipboard will stay available even after the application exits - (possibly eating memory), otherwise the clipboard will be emptied on - exit. - - @return @false if the operation is unsuccessful for any reason. - */ - bool Flush(); - - /** - Call this function to fill @a data with data on the clipboard, if - available in the required format. Returns @true on success. - */ - bool GetData(wxDataObject& data); - - /** - Returns @true if the clipboard has been opened. - */ - bool IsOpened() const; - - /** - Returns @true if there is data which matches the data format of the - given data object currently @b available on the clipboard. - - @todo The name of this function is misleading. This should be renamed - to something that more accurately indicates what it does. - */ - bool IsSupported(const wxDataFormat& format); - - /** - Returns @true if we are using the primary selection, @false if - clipboard one. - - @see UsePrimarySelection() - */ - bool IsUsingPrimarySelection() const; - - /** - Call this function to open the clipboard before calling SetData() and - GetData(). - - Call Close() when you have finished with the clipboard. You should keep - the clipboard open for only a very short time. - - @return @true on success. This should be tested (as in the sample - shown above). - */ - bool Open(); - - /** - Call this function to set the data object to the clipboard. This - function will clear all previous contents in the clipboard, so calling - it several times does not make any sense. - - After this function has been called, the clipboard owns the data, so do - not delete the data explicitly. - - @see AddData() - */ - bool SetData(wxDataObject* data); - - /** - On platforms supporting it (all X11-based ports), wxClipboard uses the - CLIPBOARD X11 selection by default. When this function is called with - @true, all subsequent clipboard operations will use PRIMARY selection - until this function is called again with @false. - - On the other platforms, there is no PRIMARY selection and so all - clipboard operations will fail. This allows to implement the standard - X11 handling of the clipboard which consists in copying data to the - CLIPBOARD selection only when the user explicitly requests it (i.e. by - selecting the "Copy" menu command) but putting the currently selected - text into the PRIMARY selection automatically, without overwriting the - normal clipboard contents with the currently selected text on the other - platforms. - */ - void UsePrimarySelection(bool primary = true); -}; - diff --git a/interface/clntdata.h b/interface/clntdata.h deleted file mode 100644 index 62d7a86429..0000000000 --- a/interface/clntdata.h +++ /dev/null @@ -1,141 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: clntdata.h -// Purpose: interface of wxClientData[Container] and wxStringClientData -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxClientDataContainer - @wxheader{clntdata.h} - - This class is a mixin that provides storage and management of "client - data." This data can either be of type void - in which case the data - @e container does not take care of freeing the data again or it is of - type wxClientData or its derivatives. In that case the container will free - the memory itself later. Note that you @e must not assign both void data - and data derived from the wxClientData class to a container. - - @note This functionality is currently duplicated in wxEvtHandler in order - to avoid having more than one vtable in that class hierarchy. - - @library{wxbase} - @category{containers} - - @see wxEvtHandler, wxClientData -*/ -class wxClientDataContainer -{ -public: - /** - Default constructor. - */ - wxClientDataContainer(); - - /** - Destructor. - */ - ~wxClientDataContainer(); - - /** - Get the untyped client data. - */ - void* GetClientData() const; - - /** - Get a pointer to the client data object. - */ - wxClientData* GetClientObject() const; - - /** - Set the untyped client data. - */ - void SetClientData(void* data); - - /** - Set the client data object. Any previous object will be deleted. - */ - void SetClientObject(wxClientData* data); -}; - - - -/** - @class wxClientData - @wxheader{clntdata.h} - - All classes deriving from wxEvtHandler (such as all controls and wxApp) can - hold arbitrary data which is here referred to as "client data". This is - useful e.g. for scripting languages which need to handle shadow objects for - most of wxWidgets' classes and which store a handle to such a shadow class - as client data in that class. This data can either be of type void - in - which case the data @e container does not take care of freeing the data - again or it is of type wxClientData or its derivatives. In that case the - container (e.g. a control) will free the memory itself later. Note that you - @e must not assign both void data and data derived from the wxClientData - class to a container. - - Some controls can hold various items and these controls can additionally - hold client data for each item. This is the case for wxChoice, wxComboBox - and wxListBox. wxTreeCtrl has a specialized class wxTreeItemData for each - item in the tree. - - If you want to add client data to your own classes, you may use the mix-in - class wxClientDataContainer. - - @library{wxbase} - @category{containers} - - @see wxEvtHandler, wxTreeItemData, wxStringClientData, - wxClientDataContainer -*/ -class wxClientData -{ -public: - /** - Constructor. - */ - wxClientData(); - - /** - Virtual destructor. - */ - ~wxClientData(); -}; - - - -/** - @class wxStringClientData - @wxheader{clntdata.h} - - Predefined client data class for holding a string. - - @library{wxbase} - @category{containers} -*/ -class wxStringClientData : public wxClientData -{ -public: - /** - Default constructor. - */ - wxStringClientData(); - - /** - Create client data with string. - */ - wxStringClientData(const wxString& data); - - /** - Get string client data. - */ - const wxString GetData() const; - - /** - Set string client data. - */ - void SetData(const wxString& data); -}; - diff --git a/interface/clrpicker.h b/interface/clrpicker.h deleted file mode 100644 index 062c134d13..0000000000 --- a/interface/clrpicker.h +++ /dev/null @@ -1,143 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: clrpicker.h -// Purpose: interface of wxColourPickerCtrl -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxColourPickerCtrl - @wxheader{clrpicker.h} - - This control allows the user to select a colour. The generic implementation - is a button which brings up a wxColourDialog when clicked. Native - implementation may differ but this is usually a (small) widget which give - access to the colour-chooser dialog. It is only available if - @c wxUSE_COLOURPICKERCTRL is set to 1 (the default). - - @beginStyleTable - @style{wxCLRP_DEFAULT_STYLE} - The default style: 0. - @style{wxCLRP_USE_TEXTCTRL} - Creates a text control to the left of the picker button which is - completely managed by the wxColourPickerCtrl and which can be used - by the user to specify a colour (see SetColour). The text control - is automatically synchronized with button's value. Use functions - defined in wxPickerBase to modify the text control. - @style{wxCLRP_SHOW_LABEL} - Shows the colour in HTML form (AABBCC) as colour button label - (instead of no label at all). - @endStyleTable - - @beginEventTable{wxColourPickerEvent} - @event{EVT_COLOURPICKER_CHANGED(id, func)} - The user changed the colour selected in the control either using the - button or using text control (see @c wxCLRP_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} - - - @see wxColourDialog, wxColourPickerEvent -*/ -class wxColourPickerCtrl : public wxPickerBase -{ -public: - /** - Initializes the object and calls Create() with all the parameters. - */ - wxColourPickerCtrl(wxWindow* parent, wxWindowID id, - const wxColour& colour = wxBLACK, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = wxCLRP_DEFAULT_STYLE, - const wxValidator& validator = wxDefaultValidator, - const wxString& name = "colourpickerctrl"); - - /** - Creates a colour picker with the given arguments. - - @param parent - Parent window, must not be non-@NULL. - @param id - The identifier for the control. - @param colour - The initial colour shown in the control. - @param pos - Initial position. - @param size - Initial size. - @param style - The window style, see wxCRLP_* flags. - @param validator - Validator which can be used for additional date checks. - @param name - Control name. - - @return @true if the control was successfully created or @false if - creation failed. - */ - bool Create(wxWindow* parent, wxWindowID id, - const wxColour& colour = wxBLACK, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = wxCLRP_DEFAULT_STYLE, - const wxValidator& validator = wxDefaultValidator, - const wxString& name = "colourpickerctrl"); - - /** - Returns the currently selected colour. - */ - wxColour GetColour() const; - - //@{ - /** - Sets the currently selected colour. See wxColour::Set(). - */ - void SetColour(const wxColour& col); - void SetColour(const wxString& colname); - //@} -}; - - - -/** - @class wxColourPickerEvent - @wxheader{clrpicker.h} - - This event class is used for the events generated by wxColourPickerCtrl. - - @beginEventTable{wxColourPickerEvent} - @event{EVT_COLOURPICKER_CHANGED(id, func)} - Generated whenever the selected colour changes. - @endEventTable - - @library{wxcore} - @category{events} - - @see wxColourPickerCtrl -*/ -class wxColourPickerEvent : public wxCommandEvent -{ -public: - /** - The constructor is not normally used by the user code. - */ - wxColourPickerEvent(wxObject* generator, int id, - const wxColour& colour); - - /** - Retrieve the colour the user has just selected. - */ - wxColour GetColour() const; - - /** - Set the colour associated with the event. - */ - void SetColour(const wxColour& pos); -}; - diff --git a/interface/cmdline.h b/interface/cmdline.h deleted file mode 100644 index 2196edb66a..0000000000 --- a/interface/cmdline.h +++ /dev/null @@ -1,450 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: cmdline.h -// Purpose: interface of wxCmdLineParser -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - wxCmdLineEntryDesc::flags field is a combination of these bit masks. - - Notice that by default (i.e. if flags are just 0), options are optional - (sic) and each call to wxCmdLineEntryDesc::AddParam() allows one more - parameter - this may be changed by giving non-default flags to it, i.e. use - wxCMD_LINE_OPTION_MANDATORY to require that the option is given and - wxCMD_LINE_PARAM_OPTIONAL to make a parameter optional. Also, - wxCMD_LINE_PARAM_MULTIPLE may be specified if the programs accepts a - variable number of parameters - but it only can be given for the last - parameter in the command line description. If you use this flag, you will - probably need to use wxCmdLineEntryDesc::GetParamCount() to retrieve the - number of parameters effectively specified after calling - wxCmdLineEntryDesc::Parse(). - - wxCMD_LINE_NEEDS_SEPARATOR can be specified to require a separator (either - a colon, an equal sign or white space) between the option name and its - value. By default, no separator is required. -*/ -enum -{ - wxCMD_LINE_OPTION_MANDATORY = 0x01, ///< This option must be given. - wxCMD_LINE_PARAM_OPTIONAL = 0x02, ///< The parameter may be omitted. - wxCMD_LINE_PARAM_MULTIPLE = 0x04, ///< The parameter may be repeated. - wxCMD_LINE_OPTION_HELP = 0x08, ///< This option is a help request. - wxCMD_LINE_NEEDS_SEPARATOR = 0x10 ///< Must have a separator before the value. -}; - -/** - The possible values of wxCmdLineEntryDesc::type which specifies the type of - the value accepted by an option. -*/ -enum wxCmdLineParamType -{ - wxCMD_LINE_VAL_STRING, - wxCMD_LINE_VAL_NUMBER, - wxCMD_LINE_VAL_DATE, - wxCMD_LINE_VAL_DOUBLE, - wxCMD_LINE_VAL_NONE -}; - -/** - The type of a command line entity used for wxCmdLineEntryDesc::kind. -*/ -enum wxCmdLineEntryType -{ - wxCMD_LINE_SWITCH, - wxCMD_LINE_OPTION, - wxCMD_LINE_PARAM, - wxCMD_LINE_USAGE_TEXT, - wxCMD_LINE_NONE ///< Use this to terminate the list. -}; - -/** - The structure wxCmdLineEntryDesc is used to describe the one command line - switch, option or parameter. An array of such structures should be passed - to wxCmdLineParser::SetDesc(). Also, the meanings of parameters of the - wxCmdLineParser::AddXXX() functions are the same as of the corresponding - fields in this structure. - - The field @c shortName is the usual, short, name of the switch or the - option. @c longName is the corresponding long name or empty if the option - has no long name. Both of these fields are unused for the parameters. Both - the short and long option names can contain only letters, digits and the - underscores. - - @c description is used by the wxCmdLineEntryDesc::Usage() method to - construct a help message explaining the syntax of the program. -*/ -struct wxCmdLineEntryDesc -{ - wxCmdLineEntryType kind; - const char *shortName; - const char *longName; - const char *description; - wxCmdLineParamType type; - int flags; -}; - -/** - @class wxCmdLineParser - @wxheader{cmdline.h} - - wxCmdLineParser is a class for parsing the command line. - - It has the following features: - - - distinguishes options, switches and parameters - - allows option grouping - - allows both short and long options - - automatically generates the usage message from the command line description - - checks types of the options values (number, date, ...). - - To use it you should follow these steps: - - -# @ref cmdlineparser_construction "Construct" an object of this class - giving it the command line to parse and optionally its description or - use the @c AddXXX() functions later. - -# Call Parse(). - -# Use Found() to retrieve the results. - - In the documentation below the following terminology is used: - - - @b switch: This is a boolean option which can be given or not, but which - doesn't have any value. We use the word switch to distinguish - such boolean options from more generic options like those - described below. For example, @c "-v" might be a switch - meaning "enable verbose mode". - - @b option: Option for us here is something which comes with a value 0 - unlike a switch. For example, @c -o: @c filename might be an - option for specifying the name of the output file. - - @b parameter: This is a required program argument. - - @b text: This is a text which can be shown in usage information. - - - @section cmdlineparser_construction Construction - - Before Parse() can be called, the command line parser object must have the - command line to parse and also the rules saying which switches, options and - parameters are valid - this is called command line description in what - follows. - - You have complete freedom of choice as to when specify the required - information, the only restriction is that it must be done before calling - Parse(). - - To specify the command line to parse you may use either one of constructors - accepting it (wxCmdLineParser(int, char**) or - wxCmdLineParser(const wxString&) usually) or, if you use the default - constructor, you can do it later by calling SetCmdLine(). - - The same holds for command line description: it can be specified either in - the constructor (with or without the command line itself) or constructed - later using either SetDesc() or combination of AddSwitch(), AddOption(), - AddParam() and AddUsageText() methods. - - Using constructors or SetDesc() uses a (usually const static) table - containing the command line description. If you want to decide which - options to accept during the run-time, using one of the AddXXX() functions - above might be preferable. - - - @section cmdlineparser_customization Customization - - wxCmdLineParser has several global options which may be changed by the - application. All of the functions described in this section should be - called before Parse(). - - First global option is the support for long (also known as GNU-style) - options. The long options are the ones which start with two dashes and look - like "--verbose", i.e. they generally are complete words and not some - abbreviations of them. As long options are used by more and more - applications, they are enabled by default, but may be disabled with - DisableLongOptions(). - - Another global option is the set of characters which may be used to start - an option (otherwise, the word on the command line is assumed to be a - parameter). Under Unix, @c "-" is always used, but Windows has at least two - common choices for this: @c "-" and @c "/". Some programs also use "+". The - default is to use what suits most the current platform, but may be changed - with SetSwitchChars() method. - - Finally, SetLogo() can be used to show some application-specific text - before the explanation given by Usage() function. - - - @section cmdlineparser_parsing Parsing the Command Line - - After the command line description was constructed and the desired options - were set, you can finally call Parse() method. It returns 0 if the command - line was correct and was parsed, -1 if the help option was specified (this - is a separate case as, normally, the program will terminate after this) or - a positive number if there was an error during the command line parsing. - - In the latter case, the appropriate error message and usage information are - logged by wxCmdLineParser itself using the standard wxWidgets logging - functions. - - - @section cmdlineparser_results Getting Results - - After calling Parse() (and if it returned 0), you may access the results of - parsing using one of overloaded Found() methods. - - For a simple switch, you will simply call Found to determine if the switch - was given or not, for an option or a parameter, you will call a version of - Found() which also returns the associated value in the provided variable. - All Found() functions return true if the switch or option were found in the - command line or false if they were not specified. - - - @library{wxbase} - @category{appmanagement} - - @see wxApp::argc, wxApp::argv, @ref page_samples_console "Console Sample" -*/ -class wxCmdLineParser -{ -public: - /** - Default constructor, you must use SetCmdLine() later. - */ - wxCmdLineParser(); - - //@{ - /** - Constructor which specifies the command line to parse. This is the - traditional (Unix) command line format. The parameters @a argc and - @a argv have the same meaning as the typical @c main() function. - - The second overloaded constructor is only available in Unicode build. - The first one is available in both ANSI and Unicode modes because under - some platforms the command line arguments are passed as ASCII strings - even to Unicode programs. - */ - wxCmdLineParser(int argc, char** argv); - wxCmdLineParser(int argc, wchar_t** argv); - //@} - - /** - Constructor which specify the command line to parse in Windows format. - The parameter cmdline has the same meaning as the corresponding - parameter of @c WinMain(). - */ - wxCmdLineParser(const wxString& cmdline); - - /** - Specifies the @ref SetDesc() "command line description" but not the - command line. You must use SetCmdLine() later. - */ - wxCmdLineParser(const wxCmdLineEntryDesc* desc); - - /** - Specifies both the command line (in Unix format) and the - @ref SetDesc() "command line description". - */ - wxCmdLineParser(const wxCmdLineEntryDesc* desc, int argc, char** argv); - - /** - Specifies both the command line (in Windows format) and the - @ref SetDesc() "command line description". - */ - wxCmdLineParser(const wxCmdLineEntryDesc* desc, - const wxString& cmdline); - - /** - Frees resources allocated by the object. - - @note This destructor is not virtual, don't use this class - polymorphically. - */ - ~wxCmdLineParser(); - - /** - Add an option @a name with an optional long name @a lng (no long name - if it is empty, which is default) taking a value of the given type - (string by default) to the command line description. - */ - void AddOption(const wxString& name, - const wxString& lng = wxEmptyString, - const wxString& desc = wxEmptyString, - wxCmdLineParamType type = wxCMD_LINE_VAL_STRING, - int flags = 0); - - /** - Add a parameter of the given @a type to the command line description. - */ - void AddParam(const wxString& desc = wxEmptyString, - wxCmdLineParamType type = wxCMD_LINE_VAL_STRING, - int flags = 0); - - /** - Add a switch @a name with an optional long name @a lng (no long name if - it is empty, which is default), description @a desc and flags @a flags - to the command line description. - */ - void AddSwitch(const wxString& name, - const wxString& lng = wxEmptyString, - const wxString& desc = wxEmptyString, - int flags = 0); - - /** - Add a string @a text to the command line description shown by Usage(). - - @since 2.9.0 - */ - void AddUsageText(const wxString& text); - - /** - Returns @true if long options are enabled, otherwise @false. - - @see EnableLongOptions() - */ - bool AreLongOptionsEnabled() const; - - /** - Breaks down the string containing the full command line in words. The - words are separated by whitespace. The quotes can be used in the input - string to quote the white space and the back slashes can be used to - quote the quotes. - */ - static wxArrayString ConvertStringToArgs(const wxChar cmdline); - - /** - Identical to EnableLongOptions(@false). - */ - void DisableLongOptions(); - - /** - Enable or disable support for the long options. - - As long options are not (yet) POSIX-compliant, this option allows to - disable them. - - @see @ref cmdlineparser_customization and AreLongOptionsEnabled() - */ - void EnableLongOptions(bool enable = true); - - /** - Returns @true if the given switch was found, @false otherwise. - */ - bool Found(const wxString& name) const; - - /** - Returns true if an option taking a string value was found and stores - the value in the provided pointer (which should not be @NULL). - */ - bool Found(const wxString& name, wxString* value) const; - - /** - Returns @true if an option taking an integer value was found and stores - the value in the provided pointer (which should not be @NULL). - */ - bool Found(const wxString& name, long* value) const; - - /** - Returns @true if an option taking a float value was found and stores - the value in the provided pointer (which should not be @NULL). - */ - bool Found(const wxString& name, double* value) const; - - /** - Returns @true if an option taking a date value was found and stores the - value in the provided pointer (which should not be @NULL). - */ - bool Found(const wxString& name, wxDateTime* value) const; - - /** - Returns the value of Nth parameter (as string only). - */ - wxString GetParam(size_t n = 0) const; - - /** - Returns the number of parameters found. This function makes sense - mostly if you had used @c wxCMD_LINE_PARAM_MULTIPLE flag. - */ - size_t GetParamCount() const; - - /** - Parse the command line, return 0 if ok, -1 if @c "-h" or @c "--help" - option was encountered and the help message was given or a positive - value if a syntax error occurred. - - @param giveUsage - If @true (default), the usage message is given if a syntax error - was encountered while parsing the command line or if help was - requested. If @false, only error messages about possible syntax - errors are given, use Usage to show the usage message from the - caller if needed. - */ - int Parse(bool giveUsage = true); - - //@{ - /** - Set the command line to parse after using one of the constructors which - don't do it. - */ - void SetCmdLine(int argc, char** argv); - void SetCmdLine(int argc, wchar_t** argv); - void SetCmdLine(const wxString& cmdline); - //@} - - /** - Constructs the command line description. - - Take the command line description from the wxCMD_LINE_NONE terminated - table. - - Example of usage: - - @code - static const wxCmdLineEntryDesc cmdLineDesc[] = - { - { wxCMD_LINE_SWITCH, "v", "verbose", "be verbose" }, - { wxCMD_LINE_SWITCH, "q", "quiet", "be quiet" }, - - { wxCMD_LINE_OPTION, "o", "output", "output file" }, - { wxCMD_LINE_OPTION, "i", "input", "input dir" }, - { wxCMD_LINE_OPTION, "s", "size", "output block size", wxCMD_LINE_VAL_NUMBER }, - { wxCMD_LINE_OPTION, "d", "date", "output file date", wxCMD_LINE_VAL_DATE }, - - { wxCMD_LINE_PARAM, NULL, NULL, "input file", wxCMD_LINE_VAL_STRING, wxCMD_LINE_PARAM_MULTIPLE }, - - { wxCMD_LINE_NONE } - }; - - wxCmdLineParser parser; - - parser.SetDesc(cmdLineDesc); - @endcode - */ - void SetDesc(const wxCmdLineEntryDesc* desc); - - /** - The @a logo is some extra text which will be shown by Usage() method. - */ - void SetLogo(const wxString& logo); - - /** - @a switchChars contains all characters with which an option or switch - may start. Default is @c "-" for Unix, @c "-/" for Windows. - */ - void SetSwitchChars(const wxString& switchChars); - - /** - Give the standard usage message describing all program options. It will - use the options and parameters descriptions specified earlier, so the - resulting message will not be helpful to the user unless the - descriptions were indeed specified. - - @see SetLogo() - */ - void Usage() const; - - /** - Return the string containing the program usage description. - - Call Usage() to directly show this string to the user. - */ - wxString GetUsageString() const; -}; - diff --git a/interface/cmdproc.h b/interface/cmdproc.h deleted file mode 100644 index a0bd1d0a2f..0000000000 --- a/interface/cmdproc.h +++ /dev/null @@ -1,242 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: cmdproc.h -// Purpose: interface of wxCommandProcessor and wxCommand -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxCommand - @wxheader{cmdproc.h} - - wxCommand is a base class for modelling an application command, which is an - action usually performed by selecting a menu item, pressing a toolbar - button or any other means provided by the application to change the data or - view. - - @library{wxcore} - @category{docview} - - @see @ref overview_docview_wxcommand -*/ -class wxCommand : public wxObject -{ -public: - /** - Constructor. wxCommand is an abstract class, so you will need to derive - a new class and call this constructor from your own constructor. - - @param canUndo - Tells the command processor whether this command is undo-able. You - can achieve the same functionality by overriding the CanUndo() - member function (if for example the criteria for undoability is - context-dependent). - @param name - Must be supplied for the command processor to display the command - name in the application's edit menu. - */ - wxCommand(bool canUndo = false, const wxString& name = NULL); - - /** - Destructor. - */ - ~wxCommand(); - - /** - Returns @true if the command can be undone, @false otherwise. - */ - bool CanUndo(); - - /** - Override this member function to execute the appropriate action when - called. - - @return @true to indicate that the action has taken place, @false - otherwise. Returning @false will indicate to the command - processor that the action is not undoable and should not be - added to the command history. - */ - bool Do(); - - /** - Returns the command name. - */ - wxString GetName(); - - /** - Override this member function to un-execute a previous Do. - - How you implement this command is totally application dependent, but - typical strategies include: - - - Perform an inverse operation on the last modified piece of data in - the document. When redone, a copy of data stored in command is pasted - back or some operation reapplied. This relies on the fact that you - know the ordering of Undos; the user can never Undo at an arbitrary - position in the command history. - - Restore the entire document state (perhaps using document - transactioning). Potentially very inefficient, but possibly easier to - code if the user interface and data are complex, and an "inverse - execute" operation is hard to write. The docview sample uses the - first method, to remove or restore segments in the drawing. - - @return @true to indicate that the action has taken place, @false - otherwise. Returning @false will indicate to the command - processor that the action is not redoable and no change should - be made to the command history. - */ - bool Undo(); -}; - - - -/** - @class wxCommandProcessor - @wxheader{cmdproc.h} - - wxCommandProcessor is a class that maintains a history of wxCommands, with - undo/redo functionality built-in. Derive a new class from this if you want - different behaviour. - - @library{wxcore} - @category{docview} - - @see @ref overview_docview_wxcommandproc, wxCommand -*/ -class wxCommandProcessor : public wxObject -{ -public: - /** - Constructor. - - @param maxCommands - May be set to a positive integer to limit the number of commands - stored to it, otherwise (and by default) the list of commands can - grow arbitrarily. - */ - wxCommandProcessor(int maxCommands = -1); - - /** - Destructor. - */ - ~wxCommandProcessor(); - - /** - Returns @true if the currently-active command can be undone, @false - otherwise. - */ - virtual bool CanUndo(); - - /** - Deletes all commands in the list and sets the current command pointer - to @NULL. - */ - virtual void ClearCommands(); - - /** - Returns the list of commands. - */ - wxList& GetCommands() const; - - /** - Returns the edit menu associated with the command processor. - */ - wxMenu* GetEditMenu() const; - - /** - Returns the maximum number of commands that the command processor - stores. - */ - int GetMaxCommands() const; - - /** - Returns the string that will be appended to the Redo menu item. - */ - const wxString& GetRedoAccelerator() const; - - /** - Returns the string that will be shown for the redo menu item. - */ - wxString GetRedoMenuLabel() const; - - /** - Returns the string that will be appended to the Undo menu item. - */ - const wxString& GetUndoAccelerator() const; - - /** - Returns the string that will be shown for the undo menu item. - */ - wxString GetUndoMenuLabel() const; - - /** - Initializes the command processor, setting the current command to the - last in the list (if any), and updating the edit menu (if one has been - specified). - */ - virtual void Initialize(); - - /** - Returns a boolean value that indicates if changes have been made since - the last save operation. This only works if MarkAsSaved() is called - whenever the project is saved. - */ - virtual bool IsDirty(); - - /** - You must call this method whenever the project is saved if you plan to - use IsDirty(). - */ - virtual void MarkAsSaved(); - - /** - Executes (redoes) the current command (the command that has just been - undone if any). - */ - virtual bool Redo(); - - /** - Tells the command processor to update the Undo and Redo items on this - menu as appropriate. Set this to @NULL if the menu is about to be - destroyed and command operations may still be performed, or the command - processor may try to access an invalid pointer. - */ - void SetEditMenu(wxMenu* menu); - - /** - Sets the menu labels according to the currently set menu and the - current command state. - */ - void SetMenuStrings(); - - /** - Sets the string that will be appended to the Redo menu item. - */ - void SetRedoAccelerator(const wxString& accel); - - /** - Sets the string that will be appended to the Undo menu item. - */ - void SetUndoAccelerator(const wxString& accel); - - /** - Submits a new command to the command processor. The command processor - calls wxCommand::Do() to execute the command; if it succeeds, the - command is stored in the history list, and the associated edit menu (if - any) updated appropriately. If it fails, the command is deleted - immediately. Once Submit() has been called, the passed command should - not be deleted directly by the application. - - @param storeIt - Indicates whether the successful command should be stored in the - history list. - */ - virtual bool Submit(wxCommand* command, bool storeIt = true); - - /** - Undoes the last command executed. - */ - virtual bool Undo(); -}; - diff --git a/interface/cmndata.h b/interface/cmndata.h deleted file mode 100644 index 70c26781d1..0000000000 --- a/interface/cmndata.h +++ /dev/null @@ -1,846 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: cmndata.h -// Purpose: interface of common wx*Data classes (font, colour, print) -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxFontData - @wxheader{cmndata.h} - - This class holds a variety of information related to font dialogs. - - @library{wxcore} - @category{cmndlg} - - @see @ref overview_cmndlg_font, wxFont, wxFontDialog -*/ -class wxFontData : public wxObject -{ -public: - /** - Constructor. Initializes @e fontColour to black, @e showHelp to @false, - @e allowSymbols to @true, @e enableEffects to @true, @e minSize to 0 - and @e maxSize to 0. - */ - wxFontData(); - - /** - Enables or disables "effects" under Windows or generic only. This - refers to the controls for manipulating colour, strikeout and underline - properties. - - The default value is @true. - */ - void EnableEffects(bool enable); - - /** - Under Windows, returns a flag determining whether symbol fonts can be - selected. Has no effect on other platforms. - - The default value is @true. - */ - bool GetAllowSymbols(); - - /** - Gets the font chosen by the user if the user pressed OK - (wxFontDialog::ShowModal() returned wxID_OK). - */ - wxFont GetChosenFont(); - - /** - Gets the colour associated with the font dialog. - - The default value is black. - */ - wxColour& GetColour(); - - /** - Determines whether "effects" are enabled under Windows. This refers to - the controls for manipulating colour, strikeout and underline - properties. - - The default value is @true. - */ - bool GetEnableEffects(); - - /** - Gets the font that will be initially used by the font dialog. This - should have previously been set by the application. - */ - wxFont GetInitialFont(); - - /** - Returns @true if the Help button will be shown (Windows only). - - The default value is @false. - */ - bool GetShowHelp(); - - /** - Under Windows, determines whether symbol fonts can be selected. Has no - effect on other platforms. - - The default value is @true. - */ - void SetAllowSymbols(bool allowSymbols); - - /** - Sets the font that will be returned to the user (for internal use - only). - */ - void SetChosenFont(const wxFont& font); - - /** - Sets the colour that will be used for the font foreground colour. - - The default colour is black. - */ - void SetColour(const wxColour& colour); - - /** - Sets the font that will be initially used by the font dialog. - */ - void SetInitialFont(const wxFont& font); - - /** - Sets the valid range for the font point size (Windows only). - - The default is 0, 0 (unrestricted range). - */ - void SetRange(int min, int max); - - /** - Determines whether the Help button will be displayed in the font dialog - (Windows only). - - The default value is @false. - */ - void SetShowHelp(bool showHelp); - - /** - Assignment operator for the font data. - */ - void operator =(const wxFontData& data); -}; - - - -/** - @class wxPageSetupDialogData - @wxheader{cmndata.h} - - This class holds a variety of information related to wxPageSetupDialog. - - It contains a wxPrintData member which is used to hold basic printer - configuration data (as opposed to the user-interface configuration settings - stored by wxPageSetupDialogData). - - @library{wxcore} - @category{printing} - - @see @ref overview_printing, wxPageSetupDialog -*/ -class wxPageSetupDialogData : public wxObject -{ -public: - /** - Default constructor. - */ - wxPageSetupDialogData(); - - /** - Copy constructor. - */ - wxPageSetupDialogData(wxPageSetupDialogData& data); - - /** - Construct an object from a print data object. - */ - wxPageSetupDialogData(wxPrintData& printData); - - /** - Destructor. - */ - ~wxPageSetupDialogData(); - - /** - Enables or disables the "Help" button (Windows only). - */ - void EnableHelp(bool flag); - - /** - Enables or disables the margin controls (Windows only). - */ - void EnableMargins(bool flag); - - /** - Enables or disables the orientation control (Windows only). - */ - void EnableOrientation(bool flag); - - /** - Enables or disables the paper size control (Windows only). - */ - void EnablePaper(bool flag); - - /** - Enables or disables the "Printer" button, which invokes a printer setup - dialog. - */ - void EnablePrinter(bool flag); - - /** - Returns @true if the dialog will simply return default printer - information (such as orientation) instead of showing a dialog (Windows - only). - */ - bool GetDefaultInfo() const; - - /** - Returns @true if the page setup dialog will take its minimum margin - values from the currently selected printer properties (Windows only). - */ - bool GetDefaultMinMargins() const; - - /** - Returns @true if the printer setup button is enabled. - */ - bool GetEnableHelp() const; - - /** - Returns @true if the margin controls are enabled (Windows only). - */ - bool GetEnableMargins() const; - - /** - Returns @true if the orientation control is enabled (Windows only). - */ - bool GetEnableOrientation() const; - - /** - Returns @true if the paper size control is enabled (Windows only). - */ - bool GetEnablePaper() const; - - /** - Returns @true if the printer setup button is enabled. - */ - bool GetEnablePrinter() const; - - /** - Returns the right (x) and bottom (y) margins in millimetres. - */ - wxPoint GetMarginBottomRight() const; - - /** - Returns the left (x) and top (y) margins in millimetres. - */ - wxPoint GetMarginTopLeft() const; - - /** - Returns the right (x) and bottom (y) minimum margins the user can enter - (Windows only). Units are in millimetres. - */ - wxPoint GetMinMarginBottomRight() const; - - /** - Returns the left (x) and top (y) minimum margins the user can enter - (Windows only). Units are in millimetres. - */ - wxPoint GetMinMarginTopLeft() const; - - /** - Returns the paper id (stored in the internal wxPrintData object). - - @see wxPrintData::SetPaperId() - */ - wxPaperSize GetPaperId() const; - - /** - Returns the paper size in millimetres. - */ - wxSize GetPaperSize() const; - - /** - Returns a reference to the print data associated with this object. - */ - wxPrintData GetPrintData(); - - /** - Returns @true if the print data associated with the dialog data is - valid. This can return @false on Windows if the current printer is not - set, for example. On all other platforms, it returns @true. - */ - bool IsOk() const; - - /** - Pass @true if the dialog will simply return default printer information - (such as orientation) instead of showing a dialog (Windows only). - */ - void SetDefaultInfo(bool flag); - - /** - Pass @true if the page setup dialog will take its minimum margin values - from the currently selected printer properties (Windows only). Units - are in millimetres. - */ - void SetDefaultMinMargins(bool flag); - - /** - Sets the right (x) and bottom (y) margins in millimetres. - */ - void SetMarginBottomRight(const wxPoint& pt); - - /** - Sets the left (x) and top (y) margins in millimetres. - */ - void SetMarginTopLeft(const wxPoint& pt); - - /** - Sets the right (x) and bottom (y) minimum margins the user can enter - (Windows only). Units are in millimetres. - */ - void SetMinMarginBottomRight(const wxPoint& pt); - - /** - Sets the left (x) and top (y) minimum margins the user can enter - (Windows only). Units are in millimetres. - */ - void SetMinMarginTopLeft(const wxPoint& pt); - - /** - Sets the paper size id. Calling this function overrides the explicit - paper dimensions passed in SetPaperSize(). - - @see wxPrintData::SetPaperId() - */ - void SetPaperId(wxPaperSize& id); - - /** - Sets the paper size in millimetres. If a corresponding paper id is - found, it will be set in the internal wxPrintData object, otherwise the - paper size overrides the paper id. - */ - void SetPaperSize(const wxSize& size); - - /** - Sets the print data associated with this object. - */ - void SetPrintData(const wxPrintData& printData); - - /** - Assigns print data to this object. - */ - void operator =(const wxPrintData& data); - - /** - Assigns page setup data to this object. - */ - void operator =(const wxPageSetupDialogData& data); -}; - - - -/** - @class wxColourData - @wxheader{cmndata.h} - - This class holds a variety of information related to colour dialogs. - - @library{wxcore} - @category{cmndlg} - - @see wxColour, wxColourDialog, @ref overview_cmndlg_colour -*/ -class wxColourData : public wxObject -{ -public: - /** - Constructor. Initializes the custom colours to @c wxNullColour, the - @e data colour setting to black, and the @e choose full setting to - @true. - */ - wxColourData(); - - /** - Destructor. - */ - ~wxColourData(); - - /** - Under Windows, determines whether the Windows colour dialog will - display the full dialog with custom colour selection controls. Under - PalmOS, determines whether colour dialog will display full rgb colour - picker or only available palette indexer. Has no meaning under other - platforms. - - The default value is @true. - */ - bool GetChooseFull() const; - - /** - Gets the current colour associated with the colour dialog. - - The default colour is black. - */ - wxColour& GetColour() const; - - /** - Returns custom colours associated with the colour dialog. - - @param i - An integer between 0 and 15, being any of the 15 custom colours - that the user has saved. The default custom colours are invalid - colours. - */ - wxColour& GetCustomColour(int i) const; - - /** - Under Windows, tells the Windows colour dialog to display the full - dialog with custom colour selection controls. Under other platforms, - has no effect. - - The default value is @true. - */ - void SetChooseFull(const bool flag); - - /** - Sets the default colour for the colour dialog. - - The default colour is black. - */ - void SetColour(const wxColour& colour); - - /** - Sets custom colours for the colour dialog. - - @param i - An integer between 0 and 15 for whatever custom colour you want to - set. The default custom colours are invalid colours. - */ - void SetCustomColour(int i, const wxColour& colour); - - /** - Assignment operator for the colour data. - */ - void operator =(const wxColourData& data); -}; - - - -/** - Enumeration of various printer bin sources. - - @see wxPrintData::SetBin() -*/ -enum wxPrintBin -{ - wxPRINTBIN_DEFAULT, - - wxPRINTBIN_ONLYONE, - wxPRINTBIN_LOWER, - wxPRINTBIN_MIDDLE, - wxPRINTBIN_MANUAL, - wxPRINTBIN_ENVELOPE, - wxPRINTBIN_ENVMANUAL, - wxPRINTBIN_AUTO, - wxPRINTBIN_TRACTOR, - wxPRINTBIN_SMALLFMT, - wxPRINTBIN_LARGEFMT, - wxPRINTBIN_LARGECAPACITY, - wxPRINTBIN_CASSETTE, - wxPRINTBIN_FORMSOURCE, - - wxPRINTBIN_USER, -}; - -/** - @class wxPrintData - @wxheader{cmndata.h} - - This class holds a variety of information related to printers and printer - device contexts. This class is used to create a wxPrinterDC and a - wxPostScriptDC. It is also used as a data member of wxPrintDialogData and - wxPageSetupDialogData, as part of the mechanism for transferring data - between the print dialogs and the application. - - @remarks - - The following functions are specific to PostScript printing and have not - yet been documented: - - @code - const wxString& GetPrinterCommand() const ; - const wxString& GetPrinterOptions() const ; - const wxString& GetPreviewCommand() const ; - const wxString& GetFilename() const ; - const wxString& GetFontMetricPath() const ; - double GetPrinterScaleX() const ; - double GetPrinterScaleY() const ; - long GetPrinterTranslateX() const ; - long GetPrinterTranslateY() const ; - // wxPRINT_MODE_PREVIEW, wxPRINT_MODE_FILE, wxPRINT_MODE_PRINTER - wxPrintMode GetPrintMode() const ; - - void SetPrinterCommand(const wxString& command) ; - void SetPrinterOptions(const wxString& options) ; - void SetPreviewCommand(const wxString& command) ; - void SetFilename(const wxString& filename) ; - void SetFontMetricPath(const wxString& path) ; - void SetPrinterScaleX(double x) ; - void SetPrinterScaleY(double y) ; - void SetPrinterScaling(double x, double y) ; - void SetPrinterTranslateX(long x) ; - void SetPrinterTranslateY(long y) ; - void SetPrinterTranslation(long x, long y) ; - void SetPrintMode(wxPrintMode printMode) ; - @endcode - - @library{wxcore} - @category{printing} - - @see @ref overview_printing, wxPrintDialog, wxPageSetupDialog, - wxPrintDialogData, wxPageSetupDialogData, @ref overview_cmndlg_print, - wxPrinterDC, wxPostScriptDC -*/ -class wxPrintData : public wxObject -{ -public: - /** - Default constructor. - */ - wxPrintData(); - - /** - Copy constructor. - */ - wxPrintData(const wxPrintData& data); - - /** - Destructor. - */ - ~wxPrintData(); - - /** - Returns the current bin (papersource). By default, the system is left - to select the bin (@c wxPRINTBIN_DEFAULT is returned). - - See SetBin() for the full list of bin values. - */ - wxPrintBin GetBin() const; - - /** - Returns @true if collation is on. - */ - bool GetCollate() const; - - /** - Returns @true if colour printing is on. - */ - bool GetColour() const; - - /** - Returns the duplex mode. One of wxDUPLEX_SIMPLEX, wxDUPLEX_HORIZONTAL, - wxDUPLEX_VERTICAL. - */ - wxDuplexMode GetDuplex() const; - - /** - Returns the number of copies requested by the user. - */ - int GetNoCopies() const; - - /** - Gets the orientation. This can be wxLANDSCAPE or wxPORTRAIT. - */ - int GetOrientation() const; - - /** - Returns the paper size id. - - @see SetPaperId() - */ - wxPaperSize GetPaperId() const; - - /** - Returns the printer name. If the printer name is the empty string, it - indicates that the default printer should be used. - */ - const wxString GetPrinterName() const; - - /** - Returns the current print quality. This can be a positive integer, - denoting the number of dots per inch, or one of the following - identifiers: - - - wxPRINT_QUALITY_HIGH - - wxPRINT_QUALITY_MEDIUM - - wxPRINT_QUALITY_LOW - - wxPRINT_QUALITY_DRAFT - - On input you should pass one of these identifiers, but on return you - may get back a positive integer indicating the current resolution - setting. - */ - wxPrintQuality GetQuality() const; - - /** - Returns @true if the print data is valid for using in print dialogs. - This can return @false on Windows if the current printer is not set, - for example. On all other platforms, it returns @true. - */ - bool IsOk() const; - - /** - Sets the current bin. - */ - void SetBin(wxPrintBin flag); - - /** - Sets collation to on or off. - */ - void SetCollate(bool flag); - - /** - Sets colour printing on or off. - */ - void SetColour(bool flag); - - /** - Returns the duplex mode. One of wxDUPLEX_SIMPLEX, wxDUPLEX_HORIZONTAL, - wxDUPLEX_VERTICAL. - */ - void SetDuplex(wxDuplexMode mode); - - /** - Sets the default number of copies to be printed out. - */ - void SetNoCopies(int n); - - /** - Sets the orientation. This can be wxLANDSCAPE or wxPORTRAIT. - */ - void SetOrientation(int orientation); - - /** - Sets the paper id. This indicates the type of paper to be used. For a - mapping between paper id, paper size and string name, see - wxPrintPaperDatabase in @c "paper.h" (not yet documented). - */ - void SetPaperId(wxPaperSize paperId); - - /** - Sets the printer name. This can be the empty string to indicate that - the default printer should be used. - */ - void SetPrinterName(const wxString& printerName); - - /** - Sets the desired print quality. This can be a positive integer, - denoting the number of dots per inch, or one of the following - identifiers: - - - wxPRINT_QUALITY_HIGH - - wxPRINT_QUALITY_MEDIUM - - wxPRINT_QUALITY_LOW - - wxPRINT_QUALITY_DRAFT - - On input you should pass one of these identifiers, but on return you - may get back a positive integer indicating the current resolution - setting. - */ - void SetQuality(wxPrintQuality quality); - - /** - Assigns print data to this object. - */ - void operator =(const wxPrintData& data); -}; - - - -/** - @class wxPrintDialogData - @wxheader{cmndata.h} - - This class holds information related to the visual characteristics of - wxPrintDialog. It contains a wxPrintData object with underlying printing - settings. - - @library{wxcore} - @category{printing} - - @see @ref overview_printing, wxPrintDialog, @ref overview_cmndlg_print -*/ -class wxPrintDialogData : public wxObject -{ -public: - /** - Default constructor. - */ - wxPrintDialogData(); - - /** - Copy constructor. - */ - wxPrintDialogData(wxPrintDialogData& dialogData); - - /** - Construct an object from a print dialog data object. - */ - wxPrintDialogData(wxPrintData& printData); - - /** - Destructor. - */ - ~wxPrintDialogData(); - - /** - Enables or disables the "Help" button. - */ - void EnableHelp(bool flag); - - /** - Enables or disables the "Page numbers" controls. - */ - void EnablePageNumbers(bool flag); - - /** - Enables or disables the "Print to file" checkbox. - */ - void EnablePrintToFile(bool flag); - - /** - Enables or disables the "Selection" radio button. - */ - void EnableSelection(bool flag); - - /** - Returns @true if the user requested that all pages be printed. - */ - bool GetAllPages() const; - - /** - Returns @true if the user requested that the document(s) be collated. - */ - bool GetCollate() const; - - /** - Returns the @e from page number, as entered by the user. - */ - int GetFromPage() const; - - /** - Returns the @e maximum page number. - */ - int GetMaxPage() const; - - /** - Returns the @e minimum page number. - */ - int GetMinPage() const; - - /** - Returns the number of copies requested by the user. - */ - int GetNoCopies() const; - - /** - Returns a reference to the internal wxPrintData object. - */ - wxPrintData& GetPrintData(); - - /** - Returns @true if the user has selected printing to a file. - */ - bool GetPrintToFile() const; - - /** - Returns @true if the user requested that the selection be printed - (where "selection" is a concept specific to the application). - */ - bool GetSelection() const; - - /** - Returns the @e "print to" page number, as entered by the user. - */ - int GetToPage() const; - - /** - Returns @true if the print data is valid for using in print dialogs. - This can return @false on Windows if the current printer is not set, - for example. On all other platforms, it returns @true. - */ - bool IsOk() const; - - /** - Sets the "Collate" checkbox to @true or @false. - */ - void SetCollate(bool flag); - - /** - Sets the @e from page number. - */ - void SetFromPage(int page); - - /** - Sets the @e maximum page number. - */ - void SetMaxPage(int page); - - /** - Sets the @e minimum page number. - */ - void SetMinPage(int page); - - /** - Sets the default number of copies the user has requested to be printed - out. - */ - void SetNoCopies(int n); - - /** - Sets the internal wxPrintData. - */ - void SetPrintData(const wxPrintData& printData); - - /** - Sets the "Print to file" checkbox to @true or @false. - */ - void SetPrintToFile(bool flag); - - /** - Selects the "Selection" radio button. The effect of printing the - selection depends on how the application implements this command, if at - all. - */ - void SetSelection(bool flag); - - /** - @deprecated This function has been deprecated since version 2.5.4. - - Determines whether the dialog to be shown will be the Print dialog - (pass @false) or Print Setup dialog (pass @true). - - */ - void SetSetupDialog(bool flag); - - /** - Sets the @e "print to" page number. - */ - void SetToPage(int page); - - /** - Assigns print data to this object. - */ - void operator =(const wxPrintData& data); - - /** - Assigns another print dialog data object to this object. - */ - void operator =(const wxPrintDialogData& data); -}; - diff --git a/interface/collpane.h b/interface/collpane.h deleted file mode 100644 index 161eff344d..0000000000 --- a/interface/collpane.h +++ /dev/null @@ -1,176 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: collpane.h -// Purpose: interface of wxCollapsiblePane -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxCollapsiblePaneEvent - @wxheader{collpane.h} - - This event class is used for the events generated by wxCollapsiblePane. - - @beginEventTable{wxCollapsiblePaneEvent} - @event{EVT_COLLAPSIBLEPANE_CHANGED(id, func)} - The user expanded or collapsed the collapsible pane. - @endEventTable - - @library{wxcore} - @category{events} - - @see wxCollapsiblePane -*/ -class wxCollapsiblePaneEvent : public wxCommandEvent -{ -public: - /** - The constructor is not normally used by the user code. - */ - wxCollapsiblePaneEvent(wxObject* generator, int id, bool collapsed); - - /** - Returns @true if the pane has been collapsed. - */ - bool GetCollapsed() const; - - /** - Sets this as a collapsed pane event (if @a collapsed is @true) or as an - expanded pane event (if @a collapsed is @false). - */ - void SetCollapsed(bool collapsed); -}; - - - -/** - @class wxCollapsiblePane - @wxheader{collpane.h} - - A collapsible pane is a container with an embedded button-like control - which can be used by the user to collapse or expand the pane's contents. - - Once constructed you should use the GetPane() function to access the pane - and add your controls inside it (i.e. use the returned pointer from - GetPane() as parent for the controls which must go in the pane, @b not the - wxCollapsiblePane itself!). - - Note that because of its nature of control which can dynamically (and - drastically) change its size at run-time under user-input, when putting - wxCollapsiblePane inside a wxSizer you should be careful to add it with a - proportion value of zero; this is because otherwise all other windows with - non-null proportion values will automatically resize each time the user - expands or collapse the pane window usually resulting in a weird, - flickering effect. - - Usage sample: - - @code - wxCollapsiblePane *collpane = new wxCollapsiblePane(this, wxID_ANY, wxT("Details:")); - - // add the pane with a zero proportion value to the 'sz' sizer which contains it - sz->Add(collpane, 0, wxGROW|wxALL, 5); - - // now add a test label in the collapsible pane using a sizer to layout it: - wxWindow *win = collpane->GetPane(); - wxSizer *paneSz = new wxBoxSizer(wxVERTICAL); - paneSz->Add(new wxStaticText(win, wxID_ANY, wxT("test!")), 1, wxGROW|wxALL, 2); - win->SetSizer(paneSz); - paneSz->SetSizeHints(win); - @endcode - - It is only available if @c wxUSE_COLLPANE is set to 1 (the default). - - @beginStyleTable - @style{wxCP_DEFAULT_STYLE} - The default style: 0. - @endStyleTable - - @beginEventTable{wxCollapsiblePaneEvent} - @event{EVT_COLLAPSIBLEPANE_CHANGED(id, func)} - The user expanded or collapsed the collapsible pane. - @endEventTable - - @library{wxcore} - @category{ctrl} - - - @see wxPanel, wxCollapsiblePaneEvent -*/ -class wxCollapsiblePane : public wxControl -{ -public: - /** - Default constructor. - */ - wxCollapsiblePane(); - - /** - Initializes the object and calls Create() with all the parameters. - */ - wxCollapsiblePane(wxWindow* parent, wxWindowID id, - const wxString& label, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = wxCP_DEFAULT_STYLE, - const wxValidator& validator = wxDefaultValidator, - const wxString& name = "collapsiblePane"); - - /** - @param parent - Parent window, must not be non-@NULL. - @param id - The identifier for the control. - @param label - The initial label shown in the button which allows the user to - expand or collapse the pane window. - @param pos - Initial position. - @param size - Initial size. - @param style - The window style, see wxCP_* flags. - @param validator - Validator which can be used for additional date checks. - @param name - Control name. - - @return @true if the control was successfully created or @false if - creation failed. - */ - bool Create(wxWindow* parent, wxWindowID id, - const wxString& label, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = wxCP_DEFAULT_STYLE, - const wxValidator& validator = wxDefaultValidator, - const wxString& name = "collapsiblePane"); - - /** - Collapses or expands the pane window. - */ - void Collapse(bool collapse = true); - - /** - Same as calling Collapse(@false). - */ - void Expand(); - - /** - Returns a pointer to the pane window. Add controls to the returned - wxWindow to make them collapsible. - */ - wxWindow* GetPane() const; - - /** - Returns @true if the pane window is currently hidden. - */ - bool IsCollapsed() const; - - /** - Returns @true if the pane window is currently shown. - */ - bool IsExpanded() const; -}; - diff --git a/interface/colordlg.h b/interface/colordlg.h deleted file mode 100644 index 1ed5b25cb8..0000000000 --- a/interface/colordlg.h +++ /dev/null @@ -1,93 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: colordlg.h -// Purpose: interface of wxColourDialog -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxColourDialog - @wxheader{colordlg.h} - - This class represents the colour chooser dialog. - - @library{wxcore} - @category{cmndlg} - - @see @ref overview_cmndlg_colour, wxColour, wxColourData, - wxGetColourFromUser() -*/ -class wxColourDialog : public wxDialog -{ -public: - /** - Constructor. Pass a parent window, and optionally a pointer to a block - of colour data, which will be copied to the colour dialog's colour - data. - - Custom colours from colour data object will be be used in the dialog's - colour palette. Invalid entries in custom colours list will be ignored - on some platforms(GTK) or replaced with white colour on platforms where - custom colours palette has fixed size (MSW). - - @see wxColourData - */ - wxColourDialog(wxWindow* parent, wxColourData* data = NULL); - - /** - Destructor. - */ - ~wxColourDialog(); - - /** - Same as wxColourDialog(). - */ - bool Create(wxWindow* parent, wxColourData* data = NULL); - - /** - Returns the colour data associated with the colour dialog. - */ - wxColourData GetColourData(); - - /** - Shows the dialog, returning wxID_OK if the user pressed OK, and - wxID_CANCEL otherwise. - */ - int ShowModal(); -}; - - - -// ============================================================================ -// Global functions/macros -// ============================================================================ - -/** @ingroup group_funcmacro_dialog */ -//@{ - -/** - Shows the colour selection dialog and returns the colour selected by user - or invalid colour (use wxColour::IsOk() to test whether a colour is valid) - if the dialog was cancelled. - - @param parent - The parent window for the colour selection dialog. - @param colInit - If given, this will be the colour initially selected in the dialog. - @param caption - If given, this will be used for the dialog caption. - @param data - Optional object storing additional colour dialog settings, such as - custom colours. If none is provided the same settings as the last time - are used. - - @header{wx/colordlg.h} -*/ -wxColour wxGetColourFromUser(wxWindow* parent, - const wxColour& colInit, - const wxString& caption = wxEmptyString, - wxColourData* data = NULL); - -//@} - diff --git a/interface/colour.h b/interface/colour.h deleted file mode 100644 index 52bc2f28d1..0000000000 --- a/interface/colour.h +++ /dev/null @@ -1,213 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: colour.h -// Purpose: interface of wxColour -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxColour - @wxheader{colour.h} - - A colour is an object representing a combination of Red, Green, and Blue - (RGB) intensity values, and is used to determine drawing colours. See the - entry for wxColourDatabase for how a pointer to a predefined, named colour - may be returned instead of creating a new colour. - - Valid RGB values are in the range 0 to 255. - - You can retrieve the current system colour settings with wxSystemSettings. - - @library{wxcore} - @category{gdi} - - @stdobjects - - ::wxNullColour - An empty, invalid colour. - - ::wxBLACK - - ::wxBLUE - - ::wxCYAN - - ::wxGREEN - - ::wxLIGHT_GREY - - ::wxRED - - ::wxWHITE - - @see wxColourDatabase, wxPen, wxBrush, wxColourDialog, wxSystemSettings -*/ -class wxColour : public wxObject -{ -public: - - /** - Default constructor. - */ - wxColour(); - - /** - @param red - The red value. - @param green - The green value. - @param blue - The blue value. - @param alpha - The alpha value. Alpha values range from 0 (wxALPHA_TRANSPARENT) to - 255 (wxALPHA_OPAQUE). - */ - wxColour(unsigned char red, unsigned char green, unsigned char blue, - unsigned char alpha = wxALPHA_OPAQUE); - - /** - @param colourName - The colour name. - */ - wxColour(const wxString& colourName); - - /** - Copy constructor. - */ - wxColour(const wxColour& colour); - - /** - Returns the alpha value, on platforms where alpha is not yet supported, this - always returns wxALPHA_OPAQUE. - */ - unsigned char Alpha() const; - - /** - Returns the blue intensity. - */ - unsigned char Blue() const; - - /** - Converts this colour to a wxString using the given flags. - - The supported flags are wxC2S_NAME, to obtain the colour name (e.g. - wxColour(255,0,0) == "red"), wxC2S_CSS_SYNTAX, to obtain the colour in - the "rgb(r,g,b)" or "rgba(r,g,b,a)" syntax (e.g. - wxColour(255,0,0,85) == "rgba(255,0,0,0.333)"), and wxC2S_HTML_SYNTAX, - to obtain the colour as "#" followed by 6 hexadecimal digits (e.g. - wxColour(255,0,0) == "#FF0000"). - - This function never fails and always returns a non-empty string but - asserts if the colour has alpha channel (i.e. is non opaque) but - wxC2S_CSS_SYNTAX (which is the only one supporting alpha) is not - specified in flags. - - @since 2.7.0 - */ - wxString GetAsString(long flags); - - /** - Returns a pixel value which is platform-dependent. On Windows, a COLORREF is - returned. - On X, an allocated pixel value is returned. - -1 is returned if the pixel is invalid (on X, unallocated). - */ - long GetPixel() const; - - /** - Returns the green intensity. - */ - unsigned char Green() const; - - /** - Returns @true if the colour object is valid (the colour has been initialised - with RGB values). - */ - bool IsOk() const; - - /** - Returns the red intensity. - */ - unsigned char Red() const; - - //@{ - /** - Sets the RGB intensity values using the given values (first overload), - extracting them from the packed long (second overload), using the given - string (third overloard). - - When using third form, Set() accepts: colour names (those listed in - wxTheColourDatabase()), the CSS-like @c "rgb(r,g,b)" or - @c "rgba(r,g,b,a)" syntax (case insensitive) and the HTML-like syntax - (i.e. @c "#" followed by 6 hexadecimal digits for red, green, blue - components). - - Returns @true if the conversion was successful, @false otherwise. - - @since 2.7.0 - */ - void Set(unsigned char red, unsigned char green, - unsigned char blue, - unsigned char alpha = wxALPHA_OPAQUE); - void Set(unsigned long RGB); - bool Set(const wxString& str); - //@} - - /** - Tests the inequality of two colours by comparing individual red, green, blue - colours and alpha values. - */ - bool operator !=(const wxColour& colour); - - //@{ - /** - Assignment operator, using a colour name to be found in the colour database. - - @see wxColourDatabase - */ - wxColour operator =(const wxColour& colour); - wxColour operator =(const wxString& colourName); - //@} - - /** - Tests the equality of two colours by comparing individual red, green, blue - colours and alpha values. - */ - bool operator ==(const wxColour& colour); -}; - - -/** @name Predefined colors. */ -//@{ -wxColour wxNullColour; -wxColour* wxBLACK; -wxColour* wxBLUE; -wxColour* wxCYAN; -wxColour* wxGREEN; -wxColour* wxLIGHT_GREY; -wxColour* wxRED; -wxColour* wxWHITE; -//@} - - - -// ============================================================================ -// Global functions/macros -// ============================================================================ - -/** @ingroup group_funcmacro_misc */ -//@{ - -/** - Converts string to a wxColour best represented by the given string. Returns - @true on success. - - @see wxToString(const wxColour&) - - @header{wx/colour.h} -*/ -bool wxFromString(const wxString& string, wxColour* colour); - -/** - Converts the given wxColour into a string. - - @see wxFromString(const wxString&, wxColour*) - - @header{wx/colour.h} -*/ -wxString wxToString(const wxColour& colour); - -//@} - diff --git a/interface/combo.h b/interface/combo.h deleted file mode 100644 index 353daaf8f5..0000000000 --- a/interface/combo.h +++ /dev/null @@ -1,755 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: combo.h -// Purpose: interface of wxComboCtrl and wxComboPopup -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxComboPopup - @wxheader{combo.h} - - In order to use a custom popup with wxComboCtrl, an interface class must be - derived from wxComboPopup. - - For more information on how to use it, see @ref comboctrl_custompopup. - - @library{wxcore} - @category{ctrl} - - @see wxComboCtrl -*/ -class wxComboPopup -{ -public: - /** - Default constructor. It is recommended that internal variables are - prepared in Init() instead (because m_combo is not valid in - constructor). - */ - wxComboPopup(); - - /** - The derived class must implement this to create the popup control. - - @return @true if the call succeeded, @false otherwise. - */ - virtual bool Create(wxWindow* parent); - - /** - Utility function that hides the popup. - */ - void Dismiss(); - - /** - The derived class may implement this to return adjusted size for the - popup control, according to the variables given. - - @param minWidth - Preferred minimum width. - @param prefHeight - Preferred height. May be -1 to indicate no preference. - @param maxWidth - Max height for window, as limited by screen size. - - @remarks This function is called each time popup is about to be shown. - */ - virtual wxSize GetAdjustedSize(int minWidth, int prefHeight, int maxHeight); - - /** - The derived class must implement this to return pointer to the - associated control created in Create(). - */ - virtual wxWindow* GetControl(); - - /** - The derived class must implement this to return string representation - of the value. - */ - virtual wxString GetStringValue() const; - - /** - The derived class must implement this to initialize its internal - variables. This method is called immediately after construction - finishes. m_combo member variable has been initialized before the call. - */ - virtual void Init(); - - /** - Utility method that returns @true if Create has been called. - - Useful in conjunction with LazyCreate(). - */ - bool IsCreated() const; - - /** - The derived class may implement this to return @true if it wants to - delay call to Create() until the popup is shown for the first time. It - is more efficient, but on the other hand it is often more convenient to - have the control created immediately. - - @remarks Base implementation returns @false. - */ - virtual bool LazyCreate(); - - /** - The derived class may implement this to do something when the parent - wxComboCtrl gets double-clicked. - */ - virtual void OnComboDoubleClick(); - - /** - The derived class may implement this to receive key events from the - parent wxComboCtrl. - - Events not handled should be skipped, as usual. - */ - virtual void OnComboKeyEvent(wxKeyEvent& event); - - /** - The derived class may implement this to do special processing when - popup is hidden. - */ - virtual void OnDismiss(); - - /** - The derived class may implement this to do special processing when - popup is shown. - */ - virtual void OnPopup(); - - /** - The derived class may implement this to paint the parent wxComboCtrl. - - Default implementation draws value as string. - */ - virtual void PaintComboControl(wxDC& dc, const wxRect& rect); - - /** - The derived class must implement this to receive string value changes - from wxComboCtrl. - */ - virtual void SetStringValue(const wxString& value); - - /** - Parent wxComboCtrl. This is parameter has been prepared before Init() - is called. - */ - wxComboCtrl m_combo; -}; - - - -/** - Features enabled for wxComboCtrl. - - @see wxComboCtrl::GetFeatures() -*/ -struct wxComboCtrlFeatures -{ - enum - { - MovableButton = 0x0001, ///< Button can be on either side of control. - BitmapButton = 0x0002, ///< Button may be replaced with bitmap. - ButtonSpacing = 0x0004, ///< Button can have spacing from the edge - ///< of the control. - TextIndent = 0x0008, ///< wxComboCtrl::SetTextIndent() can be used. - PaintControl = 0x0010, ///< Combo control itself can be custom painted. - PaintWritable = 0x0020, ///< A variable-width area in front of writable - ///< combo control's textctrl can be custom - ///< painted. - Borderless = 0x0040, ///< wxNO_BORDER window style works. - - All = MovableButton | BitmapButton | ButtonSpacing | - TextIndent | PaintControl | PaintWritable | - Borderless ///< All features. - }; -}; - - -/** - @class wxComboCtrl - @wxheader{combo.h} - - A combo control is a generic combobox that allows totally custom popup. In - addition it has other customization features. For instance, position and - size of the dropdown button can be changed. - - @section comboctrl_custompopup Setting Custom Popup for wxComboCtrl - - wxComboCtrl needs to be told somehow which control to use and this is done - by SetPopupControl(). However, we need something more than just a wxControl - in this method as, for example, we need to call - SetStringValue("initial text value") and wxControl doesn't have such - method. So we also need a wxComboPopup which is an interface which must be - implemented by a control to be usable as a popup. - - We couldn't derive wxComboPopup from wxControl as this would make it - impossible to have a class deriving from a wxWidgets control and from it, - so instead it is just a mix-in. - - Here's a minimal sample of wxListView popup: - - @code - #include - #include - - class wxListViewComboPopup : public wxListView, public wxComboPopup - { - public: - // Initialize member variables - virtual void Init() - { - m_value = -1; - } - - // Create popup control - virtual bool Create(wxWindow* parent) - { - return wxListView::Create(parent,1,wxPoint(0,0),wxDefaultSize); - } - - // Return pointer to the created control - virtual wxWindow *GetControl() { return this; } - - // Translate string into a list selection - virtual void SetStringValue(const wxString& s) - { - int n = wxListView::FindItem(-1,s); - if ( n >= 0 && n < wxListView::GetItemCount() ) - wxListView::Select(n); - } - - // Get list selection as a string - virtual wxString GetStringValue() const - { - if ( m_value >= 0 ) - return wxListView::GetItemText(m_value); - return wxEmptyString; - } - - // Do mouse hot-tracking (which is typical in list popups) - void OnMouseMove(wxMouseEvent& event) - { - // TODO: Move selection to cursor - } - - // On mouse left up, set the value and close the popup - void OnMouseClick(wxMouseEvent& WXUNUSED(event)) - { - m_value = wxListView::GetFirstSelected(); - - // TODO: Send event as well - - Dismiss(); - } - - protected: - - int m_value; // current item index - - private: - DECLARE_EVENT_TABLE() - }; - - BEGIN_EVENT_TABLE(wxListViewComboPopup, wxListView) - EVT_MOTION(wxListViewComboPopup::OnMouseMove) - EVT_LEFT_UP(wxListViewComboPopup::OnMouseClick) - END_EVENT_TABLE() - @endcode - - Here's how you would create and populate it in a dialog constructor: - - @code - wxComboCtrl* comboCtrl = new wxComboCtrl(this, wxID_ANY, wxEmptyString); - - wxListViewComboPopup* popupCtrl = new wxListViewComboPopup(); - - comboCtrl->SetPopupControl(popupCtrl); - - // Populate using wxListView methods - popupCtrl->InsertItem(popupCtrl->GetItemCount(), "First Item"); - popupCtrl->InsertItem(popupCtrl->GetItemCount(), "Second Item"); - popupCtrl->InsertItem(popupCtrl->GetItemCount(), "Third Item"); - @endcode - - @beginStyleTable - @style{wxCB_READONLY} - Text will not be editable. - @style{wxCB_SORT} - Sorts the entries in the list alphabetically. - @style{wxTE_PROCESS_ENTER} - The control will generate the event wxEVT_COMMAND_TEXT_ENTER - (otherwise pressing Enter key is either processed internally by the - control or used for navigation between dialog controls). Windows - only. - @style{wxCC_SPECIAL_DCLICK} - Double-clicking triggers a call to popup's OnComboDoubleClick. - Actual behaviour is defined by a derived class. For instance, - wxOwnerDrawnComboBox will cycle an item. This style only applies if - wxCB_READONLY is used as well. - @style{wxCC_STD_BUTTON} - Drop button will behave more like a standard push button. - @endStyleTable - - @beginEventTable{wxCommandEvent} - @event{EVT_TEXT(id, func)} - Process a wxEVT_COMMAND_TEXT_UPDATED event, when the text changes. - @event{EVT_TEXT_ENTER(id, func)} - Process a wxEVT_COMMAND_TEXT_ENTER event, when RETURN is pressed in - the combo control. - @endEventTable - - @library{wxbase} - @category{ctrl} - - - @see wxComboBox, wxChoice, wxOwnerDrawnComboBox, wxComboPopup, - wxCommandEvent -*/ -class wxComboCtrl : public wxControl -{ -public: - /** - Default constructor. - */ - wxComboCtrl(); - - /** - Constructor, creating and showing a combo control. - - @param parent - Parent window. Must not be @NULL. - @param id - Window identifier. The value 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 sized - appropriately. - @param style - Window style. See wxComboCtrl. - @param validator - Window validator. - @param name - Window name. - - @see Create(), wxValidator - */ - wxComboCtrl(wxWindow* parent, wxWindowID id, - const wxString& value = "", - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = 0, - const wxValidator& validator = wxDefaultValidator, - const wxString& name = "comboCtrl"); - - /** - Destructor, destroying the combo control. - */ - virtual ~wxComboCtrl(); - - /** - This member function is not normally called in application code. - Instead, it can be implemented in a derived class to create a custom - popup animation. - - The parameters are the same as those for DoShowPopup(). - - @return @true if animation finishes before the function returns, - @false otherwise. In the latter case you need to manually call - DoShowPopup() after the animation ends. - */ - virtual bool AnimateShow(const wxRect& rect, int flags); - - /** - Copies the selected text to the clipboard. - */ - virtual void Copy(); - - /** - Creates the combo control for two-step construction. Derived classes - should call or replace this function. See wxComboCtrl() for further - details. - */ - bool Create(wxWindow* parent, wxWindowID id, - const wxString& value = "", - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = 0, - const wxValidator& validator = wxDefaultValidator, - const wxString& name = "comboCtrl"); - - /** - Copies the selected text to the clipboard and removes the selection. - */ - virtual void Cut(); - - /** - This member function is not normally called in application code. - Instead, it can be implemented in a derived class to return default - wxComboPopup, incase @a popup is @NULL. - - @note If you have implemented OnButtonClick() to do something else than - show the popup, then DoSetPopupControl() must always set @a popup - to @NULL. - */ - void DoSetPopupControl(wxComboPopup* popup); - - /** - This member function is not normally called in application code. - Instead, it must be called in a derived class to make sure popup is - properly shown after a popup animation has finished (but only if - AnimateShow() did not finish the animation within its function scope). - - @param rect - Position to show the popup window at, in screen coordinates. - @param flags - Combination of any of the following: - @beginTable - @row2col{wxComboCtrl::ShowAbove, - Popup is shown above the control instead of below.} - @row2col{wxComboCtrl::CanDeferShow, - Showing the popup can be deferred to happen sometime after - ShowPopup() has finished. In this case, AnimateShow() must - return false.} - @endTable - */ - virtual void DoShowPopup(const wxRect& rect, int flags); - - /** - Enables or disables popup animation, if any, depending on the value of - the argument. - */ - void EnablePopupAnimation(bool enable = true); - - /** - Returns disabled button bitmap that has been set with - SetButtonBitmaps(). - - @return A reference to the disabled state bitmap. - */ - const wxBitmap GetBitmapDisabled() const; - - /** - Returns button mouse hover bitmap that has been set with - SetButtonBitmaps(). - - @return A reference to the mouse hover state bitmap. - */ - const wxBitmap GetBitmapHover() const; - - /** - Returns default button bitmap that has been set with - SetButtonBitmaps(). - - @return A reference to the normal state bitmap. - */ - const wxBitmap GetBitmapNormal() const; - - /** - Returns depressed button bitmap that has been set with - SetButtonBitmaps(). - - @return A reference to the depressed state bitmap. - */ - const wxBitmap GetBitmapPressed() const; - - /** - Returns current size of the dropdown button. - */ - wxSize GetButtonSize(); - - /** - Returns custom painted area in control. - - @see SetCustomPaintWidth(). - */ - int GetCustomPaintWidth() const; - - /** - Returns features supported by wxComboCtrl. If needed feature is - missing, you need to instead use wxGenericComboCtrl, which however may - lack a native look and feel (but otherwise sports identical API). - - @return Value returned is a combination of the flags defined in - wxComboCtrlFeatures. - */ - static int GetFeatures(); - - /** - Returns the insertion point for the combo control's text field. - - @note Under Windows, this function always returns 0 if the combo - control doesn't have the focus. - */ - virtual long GetInsertionPoint() const; - - /** - Returns the last position in the combo control text field. - */ - virtual long GetLastPosition() const; - - /** - Returns current popup interface that has been set with - SetPopupControl(). - */ - wxComboPopup* GetPopupControl(); - - /** - Returns popup window containing the popup control. - */ - wxWindow* GetPopupWindow() const; - - /** - Get the text control which is part of the combo control. - */ - wxTextCtrl* GetTextCtrl() const; - - /** - Returns actual indentation in pixels. - */ - wxCoord GetTextIndent() const; - - /** - Returns area covered by the text field (includes everything except - borders and the dropdown button). - */ - const wxRect GetTextRect() const; - - /** - Returns text representation of the current value. For writable combo - control it always returns the value in the text field. - */ - virtual wxString GetValue() const; - - /** - Dismisses the popup window. - */ - virtual void HidePopup(); - - /** - Returns @true if the popup is currently shown - */ - bool IsPopupShown() const; - - /** - Returns @true if the popup window is in the given state. Possible - values are: - - @beginTable - @row2col{wxComboCtrl::Hidden, Popup window is hidden.} - @row2col{wxComboCtrl::Animating, Popup window is being shown, but the - popup animation has not yet finished.} - @row2col{wxComboCtrl::Visible, Popup window is fully visible.} - @endTable - */ - bool IsPopupWindowState(int state) const; - - /** - Implement in a derived class to define what happens on dropdown button - click. Default action is to show the popup. - - @note If you implement this to do something else than show the popup, - you must then also implement DoSetPopupControl() to always return - @NULL. - */ - virtual void OnButtonClick(); - - /** - Pastes text from the clipboard to the text field. - */ - virtual void Paste(); - - /** - Removes the text between the two positions in the combo control text - field. - - @param from - The first position. - @param to - The last position. - */ - virtual void Remove(long from, long to); - - /** - Replaces the text between two positions with the given text, in the - combo control text field. - - @param from - The first position. - @param to - The second position. - @param text - The text to insert. - */ - virtual void Replace(long from, long to, const wxString& value); - - /** - Sets custom dropdown button graphics. - - @param bmpNormal - Default button image. - @param pushButtonBg - If @true, blank push button background is painted below the image. - @param bmpPressed - Depressed button image. - @param bmpHover - Button image when mouse hovers above it. This should be ignored on - platforms and themes that do not generally draw different kind of - button on mouse hover. - @param bmpDisabled - Disabled button image. - */ - void SetButtonBitmaps(const wxBitmap& bmpNormal, - bool pushButtonBg = false, - const wxBitmap& bmpPressed = wxNullBitmap, - const wxBitmap& bmpHover = wxNullBitmap, - const wxBitmap& bmpDisabled = wxNullBitmap); - - /** - Sets size and position of dropdown button. - - @param width - Button width. Value = 0 specifies default. - @param height - Button height. Value = 0 specifies default. - @param side - Indicates which side the button will be placed. Value can be wxLEFT - or wxRIGHT. - @param spacingX - Horizontal spacing around the button. Default is 0. - */ - void SetButtonPosition(int width = -1, int height = -1, - int side = wxRIGHT, int spacingX = 0); - - /** - Set width, in pixels, of custom painted area in control without - @c wxCB_READONLY style. In read-only wxOwnerDrawnComboBox, this is used - to indicate area that is not covered by the focus rectangle. - */ - void SetCustomPaintWidth(int width); - - /** - Sets the insertion point in the text field. - - @param pos - The new insertion point. - */ - virtual void SetInsertionPoint(long pos); - - /** - Sets the insertion point at the end of the combo control text field. - */ - virtual void SetInsertionPointEnd(); - - /** - Set side of the control to which the popup will align itself. Valid - values are @c wxLEFT, @c wxRIGHT and 0. The default value 0 means that - the most appropriate side is used (which, currently, is always - @c wxLEFT). - */ - void SetPopupAnchor(int anchorSide); - - /** - Set popup interface class derived from wxComboPopup. This method should - be called as soon as possible after the control has been created, - unless OnButtonClick() has been overridden. - */ - void SetPopupControl(wxComboPopup* popup); - - /** - Extends popup size horizontally, relative to the edges of the combo - control. - - @param extLeft - How many pixel to extend beyond the left edge of the control. - Default is 0. - @param extRight - How many pixel to extend beyond the right edge of the control. - Default is 0. - - @remarks Popup minimum width may override arguments. It is up to the - popup to fully take this into account. - */ - void SetPopupExtents(int extLeft, int extRight); - - /** - Sets preferred maximum height of the popup. - - @remarks Value -1 indicates the default. - */ - void SetPopupMaxHeight(int height); - - /** - Sets minimum width of the popup. If wider than combo control, it will - extend to the left. - - @remarks Value -1 indicates the default. Also, popup implementation may - choose to ignore this. - */ - void SetPopupMinWidth(int width); - - /** - Selects the text between the two positions, in the combo control text - field. - - @param from - The first position. - @param to - The second position. - */ - virtual void SetSelection(long from, long to); - - /** - Sets the text for the text field without affecting the popup. Thus, - unlike SetValue(), it works equally well with combo control using - @c wxCB_READONLY style. - */ - void SetText(const wxString& value); - - /** - This will set the space in pixels between left edge of the control and - the text, regardless whether control is read-only or not. Value -1 can - be given to indicate platform default. - */ - void SetTextIndent(int indent); - - /** - Sets the text for the combo control text field. - - @note For a combo control with @c wxCB_READONLY style the string must - be accepted by the popup (for instance, exist in the dropdown - list), otherwise the call to SetValue() is ignored. - */ - virtual void SetValue(const wxString& value); - - /** - Same as SetValue(), but also sends wxCommandEvent of type - wxEVT_COMMAND_TEXT_UPDATED if @a withEvent is @true. - */ - void SetValueWithEvent(const wxString& value, bool withEvent = true); - - /** - Show the popup. - */ - virtual void ShowPopup(); - - /** - Undoes the last edit in the text field. Windows only. - */ - virtual void Undo(); - - /** - Enable or disable usage of an alternative popup window, which - guarantees ability to focus the popup control, and allows common native - controls to function normally. This alternative popup window is usually - a wxDialog, and as such, when it is shown, its parent top-level window - will appear as if the focus has been lost from it. - */ - void UseAltPopupWindow(bool enable = true); -}; - diff --git a/interface/combobox.h b/interface/combobox.h deleted file mode 100644 index d70190e385..0000000000 --- a/interface/combobox.h +++ /dev/null @@ -1,302 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: combobox.h -// Purpose: interface of wxComboBox -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxComboBox - @wxheader{combobox.h} - - A combobox is like a combination of an edit control and a listbox. It can - be displayed as static list with editable or read-only text field; or a - drop-down list with text field; or a drop-down list without a text field. - - A combobox permits a single selection only. Combobox items are numbered - from zero. - - If you need a customized combobox, have a look at wxComboCtrl, - wxOwnerDrawnComboBox, wxComboPopup and the ready-to-use wxBitmapComboBox. - - @beginStyleTable - @style{wxCB_SIMPLE} - Creates a combobox with a permanently displayed list. Windows only. - @style{wxCB_DROPDOWN} - Creates a combobox with a drop-down list. - @style{wxCB_READONLY} - Same as wxCB_DROPDOWN but only the strings specified as the combobox - choices can be selected, it is impossible to select (even from a - program) a string which is not in the choices list. - @style{wxCB_SORT} - Sorts the entries in the list alphabetically. - @style{wxTE_PROCESS_ENTER} - The control will generate the event wxEVT_COMMAND_TEXT_ENTER - (otherwise pressing Enter key is either processed internally by the - control or used for navigation between dialog controls). Windows - only. - @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 - value of selection. - @event{EVT_TEXT(id, func)} - Process a wxEVT_COMMAND_TEXT_UPDATED event, when the combobox text - changes. - @event{EVT_TEXT_ENTER(id, func)} - Process a wxEVT_COMMAND_TEXT_ENTER event, when RETURN is pressed in - the combobox (notice that the combobox must have been created with - wxTE_PROCESS_ENTER style to receive this event). - @endEventTable - - @library{wxcore} - @category{ctrl} - - - @see wxListBox, wxTextCtrl, wxChoice, wxCommandEvent -*/ -class wxComboBox : public wxControl, public wxItemContainer -{ -public: - /** - Default constructor. - */ - wxComboBox(); - - //@{ - /** - Constructor, creating and showing a combobox. - - @param parent - Parent window. Must not be @NULL. - @param id - Window identifier. The value 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 sized - appropriately. - @param n - Number of strings with which to initialise the control. - @param choices - An array of strings with which to initialise the control. - @param style - Window style. See wxComboBox. - @param validator - Window validator. - @param name - Window name. - - @beginWxPythonOnly - The wxComboBox constructor in wxPython reduces the @a n and @a choices - arguments are to a single argument, which is a list of strings. - @endWxPythonOnly - - @see Create(), wxValidator - */ - wxComboBox(wxWindow* parent, wxWindowID id, - const wxString& value = "", - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - int n = 0, - const wxString choices[] = NULL, - long style = 0, - const wxValidator& validator = wxDefaultValidator, - const wxString& name = "comboBox"); - wxComboBox(wxWindow* parent, wxWindowID id, - const wxString& value, - const wxPoint& pos, - const wxSize& size, - const wxArrayString& choices, - long style = 0, - const wxValidator& validator = wxDefaultValidator, - const wxString& name = "comboBox"); - //@} - - /** - Destructor, destroying the combobox. - */ - ~wxComboBox(); - - //@{ - /** - Creates the combobox for two-step construction. Derived classes should - call or replace this function. See wxComboBox() for further details. - */ - bool Create(wxWindow* parent, wxWindowID id, - const wxString& value = "", - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - int n, const wxString choices[], - long style = 0, - const wxValidator& validator = wxDefaultValidator, - const wxString& name = "comboBox"); - bool Create(wxWindow* parent, wxWindowID id, - const wxString& value, - const wxPoint& pos, - const wxSize& size, - const wxArrayString& choices, - long style = 0, - const wxValidator& validator = wxDefaultValidator, - const wxString& name = "comboBox"); - //@} - - /** - Returns @true if the combobox is editable and there is a text selection - to copy to the clipboard. Only available on Windows. - */ - bool CanCopy() const; - - /** - Returns @true if the combobox is editable and there is a text selection - to copy to the clipboard. Only available on Windows. - */ - bool CanCut() const; - - /** - Returns @true if the combobox is editable and there is text on the - clipboard that can be pasted into the text field. Only available on - Windows. - */ - bool CanPaste() const; - - /** - Returns @true if the combobox is editable and the last undo can be - redone. Only available on Windows. - */ - bool CanRedo() const; - - /** - Returns @true if the combobox is editable and the last edit can be - undone. Only available on Windows. - */ - bool CanUndo() const; - - /** - Copies the selected text to the clipboard. - */ - void Copy(); - - /** - Copies the selected text to the clipboard and removes the selection. - */ - void Cut(); - - /** - This function does the same things as wxChoice::GetCurrentSelection() - and returns the item currently selected in the dropdown list if it's - open or the same thing as wxControlWithItems::GetSelection() otherwise. - */ - int GetCurrentSelection() const; - - /** - Returns the insertion point for the combobox's text field. - - @note Under wxMSW, this function always returns 0 if the combobox - doesn't have the focus. - */ - long GetInsertionPoint() const; - - /** - Returns the last position in the combobox text field. - */ - virtual wxTextPos GetLastPosition() const; - - /** - This is the same as wxTextCtrl::GetSelection() for the text control - which is part of the combobox. Notice that this is a different method - from wxControlWithItems::GetSelection(). - - Currently this method is only implemented in wxMSW and wxGTK. - */ - void GetSelection(long* from, long* to) const; - - /** - Returns the current value in the combobox text field. - */ - wxString GetValue() const; - - /** - Pastes text from the clipboard to the text field. - */ - void Paste(); - - /** - Redoes the last undo in the text field. Windows only. - */ - void Redo(); - - /** - Removes the text between the two positions in the combobox text field. - - @param from - The first position. - @param to - The last position. - */ - void Remove(long from, long to); - - /** - Replaces the text between two positions with the given text, in the - combobox text field. - - @param from - The first position. - @param to - The second position. - @param text - The text to insert. - */ - void Replace(long from, long to, const wxString& text); - - /** - Sets the insertion point in the combobox text field. - - @param pos - The new insertion point. - */ - void SetInsertionPoint(long pos); - - /** - Sets the insertion point at the end of the combobox text field. - */ - void SetInsertionPointEnd(); - - /** - Selects the text between the two positions, in the combobox text field. - - @param from - The first position. - @param to - The second position. - - @beginWxPythonOnly - This method is called SetMark() in wxPython, "SetSelection" is kept for - wxControlWithItems::SetSelection(). - @endWxPythonOnly - */ - void SetSelection(long from, long to); - - /** - Sets the text for the combobox text field. - - @note For a combobox with @c wxCB_READONLY style the string must be in - the combobox choices list, otherwise the call to SetValue() is - ignored. - - @param text - The text to set. - */ - void SetValue(const wxString& text); - - /** - Undoes the last edit in the text field. Windows only. - */ - void Undo(); -}; - diff --git a/interface/config.h b/interface/config.h deleted file mode 100644 index 1f7db64161..0000000000 --- a/interface/config.h +++ /dev/null @@ -1,780 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: config.h -// Purpose: interface of wxConfigBase -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxConfigBase - @wxheader{config.h} - - wxConfigBase defines the basic interface of all config classes. It can not - be used by itself (it is an abstract base class) and you will always use - one of its derivations: wxFileConfig, wxRegConfig or any other. - - However, usually you don't even need to know the precise nature of the - class you're working with but you would just use the wxConfigBase methods. - This allows you to write the same code regardless of whether you're working - with the registry under Win32 or text-based config files under Unix (or - even Windows 3.1 .INI files if you're really unlucky). To make writing the - portable code even easier, wxWidgets provides a typedef wxConfig which is - mapped onto the native wxConfigBase implementation on the given platform: - i.e. wxRegConfig under Win32 and wxFileConfig otherwise. - - See @ref overview_config for a description of all features of this class. - - It is highly recommended to use static functions Get() and/or Set(), so - please have a look at them. - - Related Include Files: - - @li @c - Let wxWidgets choose a wxConfig class for your - platform. - @li @c - Base config class. - @li @c - wxFileConfig class. - @li @c - wxRegConfig class, see also wxRegKey. - - - @section configbase_example Example - - Here is how you would typically use this class: - - @code - // using wxConfig instead of writing wxFileConfig or wxRegConfig enhances - // portability of the code - wxConfig *config = new wxConfig("MyAppName"); - - wxString str; - if ( config->Read("LastPrompt", &str) ) { - // last prompt was found in the config file/registry and its value is - // now in str - // ... - } - else { - // no last prompt... - } - - // another example: using default values and the full path instead of just - // key name: if the key is not found , the value 17 is returned - long value = config->ReadLong("/LastRun/CalculatedValues/MaxValue", 17); - - // at the end of the program we would save everything back - config->Write("LastPrompt", str); - config->Write("/LastRun/CalculatedValues/MaxValue", value); - - // the changes will be written back automatically - delete config; - @endcode - - This basic example, of course, doesn't show all wxConfig features, such as - enumerating, testing for existence and deleting the entries and groups of - entries in the config file, its abilities to automatically store the - default values or expand the environment variables on the fly. However, the - main idea is that using this class is easy and that it should normally do - what you expect it to. - - @note In the documentation of this class, the words "config file" also mean - "registry hive" for wxRegConfig and, generally speaking, might mean - any physical storage where a wxConfigBase-derived class stores its - data. - - - @section configbase_static Static Functions - - The static functions provided deal with the "default" config object. - Although its usage is not at all mandatory it may be convenient to use a - global config object instead of creating and deleting the local config - objects each time you need one (especially because creating a wxFileConfig - object might be a time consuming operation). In this case, you may create - this global config object in the very start of the program and Set() it as - the default. Then, from anywhere in your program, you may access it using - the Get() function. This global wxConfig object will be deleted by - wxWidgets automatically if it exists. Note that this implies that if you do - delete this object yourself (usually in wxApp::OnExit()) you must use - Set(@NULL) to prevent wxWidgets from deleting it the second time. - - As it happens, you may even further simplify the procedure described above: - you may forget about calling Set(). When Get() is called and there is no - current object, it will create one using Create() function. To disable this - behaviour DontCreateOnDemand() is provided. - - @note You should use either Set() or Get() because wxWidgets library itself - would take advantage of it and could save various information in it. - For example wxFontMapper or Unix version of wxFileDialog have the - ability to use wxConfig class. - - - @section configbase_paths Path Management - - As explained in the @ref overview_config "config overview", the config - classes support a file system-like hierarchy of keys (files) and groups - (directories). As in the file system case, to specify a key in the config - class you must use a path to it. Config classes also support the notion of - the current group, which makes it possible to use the relative paths. To - clarify all this, here is an example (it is only for the sake of - demonstration, it doesn't do anything sensible!): - - @code - wxConfig *config = new wxConfig("FooBarApp"); - - // right now the current path is '/' - conf->Write("RootEntry", 1); - - // go to some other place: if the group(s) don't exist, they will be created - conf->SetPath("/Group/Subgroup"); - - // create an entry in subgroup - conf->Write("SubgroupEntry", 3); - - // '..' is understood - conf->Write("../GroupEntry", 2); - conf->SetPath(".."); - - wxASSERT( conf->ReadLong("Subgroup/SubgroupEntry", 0) == 3 ); - - // use absolute path: it is allowed, too - wxASSERT( conf->ReadLong("/RootEntry", 0) == 1 ); - @endcode - - It is highly recommended that you restore the path to its old value on - function exit: - - @code - void foo(wxConfigBase *config) - { - wxString strOldPath = config->GetPath(); - - config->SetPath("/Foo/Data"); - // ... - - config->SetPath(strOldPath); - } - @endcode - - Otherwise the assert in the following example will surely fail (we suppose - here that the foo() function is the same as above except that it doesn’t - save and restore the path): - - @code - void bar(wxConfigBase *config) - { - config->Write("Test", 17); - - foo(config); - - // we're reading "/Foo/Data/Test" here! -1 will probably be returned... - wxASSERT( config->ReadLong("Test", -1) == 17 ); - } - @endcode - - Finally, the path separator in wxConfigBase and derived classes is always - "/", regardless of the platform (i.e. it is not "\\" under Windows). - - - @section configbase_enumeration Enumeration - - The enumeration functions allow you to enumerate all entries and groups in - the config file. All functions here return @false when there are no more - items. - - You must pass the same index to GetNext() and GetFirst() (don't modify it). - Please note that it is not the index of the current item (you will have - some great surprises with wxRegConfig if you assume this) and you shouldn't - even look at it: it is just a "cookie" which stores the state of the - enumeration. It can't be stored inside the class because it would prevent - you from running several enumerations simultaneously, that's why you must - pass it explicitly. - - Having said all this, enumerating the config entries/groups is very simple: - - @code - wxConfigBase *config = ...; - wxArrayString aNames; - - // enumeration variables - wxString str; - long dummy; - - // first enum all entries - bool bCont = config->GetFirstEntry(str, dummy); - while ( bCont ) { - aNames.Add(str); - - bCont = GetConfig()->GetNextEntry(str, dummy); - } - - // ... we have all entry names in aNames... - - // now all groups... - bCont = GetConfig()->GetFirstGroup(str, dummy); - while ( bCont ) { - aNames.Add(str); - - bCont = GetConfig()->GetNextGroup(str, dummy); - } - - // ... we have all group (and entry) names in aNames... - @endcode - - There are also functions to get the number of entries/subgroups without - actually enumerating them, but you will probably never need them. - - - @section configbase_keyaccess Key Access - - The key access functions are the core of wxConfigBase class: they allow you - to read and write config file data. All Read() functions take a default - value which will be returned if the specified key is not found in the - config file. - - Currently, supported types of data are: wxString, @c long, @c double, - @c bool, wxColour and any other types for which the functions - wxToString() and wxFromString() are defined. - - Try not to read long values into string variables and vice versa: - although it just might work with wxFileConfig, you will get a system - error with wxRegConfig because in the Windows registry the different - types of entries are indeed used. - - Final remark: the @a szKey parameter for all these functions can - contain an arbitrary path (either relative or absolute), not just the - key name. - - @beginWxPythonOnly - In place of a single overloaded method name, wxPython implements the - following methods: - - Read(key, default="") - Returns a string. - - ReadInt(key, default=0) - Returns an integer. - - ReadFloat(key, default=0.0) - Returns a floating point number. - - ReadBool(key, default=0) - Returns a boolean. - - Write(key, value) - Writes a string. - - WriteInt(key, value) - Writes an int. - - WriteFloat(key, value) - Writes a floating point number. - @endWxPythonOnly - - - @library{wxbase} - @category{misc} -*/ -class wxConfigBase : public wxObject -{ -public: - /** - This is the default and only constructor of the wxConfigBase class, and - derived classes. - - @param appName - The application name. If this is empty, the class will normally use - wxApp::GetAppName() to set it. The application name is used in the - registry key on Windows, and can be used to deduce the local - filename parameter if that is missing. - @param vendorName - The vendor name. If this is empty, it is assumed that no vendor - name is wanted, if this is optional for the current config class. - The vendor name is appended to the application name for - wxRegConfig. - @param localFilename - Some config classes require a local filename. If this is not - present, but required, the application name will be used instead. - @param globalFilename - Some config classes require a global filename. If this is not - present, but required, the application name will be used instead. - @param style - Can be one of wxCONFIG_USE_LOCAL_FILE and wxCONFIG_USE_GLOBAL_FILE. - The style interpretation depends on the config class and is ignored - by some implementations. For wxFileConfig, these styles determine - whether a local or global config file is created or used: if - wxCONFIG_USE_GLOBAL_FILE is used, then settings are read from the - global config file and if wxCONFIG_USE_LOCAL_FILE is used, settings - are read from and written to local config file (if they are both - set, global file is read first, then local file, overwriting global - settings). If the flag is present but the parameter is empty, the - parameter will be set to a default. If the parameter is present but - the style flag not, the relevant flag will be added to the style. - For wxRegConfig, thie GLOBAL flag refers to HKLM key while LOCAL - one is for the usual HKCU one. - @n For wxFileConfig you can also add wxCONFIG_USE_RELATIVE_PATH by - logically or'ing it to either of the _FILE options to tell - wxFileConfig to use relative instead of absolute paths. - @n On non-VMS Unix systems, the default local configuration file is - "~/.appname". However, this path may be also used as user data - directory (see wxStandardPaths::GetUserDataDir()) if the - application has several data files. In this case - wxCONFIG_USE_SUBDIR flag, which changes the default local - configuration file to "~/.appname/appname" should be used. Notice - that this flag is ignored if localFilename is provided. - wxCONFIG_USE_SUBDIR is new since wxWidgets version 2.8.2. - @n For wxFileConfig, you can also add - wxCONFIG_USE_NO_ESCAPE_CHARACTERS which will turn off character - escaping for the values of entries stored in the config file: for - example a foo key with some backslash characters will be stored as - "foo=C:\mydir" instead of the usual storage of "foo=C:\\mydir". - @n The wxCONFIG_USE_NO_ESCAPE_CHARACTERS style can be helpful if your - config file must be read or written to by a non-wxWidgets program - (which might not understand the escape characters). Note, however, - that if wxCONFIG_USE_NO_ESCAPE_CHARACTERS style is used, it is is - now your application's responsibility to ensure that there is no - newline or other illegal characters in a value, before writing that - value to the file. - @param conv - This parameter is only used by wxFileConfig when compiled in - Unicode mode. It specifies the encoding in which the configuration - file is written. - - @remarks By default, environment variable expansion is on and recording - defaults is off. - */ - wxConfigBase(const wxString& appName = wxEmptyString, - const wxString& vendorName = wxEmptyString, - const wxString& localFilename = wxEmptyString, - const wxString& globalFilename = wxEmptyString, - long style = 0, - const wxMBConv& conv = wxConvAuto()); - - /** - Empty but ensures that dtor of all derived classes is virtual. - */ - ~wxConfigBase(); - - - /** - @name Path Management - - See @ref configbase_paths - */ - //@{ - - /** - Retrieve the current path (always as absolute path). - */ - const wxString GetPath() const; - - /** - Set current path: if the first character is '/', it is the absolute - path, otherwise it is a relative path. '..' is supported. If @a strPath - doesn't exist it is created. - */ - void SetPath(const wxString& strPath); - - //@} - - - /** - @name Enumeration - - See @ref configbase_enumeration - */ - //@{ - - /** - Gets the first entry. - - @beginWxPythonOnly - The wxPython version of this method returns a 3-tuple consisting of the - continue flag, the value string, and the index for the next call. - @endWxPythonOnly - */ - bool GetFirstEntry(wxString& str, long& index) const; - - /** - Gets the first group. - - @beginWxPythonOnly - The wxPython version of this method returns a 3-tuple consisting of the - continue flag, the value string, and the index for the next call. - @endWxPythonOnly - */ - bool GetFirstGroup(wxString& str, long& index) const; - - /** - Gets the next entry. - - @beginWxPythonOnly - The wxPython version of this method returns a 3-tuple consisting of the - continue flag, the value string, and the index for the next call. - @endWxPythonOnly - */ - bool GetNextEntry(wxString& str, long& index) const; - - /** - Gets the next group. - - @beginWxPythonOnly - The wxPython version of this method returns a 3-tuple consisting of the - continue flag, the value string, and the index for the next call. - @endWxPythonOnly - */ - bool GetNextGroup(wxString& str, long& index) const; - - /** - Get number of entries in the current group. - */ - uint GetNumberOfEntries(bool bRecursive = false) const; - - /** - Get number of entries/subgroups in the current group, with or without - its subgroups. - */ - uint GetNumberOfGroups(bool bRecursive = false) const; - - //@} - - - enum EntryType - { - Type_Unknown, - Type_String, - Type_Boolean, - Type_Integer, - Type_Float - }; - - /** - @name Tests of Existence - */ - //@{ - - /** - @return @true if either a group or an entry with a given name exists. - */ - bool Exists(wxString& strName) const; - - /** - Returns the type of the given entry or @e Unknown if the entry doesn't - exist. This function should be used to decide which version of Read() - should be used because some of wxConfig implementations will complain - about type mismatch otherwise: e.g., an attempt to read a string value - from an integer key with wxRegConfig will fail. - */ - wxConfigBase::EntryType GetEntryType(const wxString& name) const; - - /** - @return @true if the entry by this name exists. - */ - bool HasEntry(wxString& strName) const; - - /** - @return @true if the group by this name exists. - */ - bool HasGroup(const wxString& strName) const; - - //@} - - - /** - @name Miscellaneous Functions - */ - //@{ - - /** - Returns the application name. - */ - wxString GetAppName() const; - - /** - Returns the vendor name. - */ - wxString GetVendorName() const; - - //@} - - - /** - @name Key Access - - See @ref configbase_keyaccess - */ - //@{ - - /** - Permanently writes all changes (otherwise, they're only written from - object's destructor). - */ - bool Flush(bool bCurrentOnly = false); - - /** - Read a string from the key, returning @true if the value was read. If - the key was not found, @a str is not changed. - */ - bool Read(const wxString& key, wxString* str) const; - /** - Read a string from the key. The default value is returned if the key - was not found. - - @return @true if value was really read, @false if the default was used. - */ - const bool Read(const wxString& key, wxString* str, - const wxString& defaultVal) const; - /** - Another version of Read(), returning the string value directly. - */ - const wxString Read(const wxString& key, - const wxString& defaultVal) const; - /** - Reads a long value, returning @true if the value was found. If the - value was not found, @a l is not changed. - */ - const bool Read(const wxString& key, long* l) const; - /** - Reads a long value, returning @true if the value was found. If the - value was not found, @a defaultVal is used instead. - */ - const bool Read(const wxString& key, long* l, - long defaultVal) const; - /** - Reads a double value, returning @true if the value was found. If the - value was not found, @a d is not changed. - */ - const bool Read(const wxString& key, double* d) const; - /** - Reads a double value, returning @true if the value was found. If the - value was not found, @a defaultVal is used instead. - */ - const bool Read(const wxString& key, double* d, - double defaultVal) const; - /** - Reads a bool value, returning @true if the value was found. If the - value was not found, @a b is not changed. - */ - const bool Read(const wxString& key, bool* b) const; - /** - Reads a bool value, returning @true if the value was found. If the - value was not found, @a defaultVal is used instead. - */ - const bool Read(const wxString& key, bool* d, - bool defaultVal) const; - /** - Reads a binary block, returning @true if the value was found. If the - value was not found, @a buf is not changed. - */ - const bool Read(const wxString& key, wxMemoryBuffer* buf) const; - /** - Reads a value of type T, for which function wxFromString() is defined, - returning @true if the value was found. If the value was not found, - @a value is not changed. - */ - const bool Read(const wxString& key, T* value) const; - /** - Reads a value of type T, for which function wxFromString() is defined, - returning @true if the value was found. If the value was not found, - @a defaultVal is used instead. - */ - const bool Read(const wxString& key, T* value, - const T& defaultVal) const; - - /** - Reads a bool value from the key and returns it. @a defaultVal is - returned if the key is not found. - */ - long ReadBool(const wxString& key, bool defaultVal) const; - - /** - Reads a double value from the key and returns it. @a defaultVal is - returned if the key is not found. - */ - long ReadDouble(const wxString& key, double defaultVal) const; - - /** - Reads a long value from the key and returns it. @a defaultVal is - returned if the key is not found. - */ - long ReadLong(const wxString& key, long defaultVal) const; - - /** - Reads a value of type T (for which the function wxFromString() must be - defined) from the key and returns it. @a defaultVal is returned if the - key is not found. - */ - T ReadObject(const wxString& key, T const& defaultVal) const; - - /** - Writes the wxString value to the config file and returns @true on - success. - */ - bool Write(const wxString& key, const wxString& value); - /** - Writes the long value to the config file and returns @true on success. - */ - bool Write(const wxString& key, long value); - /** - Writes the double value to the config file and returns @true on - success. - */ - bool Write(const wxString& key, double value); - /** - Writes the bool value to the config file and returns @true on success. - */ - bool Write(const wxString& key, bool value); - /** - Writes the wxMemoryBuffer value to the config file and returns @true on - success. - */ - bool Write(const wxString& key, const wxMemoryBuffer& buf); - /** - Writes the specified value to the config file and returns @true on - success. The function wxToString() must be defined for type @e T. - */ - bool Write(const wxString& key, T const& buf); - - //@} - - - /** - @name Rename Entries/Groups - - These functions allow renaming entries or subgroups of the current - group. They will return @false on error, typically because either the - entry/group with the original name doesn't exist, because the - entry/group with the new name already exists or because the function is - not supported in this wxConfig implementation. - */ - //@{ - - /** - Renames an entry in the current group. The entries names (both the old - and the new one) shouldn't contain backslashes, i.e. only simple names - and not arbitrary paths are accepted by this function. - - @return @false if @a oldName doesn't exist or if @a newName already - exists. - */ - bool RenameEntry(const wxString& oldName, const wxString& newName); - - /** - Renames a subgroup of the current group. The subgroup names (both the - old and the new one) shouldn't contain backslashes, i.e. only simple - names and not arbitrary paths are accepted by this function. - - @return @false if @a oldName doesn't exist or if @a newName already - exists. - */ - bool RenameGroup(const wxString& oldName, const wxString& newName); - - //@} - - - /** - @name Delete Entries/Groups - - These functions delete entries and/or groups of entries from the config - file. DeleteAll() is especially useful if you want to erase all traces - of your program presence: for example, when you uninstall it. - */ - //@{ - - /** - Delete the whole underlying object (disk file, registry key, ...). - Primarly for use by uninstallation routine. - */ - bool DeleteAll(); - - /** - Deletes the specified entry and the group it belongs to if it was the - last key in it and the second parameter is @true. - */ - bool DeleteEntry(const wxString& key, - bool bDeleteGroupIfEmpty = true); - - /** - Delete the group (with all subgroups). If the current path is under the - group being deleted it is changed to its deepest still existing - component. E.g. if the current path is @c "/A/B/C/D" and the group @c C - is deleted, the path becomes @c "/A/B". - */ - bool DeleteGroup(const wxString& key); - - //@} - - - /** - @name Options - - Some aspects of wxConfigBase behaviour can be changed during run-time. - The first of them is the expansion of environment variables in the - string values read from the config file: for example, if you have the - following in your config file: - - @code - # config file for my program - UserData = $HOME/data - - # the following syntax is valud only under Windows - UserData = %windir%\\data.dat - @endcode - - The call to Read("UserData") will return something like - @c "/home/zeitlin/data" on linux for example. - - Although this feature is very useful, it may be annoying if you read a - value which containts '$' or '%' symbols (% is used for environment - variables expansion under Windows) which are not used for environment - variable expansion. In this situation you may call - SetExpandEnvVars(@false) just before reading this value and - SetExpandEnvVars(@true) just after. Another solution would be to prefix - the offending symbols with a backslash. - */ - //@{ - - /** - Returns @true if we are expanding environment variables in key values. - */ - bool IsExpandingEnvVars() const; - - /** - Returns @true if we are writing defaults back to the config file. - */ - bool IsRecordingDefaults() const; - - /** - Determine whether we wish to expand environment variables in key - values. - */ - void SetExpandEnvVars(bool bDoIt = true); - - /** - Sets whether defaults are recorded to the config file whenever an - attempt to read the value which is not present in it is done. - - If on (default is off) all default values for the settings used by the - program are written back to the config file. This allows the user to - see what config options may be changed and is probably useful only for - wxFileConfig. - */ - void SetRecordDefaults(bool bDoIt = true); - - //@} - - - /** - Create a new config object: this function will create the "best" - implementation of wxConfig available for the current platform, see - comments near the definition of wxCONFIG_WIN32_NATIVE for details. It - returns the created object and also sets it as the current one. - */ - static wxConfigBase* Create(); - - /** - Calling this function will prevent @e Get() from automatically creating - a new config object if the current one is @NULL. It might be useful to - call it near the program end to prevent "accidental" creation of a new - config object. - */ - static void DontCreateOnDemand(); - - /** - Get the current config object. If there is no current object and - @a CreateOnDemand is @true, this creates one (using Create()) unless - DontCreateOnDemand() was called previously. - */ - static wxConfigBase* Get(bool CreateOnDemand = true); - - /** - Sets the config object as the current one, returns the pointer to the - previous current object (both the parameter and returned value may be - @NULL). - */ - static wxConfigBase* Set(wxConfigBase* pConfig); -}; - diff --git a/interface/control.h b/interface/control.h deleted file mode 100644 index 2a9f824059..0000000000 --- a/interface/control.h +++ /dev/null @@ -1,62 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: control.h -// Purpose: interface of wxControl -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxControl - @wxheader{control.h} - - This is the base class for a control or "widget". - - A control is generally a small window which processes user input and/or - displays one or more item of data. - - @library{wxcore} - @category{ctrl} - - @see wxValidator -*/ -class wxControl : public wxWindow -{ -public: - /** - Simulates the effect of the user issuing a command to the item. - - @see wxCommandEvent - */ - void Command(wxCommandEvent& event); - - /** - Returns the control's text. - - @note The returned string contains mnemonics ("&" characters) if it has - any, use GetLabelText() if they are undesired. - */ - wxString GetLabel() const; - - /** - Returns the control's label without mnemonics. - */ - const wxString GetLabelText(); - - /** - Returns the given @a label string without mnemonics. - */ - static wxString GetLabelText(const wxString& label); - - /** - Sets the item's text. - - Any "&" characters in the @a label are special and indicate that the - following character is a mnemonic for this control and can be used to - activate it from the keyboard (typically by using @e Alt key in - combination with it). To insert a literal ampersand character, you need - to double it, i.e. use "&&". - */ - void SetLabel(const wxString& label); -}; - diff --git a/interface/convauto.h b/interface/convauto.h deleted file mode 100644 index 2de565d473..0000000000 --- a/interface/convauto.h +++ /dev/null @@ -1,97 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: convauto.h -// Purpose: interface of wxConvAuto -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxConvAuto - @wxheader{convauto.h} - - This class implements a Unicode to/from multibyte converter capable of - automatically recognizing the encoding of the multibyte text on input. The - logic used is very simple: the class uses the BOM (byte order mark) if it's - present and tries to interpret the input as UTF-8 otherwise. If this fails, - the input is interpreted as being in the default multibyte encoding which - can be specified in the constructor of a wxConvAuto instance and, in turn, - defaults to the value of GetFallbackEncoding() if not explicitly given. - - For the conversion from Unicode to multibyte, the same encoding as was - previously used for multibyte to Unicode conversion is reused. If there had - been no previous multibyte to Unicode conversion, UTF-8 is used by default. - Notice that once the multibyte encoding is automatically detected, it - doesn't change any more, i.e. it is entirely determined by the first use of - wxConvAuto object in the multibyte-to-Unicode direction. However creating a - copy of wxConvAuto object, either via the usual copy constructor or - assignment operator, or using wxMBConv::Clone(), resets the automatically - detected encoding so that the new copy will try to detect the encoding of - the input on first use. - - This class is used by default in wxWidgets classes and functions reading - text from files such as wxFile, wxFFile, wxTextFile, wxFileConfig and - various stream classes so the encoding set with its SetFallbackEncoding() - method will affect how these classes treat input files. In particular, use - this method to change the fall-back multibyte encoding used to interpret - the contents of the files whose contents isn't valid UTF-8 or to disallow - it completely. - - @library{wxbase} - @category{data} - - @see @ref overview_mbconv -*/ -class wxConvAuto : public wxMBConv -{ -public: - /** - Constructs a new wxConvAuto instance. The object will try to detect the - input of the multibyte text given to its wxMBConv::ToWChar() method - automatically but if the automatic detection of Unicode encodings - fails, the fall-back encoding @a enc will be used to interpret it as - multibyte text. - - The default value of @a enc, @c wxFONTENCODING_DEFAULT, means that the - global default value (which can be set using SetFallbackEncoding()) - should be used. As with that method, passing @c wxFONTENCODING_MAX - inhibits using this encoding completely so the input multibyte text - will always be interpreted as UTF-8 in the absence of BOM and the - conversion will fail if the input doesn't form valid UTF-8 sequence. - - Another special value is @c wxFONTENCODING_SYSTEM which means to use - the encoding currently used on the user system, i.e. the encoding - returned by wxLocale::GetSystemEncoding(). Any other encoding will be - used as is, e.g. passing @c wxFONTENCODING_ISO8859_1 ensures that - non-UTF-8 input will be treated as latin1. - */ - wxConvAuto(wxFontEncoding enc = wxFONTENCODING_DEFAULT); - - /** - Disable the use of the fall back encoding: if the input doesn't have a - BOM and is not valid UTF-8, the conversion will fail. - */ - static void DisableFallbackEncoding(); - - /** - Returns the encoding used by default by wxConvAuto if no other encoding - is explicitly specified in constructor. By default, returns - @c wxFONTENCODING_ISO8859_1 but can be changed using - SetFallbackEncoding(). - */ - static wxFontEncoding GetFallbackEncoding(); - - /** - Changes the encoding used by default by wxConvAuto if no other encoding - is explicitly specified in constructor. The default value, which can be - retrieved using GetFallbackEncoding(), is @c wxFONTENCODING_ISO8859_1. - - Special values of @c wxFONTENCODING_SYSTEM or @c wxFONTENCODING_MAX can - be used for the @a enc parameter to use the encoding of the current - user locale as fall back or not use any encoding for fall back at all, - respectively (just as with the similar constructor parameter). However, - @c wxFONTENCODING_DEFAULT can't be used here. - */ - static void SetFallbackEncoding(wxFontEncoding enc); -}; - diff --git a/interface/cpp.h b/interface/cpp.h deleted file mode 100644 index b8585c519c..0000000000 --- a/interface/cpp.h +++ /dev/null @@ -1,52 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: cpp.h -// Purpose: interface of global functions -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - - -/** @ingroup group_funcmacro_misc */ -//@{ -/** - This macro returns the concatenation of the arguments passed. Unlike when - using the preprocessor operator, the arguments undergo macro expansion - before being concatenated. - - @header{wx/cpp.h} -*/ -#define wxCONCAT(x1, x2) -#define wxCONCAT3(x1, x2, x3) -#define wxCONCAT4(x1, x2, x3, x4) -#define wxCONCAT5(x1, x2, x3, x4, x5) -//@} - -/** @ingroup group_funcmacro_misc */ -//@{ - -/** - Returns the string representation of the given symbol which can be either a - literal or a macro (hence the advantage of using this macro instead of the - standard preprocessor @c # operator which doesn't work with macros). - - Notice that this macro always produces a @c char string, use - wxSTRINGIZE_T() to build a wide string Unicode build. - - @see wxCONCAT() - - @header{wx/cpp.h} -*/ -#define wxSTRINGIZE(x) - -/** - Returns the string representation of the given symbol as either an ASCII or - Unicode string, depending on the current build. This is the - Unicode-friendly equivalent of wxSTRINGIZE(). - - @header{wx/cpp.h} -*/ -#define wxSTRINGIZE_T(x) - -//@} - diff --git a/interface/cshelp.h b/interface/cshelp.h deleted file mode 100644 index e727f54a71..0000000000 --- a/interface/cshelp.h +++ /dev/null @@ -1,301 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: cshelp.h -// Purpose: interface of wxHelpProvider -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxHelpProvider - @wxheader{cshelp.h} - - wxHelpProvider is an abstract class used by a program implementing - context-sensitive help to show the help text for the given window. - - The current help provider must be explicitly set by the application using - Set(). - - @library{wxcore} - @category{help} - - @see wxContextHelp, wxContextHelpButton, wxSimpleHelpProvider, - wxHelpControllerHelpProvider, wxWindow::SetHelpText(), - wxWindow::GetHelpTextAtPoint() -*/ -class wxHelpProvider -{ -public: - /** - Virtual destructor for any base class. - */ - virtual ~wxHelpProvider(); - - /** - Associates the text with the given window. - - @remarks - Although all help providers have these functions to allow making - wxWindow::SetHelpText() work, not all of them implement the functions. - */ - virtual void AddHelp(wxWindowBase* window, const wxString& text); - - /** - Associates the text with the given ID. - - This help text will be shown for all windows with ID @a id, unless they - have more specific help text associated using the other AddHelp() - prototype. May be used to set the same help string for all Cancel - buttons in the application, for example. - - @remarks - Although all help providers have these functions to allow making - wxWindow::SetHelpText() work, not all of them implement the functions. - */ - virtual void AddHelp(wxWindowID id, const wxString& text); - - /** - Returns pointer to help provider instance. - - Unlike some other classes, the help provider is not created on demand. - This must be explicitly done by the application using Set(). - */ - static wxHelpProvider* Get(); - - /** - This version associates the given text with all windows with this id. - May be used to set the same help string for all Cancel buttons in - the application, for example. - */ - virtual wxString GetHelp(const wxWindowBase* window); - - /** - Removes the association between the window pointer and the help text. - This is called by the wxWindow destructor. Without this, the table of - help strings will fill up and when window pointers are reused, the - wrong help string will be found. - */ - virtual void RemoveHelp(wxWindowBase* window); - - /** - Set the current, application-wide help provider. - - @return Pointer to previous help provider or @NULL if there wasn't any. - */ - static wxHelpProvider* Set(wxHelpProvider* helpProvider); - - /** - Shows help for the given window. - - Override this function if the help doesn't depend on the exact position - inside the window, otherwise you need to override ShowHelpAtPoint(). - Returns @true if help was shown, or @false if no help was available for - this window. - */ - virtual bool ShowHelp(wxWindowBase* window); - - /** - This function may be overridden to show help for the window when it - should depend on the position inside the window, By default this method - forwards to ShowHelp(), so it is enough to only implement the latter if - the help doesn't depend on the position. - - @param window - Window to show help text for. - @param point - Coordinates of the mouse at the moment of help event emission. - @param origin - Help event origin, see wxHelpEvent::GetOrigin. - - @return @true if help was shown, or @false if no help was available - for this window. - - @since 2.7.0 - */ - virtual bool ShowHelpAtPoint(wxWindowBase* window, const wxPoint point, - wxHelpEvent::Origin origin); -}; - - - -/** - @class wxHelpControllerHelpProvider - @wxheader{cshelp.h} - - wxHelpControllerHelpProvider is an implementation of wxHelpProvider which - supports both context identifiers and plain text help strings. If the help - text is an integer, it is passed to wxHelpController::DisplayContextPopup(). - Otherwise, it shows the string in a tooltip as per wxSimpleHelpProvider. If - you use this with a wxCHMHelpController instance on windows, it will use - the native style of tip window instead of wxTipWindow. - - You can use the convenience function wxContextId() to convert an integer - context id to a string for passing to wxWindow::SetHelpText(). - - @library{wxcore} - @category{help} - - @see wxHelpProvider, wxSimpleHelpProvider, wxContextHelp, - wxWindow::SetHelpText(), wxWindow::GetHelpTextAtPoint() -*/ -class wxHelpControllerHelpProvider : public wxSimpleHelpProvider -{ -public: - /** - Note that the instance doesn't own the help controller. The help - controller should be deleted separately. - */ - wxHelpControllerHelpProvider(wxHelpControllerBase* hc = NULL); - - /** - Returns the help controller associated with this help provider. - */ - wxHelpControllerBase* GetHelpController() const; - - /** - Sets the help controller associated with this help provider. - */ - void SetHelpController(wxHelpControllerBase* hc); -}; - - - -/** - @class wxContextHelp - @wxheader{cshelp.h} - - This class changes the cursor to a query and puts the application into a - 'context-sensitive help mode'. When the user left-clicks on a window - within the specified window, a wxEVT_HELP event is sent to that control, - and the application may respond to it by popping up some help. - - For example: - @code - wxContextHelp contextHelp(myWindow); - @endcode - - There are a couple of ways to invoke this behaviour implicitly: - - - Use the wxDIALOG_EX_CONTEXTHELP style for a dialog (Windows only). This - will put a question mark in the titlebar, and Windows will put the - application into context-sensitive help mode automatically, with further - programming. - - - Create a wxContextHelpButton, whose predefined behaviour is - to create a context help object. Normally you will write your application - so that this button is only added to a dialog for non-Windows platforms - (use wxDIALOG_EX_CONTEXTHELP on Windows). - - Note that on Mac OS X, the cursor does not change when in context-sensitive - help mode. - - @library{wxcore} - @category{help} - - @see wxHelpEvent, wxHelpController, wxContextHelpButton -*/ -class wxContextHelp : public wxObject -{ -public: - /** - Constructs a context help object, calling BeginContextHelp() if - @a doNow is @true (the default). - - If @a window is @NULL, the top window is used. - */ - wxContextHelp(wxWindow* window = NULL, bool doNow = true); - - /** - Destroys the context help object. - */ - ~wxContextHelp(); - - /** - Puts the application into context-sensitive help mode. @a window is the - window which will be used to catch events; if @NULL, the top window - will be used. Returns @true if the application was successfully put - into context-sensitive help mode. This function only returns when the - event loop has finished. - */ - bool BeginContextHelp(wxWindow* window = NULL); - - /** - Ends context-sensitive help mode. Not normally called by the - application. - */ - bool EndContextHelp(); -}; - - - -/** - @class wxContextHelpButton - @wxheader{cshelp.h} - - Instances of this class may be used to add a question mark button that when - pressed, puts the application into context-help mode. It does this by - creating a wxContextHelp object which itself generates a wxEVT_HELP event - when the user clicks on a window. - - On Windows, you may add a question-mark icon to a dialog by use of the - wxDIALOG_EX_CONTEXTHELP extra style, but on other platforms you will have - to add a button explicitly, usually next to OK, Cancel or similar buttons. - - @library{wxcore} - @category{help} - - @see wxBitmapButton, wxContextHelp -*/ -class wxContextHelpButton : public wxBitmapButton -{ -public: - /// Default constructor. - wxContextHelpButton(); - - /** - Constructor, creating and showing a context help button. - - @param parent - Parent window. Must not be @NULL. - @param id - Button identifier. Defaults to wxID_CONTEXT_HELP. - @param pos - Button position. - @param size - Button size. If wxDefaultSize is specified then the button is sized - appropriately for the question mark bitmap. - @param style - Window style. - - @remarks - Normally you only need pass the parent window to the constructor, and - use the defaults for the remaining parameters. - */ - wxContextHelpButton(wxWindow* parent, - wxWindowID id = wxID_CONTEXT_HELP, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = wxBU_AUTODRAW); -}; - - -/** - @class wxSimpleHelpProvider - @wxheader{cshelp.h} - - wxSimpleHelpProvider is an implementation of wxHelpProvider which supports - only plain text help strings, and shows the string associated with the - control (if any) in a tooltip. - - @library{wxcore} - @category{help} - - @see wxHelpProvider, wxHelpControllerHelpProvider, wxContextHelp, - wxWindow::SetHelpText()(, wxWindow::GetHelpTextAtPoint() -*/ -class wxSimpleHelpProvider : public wxHelpProvider -{ -public: - -}; - diff --git a/interface/ctrlsub.h b/interface/ctrlsub.h deleted file mode 100644 index f540761470..0000000000 --- a/interface/ctrlsub.h +++ /dev/null @@ -1,665 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: ctrlsub.h -// Purpose: interface of wxControlWithItems -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - - -/** - @class wxItemContainerImmutable - @wxheader{ctrlsub.h} - - wxItemContainer defines an interface which is implemented by all controls - which have string subitems each of which may be selected. - - It is decomposed in wxItemContainerImmutable which omits all methods - adding/removing items and is used by wxRadioBox and wxItemContainer itself. - - Note that this is not a control, it's a mixin interface that classes - have to derive from in addition to wxControl or wxWindow. - - Examples: wxListBox, wxCheckListBox, wxChoice and wxComboBox (which - implements an extended interface deriving from this one) - - @library{wxcore} - @category{ctrl} - - @see wxControlWithItems, wxItemContainer -*/ -class wxItemContainerImmutable -{ -public: - /// Constructor - wxItemContainerImmutable(); - - //@{ - - /** - Returns the number of items in the control. - - @see IsEmpty() - */ - virtual unsigned int GetCount() const; - - /** - Returns @true if the control is empty or @false if it has some items. - - @see GetCount() - */ - bool IsEmpty() const; - - /** - Returns the label of the item with the given index. - - @param n - The zero-based index. - - @return The label of the item or an empty string if the position was - invalid. - */ - virtual wxString GetString(unsigned int n) const; - - /** - Returns the array of the labels of all items in the control. - */ - wxArrayString GetStrings() const; - - /** - Sets the label for the given item. - - @param n - The zero-based item index. - @param string - The label to set. - */ - virtual void SetString(unsigned int n, const wxString& s); - - /** - Finds an item whose label matches the given string. - - @param string - String to find. - @param caseSensitive - Whether search is case sensitive (default is not). - - @return The zero-based position of the item, or wxNOT_FOUND if the - string was not found. - */ - virtual int FindString(const wxString& s, bool bCase = false) const; - - //@} - - /// @name Selection - //@{ - - /** - Sets the selection to the given item @a n or removes the selection - entirely if @a n == @c wxNOT_FOUND. - - Note that this does not cause any command events to be emitted nor does - it deselect any other items in the controls which support multiple - selections. - - @param n - The string position to select, starting from zero. - - @see SetString(), SetStringSelection() - */ - virtual void SetSelection(int n); - - /** - Returns the index of the selected item or @c wxNOT_FOUND if no item is - selected. - - @return The position of the current selection. - - @remarks This method can be used with single selection list boxes only, - you should use wxListBox::GetSelections() for the list - boxes with wxLB_MULTIPLE style. - - @see SetSelection(), GetStringSelection() - */ - virtual int GetSelection() const; - - /** - Selects the item with the specified string in the control. This doesn't - cause any command events to be emitted. - - @param string - The string to select. - - @return @true if the specified string has been selected, @false if it - wasn't found in the control. - */ - bool SetStringSelection(const wxString& string); - - /** - Returns the label of the selected item or an empty string if no item is - selected. - - @see GetSelection() - */ - virtual wxString GetStringSelection() const; - - /** - This is the same as SetSelection() and exists only because it is - slightly more natural for controls which support multiple selection. - */ - void Select(int n); - - //@} -}; - - -/** - @class wxItemContainer - @wxheader{ctrlsub.h} - - This class is an abstract base class for some wxWidgets controls which - contain several items such as wxListBox, wxCheckListBox, wxComboBox or - wxChoice. It defines an interface which is implemented by all controls - which have string subitems each of which may be selected. - - wxItemContainer extends wxItemContainerImmutable interface with methods - for adding/removing items. - - It defines the methods for accessing the controls items and although each - of the derived classes implements them differently, they still all conform - to the same interface. - - The items in a wxItemContainer have (non-empty) string labels and, - optionally, client data associated with them. Client data may be of two - different kinds: either simple untyped (@c void *) pointers which are - simply stored by the control but not used in any way by it, or typed - pointers (wxClientData*) which are owned by the control meaning that the - typed client data (and only it) will be deleted when an item is deleted - using Delete() or the entire control is cleared using Clear(), which also - happens when it is destroyed. - - Finally note that in the same control all items must have client data of - the same type (typed or untyped), if any. This type is determined by the - first call to Append() (the version with client data pointer) or - SetClientData(). - - Note that this is not a control, it's a mixin interface that classes - have to derive from in addition to wxControl or wxWindow. Convenience - class wxControlWithItems is provided for this purpose. - - @library{wxcore} - @category{ctrl} - - @see wxControlWithItems, wxItemContainerImmutable -*/ -class wxItemContainer : public wxItemContainerImmutable -{ -public: - //@{ - - /** - Appends item into the control. - - @param item - String to add. - - @return The return value is the index of the newly inserted item. - Note that this may be different from the last one if the - control is sorted (e.g. has @c wxLB_SORT or @c wxCB_SORT - style). - */ - int Append(const wxString& item); - - /** - Appends item into the control. - - @param item - String to add. - @param clientData - Pointer to client data to associate with the new item. - - @return The return value is the index of the newly inserted item. - Note that this may be different from the last one if the - control is sorted (e.g. has @c wxLB_SORT or @c wxCB_SORT - style). - */ - int Append(const wxString& item, void* clientData); - - /** - Appends item into the control. - - @param item - String to add. - @param clientData - Pointer to client data to associate with the new item. - - @return The return value is the index of the newly inserted item. - Note that this may be different from the last one if the - control is sorted (e.g. has @c wxLB_SORT or @c wxCB_SORT - style). - */ - int Append(const wxString& item, wxClientData* clientData); - - /** - Appends several items at once into the control. - - Notice that calling this method is usually much faster than appending - them one by one if you need to add a lot of items. - - @param items - Array of strings to insert. - */ - void Append(const wxArrayString& items); - - /** - Appends several items at once into the control. - - Notice that calling this method is usually much faster than appending - them one by one if you need to add a lot of items. - - @param items - Array of strings to insert. - @param clientData - Array of client data pointers of the same size as @a items to - associate with the new items. - */ - void Append(const wxArrayString& items, void **clientData); - - /** - Appends several items at once into the control. - - Notice that calling this method is usually much faster than appending - them one by one if you need to add a lot of items. - - @param items - Array of strings to insert. - @param clientData - Array of client data pointers of the same size as @a items to - associate with the new items. - */ - void Append(const wxArrayString& items, wxClientData **clientData); - - /** - Appends several items at once into the control. - - Notice that calling this method is usually much faster than appending - them one by one if you need to add a lot of items. - - @param n - Number of items in the @a items array. - @param items - Array of strings of size @a n. - */ - void Append(unsigned int n, const wxString* items); - - /** - Appends several items at once into the control. - - Notice that calling this method is usually much faster than appending - them one by one if you need to add a lot of items. - - @param n - Number of items in the @a items array. - @param items - Array of strings of size @a n. - @param clientData - Array of client data pointers of size @a n to associate with the - new items. - */ - void Append(unsigned int n, const wxString* items, - void** clientData); - - /** - Appends several items at once into the control. - - Notice that calling this method is usually much faster than appending - them one by one if you need to add a lot of items. - - @param n - Number of items in the @a items array. - @param items - Array of strings of size @a n. - @param clientData - Array of client data pointers of size @a n to associate with the - new items. - */ - void Append(unsigned int n, const wxString* items, - wxClientData** clientData); - //@} - - /** - Removes all items from the control. - Clear() also deletes the client data of the existing items if it is - owned by the control. - */ - void Clear(); - - /** - Deletes an item from the control. - - The client data associated with the item will be also deleted if it is - owned by the control. Note that it is an error (signalled by an assert - failure in debug builds) to remove an item with the index negative or - greater or equal than the number of items in the control. - - @param n - The zero-based item index. - - @see Clear() - */ - void Delete(unsigned int n); - - //@{ - - /** - Returns a pointer to the client data associated with the given item (if - any). It is an error to call this function for a control which doesn't - have untyped client data at all although it is OK to call it even if - the given item doesn't have any client data associated with it (but - other items do). - - @param n - The zero-based position of the item. - - @return A pointer to the client data, or @NULL if not present. - */ - void* GetClientData(unsigned int n) const; - - /** - Returns a pointer to the client data associated with the given item (if - any). It is an error to call this function for a control which doesn't - have typed client data at all although it is OK to call it even if the - given item doesn't have any client data associated with it (but other - items do). - - @param n - The zero-based position of the item. - - @return A pointer to the client data, or @NULL if not present. - */ - wxClientData* GetClientObject(unsigned int n) const; - - /** - Associates the given untyped client data pointer with the given item. - Note that it is an error to call this function if any typed client data - pointers had been associated with the control items before. - - @param n - The zero-based item index. - @param data - The client data to associate with the item. - */ - void SetClientData(unsigned int n, void* data); - - /** - Associates the given typed client data pointer with the given item: the - @a data object will be deleted when the item is deleted (either - explicitly by using Delete() or implicitly when the control itself is - destroyed). Note that it is an error to call this function if any - untyped client data pointers had been associated with the control items - before. - - @param n - The zero-based item index. - @param data - The client data to associate with the item. - */ - void SetClientObject(unsigned int n, wxClientData* data); - - //@} - - //@{ - - /** - Inserts item into the control. - - @param item - String to add. - @param pos - Position to insert item before, zero based. - - @return The return value is the index of the newly inserted item. - If the insertion failed for some reason, -1 is returned. - */ - int Insert(const wxString& item, unsigned int pos); - - /** - Inserts item into the control. - - @param item - String to add. - @param pos - Position to insert item before, zero based. - @param clientData - Pointer to client data to associate with the new item. - - @return The return value is the index of the newly inserted item. - If the insertion failed for some reason, -1 is returned. - */ - int Insert(const wxString& item, unsigned int pos, void* clientData); - - /** - Inserts item into the control. - - @param item - String to add. - @param pos - Position to insert item before, zero based. - @param clientData - Pointer to client data to associate with the new item. - - @return The return value is the index of the newly inserted item. - If the insertion failed for some reason, -1 is returned. - */ - int Insert(const wxString& item, unsigned int pos, - wxClientData* clientData); - - /** - Inserts several items at once into the control. - - Notice that calling this method is usually much faster than inserting - them one by one if you need to insert a lot of items. - - @param items - Array of strings to insert. - @param pos - Position to insert the items before, zero based. - */ - void Insert(const wxArrayString& items, unsigned int pos); - - /** - Inserts several items at once into the control. - - Notice that calling this method is usually much faster than inserting - them one by one if you need to insert a lot of items. - - @param items - Array of strings to insert. - @param pos - Position to insert the items before, zero based. - @param clientData - Array of client data pointers of the same size as @a items to - associate with the new items. - */ - void Insert(const wxArrayString& items, unsigned int pos, - void **clientData); - - /** - Inserts several items at once into the control. - - Notice that calling this method is usually much faster than inserting - them one by one if you need to insert a lot of items. - - @param items - Array of strings to insert. - @param pos - Position to insert the items before, zero based. - @param clientData - Array of client data pointers of the same size as @a items to - associate with the new items. - */ - void Insert(const wxArrayString& items, unsigned int pos, - wxClientData **clientData); - - /** - Inserts several items at once into the control. - - Notice that calling this method is usually much faster than inserting - them one by one if you need to insert a lot of items. - - @param n - Number of items in the @a items array. - @param items - Array of strings of size @a n. - @param pos - Position to insert the items before, zero based. - */ - void Insert(unsigned int n, const wxString* items, - unsigned int pos); - - /** - Inserts several items at once into the control. - - Notice that calling this method is usually much faster than inserting - them one by one if you need to insert a lot of items. - - @param n - Number of items in the @a items array. - @param items - Array of strings of size @a n. - @param pos - Position to insert the new items before, zero based. - @param clientData - Array of client data pointers of size @a n to associate with the - new items. - */ - void Insert(unsigned int n, const wxString* items, - unsigned int pos, - void** clientData); - - /** - Inserts several items at once into the control. - - Notice that calling this method is usually much faster than inserting - them one by one if you need to insert a lot of items. - - @param n - Number of items in the @a items array. - @param items - Array of strings of size @a n. - @param pos - Position to insert the new items before, zero based. - @param clientData - Array of client data pointers of size @a n to associate with the - new items. - */ - void Insert(unsigned int n, const wxString* items, - unsigned int pos, - wxClientData** clientData); - //@} - - //@{ - /** - Replaces the current control contents with the given items. - - Notice that calling this method is usually much faster than appending - them one by one if you need to add a lot of items. - - @param items - Array of strings to insert. - */ - void Set(const wxArrayString& items); - - /** - Replaces the current control contents with the given items. - - Notice that calling this method is usually much faster than appending - them one by one if you need to add a lot of items. - - @param items - Array of strings to insert. - @param clientData - Array of client data pointers of the same size as @a items to - associate with the new items. - */ - void Set(const wxArrayString& items, void **clientData); - - /** - Replaces the current control contents with the given items. - - Notice that calling this method is usually much faster than appending - them one by one if you need to add a lot of items. - - @param items - Array of strings to insert. - @param clientData - Array of client data pointers of the same size as @a items to - associate with the new items. - */ - void Set(const wxArrayString& items, wxClientData **clientData); - - /** - Replaces the current control contents with the given items. - - Notice that calling this method is usually much faster than appending - them one by one if you need to add a lot of items. - - @param n - Number of items in the @a items array. - @param items - Array of strings of size @a n. - */ - void Set(unsigned int n, const wxString* items); - - /** - Replaces the current control contents with the given items. - - Notice that calling this method is usually much faster than appending - them one by one if you need to add a lot of items. - - @param n - Number of items in the @a items array. - @param items - Array of strings of size @a n. - @param clientData - Array of client data pointers of size @a n to associate with the - new items. - */ - void Set(unsigned int n, const wxString* items, void** clientData); - - /** - Replaces the current control contents with the given items. - - Notice that calling this method is usually much faster than appending - them one by one if you need to add a lot of items. - - @param n - Number of items in the @a items array. - @param items - Array of strings of size @a n. - @param clientData - Array of client data pointers of size @a n to associate with the - new items. - */ - void Set(unsigned int n, const wxString* items, wxClientData** clientData); - //@} -}; - - -/** - @class wxControlWithItems - @wxheader{ctrlsub.h} - - This is convenience class that derives from both wxControl and - wxItemContainer. It is used as basis for some wxWidgets controls - (wxChoice and wxListBox). - - @library{wxcore} - @category{ctrl} - - @see wxItemContainer, wxItemContainerImmutable -*/ -class wxControlWithItems : public wxControl, public wxItemContainer -{ -}; - diff --git a/interface/cursor.h b/interface/cursor.h deleted file mode 100644 index 7ffa1fdf10..0000000000 --- a/interface/cursor.h +++ /dev/null @@ -1,220 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: cursor.h -// Purpose: interface of wxCursor -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxCursor - @wxheader{cursor.h} - - A cursor is a small bitmap usually used for denoting where the mouse - pointer is, with a picture that might indicate the interpretation of a - mouse click. As with icons, cursors in X and MS Windows are created in a - different manner. Therefore, separate cursors will be created for the - different environments. Platform-specific methods for creating a wxCursor - object are catered for, and this is an occasion where conditional - compilation will probably be required (see wxIcon for an example). - - A single cursor object may be used in many windows (any subwindow type). - The wxWidgets convention is to set the cursor for a window, as in X, rather - than to set it globally as in MS Windows, although a global wxSetCursor() - function is also available for MS Windows use. - - @section cursor_custom Creating a Custom Cursor - - The following is an example of creating a cursor from 32x32 bitmap data - (down_bits) and a mask (down_mask) where 1 is black and 0 is white for the - bits, and 1 is opaque and 0 is transparent for the mask. It works on - Windows and GTK+. - - @code - static char down_bits[] = { 255, 255, 255, 255, 31, - 255, 255, 255, 31, 255, 255, 255, 31, 255, 255, 255, - 31, 255, 255, 255, 31, 255, 255, 255, 31, 255, 255, - 255, 31, 255, 255, 255, 31, 255, 255, 255, 25, 243, - 255, 255, 19, 249, 255, 255, 7, 252, 255, 255, 15, 254, - 255, 255, 31, 255, 255, 255, 191, 255, 255, 255, 255, - 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, - 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, - 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, - 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, - 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, - 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, - 255 }; - - static char down_mask[] = { 240, 1, 0, 0, 240, 1, - 0, 0, 240, 1, 0, 0, 240, 1, 0, 0, 240, 1, 0, 0, 240, 1, - 0, 0, 240, 1, 0, 0, 240, 1, 0, 0, 255, 31, 0, 0, 255, - 31, 0, 0, 254, 15, 0, 0, 252, 7, 0, 0, 248, 3, 0, 0, - 240, 1, 0, 0, 224, 0, 0, 0, 64, 0, 0, 0, 0, 0, 0, 0, 0, - 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, - 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, - 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, - 0, 0, 0, 0, 0 }; - - #ifdef __WXMSW__ - wxBitmap down_bitmap(down_bits, 32, 32); - wxBitmap down_mask_bitmap(down_mask, 32, 32); - - down_bitmap.SetMask(new wxMask(down_mask_bitmap)); - wxImage down_image = down_bitmap.ConvertToImage(); - down_image.SetOption(wxIMAGE_OPTION_CUR_HOTSPOT_X, 6); - down_image.SetOption(wxIMAGE_OPTION_CUR_HOTSPOT_Y, 14); - wxCursor down_cursor = wxCursor(down_image); - #else - wxCursor down_cursor = wxCursor(down_bits, 32, 32, 6, 14, - down_mask, wxWHITE, wxBLACK); - #endif - @endcode - - @library{wxcore} - @category{gdi} - - @stdobjects - - ::wxNullCursor - - ::wxSTANDARD_CURSOR - - ::wxHOURGLASS_CURSOR - - ::wxCROSS_CURSOR - - @see wxBitmap, wxIcon, wxWindow::SetCursor(), wxSetCursor(), - ::wxStockCursor -*/ -class wxCursor : public wxBitmap -{ -public: - /** - Default constructor. - */ - wxCursor(); - /** - Constructs a cursor by passing an array of bits (Motif and GTK+ only). - @a maskBits is used only under Motif and GTK+. The parameters @a fg and - @a bg are only present on GTK+, and force the cursor to use particular - background and foreground colours. - - If either @a hotSpotX or @a hotSpotY is -1, the hotspot will be the - centre of the cursor image (Motif only). - - @param bits - An array of bits. - @param maskBits - Bits for a mask bitmap. - @param width - Cursor width. - @param height - Cursor height. - @param hotSpotX - Hotspot x coordinate. - @param hotSpotY - Hotspot y coordinate. - */ - wxCursor(const char bits[], int width, int height, - int hotSpotX = -1, int hotSpotY = -1, - const char maskBits[] = NULL, - wxColour* fg = NULL, wxColour* bg = NULL); - /** - Constructs a cursor by passing a string resource name or filename. - - On MacOS when specifying a string resource name, first the color - cursors 'crsr' and then the black/white cursors 'CURS' in the resource - chain are scanned through. - - @a hotSpotX and @a hotSpotY are currently only used under Windows when - loading from an icon file, to specify the cursor hotspot relative to - the top left of the image. - - @param type - Icon type to load. Under Motif, type defaults to wxBITMAP_TYPE_XBM. - Under Windows, it defaults to wxBITMAP_TYPE_CUR_RESOURCE. Under - MacOS, it defaults to wxBITMAP_TYPE_MACCURSOR_RESOURCE. - Under X, the permitted cursor types are: -
    -
  • wxBITMAP_TYPE_XBM - Load an X bitmap file.
    • -
- Under Windows, the permitted types are: - - wxBITMAP_TYPE_CUR - Load a cursor from a .cur cursor file (only - if USE_RESOURCE_LOADING_IN_MSW is enabled in - setup.h). - - wxBITMAP_TYPE_CUR_RESOURCE - Load a Windows resource (as - specified in the .rc file). - - wxBITMAP_TYPE_ICO - Load a cursor from a .ico icon file (only if - USE_RESOURCE_LOADING_IN_MSW is enabled in - setup.h). Specify @a hotSpotX and @a hotSpotY. - @param hotSpotX - Hotspot x coordinate. - @param hotSpotY - Hotspot y coordinate. - */ - wxCursor(const wxString& cursorName, long type, - int hotSpotX = 0, int hotSpotY = 0); - /** - Constructs a cursor using a cursor identifier. - - @param cursorId - A stock cursor identifier. See ::wxStockCursor. - */ - wxCursor(wxStockCursor cursorId); - /** - Constructs a cursor from a wxImage. If cursor are monochrome on the - current platform, colors with the RGB elements all greater than 127 - will be foreground, colors less than this background. The mask (if any) - will be used to specify the transparent area. - - In wxMSW the foreground will be white and the background black. If the - cursor is larger than 32x32 it is resized. - - In wxGTK, colour cursors and alpha channel are supported (starting from - GTK+ 2.2). Otherwise the two most frequent colors will be used for - foreground and background. In any case, the cursor will be displayed at - the size of the image. - - In wxMac, if the cursor is larger than 16x16 it is resized and - currently only shown as black/white (mask respected). - */ - wxCursor(const wxImage& image); - /** - Copy constructor, uses @ref overview_refcount "reference counting". - - @param cursor - Pointer or reference to a cursor to copy. - */ - wxCursor(const wxCursor& cursor); - - /** - Destroys the cursor. See - @ref overview_refcount_destruct "reference-counted object destruction" - for more info. - - A cursor can be reused for more than one window, and does not get - destroyed when the window is destroyed. wxWidgets destroys all cursors - on application exit, although it is best to clean them up explicitly. - */ - ~wxCursor(); - - /** - Returns @true if cursor data is present. - */ - bool IsOk() const; - - /** - Assignment operator, using @ref overview_refcount "reference counting". - */ - wxCursor operator =(const wxCursor& cursor); -}; - - -/** - @name Predefined cursors. - - @see wxStockCursor -*/ -//@{ -wxCursor wxNullCursor; -wxCursor* wxSTANDARD_CURSOR; -wxCursor* wxHOURGLASS_CURSOR; -wxCursor* wxCROSS_CURSOR; -//@} - diff --git a/interface/dataobj.h b/interface/dataobj.h deleted file mode 100644 index fd5035b5ee..0000000000 --- a/interface/dataobj.h +++ /dev/null @@ -1,705 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: dataobj.h -// Purpose: interface of wx*DataObject -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxCustomDataObject - @wxheader{dataobj.h} - - wxCustomDataObject is a specialization of wxDataObjectSimple for some - application-specific data in arbitrary (either custom or one of the - standard ones). The only restriction is that it is supposed that this data - can be copied bitwise (i.e. with @c memcpy()), so it would be a bad idea to - make it contain a C++ object (though C struct is fine). - - By default, wxCustomDataObject stores the data inside in a buffer. To put - the data into the buffer you may use either SetData() or TakeData() - depending on whether you want the object to make a copy of data or not. - - This class may be used as is, but if you don't want store the data inside - the object but provide it on demand instead, you should override GetSize(), - GetData() and SetData() (or may be only the first two or only the last one - if you only allow reading/writing the data). - - @library{wxcore} - @category{dnd} - - @see wxDataObject -*/ -class wxCustomDataObject : public wxDataObjectSimple -{ -public: - /** - The constructor accepts a @a format argument which specifies the - (single) format supported by this object. If it isn't set here, - wxDataObjectSimple::SetFormat() should be used. - */ - wxCustomDataObject(const wxDataFormat& format = wxFormatInvalid); - - /** - The destructor will free the data held by the object. Notice that - although it calls the virtual Free() function, the base class version - will always be called (C++ doesn't allow calling virtual functions from - constructors or destructors), so if you override Free(), you should - override the destructor in your class as well (which would probably - just call the derived class' version of Free()). - */ - virtual ~wxCustomDataObject(); - - /** - This function is called to allocate @a size bytes of memory from - SetData(). The default version just uses the operator new. - */ - virtual void* Alloc(size_t size); - - /** - This function is called when the data is freed, you may override it to - anything you want (or may be nothing at all). The default version calls - operator delete[] on the data. - */ - virtual void Free(); - - /** - Returns a pointer to the data. - */ - virtual void* GetData() const; - - /** - Returns the data size in bytes. - */ - virtual size_t GetSize() const; - - /** - Set the data. The data object will make an internal copy. - - @beginWxPythonOnly - This method expects a string in wxPython. You can pass nearly any - object by pickling it first. - @endWxPythonOnly - */ - virtual void SetData(size_t size, const void data); - - /** - Like SetData(), but doesn't copy the data - instead the object takes - ownership of the pointer. - - @beginWxPythonOnly - This method expects a string in wxPython. You can pass nearly any - object by pickling it first. - @endWxPythonOnly - */ - virtual void TakeData(size_t size, const void data); -}; - - - -/** - @class wxDataObjectComposite - @wxheader{dataobj.h} - - wxDataObjectComposite is the simplest wxDataObject derivation which may be - used to support multiple formats. It contains several wxDataObjectSimple - objects and supports any format supported by at least one of them. Only one - of these data objects is @e preferred (the first one if not explicitly - changed by using the second parameter of Add()) and its format determines - the preferred format of the composite data object as well. - - See wxDataObject documentation for the reasons why you might prefer to use - wxDataObject directly instead of wxDataObjectComposite for efficiency - reasons. - - @library{wxcore} - @category{dnd} - - @see @ref overview_dnd, wxDataObject, wxDataObjectSimple, wxFileDataObject, - wxTextDataObject, wxBitmapDataObject -*/ -class wxDataObjectComposite : public wxDataObject -{ -public: - /** - The default constructor. - */ - wxDataObjectComposite(); - - /** - Adds the @a dataObject to the list of supported objects and it becomes - the preferred object if @a preferred is @true. - */ - void Add(wxDataObjectSimple dataObject, bool preferred = false); - - /** - Report the format passed to the SetData() method. This should be the - format of the data object within the composite that recieved data from - the clipboard or the DnD operation. You can use this method to find - out what kind of data object was recieved. - */ - wxDataFormat GetReceivedFormat() const; -}; - - - -/** - @class wxDataObjectSimple - @wxheader{dataobj.h} - - This is the simplest possible implementation of the wxDataObject class. The - data object of (a class derived from) this class only supports one format, - so the number of virtual functions to be implemented is reduced. - - Notice that this is still an abstract base class and cannot be used - directly, it must be derived. The objects supporting rendering the data - must override GetDataSize() and GetDataHere() while the objects which may - be set must override SetData(). Of course, the objects supporting both - operations must override all three methods. - - @beginWxPythonOnly - If you wish to create a derived wxDataObjectSimple class in wxPython you - should derive the class from wxPyDataObjectSimple in order to get - Python-aware capabilities for the various virtual methods. - @endWxPythonOnly - - @beginWxPerlOnly - In wxPerl, you need to derive your data object class from - Wx::PlDataObjectSimple. - @endWxPerlOnly - - @library{wxcore} - @category{dnd} - - @see @ref overview_dnd, @ref page_samples_dnd, wxFileDataObject, - wxTextDataObject, wxBitmapDataObject -*/ -class wxDataObjectSimple : public wxDataObject -{ -public: - /** - Constructor accepts the supported format (none by default) which may - also be set later with SetFormat(). - */ - wxDataObjectSimple(const wxDataFormat& format = wxFormatInvalid); - - /** - Copy the data to the buffer, return @true on success. Must be - implemented in the derived class if the object supports rendering its - data. - - @beginWxPythonOnly - When implementing this method in wxPython, no additional parameters are - required and the data should be returned from the method as a string. - @endWxPythonOnly - */ - virtual bool GetDataHere(void buf) const; - - /** - Gets the size of our data. Must be implemented in the derived class if - the object supports rendering its data. - */ - virtual size_t GetDataSize() const; - - /** - Returns the (one and only one) format supported by this object. It is - assumed that the format is supported in both directions. - */ - const wxDataFormat GetFormat() const; - - /** - Copy the data from the buffer, return @true on success. Must be - implemented in the derived class if the object supports setting its - data. - - @beginWxPythonOnly - When implementing this method in wxPython, the data comes as a single - string parameter rather than the two shown here. - @endWxPythonOnly - */ - virtual bool SetData(size_t len, const void buf); - - /** - Sets the supported format. - */ - void SetFormat(const wxDataFormat& format); -}; - - - -/** - @class wxBitmapDataObject - @wxheader{dataobj.h} - - wxBitmapDataObject is a specialization of wxDataObject for bitmap data. It - can be used without change to paste data into the wxClipboard or a - wxDropSource. A user may wish to derive a new class from this class for - providing a bitmap on-demand in order to minimize memory consumption when - offering data in several formats, such as a bitmap and GIF. - - This class may be used as is, but GetBitmap() may be overridden to increase - efficiency. - - @beginWxPythonOnly - If you wish to create a derived wxBitmapDataObject class in wxPython you - should derive the class from wxPyBitmapDataObject in order to get - Python-aware capabilities for the various virtual methods. - @endWxPythonOnly - - @library{wxcore} - @category{dnd} - - @see @ref overview_dnd, wxDataObject, wxDataObjectSimple, wxFileDataObject, - wxTextDataObject, wxDataObject -*/ -class wxBitmapDataObject : public wxDataObjectSimple -{ -public: - /** - Constructor, optionally passing a bitmap (otherwise use SetBitmap() - later). - */ - wxBitmapDataObject(const wxBitmap& bitmap = wxNullBitmap); - - /** - Returns the bitmap associated with the data object. You may wish to - override this method when offering data on-demand, but this is not - required by wxWidgets' internals. Use this method to get data in bitmap - form from the wxClipboard. - */ - virtual wxBitmap GetBitmap() const; - - /** - Sets the bitmap associated with the data object. This method is called - when the data object receives data. Usually there will be no reason to - override this function. - */ - virtual void SetBitmap(const wxBitmap& bitmap); -}; - - - -/** - @class wxDataFormat - @wxheader{dataobj.h} - - A wxDataFormat is an encapsulation of a platform-specific format handle - which is used by the system for the clipboard and drag and drop operations. - The applications are usually only interested in, for example, pasting data - from the clipboard only if the data is in a format the program understands - and a data format is something which uniquely identifies this format. - - On the system level, a data format is usually just a number (@c CLIPFORMAT - under Windows or @c Atom under X11, for example) and the standard formats - are, indeed, just numbers which can be implicitly converted to wxDataFormat. - The standard formats are: - - @beginDefList - @itemdef{wxDF_INVALID, - An invalid format - used as default argument for functions taking - a wxDataFormat argument sometimes.} - @itemdef{wxDF_TEXT, - Text format (wxString).} - @itemdef{wxDF_BITMAP, - A bitmap (wxBitmap).} - @itemdef{wxDF_METAFILE, - A metafile (wxMetafile, Windows only).} - @itemdef{wxDF_FILENAME, - A list of filenames.} - @itemdef{wxDF_HTML, - An HTML string. This is only valid when passed to - wxSetClipboardData when compiled with Visual C++ in non-Unicode - mode.} - @endDefList - - As mentioned above, these standard formats may be passed to any function - taking wxDataFormat argument because wxDataFormat has an implicit - conversion from them (or, to be precise from the type - @c wxDataFormat::NativeFormat which is the type used by the underlying - platform for data formats). - - Aside the standard formats, the application may also use custom formats - which are identified by their names (strings) and not numeric identifiers. - Although internally custom format must be created (or @e registered) first, - you shouldn't care about it because it is done automatically the first time - the wxDataFormat object corresponding to a given format name is created. - The only implication of this is that you should avoid having global - wxDataFormat objects with non-default constructor because their - constructors are executed before the program has time to perform all - necessary initialisations and so an attempt to do clipboard format - registration at this time will usually lead to a crash! - - @library{wxbase} - @category{dnd} - - @see @ref overview_dnd, @ref page_samples_dnd, wxDataObject -*/ -class wxDataFormat -{ -public: - /** - Constructs a data format object for one of the standard data formats or - an empty data object (use SetType() or SetId() later in this case). - */ - wxDataFormat(NativeFormat format = wxDF_INVALID); - /** - Constructs a data format object for a custom format identified by its - name @a format. - */ - wxDataFormat(const wxChar format); - - /** - Returns the name of a custom format (this function will fail for a - standard format). - */ - wxString GetId() const; - - /** - Returns the platform-specific number identifying the format. - */ - NativeFormat GetType() const; - - /** - Sets the format to be the custom format identified by the given name. - */ - void SetId(const wxChar format); - - /** - Sets the format to the given value, which should be one of wxDF_XXX - constants. - */ - void SetType(NativeFormat format); - - /** - Returns @true if the formats are different. - */ - bool operator !=(const wxDataFormat& format) const; - - /** - Returns @true if the formats are equal. - */ - bool operator ==(const wxDataFormat& format) const; -}; - - - -/** - @class wxURLDataObject - @wxheader{dataobj.h} - - wxURLDataObject is a wxDataObject containing an URL and can be used e.g. - when you need to put an URL on or retrieve it from the clipboard: - - @code - wxTheClipboard->SetData(new wxURLDataObject(url)); - @endcode - - @note This class is derived from wxDataObjectComposite on Windows rather - than wxTextDataObject on all other platforms. - - @library{wxcore} - @category{dnd} - - @see @ref overview_dnd, wxDataObject -*/ -class wxURLDataObject: public wxTextDataObject -{ -public: - /** - Constructor, may be used to initialize the URL. If @a url is empty, - SetURL() can be used later. - */ - wxURLDataObject(const wxString& url = wxEmptyString); - - /** - Returns the URL stored by this object, as a string. - */ - wxString GetURL() const; - - /** - Sets the URL stored by this object. - */ - void SetURL(const wxString& url); -}; - - - -/** - @class wxDataObject - @wxheader{dataobj.h} - - A wxDataObject represents data that can be copied to or from the clipboard, - or dragged and dropped. The important thing about wxDataObject is that this - is a 'smart' piece of data unlike 'dumb' data containers such as memory - buffers or files. Being 'smart' here means that the data object itself - should know what data formats it supports and how to render itself in each - of its supported formats. - - A supported format, incidentally, is exactly the format in which the data - can be requested from a data object or from which the data object may be - set. In the general case, an object may support different formats on - 'input' and 'output', i.e. it may be able to render itself in a given - format but not be created from data on this format or vice versa. - wxDataObject defines an enumeration type which distinguishes between them: - - @code - enum Direction - { - Get = 0x01, // format is supported by GetDataHere() - Set = 0x02 // format is supported by SetData() - }; - @endcode - - See wxDataFormat documentation for more about formats. - - Not surprisingly, being 'smart' comes at a price of added complexity. This - is reasonable for the situations when you really need to support multiple - formats, but may be annoying if you only want to do something simple like - cut and paste text. - - To provide a solution for both cases, wxWidgets has two predefined classes - which derive from wxDataObject: wxDataObjectSimple and - wxDataObjectComposite. wxDataObjectSimple is the simplest wxDataObject - possible and only holds data in a single format (such as HTML or text) and - wxDataObjectComposite is the simplest way to implement a wxDataObject that - does support multiple formats because it achieves this by simply holding - several wxDataObjectSimple objects. - - So, you have several solutions when you need a wxDataObject class (and you - need one as soon as you want to transfer data via the clipboard or drag and - drop): - - -# Use one of the built-in classes. - - You may use wxTextDataObject, wxBitmapDataObject or wxFileDataObject - in the simplest cases when you only need to support one format and - your data is either text, bitmap or list of files. - -# Use wxDataObjectSimple - - Deriving from wxDataObjectSimple is the simplest solution for custom - data - you will only support one format and so probably won't be able - to communicate with other programs, but data transfer will work in - your program (or between different copies of it). - -# Use wxDataObjectComposite - - This is a simple but powerful solution which allows you to support - any number of formats (either standard or custom if you combine it - with the previous solution). - -# Use wxDataObject Directly - - This is the solution for maximal flexibility and efficiency, but it - is also the most difficult to implement. - - Please note that the easiest way to use drag and drop and the clipboard - with multiple formats is by using wxDataObjectComposite, but it is not the - most efficient one as each wxDataObjectSimple would contain the whole data - in its respective formats. Now imagine that you want to paste 200 pages of - text in your proprietary format, as well as Word, RTF, HTML, Unicode and - plain text to the clipboard and even today's computers are in trouble. For - this case, you will have to derive from wxDataObject directly and make it - enumerate its formats and provide the data in the requested format on - demand. - - Note that neither the GTK+ data transfer mechanisms for clipboard and drag - and drop, nor OLE data transfer, copy any data until another application - actually requests the data. This is in contrast to the 'feel' offered to - the user of a program who would normally think that the data resides in the - clipboard after having pressed 'Copy' - in reality it is only declared to - be available. - - There are several predefined data object classes derived from - wxDataObjectSimple: wxFileDataObject, wxTextDataObject, wxBitmapDataObject - and wxURLDataObject which can be used without change. - - You may also derive your own data object classes from wxCustomDataObject - for user-defined types. The format of user-defined data is given as a - mime-type string literal, such as "application/word" or "image/png". These - strings are used as they are under Unix (so far only GTK+) to identify a - format and are translated into their Windows equivalent under Win32 (using - the OLE IDataObject for data exchange to and from the clipboard and for - drag and drop). Note that the format string translation under Windows is - not yet finished. - - Each class derived directly from wxDataObject must override and implement - all of its functions which are pure virtual in the base class. The data - objects which only render their data or only set it (i.e. work in only one - direction), should return 0 from GetFormatCount(). - - @beginWxPythonOnly - At this time this class is not directly usable from wxPython. Derive a - class from wxPyDataObjectSimple() instead. - @endWxPythonOnly - - @beginWxPerlOnly - This class is not currently usable from wxPerl; you may use - Wx::PlDataObjectSimple instead. - @endWxPerlOnly - - @library{wxcore} - @category{dnd} - - @see @ref overview_dnd, @ref page_samples_dnd, wxFileDataObject, - wxTextDataObject, wxBitmapDataObject, wxCustomDataObject, - wxDropTarget, wxDropSource, wxTextDropTarget, wxFileDropTarget -*/ -class wxDataObject -{ -public: - /** - Constructor. - */ - wxDataObject(); - - /** - Destructor. - */ - ~wxDataObject(); - - /** - Copy all supported formats in the given direction to the array pointed - to by @a formats. There is enough space for GetFormatCount(dir) formats - in it. - */ - virtual void GetAllFormats(wxDataFormat* formats, - Direction dir = Get) const; - - /** - The method will write the data of the format @a format in the buffer - @a buf and return @true on success, @false on failure. - */ - virtual bool GetDataHere(const wxDataFormat& format, void buf) const; - - /** - Returns the data size of the given format @a format. - */ - virtual size_t GetDataSize(const wxDataFormat& format) const; - - /** - Returns the number of available formats for rendering or setting the - data. - */ - virtual size_t GetFormatCount(Direction dir = Get) const; - - /** - Returns the preferred format for either rendering the data (if @a dir - is @c Get, its default value) or for setting it. Usually this will be - the native format of the wxDataObject. - */ - virtual wxDataFormat GetPreferredFormat(Direction dir = Get) const; - - /** - Set the data in the format @a format of the length @a len provided in - the buffer @a buf. - - @return @true on success, @false on failure. - */ - virtual bool SetData(const wxDataFormat& format, size_t len, - const void buf); -}; - - - -/** - @class wxTextDataObject - @wxheader{dataobj.h} - - wxTextDataObject is a specialization of wxDataObject for text data. It can - be used without change to paste data into the wxClipboard or a - wxDropSource. A user may wish to derive a new class from this class for - providing text on-demand in order to minimize memory consumption when - offering data in several formats, such as plain text and RTF because by - default the text is stored in a string in this class, but it might as well - be generated when requested. For this, GetTextLength() and GetText() will - have to be overridden. - - Note that if you already have the text inside a string, you will not - achieve any efficiency gain by overriding these functions because copying - wxStrings is already a very efficient operation (data is not actually - copied because wxStrings are reference counted). - - @beginWxPythonOnly - If you wish to create a derived wxTextDataObject class in wxPython you - should derive the class from wxPyTextDataObject in order to get - Python-aware capabilities for the various virtual methods. - @endWxPythonOnly - - @library{wxcore} - @category{dnd} - - @see @ref overview_dnd, wxDataObject, wxDataObjectSimple, wxFileDataObject, - wxBitmapDataObject -*/ -class wxTextDataObject : public wxDataObjectSimple -{ -public: - /** - Constructor, may be used to initialise the text (otherwise SetText() - should be used later). - */ - wxTextDataObject(const wxString& text = wxEmptyString); - - /** - Returns the text associated with the data object. You may wish to - override this method when offering data on-demand, but this is not - required by wxWidgets' internals. Use this method to get data in text - form from the wxClipboard. - */ - virtual wxString GetText() const; - - /** - Returns the data size. By default, returns the size of the text data - set in the constructor or using SetText(). This can be overridden to - provide text size data on-demand. It is recommended to return the text - length plus 1 for a trailing zero, but this is not strictly required. - */ - virtual size_t GetTextLength() const; - - /** - Sets the text associated with the data object. This method is called - when the data object receives the data and, by default, copies the text - into the member variable. If you want to process the text on the fly - you may wish to override this function. - */ - virtual void SetText(const wxString& strText); -}; - - - -/** - @class wxFileDataObject - @wxheader{dataobj.h} - - wxFileDataObject is a specialization of wxDataObject for file names. The - program works with it just as if it were a list of absolute file names, but - internally it uses the same format as Explorer and other compatible - programs under Windows or GNOME/KDE filemanager under Unix which makes it - possible to receive files from them using this class. - - @warning Under all non-Windows platforms this class is currently - "input-only", i.e. you can receive the files from another - application, but copying (or dragging) file(s) from a wxWidgets - application is not currently supported. PS: GTK2 should work as - well. - - @library{wxcore} - @category{dnd} - - @see wxDataObject, wxDataObjectSimple, wxTextDataObject, - wxBitmapDataObject, wxDataObject -*/ -class wxFileDataObject : public wxDataObjectSimple -{ -public: - /** - Constructor. - */ - wxFileDataObject(); - - /** - Adds a file to the file list represented by this data object (Windows - only). - */ - virtual void AddFile(const wxString& file); - - /** - Returns the array of file names. - */ - const wxArrayString GetFilenames() const; -}; - diff --git a/interface/dataview.h b/interface/dataview.h deleted file mode 100644 index 533e8ec36b..0000000000 --- a/interface/dataview.h +++ /dev/null @@ -1,1997 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: dataview.h -// Purpose: interface of wxDataViewIconText -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxDataViewIconText - @wxheader{dataview.h} - - wxDataViewIconText is used by - wxDataViewIconTextRenderer - for data transfer. This class can be converted to a from - a wxVariant. - - @library{wxbase} - @category{dvc} -*/ -class wxDataViewIconText : public wxObject -{ -public: - //@{ - /** - Constructor. - */ - wxDataViewIconText(const wxString& text = wxEmptyString, - const wxIcon& icon = wxNullIcon); - wxDataViewIconText(const wxDataViewIconText& other); - //@} - - /** - Gets the icon. - */ - const wxIcon GetIcon() const; - - /** - Gets the text. - */ - wxString GetText() const; - - /** - Set the icon. - */ - void SetIcon(const wxIcon& icon); - - /** - Set the text. - */ - void SetText(const wxString& text); -}; - - - -/** - @class wxDataViewEvent - @wxheader{dataview.h} - - wxDataViewEvent - the event class for the wxDataViewCtrl notifications - - @library{wxadv} - @category{events,dvc} -*/ -class wxDataViewEvent : public wxNotifyEvent -{ -public: - //@{ - /** - - */ - wxDataViewEvent(wxEventType commandType = wxEVT_NULL, - int winid = 0); - wxDataViewEvent(const wxDataViewEvent& event); - //@} - - /** - Used to clone the event. - */ - wxEvent* Clone() const; - - /** - Returns the position of the column in the control or -1 - if no column field was set by the event emitter. - */ - int GetColumn() const; - - /** - Returns a pointer to the wxDataViewColumn from which - the event was emitted or @NULL. - */ - wxDataViewColumn* GetDataViewColumn(); - - /** - Returns the wxDataViewModel associated with the event. - */ - wxDataViewModel* GetModel() const; - - /** - Returns a the position of a context menu event in screen coordinates. - */ - wxPoint GetPosition() const; - - /** - Returns a reference to a value. - */ - const wxVariant GetValue() const; - - /** - - */ - void SetColumn(int col); - - /** - For wxEVT_DATAVIEW_COLUMN_HEADER_CLICKED only. - */ - void SetDataViewColumn(wxDataViewColumn* col); - - /** - - */ - void SetModel(wxDataViewModel* model); - - /** - - */ - void SetValue(const wxVariant& value); -}; - - - -/** - @class wxDataViewModel - @wxheader{dataview.h} - - wxDataViewModel is the base class for all data model to be - displayed by a wxDataViewCtrl. - All other models derive from it and must implement its - pure virtual functions in order to define a complete - data model. In detail, you need to override - wxDataViewModel::IsContainer, - wxDataViewModel::GetParent, - wxDataViewModel::GetChildren, - wxDataViewModel::GetColumnCount, - wxDataViewModel::GetColumnType and - wxDataViewModel::GetValue in order to - define the data model which acts as an interface between - your actual data and the wxDataViewCtrl. Since you will - usually also allow the wxDataViewCtrl to change your data - through its graphical interface, you will also have to override - wxDataViewModel::SetValue which the - wxDataViewCtrl will call when a change to some data has been - commited. - - wxDataViewModel (as indeed the entire wxDataViewCtrl - code) is using wxVariant to store data and - its type in a generic way. wxVariant can be extended to contain - almost any data without changes to the original class. - - The data that is presented through this data model is expected - to change at run-time. You need to inform the data model when - a change happened. Depending on what happened you need to call - one of the following methods: - wxDataViewModel::ValueChanged, - wxDataViewModel::ItemAdded, - wxDataViewModel::ItemDeleted, - wxDataViewModel::ItemChanged, - wxDataViewModel::Cleared. There are - plural forms for notification of addition, change - or removal of several item at once. See - wxDataViewModel::ItemsAdded, - wxDataViewModel::ItemsDeleted, - wxDataViewModel::ItemsChanged. - - Note that wxDataViewModel does not define the position or - index of any item in the control because different controls - might display the same data differently. wxDataViewModel does - provide a wxDataViewModel::Compare method - which the wxDataViewCtrl may use to sort the data either - in conjunction with a column header or without (see - wxDataViewModel::HasDefaultCompare). - - This class maintains a list of - wxDataViewModelNotifier - which link this class to the specific implementations on the - supported platforms so that e.g. calling - wxDataViewModel::ValueChanged - on this model will just call - wxDataViewModelNotifier::ValueChanged - for each notifier that has been added. You can also add - your own notifier in order to get informed about any changes - to the data in the list model. - - Currently wxWidgets provides the following models apart - from the base model: - wxDataViewIndexListModel, - wxDataViewVirtualListModel, - wxDataViewTreeStore. - - Note that wxDataViewModel is reference counted, derives from - wxObjectRefData and cannot be deleted - directly as it can be shared by several wxDataViewCtrls. This - implies that you need to decrease the reference count after - associating the model with a control like this: - - @code - wxDataViewCtrl *musicCtrl = new wxDataViewCtrl( this, ID_MUSIC_CTRL ); - wxDataViewModel *musicModel = new MyMusicModel; - m_musicCtrl-AssociateModel( musicModel ); - musicModel-DecRef(); // avoid memory leak !! - // add columns now - @endcode - - - @library{wxadv} - @category{dvc} -*/ -class wxDataViewModel : public wxObjectRefData -{ -public: - /** - Constructor. - */ - wxDataViewModel(); - - /** - Destructor. This should not be called directly. Use DecRef() instead. - */ - ~wxDataViewModel(); - - /** - Adds a wxDataViewModelNotifier - to the model. - */ - void AddNotifier(wxDataViewModelNotifier* notifier); - - /** - Called to inform the model that all data has been cleared. The - control will reread the data from the model again. - */ - virtual bool Cleared(); - - /** - The compare function to be used by control. The default compare function - sorts by container and other items separately and in ascending order. - Override this for a different sorting behaviour. - See also HasDefaultCompare(). - */ - virtual int Compare(const wxDataViewItem& item1, - const wxDataViewItem& item2, - unsigned int column, - bool ascending); - - /** - Oberride this to indicate that the item has special font attributes. - This only affects the - wxDataViewTextRendererText() renderer. - See also wxDataViewItemAttr. - */ - bool GetAttr(const wxDataViewItem& item, unsigned int col, - wxDataViewItemAttr& attr); - - /** - Override this so the control can query the child items of - an item. Returns the number of items. - */ - virtual unsigned int GetChildren(const wxDataViewItem& item, - wxDataViewItemArray& children) const; - - /** - Override this to indicate the number of columns in the model. - */ - virtual unsigned int GetColumnCount() const; - - /** - Override this to indicate what type of data is stored in the - column specified by @e col. This should return a string - indicating the type of data as reported by wxVariant. - */ - virtual wxString GetColumnType(unsigned int col) const; - - /** - Override this to indicate which wxDataViewItem representing the parent - of @a item or an invalid wxDataViewItem if the the root item is - the parent item. - */ - virtual wxDataViewItem GetParent(const wxDataViewItem& item) const; - - /** - Override this to indicate the value of @e item - A wxVariant is used to store the data. - */ - virtual void GetValue(wxVariant& variant, - const wxDataViewItem& item, - unsigned int col) const; - - /** - Override this method to indicate if a container item merely - acts as a headline (or for categorisation) or if it also - acts a normal item with entries for futher columns. By - default returns @e @false. - */ - virtual bool HasContainerColumns(const wxDataViewItem& item) const; - - /** - Override this to indicate that the model provides a default compare - function that the control should use if no wxDataViewColumn has been - chosen for sorting. Usually, the user clicks on a column header for - sorting, the data will be sorted alphanumerically. If any other - order (e.g. by index or order of appearance) is required, then this - should be used. See also wxDataViewIndexListModel - for a model which makes use of this. - */ - virtual bool HasDefaultCompare() const; - - /** - Override this to indicate of @a item is a container, i.e. if - it can have child items. - */ - virtual bool IsContainer(const wxDataViewItem& item) const; - - /** - Call this to inform the model that an item has been added - to the data. - */ - virtual bool ItemAdded(const wxDataViewItem& parent, - const wxDataViewItem& item); - - /** - Call this to inform the model that an item has changed. - This will eventually emit a wxEVT_DATAVIEW_ITEM_VALUE_CHANGED - event (in which the column fields will not be set) to the user. - */ - virtual bool ItemChanged(const wxDataViewItem& item); - - /** - Call this to inform the model that an item has been deleted from the data. - */ - virtual bool ItemDeleted(const wxDataViewItem& parent, - const wxDataViewItem& item); - - /** - Call this to inform the model that several items have been added - to the data. - */ - virtual bool ItemsAdded(const wxDataViewItem& parent, - const wxDataViewItemArray& items); - - /** - Call this to inform the model that several items have changed. - This will eventually emit wxEVT_DATAVIEW_ITEM_VALUE_CHANGED - events (in which the column fields will not be set) to the user. - */ - virtual bool ItemsChanged(const wxDataViewItemArray& items); - - /** - Call this to inform the model that several items have been deleted. - */ - virtual bool ItemsDeleted(const wxDataViewItem& parent, - const wxDataViewItemArray& items); - - /** - Remove the @a notifier from the list of notifiers. - */ - void RemoveNotifier(wxDataViewModelNotifier* notifier); - - /** - Call this to initiate a resort after the sort function has - been changed. - */ - virtual void Resort(); - - /** - This gets called in order to set a value in the data model. - The most common scenario is that the wxDataViewCtrl calls - this method after the user changed some data in the view. - Afterwards ValueChanged() - has to be called! - */ - virtual bool SetValue(const wxVariant& variant, - const wxDataViewItem& item, - unsigned int col); - - /** - Call this to inform this model that a value in the model has - been changed. This is also called from wxDataViewCtrl's - internal editing code, e.g. when editing a text field - in the control. - This will eventually emit a wxEVT_DATAVIEW_ITEM_VALUE_CHANGED - event to the user. - */ - virtual bool ValueChanged(const wxDataViewItem& item, - unsigned int col); -}; - - - -/** - @class wxDataViewIndexListModel - @wxheader{dataview.h} - - wxDataViewIndexListModel is a specialized data model which lets - you address an item by its position (row) rather than its - wxDataViewItem (which you can obtain from this class). - This model also provides its own wxDataViewIndexListModel::Compare - method which sorts the model's data by the index. - - This model is not a virtual model since the control stores - each wxDataViewItem. Use wxDataViewVirtualListModel if you - need to display millions of items or have other reason to - use a virtual control. - - @library{wxbase} - @category{dvc} -*/ -class wxDataViewIndexListModel : public wxDataViewModel -{ -public: - /** - Constructor. - */ - wxDataViewIndexListModel(unsigned int initial_size = 0); - - /** - Destructor. - */ - ~wxDataViewIndexListModel(); - - /** - Compare method that sorts the items by their index. - */ - int Compare(const wxDataViewItem& item1, - const wxDataViewItem& item2, - unsigned int column, bool ascending); - - /** - Oberride this to indicate that the row has special font attributes. - This only affects the - wxDataViewTextRendererText() renderer. - See also wxDataViewItemAttr. - */ - bool GetAttr(unsigned int row, unsigned int col, - wxDataViewItemAttr& attr); - - /** - Returns the wxDataViewItem at the given @e row. - */ - wxDataViewItem GetItem(unsigned int row) const; - - /** - Returns the position of given @e item. - */ - unsigned int GetRow(const wxDataViewItem& item) const; - - /** - Override this to allow getting values from the model. - */ - void GetValue(wxVariant& variant, unsigned int row, - unsigned int col) const; - - /** - Call this after if the data has to be read again from - the model. This is useful after major changes when - calling the methods below (possibly thousands of times) - doesn't make sense. - */ - void Reset(unsigned int new_size); - - /** - Call this after a row has been appended to the model. - */ - void RowAppended(); - - /** - Call this after a row has been changed. - */ - void RowChanged(unsigned int row); - - /** - Call this after a row has been deleted. - */ - void RowDeleted(unsigned int row); - - /** - Call this after a row has been inserted at the given position. - */ - void RowInserted(unsigned int before); - - /** - Call this after a row has been prepended to the model. - */ - void RowPrepended(); - - /** - Call this after a value has been changed. - */ - void RowValueChanged(unsigned int row, unsigned int col); - - /** - Call this after rows have been deleted. The array will internally - get copied and sorted in descending order so that the rows with - the highest position will be deleted first. - */ - void RowsDeleted(const wxArrayInt& rows); - - /** - Called in order to set a value in the model. - */ - bool SetValue(const wxVariant& variant, unsigned int row, - unsigned int col); -}; - - - -/** - @class wxDataViewVirtualListModel - @wxheader{dataview.h} - - wxDataViewVirtualListModel is a specialized data model which lets - you address an item by its position (row) rather than its - wxDataViewItem and as such offers the exact same interface as - wxDataViewIndexListModel. The important difference is that under - platforms other than OS X, using this model will result in a - truely virtual control able to handle millions of items as the - control doesn't store any item (a feature not supported by the - Carbon API under OS X). - - @see wxDataViewIndexListModel for the API. - - @library{wxbase} - @category{dvc} -*/ -class wxDataViewVirtualListModel : public wxDataViewModel -{ -public: - /** - Constructor. - */ - wxDataViewVirtualListModel(unsigned int initial_size = 0); -}; - - - -/** - @class wxDataViewItemAttr - @wxheader{dataview.h} - - This class is used to indicate to a wxDataViewCtrl - that a certain Item() has extra font attributes - for its renderer. For this, it is required to override - wxDataViewModel::GetAttr. - - Attributes are currently only supported by - wxDataViewTextRendererText(). - - @library{wxadv} - @category{dvc} -*/ -class wxDataViewItemAttr -{ -public: - /** - Constructor. - */ - wxDataViewItemAttr(); - - /** - Call this to indicate that the item shall be displayed in bold text. - */ - void SetBold(bool set); - - /** - Call this to indicate that the item shall be displayed with - that colour. - */ - void SetColour(const wxColour& colour); - - /** - Call this to indicate that the item shall be displayed in italic text. - */ - void SetItalic(bool set); -}; - - - -/** - @class wxDataViewItem - @wxheader{dataview.h} - - wxDataViewItem is a small opaque class that represents an - item in a wxDataViewCtrl in a - persistent way, i.e. indepent of the position of the - item in the control or changes to its contents. It must - hold a unique ID of type @e void* in its only field - and can be converted to a from it. - - If the ID is @e @NULL the wxDataViewItem is invalid and - wxDataViewItem::IsOk will return @e @false - which used in many places in the API of wxDataViewCtrl - to indicate that e.g. no item was found. An ID of @NULL - is also used to indicate the invisible root. Examples - for this are - wxDataViewModel::GetParent and - wxDataViewModel::GetChildren. - - @library{wxadv} - @category{dvc} -*/ -class wxDataViewItem -{ -public: - //@{ - /** - - */ - wxDataViewItem(void* id = NULL); - wxDataViewItem(const wxDataViewItem& item); - //@} - - /** - Returns the ID. - */ - void* GetID() const; - - /** - Returns @true if the ID is not @e @NULL. - */ - bool IsOk() const; -}; - - - -/** - @class wxDataViewCtrl - @wxheader{dataview.h} - - wxDataViewCtrl is a control to display data either - in a tree like fashion or in a tabular form or both. - If you only need to display a simple tree structure - with an API more like the older wxTreeCtrl class, - then the specialized wxDataViewTreeCtrl - can be used. - - A wxDataViewItem is used - to represent a (visible) item in the control. - - Unlike wxListCtrl wxDataViewCtrl doesn't - get its data from the user through virtual functions or by - setting it directly. Instead you need to write your own - wxDataViewModel and associate - it with this control. Then you need to add a number of - wxDataViewColumn to this control to - define what each column shall display. Each wxDataViewColumn - in turn owns 1 instance of a - wxDataViewRenderer to render its - cells. A number of standard renderers for rendering text, dates, - images, toggle, a progress bar etc. are provided. Additionally, - the user can write custom renderes deriving from - wxDataViewCustomRenderer - for displaying anything. - - All data transfer from the control to the model and the user - code is done through wxVariant which can - be extended to support more data formats as necessary. - Accordingly, all type information uses the strings returned - from wxVariant::GetType. - - @beginStyleTable - @style{wxDV_SINGLE} - Single selection mode. This is the default. - @style{wxDV_MULTIPLE} - Multiple selection mode. - @style{wxDV_ROW_LINES} - Use alternating colours for rows if supported by platform and theme. - @style{wxDV_HORIZ_RULES} - Display fine rules between row if supported. - @style{wxDV_VERT_RULES} - Display fine rules between columns is supported. - @style{wxDV_VARIABLE_LINE_HEIGHT} - Allow variable line heights. This can be inefficient when displaying large number of items. - @endStyleTable - - @library{wxadv} - @category{ctrl,dvc} - -*/ -class wxDataViewCtrl : public wxControl -{ -public: - /** - Default Constructor. - */ - wxDataViewCtrl(); - - /** - Constructor. Calls Create(). - */ - wxDataViewCtrl(wxWindow* parent, wxWindowID id, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = 0, - const wxValidator& validator = wxDefaultValidator); - - /** - Destructor. - */ - ~wxDataViewCtrl(); - - /** - Appends a wxDataViewColumn to the control. Returns @true on success. - Note that there is a number of short cut methods which implicitly create - a wxDataViewColumn and a wxDataViewRenderer for it (see below). - */ - virtual bool AppendColumn(wxDataViewColumn* col); - - /** - Prepends a wxDataViewColumn to the control. Returns @true on success. - Note that there is a number of short cut methods which implicitly create - a wxDataViewColumn and a wxDataViewRenderer for it. - */ - virtual bool PrependColumn(wxDataViewColumn* col); - - /** - Inserts a wxDataViewColumn to the control. Returns @true on success. - */ - virtual bool InsertColumn(unsigned int pos, wxDataViewColumn* col); - - //@{ - /** - Appends a column for rendering a bitmap. Returns the wxDataViewColumn - created in the function or @NULL on failure. - */ - wxDataViewColumn* AppendBitmapColumn(const wxString& label, - unsigned int model_column, - wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, - int width = -1, - wxAlignment align = wxALIGN_CENTER, - int flags = wxDATAVIEW_COL_RESIZABLE); - wxDataViewColumn* AppendBitmapColumn(const wxBitmap& label, - unsigned int model_column, - wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, - int width = -1, - wxAlignment align = wxALIGN_CENTER, - int flags = wxDATAVIEW_COL_RESIZABLE); - //@} - - //@{ - /** - Appends a column for rendering a date. Returns the wxDataViewColumn - created in the function or @NULL on failure. - - NB: The @e align parameter is applied to both the column header and - the column renderer. - */ - wxDataViewColumn* AppendDateColumn(const wxString& label, - unsigned int model_column, - wxDataViewCellMode mode = wxDATAVIEW_CELL_ACTIVATABLE, - int width = -1, - wxAlignment align = wxALIGN_CENTER, - int flags = wxDATAVIEW_COL_RESIZABLE); - wxDataViewColumn* AppendDateColumn(const wxBitmap& label, - unsigned int model_column, - wxDataViewCellMode mode = wxDATAVIEW_CELL_ACTIVATABLE, - int width = -1, - wxAlignment align = wxALIGN_CENTER, - int flags = wxDATAVIEW_COL_RESIZABLE); - //@} - - //@{ - /** - Appends a column for rendering text with an icon. Returns the wxDataViewColumn - created in the function or @NULL on failure. This method uses the - wxDataViewIconTextRenderer class. - - NB: The @e align parameter is applied to both the column header and - the column renderer. - */ - wxDataViewColumn* AppendIconTextColumn(const wxString& label, - unsigned int model_column, - wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, - int width = -1, - wxAlignment align = wxALIGN_LEFT, - int flags = wxDATAVIEW_COL_RESIZABLE); - wxDataViewColumn* AppendIconTextColumn(const wxBitmap& label, - unsigned int model_column, - wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, - int width = -1, - wxAlignment align = wxALIGN_LEFT, - int flags = wxDATAVIEW_COL_RESIZABLE); - //@} - - //@{ - /** - Appends a column for rendering a progress indicator. Returns the - wxDataViewColumn created in the function or @NULL on failure. - - NB: The @e align parameter is applied to both the column header and - the column renderer. - */ - wxDataViewColumn* AppendProgressColumn(const wxString& label, - unsigned int model_column, - wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, - int width = 80, - wxAlignment align = wxALIGN_CENTER, - int flags = wxDATAVIEW_COL_RESIZABLE); - wxDataViewColumn* AppendProgressColumn(const wxBitmap& label, - unsigned int model_column, - wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, - int width = 80, - wxAlignment align = wxALIGN_CENTER, - int flags = wxDATAVIEW_COL_RESIZABLE); - //@} - - //@{ - /** - Appends a column for rendering text. Returns the wxDataViewColumn - created in the function or @NULL on failure. - - NB: The @e align parameter is applied to both the column header and - the column renderer. - */ - wxDataViewColumn* AppendTextColumn(const wxString& label, - unsigned int model_column, - wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, - int width = -1, - wxAlignment align = wxALIGN_LEFT, - int flags = wxDATAVIEW_COL_RESIZABLE); - wxDataViewColumn* AppendTextColumn(const wxBitmap& label, - unsigned int model_column, - wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, - int width = -1, - wxAlignment align = wxALIGN_LEFT, - int flags = wxDATAVIEW_COL_RESIZABLE); - //@} - - //@{ - /** - Appends a column for rendering a toggle. Returns the wxDataViewColumn - created in the function or @NULL on failure. - - NB: The @e align parameter is applied to both the column header and - the column renderer. - */ - wxDataViewColumn* AppendToggleColumn(const wxString& label, - unsigned int model_column, - wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, - int width = 30, - wxAlignment align = wxALIGN_CENTER, - int flags = wxDATAVIEW_COL_RESIZABLE); - wxDataViewColumn* AppendToggleColumn(const wxBitmap& label, - unsigned int model_column, - wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, - int width = 30, - wxAlignment align = wxALIGN_CENTER, - int flags = wxDATAVIEW_COL_RESIZABLE); - //@} - - /** - Associates a wxDataViewModel with the control. This increases the reference - count of the model by 1. - */ - virtual bool AssociateModel(wxDataViewModel* model); - - /** - Removes all columns. - */ - virtual bool ClearColumns(); - - /** - Unselects all rows. - */ - void ClearSelection(); - - /** - Collapses the item. - */ - void Collapse(const wxDataViewItem& item); - - /** - Create the control. Useful for two step creation. - */ - bool Create(wxWindow* parent, wxWindowID id, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = 0, - const wxValidator& validator = wxDefaultValidator); - - /** - Deletes given column. - */ - virtual bool DeleteColumn(const wxDataViewColumn* column); - - /** - Call this to ensure that the given item is visible. - */ - void EnsureVisible(const wxDataViewItem& item, - const wxDataViewColumn* column = NULL); - - /** - Expands the item. - */ - void Expand(const wxDataViewItem& item); - - /** - Returns pointer to the column. @a pos refers to the - position in the control which may change after reordering - columns by the user. - */ - virtual wxDataViewColumn* GetColumn(unsigned int pos) const; - - /** - Returns the number of columns. - */ - virtual unsigned int GetColumnCount() const; - - /** - Returns the position of the column or -1 if not found in the control. - */ - virtual int GetColumnPosition(const wxDataViewColumn* column) const; - - /** - Returns column containing the expanders. - */ - wxDataViewColumn* GetExpanderColumn() const; - - /** - Returns indentation. - */ - int GetIndent() const; - - /** - Returns item rect. - */ - wxRect GetItemRect(const wxDataViewItem& item, - const wxDataViewColumn* col = NULL) const; - - /** - Returns pointer to the data model associated with the - control (if any). - */ - virtual wxDataViewModel* GetModel() const; - - /** - Returns first selected item or an invalid item if none is selected. - */ - wxDataViewItem GetSelection() const; - - /** - Fills @a sel with currently selected items and returns - their number. - */ - int GetSelections(wxDataViewItemArray& sel) const; - - /** - Returns the wxDataViewColumn currently responsible for sorting - or @NULL if none has been selected. - */ - virtual wxDataViewColumn* GetSortingColumn() const; - - /** - Hittest. - */ - void HitTest(const wxPoint& point, wxDataViewItem& item, - wxDataViewColumn*& col) const; - - /** - Return @true if the item is selected. - */ - bool IsSelected(const wxDataViewItem& item) const; - - /** - Select the given item. - */ - void Select(const wxDataViewItem& item); - - /** - Select all items. - */ - void SelectAll(); - - /** - Set which column shall contain the tree-like expanders. - */ - void SetExpanderColumn(wxDataViewColumn* col); - - /** - Sets the indendation. - */ - void SetIndent(int indent); - - /** - Sets the selection to the array of wxDataViewItems. - */ - void SetSelections(const wxDataViewItemArray& sel); - - /** - Unselect the given item. - */ - void Unselect(const wxDataViewItem& item); - - /** - Unselect all item. This method only has effect if multiple - selections are allowed. - */ - void UnselectAll(); -}; - - - -/** - @class wxDataViewModelNotifier - @wxheader{dataview.h} - - A wxDataViewModelNotifier instance is owned by a - wxDataViewModel - and mirrors its notification interface. See - the documentation of that class for further - information. - - @library{wxbase} - @category{dvc} -*/ -class wxDataViewModelNotifier -{ -public: - /** - Constructor. - */ - wxDataViewModelNotifier(); - - /** - Destructor. - */ - ~wxDataViewModelNotifier(); - - /** - Called by owning model. - */ - bool Cleared(); - - /** - Get owning wxDataViewModel. - */ - wxDataViewModel* GetOwner() const; - - /** - Called by owning model. - */ - bool ItemAdded(const wxDataViewItem& parent, - const wxDataViewItem& item); - - /** - Called by owning model. - */ - bool ItemChanged(const wxDataViewItem& item); - - /** - Called by owning model. - */ - bool ItemDeleted(const wxDataViewItem& parent, - const wxDataViewItem& item); - - /** - Called by owning model. - */ - bool ItemsAdded(const wxDataViewItem& parent, - const wxDataViewItemArray& items); - - /** - Called by owning model. - */ - bool ItemsChanged(const wxDataViewItemArray& items); - - /** - Called by owning model. - */ - bool ItemsDeleted(const wxDataViewItem& parent, - const wxDataViewItemArray& items); - - /** - Called by owning model. - */ - void Resort(); - - /** - Set owner of this notifier. Used internally. - */ - void SetOwner(wxDataViewModel* owner); - - /** - Called by owning model. - */ - bool ValueChanged(const wxDataViewItem& item, unsigned int col); -}; - - - -/** - @class wxDataViewRenderer - @wxheader{dataview.h} - - This class is used by wxDataViewCtrl to render the individual cells. - One instance of a renderer class is owned by a wxDataViewColumn. There - is a number of ready-to-use renderers provided: - wxDataViewTextRenderer, - wxDataViewTextRendererAttr, - wxDataViewIconTextRenderer, - wxDataViewToggleRenderer, - wxDataViewProgressRenderer, - wxDataViewBitmapRenderer, - wxDataViewDateRenderer. - wxDataViewSpinRenderer. - - Additionally, the user can write own renderers by deriving from - wxDataViewCustomRenderer. - - The @e wxDataViewCellMode flag controls, what actions - the cell data allows. @e wxDATAVIEW_CELL_ACTIVATABLE - indicates that the user can double click the cell and - something will happen (e.g. a window for editing a date - will pop up). @e wxDATAVIEW_CELL_EDITABLE indicates - that the user can edit the data in-place, i.e. an control - will show up after a slow click on the cell. This behaviour - is best known from changing the filename in most file - managers etc. - - - @code - enum wxDataViewCellMode - { - wxDATAVIEW_CELL_INERT, - wxDATAVIEW_CELL_ACTIVATABLE, - wxDATAVIEW_CELL_EDITABLE - }; - @endcode - - The @e wxDataViewCellRenderState flag controls how the - the renderer should display its contents in a cell: - - @code - enum wxDataViewCellRenderState - { - wxDATAVIEW_CELL_SELECTED = 1, - wxDATAVIEW_CELL_PRELIT = 2, - wxDATAVIEW_CELL_INSENSITIVE = 4, - wxDATAVIEW_CELL_FOCUSED = 8 - }; - @endcode - - - @library{wxadv} - @category{dvc} -*/ -class wxDataViewRenderer : public wxObject -{ -public: - /** - Constructor. - */ - wxDataViewRenderer(const wxString& varianttype, - wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, - int align = wxDVR_DEFAULT_ALIGNMENT ); - - /** - Returns the alignment. See SetAlignment() - */ - virtual int GetAlignment() const; - - /** - Returns the cell mode. - */ - virtual wxDataViewCellMode GetMode(); - - /** - Returns pointer to the owning wxDataViewColumn. - */ - virtual wxDataViewColumn* GetOwner() const; - - /** - This methods retrieves the value from the renderer in order to - transfer the value back to the data model. Returns @e @false - on failure. - */ - virtual bool GetValue(wxVariant& value); - - /** - Returns a string with the type of the wxVariant - supported by this renderer. - */ - virtual wxString GetVariantType(); - - /** - Sets the alignment of the renderer's content. The default value - of wxDVR_DEFAULT_ALIGMENT indicates that the content should - have the same alignment as the column header. The method is - not implemented under OS X and the renderer always aligns its - contents as the column header on that platform. The other platforms - support both vertical and horizontal alignment. - */ - virtual void SetAlignment( int align ); - /** - Sets the owning wxDataViewColumn. This - is usually called from within wxDataViewColumn. - */ - virtual void SetOwner(wxDataViewColumn* owner); - - /** - Set the value of the renderer (and thus its cell) to @e value. - The internal code will then render this cell with this data. - */ - virtual bool SetValue(const wxVariant& value); - - /** - Before data is committed to the data model, it is passed to this - method where it can be checked for validity. This can also be - used for checking a valid range or limiting the user input in - a certain aspect (e.g. max number of characters or only alphanumeric - input, ASCII only etc.). Return @e @false if the value is - not valid. - Please note that due to implementation limitations, this validation - is done after the editing control already is destroyed and the - editing process finished. - */ - virtual bool Validate(wxVariant& value); -}; - - - -/** - @class wxDataViewTextRenderer - @wxheader{dataview.h} - - wxDataViewTextRenderer is used for rendering text. It supports - in-place editing if desired. - - @library{wxadv} - @category{dvc} -*/ -class wxDataViewTextRenderer : public wxDataViewRenderer -{ -public: - /** - - */ - wxDataViewTextRenderer(const wxString& varianttype = "string", - wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, - int align = wxDVR_DEFAULT_ALIGNMENT ); -}; - - - -/** - @class wxDataViewIconTextRenderer - @wxheader{dataview.h} - - The wxDataViewIconTextRenderer class is used to display text with - a small icon next to it as it is typically done in a file manager. - This classes uses the wxDataViewIconText - helper class to store its data. wxDataViewIonText can be converted - to a from a wxVariant using the left shift - operator. - - @library{wxadv} - @category{dvc} -*/ -class wxDataViewIconTextRenderer : public wxDataViewRenderer -{ -public: - /** - - */ - wxDataViewIconTextRenderer(const wxString& varianttype = "wxDataViewIconText", - wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, - int align = wxDVR_DEFAULT_ALIGNMENT ); -}; - - - -/** - @class wxDataViewProgressRenderer - @wxheader{dataview.h} - - wxDataViewProgressRenderer - - @library{wxadv} - @category{dvc} -*/ -class wxDataViewProgressRenderer : public wxDataViewRenderer -{ -public: - /** - - */ - wxDataViewProgressRenderer(const wxString& label = wxEmptyString, - const wxString& varianttype = "long", - wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, - int align = wxDVR_DEFAULT_ALIGNMENT ); -}; - - - -/** - @class wxDataViewSpinRenderer - @wxheader{dataview.h} - - This is a specialized renderer for rendering integer values. It - supports modifying the values in-place by using a wxSpinCtrl. - The renderer only support variants of type @e long. - - @library{wxbase} - @category{dvc} -*/ -class wxDataViewSpinRenderer : public wxDataViewCustomRenderer -{ -public: - /** - Constructor. @a min and @a max indicate the minimum und - maximum values of for the wxSpinCtrl. - */ - wxDataViewSpinRenderer(int min, int max, - wxDataViewCellMode mode = wxDATAVIEW_CELL_EDITABLE, - int align = wxDVR_DEFAULT_ALIGNMENT); -}; - - - -/** - @class wxDataViewToggleRenderer - @wxheader{dataview.h} - - wxDataViewToggleRenderer - - @library{wxadv} - @category{dvc} -*/ -class wxDataViewToggleRenderer : public wxDataViewRenderer -{ -public: - /** - - */ - wxDataViewToggleRenderer(const wxString& varianttype = "bool", - wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT); -}; - - - -/** - @class wxDataViewDateRenderer - @wxheader{dataview.h} - - wxDataViewDateRenderer - - @library{wxadv} - @category{dvc} -*/ -class wxDataViewDateRenderer : public wxDataViewRenderer -{ -public: - /** - - */ - wxDataViewDateRenderer(const wxString& varianttype = "datetime", - wxDataViewCellMode mode = wxDATAVIEW_CELL_ACTIVATABLE); -}; - - - -/** - @class wxDataViewTextRendererAttr - @wxheader{dataview.h} - - The same as wxDataViewTextRenderer but with - support for font attributes. Font attributes are currently only supported - under GTK+ and MSW. - - See also wxDataViewModel::GetAttr and - wxDataViewItemAttr. - - @library{wxadv} - @category{dvc} -*/ -class wxDataViewTextRendererAttr : public wxDataViewTextRenderer -{ -public: - /** - - */ - wxDataViewTextRendererAttr(const wxString& varianttype = "string", - wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, - int align = wxDVR_DEFAULT_ALIGNMENT); -}; - - - -/** - @class wxDataViewCustomRenderer - @wxheader{dataview.h} - - You need to derive a new class from wxDataViewCustomRenderer in - order to write a new renderer. You need to override at least - wxDataViewRenderer::SetValue, - wxDataViewRenderer::GetValue, - wxDataViewCustomRenderer::GetSize - and wxDataViewCustomRenderer::Render. - - If you want your renderer to support in-place editing then you - also need to override - wxDataViewCustomRenderer::HasEditorCtrl, - wxDataViewCustomRenderer::CreateEditorCtrl - and wxDataViewCustomRenderer::GetValueFromEditorCtrl. - Note that a special event handler will be pushed onto that - editor control which handles ENTER and focus out events - in order to end the editing. - - @library{wxadv} - @category{dvc} -*/ -class wxDataViewCustomRenderer : public wxDataViewRenderer -{ -public: - /** - Constructor. - */ - wxDataViewCustomRenderer(const wxString& varianttype = "string", - wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, - int align = wxDVR_DEFAULT_ALIGNMENT ); - - /** - Destructor. - */ - ~wxDataViewCustomRenderer(); - - /** - Override this to react to double clicks or ENTER. This method will - only be called in wxDATAVIEW_CELL_ACTIVATABLE mode. - */ - virtual bool Activate( wxRect cell, - wxDataViewModel* model, - const wxDataViewItem & item, - unsigned int col ); - - /** - Override this to create the actual editor control once editing - is about to start. @a parent is the parent of the editor - control, @a labelRect indicates the position and - size of the editor control and @a value is its initial value: - */ - virtual wxControl* CreateEditorCtrl(wxWindow* parent, - wxRect labelRect, - const wxVariant& value); - - /** - Create DC on request. Internal. - */ - virtual wxDC* GetDC(); - - /** - Return size required to show content. - */ - virtual wxSize GetSize(); - - /** - Overrride this so that the renderer can get the value - from the editor control (pointed to by @e editor): - */ - virtual bool GetValueFromEditorCtrl(wxControl* editor, - wxVariant& value); - - /** - Override this and make it return @e @true in order to - indicate that this renderer supports in-place editing. - */ - virtual bool HasEditorCtrl(); - - /** - Overrride this to react to a left click. This method will - only be called in wxDATAVIEW_CELL_ACTIVATABLE mode. - */ - virtual bool LeftClick( wxPoint cursor, - wxRect cell, - wxDataViewModel * model, - const wxDataViewItem & item, - unsigned int col ); - - /** - Override this to render the cell. Before this is called, - wxDataViewRenderer::SetValue was called - so that this instance knows what to render. - */ - virtual bool Render(wxRect cell, wxDC* dc, int state); - - /** - This method should be called from within Render() - whenever you need to render simple text. This will ensure that the - correct colour, font and vertical alignment will be chosen so the - text will look the same as text drawn by native renderers. - */ - bool RenderText(const wxString& text, int xoffset, wxRect cell, - wxDC* dc, int state); - - /** - Overrride this to start a drag operation. Not yet - supported - */ - virtual bool StartDrag(wxPoint cursor, wxRect cell, - wxDataViewModel* model, - const wxDataViewItem & item, - unsigned int col); -}; - - - -/** - @class wxDataViewBitmapRenderer - @wxheader{dataview.h} - - wxDataViewBitmapRenderer - - @library{wxadv} - @category{dvc} -*/ -class wxDataViewBitmapRenderer : public wxDataViewRenderer -{ -public: - /** - - */ - wxDataViewBitmapRenderer(const wxString& varianttype = "wxBitmap", - wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, - int align = wxDVR_DEFAULT_ALIGNMENT, -}; - - - -/** - @class wxDataViewColumn - @wxheader{dataview.h} - - This class represents a column in a wxDataViewCtrl. - One wxDataViewColumn is bound to one column in the data model, - to which the wxDataViewCtrl has been associated. - - An instance of wxDataViewRenderer is used by - this class to render its data. - - @library{wxadv} - @category{dvc} -*/ -class wxDataViewColumn : public wxObject -{ -public: - //@{ - /** - Constructors. - */ - wxDataViewColumn(const wxString& title, - wxDataViewRenderer* renderer, - unsigned int model_column, - int width = wxDVC_DEFAULT_WIDTH, - wxAlignment align = wxALIGN_CENTRE, - int flags = wxDATAVIEW_COL_RESIZABLE); - wxDataViewColumn(const wxBitmap& bitmap, - wxDataViewRenderer* renderer, - unsigned int model_column, - int width = wxDVC_DEFAULT_WIDTH, - wxAlignment align = wxALIGN_CENTRE, - int flags = wxDATAVIEW_COL_RESIZABLE); - //@} - - /** - Destructor. - */ - ~wxDataViewColumn(); - - /** - Returns the bitmap in the header of the column, if any. - */ - const wxBitmap GetBitmap(); - - /** - Returns the index of the column of the model, which this - wxDataViewColumn is displaying. - */ - unsigned int GetModelColumn(); - - /** - Returns the owning wxDataViewCtrl. - */ - wxDataViewCtrl* GetOwner() const; - - /** - Returns the renderer of this wxDataViewColumn. - See also wxDataViewRenderer. - */ - wxDataViewRenderer* GetRenderer(); - - /** - Returns @true if the column is reorderable. - */ - bool GetReorderable(); - - /** - Returns @true if the column is sortable. - See SetSortable() - */ - bool GetSortable(); - - /** - Returns the width of the column. - */ - int GetWidth(); - - /** - Returns @true, if the sort order is ascending. - See also SetSortOrder() - */ - bool IsSortOrderAscending(); - - /** - Set the alignment of the column header. - */ - void SetAlignment(wxAlignment align); - - /** - Set the bitmap of the column header. - */ - void SetBitmap(const wxBitmap& bitmap); - - /** - Indicate wether the column can be reordered by the - user using the mouse. This is typically implemented - visually by dragging the header button around. - */ - void SetReorderable(bool reorderable); - - /** - Indicate the sort order if the implementation of the - wxDataViewCtrl supports it, most commonly by showing - a little arrow. - */ - void SetSortOrder(bool ascending); - - /** - Indicate that the column is sortable. This does - not show any sorting indicate yet, but it does - make the column header clickable. Call - SetSortOrder() - afterwards to actually make the sort indicator appear. - If @a sortable is @false, the column header is - no longer clickable and the sort indicator (little - arrow) will disappear. - */ - void SetSortable(bool sortable); - - /** - Set the title of the column header to @e title. - */ - void SetTitle(const wxString& title); -}; - - - -/** - @class wxDataViewTreeCtrl - @wxheader{dataview.h} - - This class is a wxDataViewCtrl which internally - uses a wxDataViewTreeStore and forwards - most of its API to that class. Additionally, it uses a wxImageList - to store a list of icons. The main purpose of this class is to look - like a wxTreeCtrl to make a transition from it - to the wxDataViewCtrl class simpler. - - @library{wxbase} - @category{ctrl,dvc} - -*/ -class wxDataViewTreeCtrl : public wxDataViewCtrl -{ -public: - //@{ - /** - Constructor. Calls Create(). - */ - wxDataViewTreeCtrl(); - wxDataViewTreeCtrl(wxWindow* parent, wxWindowID id, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = wxDV_NO_HEADER, - const wxValidator& validator = wxDefaultValidator); - //@} - - /** - Destructor. Deletes the image list if any. - */ - ~wxDataViewTreeCtrl(); - - /** - - */ - wxDataViewItem AppendContainer(const wxDataViewItem& parent, - const wxString& text, - int icon = -1, - int expanded = -1, - wxClientData* data = NULL); - - /** - - */ - wxDataViewItem AppendItem(const wxDataViewItem& parent, - const wxString& text, - int icon = -1, - wxClientData* data = NULL); - - /** - Creates the control and a wxDataViewTreeStore as - its internal model. - */ - bool Create(wxWindow* parent, wxWindowID id, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = wxDV_NO_HEADER, - const wxValidator& validator = wxDefaultValidator); - - /** - Calls the identical method from wxDataViewTreeStore. - */ - void DeleteAllItems(); - - /** - Calls the identical method from wxDataViewTreeStore. - */ - void DeleteChildren(const wxDataViewItem& item); - - /** - Calls the identical method from wxDataViewTreeStore. - */ - void DeleteItem(const wxDataViewItem& item); - - /** - Calls the identical method from wxDataViewTreeStore. - */ - int GetChildCount(const wxDataViewItem& parent) const; - - /** - Returns the image list. - */ - wxImageList* GetImageList(); - - /** - Calls the identical method from wxDataViewTreeStore. - */ - wxClientData* GetItemData(const wxDataViewItem& item) const; - - /** - Calls the identical method from wxDataViewTreeStore. - */ - const wxIcon GetItemExpandedIcon(const wxDataViewItem& item) const; - - /** - Calls the identical method from wxDataViewTreeStore. - */ - const wxIcon GetItemIcon(const wxDataViewItem& item) const; - - /** - Calls the identical method from wxDataViewTreeStore. - */ - wxString GetItemText(const wxDataViewItem& item) const; - - /** - Calls the identical method from wxDataViewTreeStore. - */ - wxDataViewItem GetNthChild(const wxDataViewItem& parent, - unsigned int pos) const; - - //@{ - /** - Returns the store. - */ - wxDataViewTreeStore* GetStore() const; - const wxDataViewTreeStore* GetStore() const; - //@} - - /** - Calls the same method from wxDataViewTreeStore but uess - and index position in the image list instead of a wxIcon. - */ - wxDataViewItem InsertContainer(const wxDataViewItem& parent, - const wxDataViewItem& previous, - const wxString& text, - int icon = -1, - int expanded = -1, - wxClientData* data = NULL); - - /** - Calls the same method from wxDataViewTreeStore but uess - and index position in the image list instead of a wxIcon. - */ - wxDataViewItem InsertItem(const wxDataViewItem& parent, - const wxDataViewItem& previous, - const wxString& text, - int icon = -1, - wxClientData* data = NULL); - - /** - Calls the same method from wxDataViewTreeStore but uess - and index position in the image list instead of a wxIcon. - */ - wxDataViewItem PrependContainer(const wxDataViewItem& parent, - const wxString& text, - int icon = -1, - int expanded = -1, - wxClientData* data = NULL); - - /** - Calls the same method from wxDataViewTreeStore but uess - and index position in the image list instead of a wxIcon. - */ - wxDataViewItem PrependItem(const wxDataViewItem& parent, - const wxString& text, - int icon = -1, - wxClientData* data = NULL); - - /** - Sets the image list. - */ - void SetImageList(wxImageList* imagelist); - - /** - Calls the identical method from wxDataViewTreeStore. - */ - void SetItemData(const wxDataViewItem& item, wxClientData* data); - - /** - Calls the identical method from wxDataViewTreeStore. - */ - void SetItemExpandedIcon(const wxDataViewItem& item, - const wxIcon& icon); - - /** - Calls the identical method from wxDataViewTreeStore. - */ - void SetItemIcon(const wxDataViewItem& item, const wxIcon& icon); - - /** - Calls the identical method from wxDataViewTreeStore. - */ - void SetItemText(const wxDataViewItem& item, - const wxString& text); -}; - - - -/** - @class wxDataViewTreeStore - @wxheader{dataview.h} - - wxDataViewTreeStore is a specialised wxDataViewModel - for displaying simple trees very much like wxTreeCtrl - does and it offers a similar API. This class actually stores the entire - tree (therefore its name) and implements all virtual methods from the base - class so it can be used directly without having to derive any class from it. - This comes at the price of much reduced flexibility. - - @library{wxadv} - @category{dvc} -*/ -class wxDataViewTreeStore : public wxDataViewModel -{ -public: - /** - Constructor. Creates the invisible root node internally. - */ - wxDataViewTreeStore(); - - /** - Destructor. - */ - ~wxDataViewTreeStore(); - - /** - Append a container. - */ - wxDataViewItem AppendContainer(const wxDataViewItem& parent, - const wxString& text, - const wxIcon& icon = wxNullIcon, - const wxIcon& expanded = wxNullIcon, - wxClientData* data = NULL); - - /** - Append an item. - */ - wxDataViewItem AppendItem(const wxDataViewItem& parent, - const wxString& text, - const wxIcon& icon = wxNullIcon, - wxClientData* data = NULL); - - /** - Delete all item in the model. - */ - void DeleteAllItems(); - - /** - Delete all children of the item, but not the item itself. - */ - void DeleteChildren(const wxDataViewItem& item); - - /** - Delete this item. - */ - void DeleteItem(const wxDataViewItem& item); - - /** - Return the number of children of item. - */ - int GetChildCount(const wxDataViewItem& parent) const; - - /** - Returns the client data asoociated with the item. - */ - wxClientData* GetItemData(const wxDataViewItem& item) const; - - /** - Returns the icon to display in expanded containers. - */ - const wxIcon GetItemExpandedIcon(const wxDataViewItem& item) const; - - /** - Returns the icon of the item. - */ - const wxIcon GetItemIcon(const wxDataViewItem& item) const; - - /** - Returns the text of the item. - */ - wxString GetItemText(const wxDataViewItem& item) const; - - /** - Returns the nth child item of item. - */ - wxDataViewItem GetNthChild(const wxDataViewItem& parent, - unsigned int pos) const; - - /** - Inserts a container after @e previous. - */ - wxDataViewItem InsertContainer(const wxDataViewItem& parent, - const wxDataViewItem& previous, - const wxString& text, - const wxIcon& icon = wxNullIcon, - const wxIcon& expanded = wxNullIcon, - wxClientData* data = NULL); - - /** - Inserts an item after @e previous. - */ - wxDataViewItem InsertItem(const wxDataViewItem& parent, - const wxDataViewItem& previous, - const wxString& text, - const wxIcon& icon = wxNullIcon, - wxClientData* data = NULL); - - /** - Inserts a container before the first child item or @e parent. - */ - wxDataViewItem PrependContainer(const wxDataViewItem& parent, - const wxString& text, - const wxIcon& icon = wxNullIcon, - const wxIcon& expanded = wxNullIcon, - wxClientData* data = NULL); - - /** - Inserts an item before the first child item or @e parent. - */ - wxDataViewItem PrependItem(const wxDataViewItem& parent, - const wxString& text, - const wxIcon& icon = wxNullIcon, - wxClientData* data = NULL); - - /** - Sets the client data associated with the item. - */ - void SetItemData(const wxDataViewItem& item, wxClientData* data); - - /** - Sets the expanded icon for the item. - */ - void SetItemExpandedIcon(const wxDataViewItem& item, - const wxIcon& icon); - - /** - Sets the icon for the item. - */ - void SetItemIcon(const wxDataViewItem& item, const wxIcon& icon); -}; - diff --git a/interface/datectrl.h b/interface/datectrl.h deleted file mode 100644 index d32451ce57..0000000000 --- a/interface/datectrl.h +++ /dev/null @@ -1,157 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: datectrl.h -// Purpose: interface of wxDatePickerCtrl -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxDatePickerCtrl - @wxheader{datectrl.h} - - This control allows the user to select a date. Unlike wxCalendarCtrl, which - is a relatively big control, wxDatePickerCtrl is implemented as a small - window showing the currently selected date. The control can be edited using - the keyboard, and can also display a popup window for more user-friendly - date selection, depending on the styles used and the platform, except - PalmOS where date is selected using native dialog. - - It is only available if @c wxUSE_DATEPICKCTRL is set to 1. - - @beginStyleTable - @style{wxDP_SPIN} - Creates a control without a month calendar drop down but with - spin-control-like arrows to change individual date components. This - style is not supported by the generic version. - @style{wxDP_DROPDOWN} - Creates a control with a month calendar drop-down part from which - the user can select a date. - @style{wxDP_DEFAULT} - Creates a control with the style that is best supported for the - current platform (currently wxDP_SPIN under Windows and - wxDP_DROPDOWN elsewhere). - @style{wxDP_ALLOWNONE} - With this style, the control allows the user to not enter any valid - date at all. Without it - the default - the control always has some - valid date. - @style{wxDP_SHOWCENTURY} - Forces display of the century in the default date format. Without - this style the century could be displayed, or not, depending on the - default date representation in the system. - @endStyleTable - - @beginEventTable{wxDateEvent} - @event{EVT_DATE_CHANGED(id, func)} - This event fires when the user changes the current selection in the - control. - @endEventTable - - @library{wxadv} - @category{pickers} - - - @see wxCalendarCtrl, wxDateEvent -*/ -class wxDatePickerCtrl : public wxControl -{ -public: - /** - Initializes the object and calls Create() with all the parameters. - */ - wxDatePickerCtrl(wxWindow* parent, wxWindowID id, - const wxDateTime& dt = wxDefaultDateTime, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = wxDP_DEFAULT | wxDP_SHOWCENTURY, - const wxValidator& validator = wxDefaultValidator, - const wxString& name = "datectrl"); - - /** - @param parent - Parent window, must not be non-@NULL. - @param id - The identifier for the control. - @param dt - The initial value of the control, if an invalid date (such as the - default value) is used, the control is set to today. - @param pos - Initial position. - @param size - Initial size. If left at default value, the control chooses its own - best size by using the height approximately equal to a text control - and width large enough to show the date string fully. - @param style - The window style, should be left at 0 as there are no special - styles for this control in this version. - @param validator - Validator which can be used for additional date checks. - @param name - Control name. - - @return @true if the control was successfully created or @false if - creation failed. - */ - bool Create(wxWindow* parent, wxWindowID id, - const wxDateTime& dt = wxDefaultDateTime, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = wxDP_DEFAULT | wxDP_SHOWCENTURY, - const wxValidator& validator = wxDefaultValidator, - const wxString& name = "datectrl"); - - /** - If the control had been previously limited to a range of dates using - SetRange(), returns the lower and upper bounds of this range. If no - range is set (or only one of the bounds is set), @a dt1 and/or @a dt2 - are set to be invalid. - - @param dt1 - Pointer to the object which receives the lower range limit or - becomes invalid if it is not set. May be @NULL if the caller is not - interested in lower limit. - @param dt2 - Same as above but for the upper limit. - - @return @false if no range limits are currently set, @true if at least - one bound is set. - */ - bool GetRange(wxDateTime* dt1, wxDateTime dt2) const; - - /** - Returns the currently selected. If there is no selection or the - selection is outside of the current range, an invalid object is - returned. - */ - wxDateTime GetValue() const; - - /** - Sets the display format for the date in the control. See wxDateTime for - the meaning of format strings. - - @note This function is only available in the generic version of this - control. The native version always uses the current system locale. - - @remarks If the format parameter is invalid, the behaviour is undefined. - */ - void SetFormat(const wxChar* format); - - /** - Sets the valid range for the date selection. If @a dt1 is valid, it - becomes the earliest date (inclusive) accepted by the control. If - @a dt2 is valid, it becomes the latest possible date. - - @remarks If the current value of the control is outside of the newly - set range bounds, the behaviour is undefined. - */ - void SetRange(const wxDateTime& dt1, const wxDateTime& dt2); - - /** - Changes the current value of the control. The date should be valid and - included in the currently selected range, if any. - - Calling this method does not result in a date change event. - */ - void SetValue(const wxDateTime& dt); -}; - diff --git a/interface/dateevt.h b/interface/dateevt.h deleted file mode 100644 index 13bb4bb7e5..0000000000 --- a/interface/dateevt.h +++ /dev/null @@ -1,34 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: dateevt.h -// Purpose: interface of wxDateEvent -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxDateEvent - @wxheader{dateevt.h} - - This event class holds information about a date change and is used together - with wxDatePickerCtrl. It also serves as a base class - for wxCalendarEvent. - - @library{wxadv} - @category{events} -*/ -class wxDateEvent : public wxCommandEvent -{ -public: - /** - Returns the date. - */ - const wxDateTime GetDate() const; - - /** - Sets the date carried by the event, normally only used by the library - internally. - */ - void SetDate(const wxDateTime& date); -}; - diff --git a/interface/datetime.h b/interface/datetime.h deleted file mode 100644 index ce9810ebb6..0000000000 --- a/interface/datetime.h +++ /dev/null @@ -1,2061 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: datetime.h -// Purpose: interface of wxDateTime -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxDateTime - @wxheader{datetime.h} - - wxDateTime class represents an absolute moment in the time. - - The type @c wxDateTime_t is typedefed as unsigned short and is - used to contain the number of years, hours, minutes, seconds and - milliseconds. - - - @section datetime_constants Constants - - Global constant wxDefaultDateTime and synonym for it wxInvalidDateTime are - defined. This constant will be different from any valid wxDateTime object. - - All the following constants are defined inside wxDateTime class (i.e., to - refer to them you should prepend their names with "wxDateTime::"). - - Time zone symbolic names: - - @code - enum TZ - { - // the time in the current time zone - Local, - - // zones from GMT (= Greenwhich Mean Time): they're guaranteed to be - // consequent numbers, so writing something like `GMT0 + offset' is - // safe if abs(offset) <= 12 - - // underscore stands for minus - GMT_12, GMT_11, GMT_10, GMT_9, GMT_8, GMT_7, - GMT_6, GMT_5, GMT_4, GMT_3, GMT_2, GMT_1, - GMT0, - GMT1, GMT2, GMT3, GMT4, GMT5, GMT6, - GMT7, GMT8, GMT9, GMT10, GMT11, GMT12, GMT13, - // Note that GMT12 and GMT_12 are not the same: there is a difference - // of exactly one day between them - - // some symbolic names for TZ - - // Europe - WET = GMT0, // Western Europe Time - WEST = GMT1, // Western Europe Summer Time - CET = GMT1, // Central Europe Time - CEST = GMT2, // Central Europe Summer Time - EET = GMT2, // Eastern Europe Time - EEST = GMT3, // Eastern Europe Summer Time - MSK = GMT3, // Moscow Time - MSD = GMT4, // Moscow Summer Time - - // US and Canada - AST = GMT_4, // Atlantic Standard Time - ADT = GMT_3, // Atlantic Daylight Time - EST = GMT_5, // Eastern Standard Time - EDT = GMT_4, // Eastern Daylight Saving Time - CST = GMT_6, // Central Standard Time - CDT = GMT_5, // Central Daylight Saving Time - MST = GMT_7, // Mountain Standard Time - MDT = GMT_6, // Mountain Daylight Saving Time - PST = GMT_8, // Pacific Standard Time - PDT = GMT_7, // Pacific Daylight Saving Time - HST = GMT_10, // Hawaiian Standard Time - AKST = GMT_9, // Alaska Standard Time - AKDT = GMT_8, // Alaska Daylight Saving Time - - // Australia - - A_WST = GMT8, // Western Standard Time - A_CST = GMT13 + 1, // Central Standard Time (+9.5) - A_EST = GMT10, // Eastern Standard Time - A_ESST = GMT11, // Eastern Summer Time - - // New Zealand - NZST = GMT12, // Standard Time - NZDT = GMT13, // Daylight Saving Time - - // Universal Coordinated Time = the new and politically correct name - // for GMT - UTC = GMT0 - }; - @endcode - - Month names: Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec and - Inv_Month for an invalid month are the values of @c wxDateTime::Month enum. - - Likewise, Sun, Mon, Tue, Wed, Thu, Fri, Sat, and Inv_WeekDay are the values - in @c wxDateTime::WeekDay enum. - - Finally, Inv_Year is defined to be an invalid value for year parameter. - - GetMonthName() and GetWeekDayName() functions use the following flags: - - @code - enum NameFlags - { - Name_Full = 0x01, // return full name - Name_Abbr = 0x02 // return abbreviated name - }; - @endcode - - Several functions accept an extra parameter specifying the calendar to use - (although most of them only support now the Gregorian calendar). This - parameters is one of the following values: - - @code - enum Calendar - { - Gregorian, // calendar currently in use in Western countries - Julian // calendar in use since -45 until the 1582 (or later) - }; - @endcode - - Date calculations often depend on the country and wxDateTime allows to set - the country whose conventions should be used using SetCountry(). It takes - one of the following values as parameter: - - @code - enum Country - { - Country_Unknown, // no special information for this country - Country_Default, // set the default country with SetCountry() method - // or use the default country with any other - - Country_WesternEurope_Start, - Country_EEC = Country_WesternEurope_Start, - France, - Germany, - UK, - Country_WesternEurope_End = UK, - - Russia, - - USA - }; - @endcode - - Different parts of the world use different conventions for the week start. - In some countries, the week starts on Sunday, while in others -- on Monday. - The ISO standard doesn't address this issue, so we support both conventions - in the functions whose result depends on it (GetWeekOfYear() and - GetWeekOfMonth()). - - The desired behvaiour may be specified by giving one of the following - constants as argument to these functions: - - @code - enum WeekFlags - { - Default_First, // Sunday_First for US, Monday_First for the rest - Monday_First, // week starts with a Monday - Sunday_First // week starts with a Sunday - }; - @endcode - - - @section datetime_static Static Functions - - All static functions either set or return the static variables of - wxDateSpan (the country), return the current moment, year, month or number - of days in it, or do some general calendar-related actions. - - Please note that although several function accept an extra Calendar - parameter, it is currently ignored as only the Gregorian calendar is - supported. Future versions will support other calendars. - - @beginWxPythonOnly - These methods are standalone functions named - "wxDateTime_" in wxPython. - @endWxPythonOnly - - - @section datetime_formatting Date Formatting and Parsing - - The date formatting and parsing functions convert wxDateTime objects to and - from text. The conversions to text are mostly trivial: you can either do it - using the default date and time representations for the current locale - (FormatDate() and FormatTime()), using the international standard - representation defined by ISO 8601 (FormatISODate(), FormatISOTime() and - FormatISOCombined()) or by specifying any format at all and using Format() - directly. - - The conversions from text are more interesting, as there are much more - possibilities to care about. The simplest cases can be taken care of with - ParseFormat() which can parse any date in the given (rigid) format. - ParseRfc822Date() is another function for parsing dates in predefined - format -- the one of RFC 822 which (still...) defines the format of email - messages on the Internet. This format can not be described with - @c strptime(3)-like format strings used by Format(), hence the need for a - separate function. - - But the most interesting functions are ParseTime(), ParseDate() and - ParseDateTime(). They try to parse the date and time (or only one of them) - in 'free' format, i.e. allow them to be specified in any of possible ways. - These functions will usually be used to parse the (interactive) user input - which is not bound to be in any predefined format. As an example, - ParseDateTime() can parse the strings such as "tomorrow", "March first" and - even "next Sunday". - - Finally notice that each of the parsing functions is available in several - overloads: if the input string is a narrow (@c char *) string, then a - narrow pointer is returned. If the input string is a wide string, a wide - char pointer is returned. Finally, if the input parameter is a wxString, a - narrow char pointer is also returned for backwards compatibility but there - is also an additional argument of wxString::const_iterator type in which, - if it is not @NULL, an iterator pointing to the end of the scanned string - part is returned. - - - @library{wxbase} - @category{data} - - @stdobjects - - ::wxDefaultDateTime - - @see @ref overview_datetime, wxTimeSpan, wxDateSpan, wxCalendarCtrl -*/ -class wxDateTime -{ -public: - /** - @name Constructors, Assignment Operators and Setters - - Constructors and various Set() methods are collected here. If you - construct a date object from separate values for day, month and year, - you should use IsValid() method to check that the values were correct - as constructors can not return an error code. - */ - //@{ - - /** - Default constructor. Use one of the Set() functions to initialize the - object later. - */ - wxDateTime(); - /** - Same as Set(). - - @beginWxPythonOnly - This constructor is named "wxDateTimeFromTimeT" in wxPython. - @endWxPythonOnly - */ - wxDateTime& wxDateTime(time_t timet); - /** - Same as Set(). - - @beginWxPythonOnly Unsupported. @endWxPythonOnly - */ - wxDateTime& wxDateTime(const struct tm& tm); - /** - Same as Set(). - - @beginWxPythonOnly - This constructor is named "wxDateTimeFromJDN" in wxPython. - @endWxPythonOnly - */ - wxDateTime& wxDateTime(double jdn); - /** - Same as Set(). - - @beginWxPythonOnly - This constructor is named "wxDateTimeFromHMS" in wxPython. - @endWxPythonOnly - */ - wxDateTime& wxDateTime(wxDateTime_t hour, wxDateTime_t minute = 0, - wxDateTime_t second = 0, wxDateTime_t millisec = 0); - /** - Same as Set(). - - @beginWxPythonOnly - This constructor is named "wxDateTimeFromDMY" in wxPython. - @endWxPythonOnly - */ - wxDateTime(wxDateTime_t day, Month month = Inv_Month, - int year = Inv_Year, wxDateTime_t hour = 0, - wxDateTime_t minute = 0, wxDateTime_t second = 0, - wxDateTime_t millisec = 0); - - /** - Same as SetFromMSWSysTime. - - @param st - Input, Windows SYSTEMTIME reference - @since 2.9.0 - @remarks MSW only - */ - wxDateTime(const struct _SYSTEMTIME& st); - - - /** - Reset time to midnight (00:00:00) without changing the date. - */ - wxDateTime& ResetTime(); - - /** - Constructs the object from @a timet value holding the number of seconds - since Jan 1, 1970. - - @beginWxPythonOnly - This method is named "SetTimeT" in wxPython. - @endWxPythonOnly - */ - wxDateTime& Set(time_t timet); - /** - Sets the date and time from the broken down representation in the - standard @a tm structure. - - @beginWxPythonOnly Unsupported. @endWxPythonOnly - */ - wxDateTime& Set(const struct tm& tm); - /** - Sets the date from the so-called Julian Day Number. - - By definition, the Julian Day Number, usually abbreviated as JDN, of a - particular instant is the fractional number of days since 12 hours - Universal Coordinated Time (Greenwich mean noon) on January 1 of the - year -4712 in the Julian proleptic calendar. - - @beginWxPythonOnly - This method is named "SetJDN" in wxPython. - @endWxPythonOnly - */ - wxDateTime& Set(double jdn); - /** - Sets the date to be equal to Today() and the time from supplied - parameters. - - @beginWxPythonOnly - This method is named "SetHMS" in wxPython. - @endWxPythonOnly - */ - wxDateTime& Set(wxDateTime_t hour, wxDateTime_t minute = 0, - wxDateTime_t second = 0, wxDateTime_t millisec = 0); - /** - Sets the date and time from the parameters. - */ - wxDateTime& Set(wxDateTime_t day, Month month = Inv_Month, - int year = Inv_Year, wxDateTime_t hour = 0, - wxDateTime_t minute = 0, wxDateTime_t second = 0, - wxDateTime_t millisec = 0); - - /** - Sets the day without changing other date components. - */ - wxDateTime& SetDay(short unsigned int); - - /** - Sets the date from the date and time in DOS format. - */ - wxDateTime& SetFromDOS(unsigned long ddt); - - /** - Sets the hour without changing other date components. - */ - wxDateTime& SetHour(short unsigned int); - - /** - Sets the millisecond without changing other date components. - */ - wxDateTime& SetMillisecond(short unsigned int); - - /** - Sets the minute without changing other date components. - */ - wxDateTime& SetMinute(short unsigned int); - - /** - Sets the month without changing other date components. - */ - wxDateTime& SetMonth(Month month); - - /** - Sets the second without changing other date components. - */ - wxDateTime& SetSecond(short unsigned int); - - /** - Sets the date and time of to the current values. Same as assigning the - result of Now() to this object. - */ - wxDateTime& SetToCurrent(); - - /** - Sets the year without changing other date components. - */ - wxDateTime& SetYear(int year); - - /** - Same as Set(). - */ - wxDateTime& operator=(time_t timet); - /** - Same as Set(). - */ - wxDateTime& operator=(const struct tm& tm); - - //@} - - - - /** - @name Accessors - - Here are the trivial accessors. Other functions, which might have to - perform some more complicated calculations to find the answer are under - the "Date Arithmetics" section. - */ - //@{ - - /** - Returns the date and time in DOS format. - */ - long unsigned int GetAsDOS() const; - - /** - Initialize using the Windows SYSTEMTIME structure. - @param st - Input, Windows SYSTEMTIME reference - @since 2.9.0 - @remarks MSW only - */ - wxDateTime& SetFromMSWSysTime(const struct _SYSTEMTIME& st); - - /** - Returns the date and time in the Windows SYSTEMTIME format. - @param st - Output, pointer to Windows SYSTEMTIME - @since 2.9.0 - @remarks MSW only - */ - void GetAsMSWSysTime(struct _SYSTEMTIME* st) const; - - /** - Returns the century of this date. - */ - int GetCentury(const TimeZone& tz = Local) const; - - /** - Returns the object having the same date component as this one but time - of 00:00:00. - - @since 2.8.2 - - @see ResetTime() - */ - wxDateTime GetDateOnly() const; - - /** - Returns the day in the given timezone (local one by default). - */ - short unsigned int GetDay(const TimeZone& tz = Local) const; - - /** - Returns the day of the year (in 1-366 range) in the given timezone - (local one by default). - */ - short unsigned int GetDayOfYear(const TimeZone& tz = Local) const; - - /** - Returns the hour in the given timezone (local one by default). - */ - short unsigned int GetHour(const TimeZone& tz = Local) const; - - /** - Returns the milliseconds in the given timezone (local one by default). - */ - short unsigned int GetMillisecond(const TimeZone& tz = Local) const; - - /** - Returns the minute in the given timezone (local one by default). - */ - short unsigned int GetMinute(const TimeZone& tz = Local) const; - - /** - Returns the month in the given timezone (local one by default). - */ - Month GetMonth(const TimeZone& tz = Local) const; - - /** - Returns the seconds in the given timezone (local one by default). - */ - short unsigned int GetSecond(const TimeZone& tz = Local) const; - - /** - Returns the number of seconds since Jan 1, 1970. An assert failure will - occur if the date is not in the range covered by @c time_t type. - */ - time_t GetTicks() const; - - /** - Returns broken down representation of the date and time. - */ - Tm GetTm(const TimeZone& tz = Local) const; - - /** - Returns the week day in the given timezone (local one by default). - */ - WeekDay GetWeekDay(const TimeZone& tz = Local) const; - - /** - Returns the ordinal number of the week in the month (in 1-5 range). - - As GetWeekOfYear(), this function supports both conventions for the - week start. See the description of these @c WeekFlags in the - @ref datetime_constants section. - */ - wxDateTime_t GetWeekOfMonth(WeekFlags flags = Monday_First, - const TimeZone& tz = Local) const; - - /** - Returns the number of the week of the year this date is in. The first - week of the year is, according to international standards, the one - containing Jan 4 or, equivalently, the first week which has Thursday in - this year. Both of these definitions are the same as saying that the - first week of the year must contain more than half of its days in this - year. Accordingly, the week number will always be in 1-53 range (52 for - non-leap years). - - The function depends on the @ref datetime_constants "week start" - convention specified by the @a flags argument but its results for - @c Sunday_First are not well-defined as the ISO definition quoted above - applies to the weeks starting on Monday only. - */ - wxDateTime_t GetWeekOfYear(WeekFlags flags = Monday_First, - const TimeZone& tz = Local) const; - - /** - Returns the year in the given timezone (local one by default). - */ - int GetYear(const TimeZone& tz = Local) const; - - /** - Returns @true if the given date is later than the date of adoption of - the Gregorian calendar in the given country (and hence the Gregorian - calendar calculations make sense for it). - */ - bool IsGregorianDate(GregorianAdoption country = Gr_Standard) const; - - /** - Returns @true if the object represents a valid time moment. - */ - bool IsValid() const; - - /** - Returns @true is this day is not a holiday in the given country. - */ - bool IsWorkDay(Country country = Country_Default) const; - - //@} - - - - /** - @name Date Comparison - - There are several functions to allow date comparison. To supplement - them, a few global operators, etc taking wxDateTime are defined. - */ - //@{ - - /** - Returns @true if this date precedes the given one. - */ - bool IsEarlierThan(const wxDateTime& datetime) const; - - /** - Returns @true if the two dates are strictly identical. - */ - bool IsEqualTo(const wxDateTime& datetime) const; - - /** - Returns @true if the date is equal to another one up to the given time - interval, i.e. if the absolute difference between the two dates is less - than this interval. - */ - bool IsEqualUpTo(const wxDateTime& dt, const wxTimeSpan& ts) const; - - /** - Returns @true if this date is later than the given one. - */ - bool IsLaterThan(const wxDateTime& datetime) const; - - /** - Returns @true if the date is the same without comparing the time parts. - */ - bool IsSameDate(const wxDateTime& dt) const; - - /** - Returns @true if the time is the same (although dates may differ). - */ - bool IsSameTime(const wxDateTime& dt) const; - - /** - Returns @true if this date lies strictly between the two given dates. - - @see IsBetween() - */ - bool IsStrictlyBetween(const wxDateTime& t1, - const wxDateTime& t2) const; - - /** - Returns @true if IsStrictlyBetween() is @true or if the date is equal - to one of the limit values. - - @see IsStrictlyBetween() - */ - bool IsBetween(const wxDateTime& t1, const wxDateTime& t2) const; - - //@} - - - - /** - @name Date Arithmetics - - These functions carry out - @ref overview_datetime_arithmetics "arithmetics" on the wxDateTime - objects. As explained in the overview, either wxTimeSpan or wxDateSpan - may be added to wxDateTime, hence all functions are overloaded to - accept both arguments. - - Also, both Add() and Subtract() have both const and non-const version. - The first one returns a new object which represents the sum/difference - of the original one with the argument while the second form modifies - the object to which it is applied. The operators "-=" and "+=" are - defined to be equivalent to the second forms of these functions. - */ - //@{ - - /** - Adds the given date span to this object. - - @beginWxPythonOnly - This method is named "AddDS" in wxPython. - @endWxPythonOnly - */ - wxDateTime Add(const wxDateSpan& diff) const; - /** - Adds the given date span to this object. - - @beginWxPythonOnly - This method is named "AddDS" in wxPython. - @endWxPythonOnly - */ - wxDateTime Add(const wxDateSpan& diff); - /** - Adds the given time span to this object. - - @beginWxPythonOnly - This method is named "AddTS" in wxPython. - @endWxPythonOnly - */ - wxDateTime Add(const wxTimeSpan& diff) const; - /** - Adds the given time span to this object. - - @beginWxPythonOnly - This method is named "AddTS" in wxPython. - @endWxPythonOnly - */ - wxDateTime& Add(const wxTimeSpan& diff); - - /** - Subtracts the given time span from this object. - - @beginWxPythonOnly - This method is named "SubtractTS" in wxPython. - @endWxPythonOnly - */ - wxDateTime Subtract(const wxTimeSpan& diff) const; - /** - Subtracts the given time span from this object. - - @beginWxPythonOnly - This method is named "SubtractTS" in wxPython. - @endWxPythonOnly - */ - wxDateTime& Subtract(const wxTimeSpan& diff); - /** - Subtracts the given date span from this object. - - @beginWxPythonOnly - This method is named "SubtractDS" in wxPython. - @endWxPythonOnly - */ - wxDateTime Subtract(const wxDateSpan& diff) const; - /** - Subtracts the given date span from this object. - - @beginWxPythonOnly - This method is named "SubtractDS" in wxPython. - @endWxPythonOnly - */ - wxDateTime& Subtract(const wxDateSpan& diff); - /** - Subtracts another date from this one and returns the difference between - them as a wxTimeSpan. - */ - wxTimeSpan Subtract(const wxDateTime& dt) const; - - /** - Adds the given date span to this object. - */ - wxDateTime operator+=(const wxDateSpan& diff); - /** - Subtracts the given date span from this object. - */ - wxDateTime& operator-=(const wxDateSpan& diff); - /** - Adds the given time span to this object. - */ - wxDateTime& operator+=(const wxTimeSpan& diff); - /** - Subtracts the given time span from this object. - */ - wxDateTime& operator-=(const wxTimeSpan& diff); - - //@} - - - - /** - @name Date Formatting and Parsing - - See @ref datetime_formatting - */ - //@{ - - /** - This function does the same as the standard ANSI C @c strftime(3) - function. Please see its description for the meaning of @a format - parameter. - - It also accepts a few wxWidgets-specific extensions: you can optionally - specify the width of the field to follow using @c printf(3)-like syntax - and the format specification @c "%l" can be used to get the number of - milliseconds. - - @see ParseFormat() - */ - wxString Format(const wxChar* format = wxDefaultDateTimeFormat, - const TimeZone& tz = Local) const; - - /** - Identical to calling Format() with @c "%x" argument (which means - "preferred date representation for the current locale"). - */ - wxString FormatDate() const; - - /** - Returns the combined date-time representation in the ISO 8601 format - @c "YYYY-MM-DDTHH:MM:SS". The @a sep parameter default value produces - the result exactly corresponding to the ISO standard, but it can also - be useful to use a space as seprator if a more human-readable combined - date-time representation is needed. - - @see FormatISODate(), FormatISOTime(), ParseISOCombined() - */ - wxString FormatISOCombined(char sep = 'T') const; - - /** - This function returns the date representation in the ISO 8601 format - @c "YYYY-MM-DD". - */ - wxString FormatISODate() const; - - /** - This function returns the time representation in the ISO 8601 format - @c "HH:MM:SS". - */ - wxString FormatISOTime() const; - - /** - Identical to calling Format() with @c "%X" argument (which means - "preferred time representation for the current locale"). - */ - wxString FormatTime() const; - - /** - This function is like ParseDateTime(), but it only allows the date to - be specified. It is thus less flexible then ParseDateTime(), but also - has less chances to misinterpret the user input. - - @return @NULL if the conversion failed, otherwise return the pointer - to the character which stopped the scan. - */ - const char* ParseDate(const wxString& date, - wxString::const_iterator* end = NULL); - /** - This function is like ParseDateTime(), but it only allows the date to - be specified. It is thus less flexible then ParseDateTime(), but also - has less chances to misinterpret the user input. - - @return @NULL if the conversion failed, otherwise return the pointer - to the character which stopped the scan. - */ - const char* ParseDate(const char* date); - /** - This function is like ParseDateTime(), but it only allows the date to - be specified. It is thus less flexible then ParseDateTime(), but also - has less chances to misinterpret the user input. - - @return @NULL if the conversion failed, otherwise return the pointer - to the character which stopped the scan. - */ - const wchar_t* ParseDate(const wchar_t* date); - - /** - Parses the string @a datetime containing the date and time in free - format. This function tries as hard as it can to interpret the given - string as date and time. Unlike ParseRfc822Date(), it will accept - anything that may be accepted and will only reject strings which can - not be parsed in any way at all. - - @return @NULL if the conversion failed, otherwise return the pointer - to the character which stopped the scan. - */ - const char* ParseDateTime(const wxString& datetime, - wxString::const_iterator* end = NULL); - /** - Parses the string @a datetime containing the date and time in free - format. This function tries as hard as it can to interpret the given - string as date and time. Unlike ParseRfc822Date(), it will accept - anything that may be accepted and will only reject strings which can - not be parsed in any way at all. - - @return @NULL if the conversion failed, otherwise return the pointer - to the character which stopped the scan. - */ - const char* ParseDateTime(const char* datetime); - /** - Parses the string @a datetime containing the date and time in free - format. This function tries as hard as it can to interpret the given - string as date and time. Unlike ParseRfc822Date(), it will accept - anything that may be accepted and will only reject strings which can - not be parsed in any way at all. - - @return @NULL if the conversion failed, otherwise return the pointer - to the character which stopped the scan. - */ - const wchar_t* ParseDateTime(const wchar_t* datetime); - - /** - This function parses the string @a date according to the given - @e format. The system @c strptime(3) function is used whenever - available, but even if it is not, this function is still implemented, - although support for locale-dependent format specifiers such as - @c "%c", @c "%x" or @c "%X" may not be perfect and GNU extensions such - as @c "%z" and @c "%Z" are not implemented. This function does handle - the month and weekday names in the current locale on all platforms, - however. - - Please see the description of the ANSI C function @c strftime(3) for - the syntax of the format string. - - The @a dateDef parameter is used to fill in the fields which could not - be determined from the format string. For example, if the format is - @c "%d" (the day of the month), the month and the year are taken from - @a dateDef. If it is not specified, Today() is used as the default - date. - - @return @NULL if the conversion failed, otherwise return the pointer - to the character which stopped the scan. - */ - const char* ParseFormat(const wxString& date, - const wxString& format = wxDefaultDateTimeFormat, - const wxDateTime& dateDef = wxDefaultDateTime, - wxString::const_iterator* end = NULL); - /** - This function parses the string @a date according to the given - @e format. The system @c strptime(3) function is used whenever - available, but even if it is not, this function is still implemented, - although support for locale-dependent format specifiers such as - @c "%c", @c "%x" or @c "%X" may not be perfect and GNU extensions such - as @c "%z" and @c "%Z" are not implemented. This function does handle - the month and weekday names in the current locale on all platforms, - however. - - Please see the description of the ANSI C function @c strftime(3) for - the syntax of the format string. - - The @a dateDef parameter is used to fill in the fields which could not - be determined from the format string. For example, if the format is - @c "%d" (the day of the month), the month and the year are taken from - @a dateDef. If it is not specified, Today() is used as the default - date. - - @return @NULL if the conversion failed, otherwise return the pointer - to the character which stopped the scan. - */ - const char* ParseFormat(const char* date, - const wxString& format = wxDefaultDateTimeFormat, - const wxDateTime& dateDef = wxDefaultDateTime); - /** - This function parses the string @a date according to the given - @e format. The system @c strptime(3) function is used whenever - available, but even if it is not, this function is still implemented, - although support for locale-dependent format specifiers such as - @c "%c", @c "%x" or @c "%X" may not be perfect and GNU extensions such - as @c "%z" and @c "%Z" are not implemented. This function does handle - the month and weekday names in the current locale on all platforms, - however. - - Please see the description of the ANSI C function @c strftime(3) for - the syntax of the format string. - - The @a dateDef parameter is used to fill in the fields which could not - be determined from the format string. For example, if the format is - @c "%d" (the day of the month), the month and the year are taken from - @a dateDef. If it is not specified, Today() is used as the default - date. - - @return @NULL if the conversion failed, otherwise return the pointer - to the character which stopped the scan. - */ - const wchar_t* ParseFormat(const wchar_t* date, - const wxString& format = wxDefaultDateTimeFormat, - const wxDateTime& dateDef = wxDefaultDateTime); - - /** - This function parses the string containing the date and time in ISO - 8601 combined format @c "YYYY-MM-DDTHH:MM:SS". The separator between - the date and time parts must be equal to @a sep for the function to - succeed. - - @return @true if the entire string was parsed successfully, @false - otherwise. - */ - bool ParseISOCombined(const wxString& date, char sep = 'T'); - - /** - This function parses the date in ISO 8601 format @c "YYYY-MM-DD". - - @return @true if the entire string was parsed successfully, @false - otherwise. - */ - bool ParseISODate(const wxString& date); - - /** - This function parses the time in ISO 8601 format @c "HH:MM:SS". - - @return @true if the entire string was parsed successfully, @false - otherwise. - */ - bool ParseISOTime(const wxString& date); - - /** - Parses the string @a date looking for a date formatted according to the - RFC 822 in it. The exact description of this format may, of course, be - found in the RFC (section 5), but, briefly, this is the format used in - the headers of Internet email messages and one of the most common - strings expressing date in this format may be something like - @c "Sat, 18 Dec 1999 00:48:30 +0100". - - Returns @NULL if the conversion failed, otherwise return the pointer to - the character immediately following the part of the string which could - be parsed. If the entire string contains only the date in RFC 822 - format, the returned pointer will be pointing to a @c NUL character. - - This function is intentionally strict, it will return an error for any - string which is not RFC 822 compliant. If you need to parse date - formatted in more free ways, you should use ParseDateTime() or - ParseDate() instead. - */ - const char* ParseRfc822Date(const wxString& date, - wxString::const_iterator* end = NULL); - /** - Parses the string @a date looking for a date formatted according to the - RFC 822 in it. The exact description of this format may, of course, be - found in the RFC (section 5), but, briefly, this is the format used in - the headers of Internet email messages and one of the most common - strings expressing date in this format may be something like - @c "Sat, 18 Dec 1999 00:48:30 +0100". - - Returns @NULL if the conversion failed, otherwise return the pointer to - the character immediately following the part of the string which could - be parsed. If the entire string contains only the date in RFC 822 - format, the returned pointer will be pointing to a @c NUL character. - - This function is intentionally strict, it will return an error for any - string which is not RFC 822 compliant. If you need to parse date - formatted in more free ways, you should use ParseDateTime() or - ParseDate() instead. - */ - const char* ParseRfc822Date(const char* date); - /** - Parses the string @a date looking for a date formatted according to the - RFC 822 in it. The exact description of this format may, of course, be - found in the RFC (section 5), but, briefly, this is the format used in - the headers of Internet email messages and one of the most common - strings expressing date in this format may be something like - @c "Sat, 18 Dec 1999 00:48:30 +0100". - - Returns @NULL if the conversion failed, otherwise return the pointer to - the character immediately following the part of the string which could - be parsed. If the entire string contains only the date in RFC 822 - format, the returned pointer will be pointing to a @c NUL character. - - This function is intentionally strict, it will return an error for any - string which is not RFC 822 compliant. If you need to parse date - formatted in more free ways, you should use ParseDateTime() or - ParseDate() instead. - */ - const wchar_t* ParseRfc822Date(const wchar_t* date); - - /** - This functions is like ParseDateTime(), but only allows the time to be - specified in the input string. - - @return @NULL if the conversion failed, otherwise return the pointer - to the character which stopped the scan. - */ - const char* ParseTime(const wxString& time, - wxString::const_iterator* end = NULL); - /** - This functions is like ParseDateTime(), but only allows the time to be - specified in the input string. - - @return @NULL if the conversion failed, otherwise return the pointer - to the character which stopped the scan. - */ - const char* ParseTime(const char* time); - /** - This functions is like ParseDateTime(), but only allows the time to be - specified in the input string. - - @return @NULL if the conversion failed, otherwise return the pointer - to the character which stopped the scan. - */ - const wchar_t* ParseTime(const wchar_t* time); - - //@} - - - - /** - @name Calendar Calculations - - The functions in this section perform the basic calendar calculations, - mostly related to the week days. They allow to find the given week day - in the week with given number (either in the month or in the year) and - so on. - - None of the functions in this section modify the time part of the - wxDateTime, they only work with the date part of it. - */ - //@{ - - /** - Returns the copy of this object to which SetToLastMonthDay() was - applied. - */ - wxDateTime GetLastMonthDay(Month month = Inv_Month, - int year = Inv_Year) const; - - /** - Returns the copy of this object to which SetToLastWeekDay() was - applied. - */ - wxDateTime GetLastWeekDay(WeekDay weekday, Month month = Inv_Month, - int year = Inv_Year); - - /** - Returns the copy of this object to which SetToNextWeekDay() was - applied. - */ - wxDateTime GetNextWeekDay(WeekDay weekday) const; - - /** - Returns the copy of this object to which SetToPrevWeekDay() was - applied. - */ - wxDateTime GetPrevWeekDay(WeekDay weekday) const; - - /** - Returns the copy of this object to which SetToWeekDay() was applied. - */ - wxDateTime GetWeekDay(WeekDay weekday, int n = 1, Month month = Inv_Month, - int year = Inv_Year) const; - - /** - Returns the copy of this object to which SetToWeekDayInSameWeek() was - applied. - */ - wxDateTime GetWeekDayInSameWeek(WeekDay weekday, - WeekFlags flags = Monday_First) const; - - /** - Returns the copy of this object to which SetToYearDay() was applied. - */ - wxDateTime GetYearDay(wxDateTime_t yday) const; - - /** - Sets the date to the last day in the specified month (the current one - by default). - - @return The reference to the modified object itself. - */ - wxDateTime SetToLastMonthDay(Month month = Inv_Month, - int year = Inv_Year); - - /** - The effect of calling this function is the same as of calling - @c SetToWeekDay(-1, weekday, month, year). The date will be set to the - last @a weekday in the given month and year (the current ones by - default). Always returns @true. - */ - bool SetToLastWeekDay(WeekDay weekday, Month month = Inv_Month, - int year = Inv_Year); - - /** - Sets the date so that it will be the first @a weekday following the - current date. - - @return The reference to the modified object itself. - */ - wxDateTime& SetToNextWeekDay(WeekDay weekday); - - /** - Sets the date so that it will be the last @a weekday before the current - date. - - @return The reference to the modified object itself. - */ - wxDateTime& SetToPrevWeekDay(WeekDay weekday); - - /** - Sets the date to the @e n-th @a weekday in the given month of the given - year (the current month and year are used by default). The parameter - @a n may be either positive (counting from the beginning of the month) - or negative (counting from the end of it). - - For example, SetToWeekDay(2, wxDateTime::Wed) will set the date to the - second Wednesday in the current month and - SetToWeekDay(-1, wxDateTime::Sun) will set the date to the last Sunday - in the current month. - - @return @true if the date was modified successfully, @false otherwise - meaning that the specified date doesn't exist. - */ - bool SetToWeekDay(WeekDay weekday, int n = 1, - Month month = Inv_Month, int year = Inv_Year); - - /** - Adjusts the date so that it will still lie in the same week as before, - but its week day will be the given one. - - @return The reference to the modified object itself. - */ - wxDateTime SetToWeekDayInSameWeek(WeekDay weekday, - WeekFlags flags = Monday_First); - - /** - Sets the date to the day number @a yday in the same year (i.e., unlike - the other functions, this one does not use the current year). The day - number should be in the range 1-366 for the leap years and 1-365 for - the other ones. - - @return The reference to the modified object itself. - */ - wxDateTime& SetToYearDay(wxDateTime_t yday); - - //@} - - - - /** - @name Astronomical/Historical Functions - - Some degree of support for the date units used in astronomy and/or - history is provided. You can construct a wxDateTime object from a - JDN and you may also get its JDN, MJD or Rata Die number from it. - - Related functions in other groups: wxDateTime(double), Set(double) - */ - //@{ - - /** - Synonym for GetJulianDayNumber(). - */ - double GetJDN() const; - - /** - Returns the JDN corresponding to this date. Beware of rounding errors! - - @see GetModifiedJulianDayNumber() - */ - double GetJulianDayNumber() const; - - /** - Synonym for GetModifiedJulianDayNumber(). - */ - double GetMJD() const; - - /** - Returns the @e "Modified Julian Day Number" (MJD) which is, by - definition, is equal to JDN - 2400000.5. The MJDs are simpler to work - with as the integral MJDs correspond to midnights of the dates in the - Gregorian calendar and not the noons like JDN. The MJD 0 represents - Nov 17, 1858. - */ - double GetModifiedJulianDayNumber() const; - - /** - Return the @e Rata Die number of this date. - - By definition, the Rata Die number is a date specified as the number of - days relative to a base date of December 31 of the year 0. Thus January - 1 of the year 1 is Rata Die day 1. - */ - double GetRataDie() const; - - //@} - - - - /** - @name Time Zone and DST Support - - Please see the @ref overview_datetime_timezones "time zone overview" - for more information about time zones. Normally, these functions should - be rarely used. - - Related functions in other groups: GetBeginDST(), GetEndDST() - */ - //@{ - - /** - Transform the date from the given time zone to the local one. If - @a noDST is @true, no DST adjustments will be made. - - @return The date in the local time zone. - */ - wxDateTime FromTimezone(const TimeZone& tz, bool noDST = false) const; - - /** - Returns @true if the DST is applied for this date in the given country. - - @see GetBeginDST(), GetEndDST() - */ - int IsDST(Country country = Country_Default) const; - - /** - Same as FromTimezone() but modifies the object in place. - */ - wxDateTime MakeFromTimezone(const TimeZone& tz, bool noDST = false); - - /** - Modifies the object in place to represent the date in another time - zone. If @a noDST is @true, no DST adjustments will be made. - */ - wxDateTime MakeTimezone(const TimeZone& tz, bool noDST = false); - - /** - This is the same as calling MakeTimezone() with the argument @c GMT0. - */ - wxDateTime& MakeUTC(bool noDST = false); - - /** - Transform the date to the given time zone. If @a noDST is @true, no DST - adjustments will be made. - - @return The date in the new time zone. - */ - wxDateTime ToTimezone(const TimeZone& tz, bool noDST = false) const; - - /** - This is the same as calling ToTimezone() with the argument @c GMT0. - */ - wxDateTime ToUTC(bool noDST = false) const; - - //@} - - - - - - /** - Converts the year in absolute notation (i.e. a number which can be - negative, positive or zero) to the year in BC/AD notation. For the - positive years, nothing is done, but the year 0 is year 1 BC and so for - other years there is a difference of 1. - - This function should be used like this: - - @code - wxDateTime dt(...); - int y = dt.GetYear(); - printf("The year is %d%s", wxDateTime::ConvertYearToBC(y), y > 0 ? "AD" : "BC"); - @endcode - */ - static int ConvertYearToBC(int year); - - /** - Returns the translations of the strings @c AM and @c PM used for time - formatting for the current locale. Either of the pointers may be @NULL - if the corresponding value is not needed. - */ - static void GetAmPmStrings(wxString* am, wxString* pm); - - /** - Get the beginning of DST for the given country in the given year - (current one by default). This function suffers from limitations - described in the @ref overview_datetime_dst "DST overview". - - @see GetEndDST() - */ - static wxDateTime GetBeginDST(int year = Inv_Year, - Country country = Country_Default); - - /** - Returns the end of DST for the given country in the given year (current - one by default). - - @see GetBeginDST() - */ - static wxDateTime GetEndDST(int year = Inv_Year, - Country country = Country_Default); - - /** - Get the current century, i.e. first two digits of the year, in given - calendar (only Gregorian is currently supported). - */ - static int GetCentury(int year); - - /** - Returns the current default country. The default country is used for - DST calculations, for example. - - @see SetCountry() - */ - static Country GetCountry(); - - /** - Get the current month in given calendar (only Gregorian is currently - supported). - */ - static Month GetCurrentMonth(Calendar cal = Gregorian); - - /** - Get the current year in given calendar (only Gregorian is currently - supported). - */ - static int GetCurrentYear(Calendar cal = Gregorian); - - /** - Gets the full (default) or abbreviated (specify @c Name_Abbr name of - the given month. - - @see GetWeekDayName() - */ - static wxString GetMonthName(Month month, NameFlags flags = Name_Full); - - /** - Returns the number of days in the given year. The only supported value - for @a cal currently is @c Gregorian. - - @beginWxPythonOnly - This method is named "GetNumberOfDaysInYear" in wxPython. - @endWxPythonOnly - */ - static wxDateTime_t GetNumberOfDays(int year, Calendar cal = Gregorian); - - /** - Returns the number of days in the given month of the given year. The - only supported value for @a cal currently is @c Gregorian. - - @beginWxPythonOnly - This method is named "GetNumberOfDaysInMonth" in wxPython. - @endWxPythonOnly - */ - static wxDateTime_t GetNumberOfDays(Month month, int year = Inv_Year, - Calendar cal = Gregorian); - - /** - Returns the current time. - */ - static time_t GetTimeNow(); - - /** - Returns the current time broken down using the buffer whose adress is - passed to the function with @a tm to store the result. - */ - static struct tm* GetTmNow(struct tm *tm); - - /** - Returns the current time broken down. Note that this function returns a - pointer to a static buffer that's reused by calls to this function and - certain C library functions (e.g. localtime). If there is any chance - your code might be used in a multi-threaded application, you really - should use GetTmNow(struct tm *) instead. - */ - static struct tm* GetTmNow(); - - /** - Gets the full (default) or abbreviated (specify @c Name_Abbr) name of - the given week day. - - @see GetMonthName() - */ - static wxString GetWeekDayName(WeekDay weekday, - NameFlags flags = Name_Full); - - /** - Returns @true if DST was used n the given year (the current one by - default) in the given country. - */ - static bool IsDSTApplicable(int year = Inv_Year, - Country country = Country_Default); - - /** - Returns @true if the @a year is a leap one in the specified calendar. - This functions supports Gregorian and Julian calendars. - */ - static bool IsLeapYear(int year = Inv_Year, Calendar cal = Gregorian); - - /** - This function returns @true if the specified (or default) country is - one of Western European ones. It is used internally by wxDateTime to - determine the DST convention and date and time formatting rules. - */ - static bool IsWestEuropeanCountry(Country country = Country_Default); - - /** - Returns the object corresponding to the current time. - - Example: - - @code - wxDateTime now = wxDateTime::Now(); - printf("Current time in Paris:\t%s\n", now.Format("%c", wxDateTime::CET).c_str()); - @endcode - - @note This function is accurate up to seconds. UNow() should be used - for better precision, but it is less efficient and might not be - available on all platforms. - - @see Today() - */ - static wxDateTime Now(); - - /** - Sets the country to use by default. This setting influences the DST - calculations, date formatting and other things. - - The possible values for @a country parameter are enumerated in the - @ref datetime_constants section. - - @see GetCountry() - */ - static void SetCountry(Country country); - - /** - Set the date to the given @a weekday in the week number @a numWeek of - the given @a year . The number should be in range 1-53. - - Note that the returned date may be in a different year than the one - passed to this function because both the week 1 and week 52 or 53 (for - leap years) contain days from different years. See GetWeekOfYear() for - the explanation of how the year weeks are counted. - */ - static wxDateTime SetToWeekOfYear(int year, wxDateTime_t numWeek, - WeekDay weekday = Mon); - - /** - Returns the object corresponding to the midnight of the current day - (i.e. the same as Now(), but the time part is set to 0). - - @see Now() - */ - static wxDateTime Today(); - - /** - Returns the object corresponding to the current time including the - milliseconds if a function to get time with such precision is available - on the current platform (supported under most Unices and Win32). - - @see Now() - */ - static wxDateTime UNow(); -}; - -/** - Global instance of an empty wxDateTime object. - - @todo Would it be better to rename this wxNullDateTime so it's consistent - with the rest of the "empty/invalid/null" global objects? -*/ -const wxDateTime wxDefaultDateTime; - - - -/** - @class wxDateTimeWorkDays - @wxheader{datetime.h} - - @todo Write wxDateTimeWorkDays documentation. - - @library{wxbase} - @category{data} -*/ -class wxDateTimeWorkDays -{ -public: - -}; - - - -/** - @class wxDateSpan - @wxheader{datetime.h} - - This class is a "logical time span" and is useful for implementing program - logic for such things as "add one month to the date" which, in general, - doesn't mean to add 60*60*24*31 seconds to it, but to take the same date - the next month (to understand that this is indeed different consider adding - one month to Feb, 15 -- we want to get Mar, 15, of course). - - When adding a month to the date, all lesser components (days, hours, ...) - won't be changed unless the resulting date would be invalid: for example, - Jan 31 + 1 month will be Feb 28, not (non-existing) Feb 31. - - Because of this feature, adding and subtracting back again the same - wxDateSpan will @b not, in general, give back the original date: Feb 28 - 1 - month will be Jan 28, not Jan 31! - - wxDateSpan objects can be either positive or negative. They may be - multiplied by scalars which multiply all deltas by the scalar: i.e. - 2*(1 month and 1 day) is 2 months and 2 days. They can be added together - with wxDateTime or wxTimeSpan, but the type of result is different for each - case. - - @warning If you specify both weeks and days, the total number of days added - will be 7*weeks + days! See also GetTotalDays(). - - Equality operators are defined for wxDateSpans. Two wxDateSpans are equal - if and only if they both give the same target date when added to @b every - source date. Thus wxDateSpan::Months(1) is not equal to - wxDateSpan::Days(30), because they don't give the same date when added to - Feb 1st. But wxDateSpan::Days(14) is equal to wxDateSpan::Weeks(2). - - Finally, notice that for adding hours, minutes and so on you don't need - this class at all: wxTimeSpan will do the job because there are no - subtleties associated with those (we don't support leap seconds). - - @library{wxbase} - @category{data} - - @see @ref overview_datetime, wxDateTime -*/ -class wxDateSpan -{ -public: - /** - Constructs the date span object for the given number of years, months, - weeks and days. Note that the weeks and days add together if both are - given. - */ - wxDateSpan(int years = 0, int months = 0, int weeks = 0, int days = 0); - - /** - Returns the sum of two date spans. - - @return A new wxDateSpan object with the result. - */ - wxDateSpan Add(const wxDateSpan& other) const; - /** - Adds the given wxDateSpan to this wxDateSpan and returns a reference - to itself. - */ - wxDateSpan& Add(const wxDateSpan& other); - - /** - Returns a date span object corresponding to one day. - - @see Days() - */ - static wxDateSpan Day(); - - /** - Returns a date span object corresponding to the given number of days. - - @see Day() - */ - static wxDateSpan Days(int days); - - /** - Returns the number of days (not counting the weeks component) in this - date span. - - @see GetTotalDays() - */ - int GetDays() const; - - /** - Returns the number of the months (not counting the years) in this date - span. - */ - int GetMonths() const; - - /** - Returns the combined number of days in this date span, counting both - weeks and days. This doesn't take months or years into account. - - @see GetWeeks(), GetDays() - */ - int GetTotalDays() const; - - /** - Returns the number of weeks in this date span. - - @see GetTotalDays() - */ - int GetWeeks() const; - - /** - Returns the number of years in this date span. - */ - int GetYears() const; - - /** - Returns a date span object corresponding to one month. - - @see Months() - */ - static wxDateSpan Month(); - - /** - Returns a date span object corresponding to the given number of months. - - @see Month() - */ - static wxDateSpan Months(int mon); - - /** - Returns the product of the date span by the specified @a factor. The - product is computed by multiplying each of the components by the - @a factor. - - @return A new wxDateSpan object with the result. - */ - wxDateSpan Multiply(int factor) const; - /** - Multiplies this date span by the specified @a factor. The product is - computed by multiplying each of the components by the @a factor. - - @return A reference to this wxDateSpan object modified in place. - */ - wxDateSpan& Multiply(int factor); - - /** - Changes the sign of this date span. - - @see Negate() - */ - wxDateSpan& Neg(); - - /** - Returns a date span with the opposite sign. - - @see Neg() - */ - wxDateSpan Negate() const; - - /** - Sets the number of days (without modifying any other components) in - this date span. - */ - wxDateSpan& SetDays(int n); - - /** - Sets the number of months (without modifying any other components) in - this date span. - */ - wxDateSpan& SetMonths(int n); - - /** - Sets the number of weeks (without modifying any other components) in - this date span. - */ - wxDateSpan& SetWeeks(int n); - - /** - Sets the number of years (without modifying any other components) in - this date span. - */ - wxDateSpan& SetYears(int n); - - /** - Returns the difference of two date spans. - - @return A new wxDateSpan object with the result. - */ - wxDateSpan Subtract(const wxDateSpan& other) const; - /** - Subtracts the given wxDateSpan to this wxDateSpan and returns a - reference to itself. - */ - wxDateSpan& Subtract(const wxDateSpan& other); - - /** - Returns a date span object corresponding to one week. - - @see Weeks() - */ - static wxDateSpan Week(); - - /** - Returns a date span object corresponding to the given number of weeks. - - @see Week() - */ - static wxDateSpan Weeks(int weeks); - - /** - Returns a date span object corresponding to one year. - - @see Years() - */ - static wxDateSpan Year(); - - /** - Returns a date span object corresponding to the given number of years. - - @see Year() - */ - static wxDateSpan Years(int years); - - /** - Adds the given wxDateSpan to this wxDateSpan and returns the result. - */ - wxDateSpan& operator+=(const wxDateSpan& other); - - /** - Subtracts the given wxDateSpan to this wxDateSpan and returns the - result. - */ - wxDateSpan& operator-=(const wxDateSpan& other); - - /** - Changes the sign of this date span. - - @see Negate() - */ - wxDateSpan& operator-(); - - /** - Multiplies this date span by the specified @a factor. The product is - computed by multiplying each of the components by the @a factor. - - @return A reference to this wxDateSpan object modified in place. - */ - wxDateSpan& operator*=(int factor); - - /** - Returns @true if this date span is different from the other one. - */ - bool operator!=(const wxDateSpan&) const; - - /** - Returns @true if this date span is equal to the other one. Two date - spans are considered equal if and only if they have the same number of - years and months and the same total number of days (counting both days - and weeks). - */ - bool operator==(const wxDateSpan&) const; -}; - - - -/** - @class wxTimeSpan - @wxheader{datetime.h} - - wxTimeSpan class represents a time interval. - - @library{wxbase} - @category{data} - - @see @ref overview_datetime, wxDateTime -*/ -class wxTimeSpan -{ -public: - /** - Default constructor, constructs a zero timespan. - */ - wxTimeSpan(); - /** - Constructs timespan from separate values for each component, with the - date set to 0. Hours are not restricted to 0-24 range, neither are - minutes, seconds or milliseconds. - */ - wxTimeSpan(long hours, long min, long sec, long msec); - - /** - Returns the absolute value of the timespan: does not modify the object. - */ - wxTimeSpan Abs() const; - - /** - Returns the sum of two time spans. - - @return A new wxDateSpan object with the result. - */ - wxTimeSpan Add(const wxTimeSpan& diff) const; - /** - Adds the given wxTimeSpan to this wxTimeSpan and returns a reference - to itself. - */ - wxTimeSpan& Add(const wxTimeSpan& diff); - - /** - Returns the timespan for one day. - */ - static wxTimespan Day(); - - /** - Returns the timespan for the given number of days. - */ - static wxTimespan Days(long days); - - /** - Returns the string containing the formatted representation of the time - span. The following format specifiers are allowed after %: - - - @c H - Number of Hours - - @c M - Number of Minutes - - @c S - Number of Seconds - - @c l - Number of Milliseconds - - @c D - Number of Days - - @c E - Number of Weeks - - @c % - The percent character - - Note that, for example, the number of hours in the description above is - not well defined: it can be either the total number of hours (for - example, for a time span of 50 hours this would be 50) or just the hour - part of the time span, which would be 2 in this case as 50 hours is - equal to 2 days and 2 hours. - - wxTimeSpan resolves this ambiguity in the following way: if there had - been, indeed, the @c %D format specified preceding the @c %H, then it - is interpreted as 2. Otherwise, it is 50. - - The same applies to all other format specifiers: if they follow a - specifier of larger unit, only the rest part is taken, otherwise the - full value is used. - */ - wxString Format(const wxString& = wxDefaultTimeSpanFormat) const; - - /** - Returns the difference in number of days. - */ - int GetDays() const; - - /** - Returns the difference in number of hours. - */ - int GetHours() const; - - /** - Returns the difference in number of milliseconds. - */ - wxLongLong GetMilliseconds() const; - - /** - Returns the difference in number of minutes. - */ - int GetMinutes() const; - - /** - Returns the difference in number of seconds. - */ - wxLongLong GetSeconds() const; - - /** - Returns the internal representation of timespan. - */ - wxLongLong GetValue() const; - - /** - Returns the difference in number of weeks. - */ - int GetWeeks() const; - - /** - Returns the timespan for one hour. - */ - static wxTimespan Hour(); - - /** - Returns the timespan for the given number of hours. - */ - static wxTimespan Hours(long hours); - - /** - Returns @true if two timespans are equal. - */ - bool IsEqualTo(const wxTimeSpan& ts) const; - - /** - Compares two timespans: works with the absolute values, i.e. -2 hours - is longer than 1 hour. Also, it will return @false if the timespans are - equal in absolute value. - */ - bool IsLongerThan(const wxTimeSpan& ts) const; - - /** - Returns @true if the timespan is negative. - */ - bool IsNegative() const; - - /** - Returns @true if the timespan is empty. - */ - bool IsNull() const; - - /** - Returns @true if the timespan is positive. - */ - bool IsPositive() const; - - /** - Compares two timespans: works with the absolute values, i.e. 1 hour is - shorter than -2 hours. Also, it will return @false if the timespans are - equal in absolute value. - */ - bool IsShorterThan(const wxTimeSpan& ts) const; - - /** - Returns the timespan for one millisecond. - */ - static wxTimespan Millisecond(); - - /** - Returns the timespan for the given number of milliseconds. - */ - static wxTimespan Milliseconds(long ms); - - /** - Returns the timespan for one minute. - */ - static wxTimespan Minute(); - - /** - Returns the timespan for the given number of minutes. - */ - static wxTimespan Minutes(long min); - - /** - Returns the product of this time span by @a n. - - @return A new wxTimeSpan object with the result. - */ - wxTimeSpan Multiply(int n) const; - /** - Multiplies this time span by @a n. - - @return A reference to this wxTimeSpan object modified in place. - */ - wxTimeSpan& Multiply(int n); - - /** - Negate the value of the timespan. - - @see Negate() - */ - wxTimeSpan& Neg(); - - /** - Returns timespan with inverted sign. - - @see Neg() - */ - wxTimeSpan Negate() const; - - /** - Returns the timespan for one second. - */ - static wxTimespan Second(); - - /** - Returns the timespan for the given number of seconds. - */ - static wxTimespan Seconds(long sec); - - /** - Returns the difference of two time spans. - - @return A new wxDateSpan object with the result. - */ - wxTimeSpan Subtract(const wxTimeSpan& diff) const; - /** - Subtracts the given wxTimeSpan to this wxTimeSpan and returns a - reference to itself. - */ - wxTimeSpan& Subtract(const wxTimeSpan& diff); - - /** - Returns the timespan for one week. - */ - static wxTimespan Week(); - - /** - Returns the timespan for the given number of weeks. - */ - static wxTimespan Weeks(long weeks); - - /** - Adds the given wxTimeSpan to this wxTimeSpan and returns the result. - */ - wxTimeSpan& operator+=(const wxTimeSpan& diff); - - /** - Multiplies this time span by @a n. - - @return A reference to this wxTimeSpan object modified in place. - */ - wxTimeSpan& operator*=(int n); - - /** - Negate the value of the timespan. - - @see Negate() - */ - wxTimeSpan& operator-(); - - /** - Subtracts the given wxTimeSpan to this wxTimeSpan and returns the - result. - */ - wxTimeSpan& operator-=(const wxTimeSpan& diff); -}; - - - -/** - @class wxDateTimeHolidayAuthority - @wxheader{datetime.h} - - @todo Write wxDateTimeHolidayAuthority documentation. - - @library{wxbase} - @category{misc} -*/ -class wxDateTimeHolidayAuthority -{ -public: - -}; - diff --git a/interface/datstrm.h b/interface/datstrm.h deleted file mode 100644 index 3a0629dba9..0000000000 --- a/interface/datstrm.h +++ /dev/null @@ -1,280 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: datstrm.h -// Purpose: interface of wxDataInputStream and wxDataOutputStream -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxDataOutputStream - @wxheader{datstrm.h} - - This class provides functions that write binary data types in a portable - way. Data can be written in either big-endian or little-endian format, - little-endian being the default on all architectures. - - If you want to write data to text files (or streams) use wxTextOutputStream - instead. - - The "<<" operator is overloaded and you can use this class like a standard - C++ iostream. See wxDataInputStream for its usage and caveats. - - @library{wxbase} - @category{streams} - - @see wxDataInputStream -*/ -class wxDataOutputStream -{ -public: - /** - Constructs a datastream object from an output stream. Only write - methods will be available. - - @param stream - The output stream. - */ - wxDataOutputStream(wxOutputStream& stream); - /** - Constructs a datastream object from an output stream. Only write - methods will be available. This constructor is only available in - Unicode builds of wxWidgets. - - @param stream - The output stream. - @param conv - Charset conversion object object used to encoding Unicode strings - before writing them to the stream in Unicode mode (see - WriteString() for a detailed description). Note that you must not - destroy @a conv before you destroy this wxDataOutputStream - instance! It is recommended to use the default value (UTF-8). - */ - wxDataOutputStream(wxOutputStream& stream, - const wxMBConv& conv = wxConvAuto()); - - /** - Destroys the wxDataOutputStream object. - */ - ~wxDataOutputStream(); - - /** - If @a be_order is @true, all data will be written in big-endian order, - e.g. for reading on a Sparc or from Java-Streams (which always use - big-endian order), otherwise data will be written in little-endian - order. - */ - void BigEndianOrdered(bool be_order); - - /** - Writes the single byte @a i8 to the stream. - */ - void Write8(wxUint8 i8); - /** - Writes an array of bytes to the stream. The amount of bytes to write is - specified with the @a size variable. - */ - void Write8(const wxUint8* buffer, size_t size); - - /** - Writes the 16 bit unsigned integer @a i16 to the stream. - */ - void Write16(wxUint16 i16); - /** - Writes an array of 16 bit unsigned integer to the stream. The amount of - 16 bit unsigned integer to write is specified with the @a size variable. - */ - void Write16(const wxUint16* buffer, size_t size); - - /** - Writes the 32 bit unsigned integer @a i32 to the stream. - */ - void Write32(wxUint32 i32); - /** - Writes an array of 32 bit unsigned integer to the stream. The amount of - 32 bit unsigned integer to write is specified with the @a size variable. - */ - void Write32(const wxUint32* buffer, size_t size); - - /** - Writes the 64 bit unsigned integer @a i64 to the stream. - */ - void Write64(wxUint64 i64); - /** - Writes an array of 64 bit unsigned integer to the stream. The amount of - 64 bit unsigned integer to write is specified with the @a size variable. - */ - void Write64(const wxUint64* buffer, size_t size); - - /** - Writes the double @a f to the stream using the IEEE format. - */ - void WriteDouble(double f); - /** - Writes an array of double to the stream. The amount of double to write is - specified with the @a size variable. - */ - void WriteDouble(const double* buffer, size_t size); - - /** - Writes @a string to the stream. Actually, this method writes the size - of the string before writing @a string itself. - - In ANSI build of wxWidgets, the string is written to the stream in - exactly same way it is represented in memory. In Unicode build, - however, the string is first converted to multibyte representation with - @e conv object passed to stream's constructor (consequently, ANSI - applications can read data written by Unicode application, as long as - they agree on encoding) and this representation is written to the - stream. UTF-8 is used by default. - */ - void WriteString(const wxString& string); -}; - - - -/** - @class wxDataInputStream - @wxheader{datstrm.h} - - This class provides functions that read binary data types in a portable - way. Data can be read in either big-endian or little-endian format, - little-endian being the default on all architectures. - - If you want to read data from text files (or streams) use wxTextInputStream - instead. - - The ">>" operator is overloaded and you can use this class like a standard - C++ iostream. Note, however, that the arguments are the fixed size types - wxUint32, wxInt32 etc and on a typical 32-bit computer, none of these match - to the "long" type (wxInt32 is defined as signed int on 32-bit - architectures) so that you cannot use long. To avoid problems (here and - elsewhere), make use of the wxInt32, wxUint32, etc types. - - For example: - - @code - wxFileInputStream input( "mytext.dat" ); - wxDataInputStream store( input ); - wxUint8 i1; - float f2; - wxString line; - - store >> i1; // read a 8 bit integer. - store >> i1 >> f2; // read a 8 bit integer followed by float. - store >> line; // read a text line - @endcode - - @library{wxbase} - @category{streams} - - @see wxDataOutputStream -*/ -class wxDataInputStream -{ -public: - /** - Constructs a datastream object from an input stream. Only read methods - will be available. - - @param stream - The input stream. - */ - wxDataInputStream(wxInputStream& stream); - /** - Constructs a datastream object from an input stream. Only read methods - will be available. This constructor is only available in Unicode builds - of wxWidgets. - - @param stream - The input stream. - @param conv - Charset conversion object object used to decode strings in Unicode - mode (see ReadString() for a detailed description). Note that you - must not destroy @a conv before you destroy this wxDataInputStream - instance! - */ - wxDataInputStream(wxInputStream& stream, - const wxMBConv& conv = wxConvAuto()); - - /** - Destroys the wxDataInputStream object. - */ - ~wxDataInputStream(); - - /** - If @a be_order is @true, all data will be read in big-endian order, - such as written by programs on a big endian architecture (e.g. Sparc) - or written by Java-Streams (which always use big-endian order). - */ - void BigEndianOrdered(bool be_order); - - /** - Reads a single byte from the stream. - */ - wxUint8 Read8(); - /** - Reads bytes from the stream in a specified buffer. The amount of bytes - to read is specified by the @a size variable. - */ - void Read8(wxUint8* buffer, size_t size); - - /** - Reads a 16 bit unsigned integer from the stream. - */ - wxUint16 Read16(); - /** - Reads 16 bit unsigned integers from the stream in a specified buffer. - The amount of 16 bit unsigned integers to read is specified by the - @a size variable. - */ - void Read16(wxUint16* buffer, size_t size); - - /** - Reads a 32 bit unsigned integer from the stream. - */ - wxUint32 Read32(); - /** - Reads 32 bit unsigned integers from the stream in a specified buffer. - The amount of 32 bit unsigned integers to read is specified by the - @a size variable. - */ - void Read32(wxUint32* buffer, size_t size); - - /** - Reads a 64 bit unsigned integer from the stream. - */ - wxUint64 Read64(); - /** - Reads 64 bit unsigned integers from the stream in a specified buffer. - The amount of 64 bit unsigned integers to read is specified by the - @a size variable. - */ - void Read64(wxUint64* buffer, size_t size); - - /** - Reads a double (IEEE encoded) from the stream. - */ - double ReadDouble(); - /** - Reads double data (IEEE encoded) from the stream in a specified buffer. - The amount of doubles to read is specified by the @a size variable. - */ - void ReadDouble(double* buffer, size_t size); - - /** - Reads a string from a stream. Actually, this function first reads a - long integer specifying the length of the string (without the last null - character) and then reads the string. - - In Unicode build of wxWidgets, the fuction first reads multibyte - (char*) string from the stream and then converts it to Unicode using - the @e conv object passed to constructor and returns the result as - wxString. You are responsible for using the same convertor as when - writing the stream. - - @see wxDataOutputStream::WriteString() - */ - wxString ReadString(); -}; - diff --git a/interface/dc.h b/interface/dc.h deleted file mode 100644 index 107cc06058..0000000000 --- a/interface/dc.h +++ /dev/null @@ -1,1145 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: dc.h -// Purpose: interface of wxDC -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxDC - @wxheader{dc.h} - - A wxDC is a @e "device context" onto which graphics and text can be drawn. - It is intended to represent different output devices and offers a common - abstract API for drawing on any of them. - - wxWidgets offers an alternative drawing API based on the modern drawing - backends GDI+, CoreGraphics and Cairo. See wxGraphicsContext, wxGraphicsRenderer - and related classes. There is also a wxGCDC linking the APIs by offering - the wxDC API ontop of a wxGraphicsContext. - - wxDC is an abstract base class and cannot be created directly. - Use wxPaintDC, wxClientDC, wxWindowDC, wxScreenDC, wxMemoryDC or - wxPrinterDC. Notice that device contexts which are associated with windows - (i.e. wxClientDC, wxWindowDC and wxPaintDC) use the window font and colours - by default (starting with wxWidgets 2.9.0) but the other device context - classes use system-default values so you always must set the appropriate - fonts and colours before using them. - - In addition to the versions of the methods documented below, there - are also versions which accept single wxPoint parameter instead - of the two wxCoord ones or wxPoint and wxSize instead of the four - wxCoord parameters. - - Beginning with wxWidgets 2.9.0 the entire wxDC code has been - reorganized. All platform dependent code (actually all drawing code) - has been moved into backend classes which derive from a common - wxDCImpl class. The user-visible classes such as wxClientDC and - wxPaintDC merely forward all calls to the backend implementation. - - On Mac OS X colours with alpha channel are supported. Instances wxPen - or wxBrush that are built from wxColour use the colour's alpha values - when stroking or filling. - - @library{wxcore} - @category{dc,gdi} - - @see @ref overview_dc, wxGraphicsContext - - @todo Precise definition of default/initial state. - @todo Pixelwise definition of operations (e.g. last point of a line not - drawn). - @todo Coordinates: state clearly which type of coordinates are returned by - the various Get*Point() or similar functions - often they are client - coordinates but not always. -*/ -class wxDC : public wxObject -{ -public: - /** - Copy from a source DC to this DC, specifying the destination - coordinates, size of area to copy, source DC, source coordinates, - logical function, whether to use a bitmap mask, and mask source - position. - - @param xdest - Destination device context x position. - @param ydest - Destination device context y position. - @param width - Width of source area to be copied. - @param height - Height of source area to be copied. - @param source - Source device context. - @param xsrc - Source device context x position. - @param ysrc - Source device context y position. - @param logicalFunc - Logical function to use, see SetLogicalFunction(). - @param useMask - If @true, Blit does a transparent blit using the mask that is - associated with the bitmap selected into the source device context. - The Windows implementation does the following if MaskBlt cannot be - used: -
    -
  1. Creates a temporary bitmap and copies the destination area into - it.
    2. -
  2. Copies the source area into the temporary bitmap using the - specified logical function.
    3. -
  3. Sets the masked area in the temporary bitmap to BLACK by ANDing - the mask bitmap with the temp bitmap with the foreground colour - set to WHITE and the bg colour set to BLACK.
    4. -
  4. Sets the unmasked area in the destination area to BLACK by - ANDing the mask bitmap with the destination area with the - foreground colour set to BLACK and the background colour set to - WHITE.
    5. -
  5. ORs the temporary bitmap with the destination area.
    6. -
  6. Deletes the temporary bitmap.
    7. -
- This sequence of operations ensures that the source's transparent - area need not be black, and logical functions are supported. - @n @b Note: on Windows, blitting with masks can be speeded up - considerably by compiling wxWidgets with the wxUSE_DC_CACHE option - enabled. You can also influence whether MaskBlt or the explicit - mask blitting code above is used, by using wxSystemOptions and - setting the @c no-maskblt option to 1. - @param xsrcMask - Source x position on the mask. If both xsrcMask and ysrcMask are - -1, xsrc and ysrc will be assumed for the mask source position. - Currently only implemented on Windows. - @param ysrcMask - Source y position on the mask. If both xsrcMask and ysrcMask are - -1, xsrc and ysrc will be assumed for the mask source position. - Currently only implemented on Windows. - - @remarks There is partial support for Blit() in wxPostScriptDC, under X. - - @see StretchBlit(), wxMemoryDC, wxBitmap, wxMask - */ - bool Blit(wxCoord xdest, wxCoord ydest, wxCoord width, - wxCoord height, wxDC* source, wxCoord xsrc, wxCoord ysrc, - int logicalFunc = wxCOPY, bool useMask = false, - wxCoord xsrcMask = -1, wxCoord ysrcMask = -1); - - /** - Adds the specified point to the bounding box which can be retrieved - with MinX(), MaxX() and MinY(), MaxY() functions. - - @see ResetBoundingBox() - */ - void CalcBoundingBox(wxCoord x, wxCoord y); - - /** - Clears the device context using the current background brush. - */ - void Clear(); - - /** - Performs all necessary computations for given platform and context type - after each change of scale and origin parameters. Usually called - automatically internally after such changes. - */ - virtual void ComputeScaleAndOrigin(); - - /** - Displays a cross hair using the current pen. This is a vertical and - horizontal line the height and width of the window, centred on the - given point. - */ - void CrossHair(wxCoord x, wxCoord y); - - /** - Destroys the current clipping region so that none of the DC is clipped. - - @see SetClippingRegion() - */ - void DestroyClippingRegion(); - - /** - Convert device X coordinate to logical coordinate, using the current - mapping mode. - */ - virtual wxCoord DeviceToLogicalX(wxCoord x); - - /** - Convert device X coordinate to relative logical coordinate, using the - current mapping mode but ignoring the x axis orientation. Use this - function for converting a width, for example. - */ - virtual wxCoord DeviceToLogicalXRel(wxCoord x); - - /** - Converts device Y coordinate to logical coordinate, using the current - mapping mode. - */ - virtual wxCoord DeviceToLogicalY(wxCoord y); - - /** - Convert device Y coordinate to relative logical coordinate, using the - current mapping mode but ignoring the y axis orientation. Use this - function for converting a height, for example. - */ - virtual wxCoord DeviceToLogicalYRel(wxCoord y); - - /** - Draws an arc of a circle, centred on (@a xc, @a yc), with starting - point (@a x1, @a y1) and ending at (@a x2, @a y2). The current pen is - used for the outline and the current brush for filling the shape. - - The arc is drawn in a counter-clockwise direction from the start point - to the end point. - */ - void DrawArc(wxCoord x1, wxCoord y1, wxCoord x2, wxCoord y2, - wxCoord xc, wxCoord yc); - - /** - Draw a bitmap on the device context at the specified point. If - @a transparent is @true and the bitmap has a transparency mask, the - bitmap will be drawn transparently. - - When drawing a mono-bitmap, the current text foreground colour will be - used to draw the foreground of the bitmap (all bits set to 1), and the - current text background colour to draw the background (all bits set to - 0). - - @see SetTextForeground(), SetTextBackground(), wxMemoryDC - */ - void DrawBitmap(const wxBitmap& bitmap, wxCoord x, wxCoord y, - bool transparent); - - //@{ - /** - Draws a check mark inside the given rectangle. - */ - void DrawCheckMark(wxCoord x, wxCoord y, wxCoord width, wxCoord height); - void DrawCheckMark(const wxRect& rect); - //@} - - //@{ - /** - Draws a circle with the given centre and radius. - - @see DrawEllipse() - */ - void DrawCircle(wxCoord x, wxCoord y, wxCoord radius); - void DrawCircle(const wxPoint& pt, wxCoord radius); - //@} - - //@{ - /** - Draws an ellipse contained in the rectangle specified either with the - given top left corner and the given size or directly. The current pen - is used for the outline and the current brush for filling the shape. - - @see DrawCircle() - */ - void DrawEllipse(wxCoord x, wxCoord y, wxCoord width, wxCoord height); - void DrawEllipse(const wxPoint& pt, const wxSize& size); - void DrawEllipse(const wxRect& rect); - //@} - - /** - Draws an arc of an ellipse. The current pen is used for drawing the arc - and the current brush is used for drawing the pie. - - @a x and @a y specify the x and y coordinates of the upper-left corner - of the rectangle that contains the ellipse. - - @a width and @a height specify the width and height of the rectangle - that contains the ellipse. - - @a start and @a end specify the start and end of the arc relative to - the three-o'clock position from the center of the rectangle. Angles are - specified in degrees (360 is a complete circle). Positive values mean - counter-clockwise motion. If @a start is equal to @e end, a complete - ellipse will be drawn. - */ - void DrawEllipticArc(wxCoord x, wxCoord y, wxCoord width, wxCoord height, - double start, double end); - - /** - Draw an icon on the display (does nothing if the device context is - PostScript). This can be the simplest way of drawing bitmaps on a - window. - */ - void DrawIcon(const wxIcon& icon, wxCoord x, wxCoord y); - - //@{ - /** - Draw optional bitmap and the text into the given rectangle and aligns - it as specified by alignment parameter; it also will emphasize the - character with the given index if it is != -1 and return the bounding - rectangle if required. - */ - virtual void DrawLabel(const wxString& text, const wxBitmap& image, - const wxRect& rect, - int alignment = wxALIGN_LEFT | wxALIGN_TOP, - int indexAccel = -1, wxRect* rectBounding = NULL); - void DrawLabel(const wxString& text, const wxRect& rect, - int alignment = wxALIGN_LEFT | wxALIGN_TOP, - int indexAccel = -1); - //@} - - /** - Draws a line from the first point to the second. The current pen is - used for drawing the line. Note that the point (@a x2, @a y2) is not - part of the line and is not drawn by this function (this is consistent - with the behaviour of many other toolkits). - */ - void DrawLine(wxCoord x1, wxCoord y1, wxCoord x2, wxCoord y2); - - /** - Draws lines using an array of points of size @a n adding the optional - offset coordinate. The current pen is used for drawing the lines. - - @beginWxPythonOnly - The wxPython version of this method accepts a Python list of wxPoint - objects. - @endWxPythonOnly - */ - void DrawLines(int n, wxPoint points[], wxCoord xoffset = 0, - wxCoord yoffset = 0); - /** - This method uses a list of wxPoints, adding the optional offset - coordinate. The programmer is responsible for deleting the list of - points. - - @beginWxPythonOnly - The wxPython version of this method accepts a Python list of wxPoint - objects. - @endWxPythonOnly - */ - void DrawLines(const wxPointList* points, - wxCoord xoffset = 0, wxCoord yoffset = 0); - - /** - Draws a point using the color of the current pen. Note that the other - properties of the pen are not used, such as width. - */ - void DrawPoint(wxCoord x, wxCoord y); - - /** - Draws a filled polygon using an array of points of size @a n, adding - the optional offset coordinate. The first and last points are - automatically closed. - - The last argument specifies the fill rule: @b wxODDEVEN_RULE (the - default) or @b wxWINDING_RULE. - - The current pen is used for drawing the outline, and the current brush - for filling the shape. Using a transparent brush suppresses filling. - */ - void DrawPolygon(int n, wxPoint points[], wxCoord xoffset = 0, - wxCoord yoffset = 0, int fill_style = wxODDEVEN_RULE); - /** - This method draws a filled polygon using a list of wxPoints, adding the - optional offset coordinate. The first and last points are automatically - closed. - - The last argument specifies the fill rule: @b wxODDEVEN_RULE (the - default) or @b wxWINDING_RULE. - - The current pen is used for drawing the outline, and the current brush - for filling the shape. Using a transparent brush suppresses filling. - - The programmer is responsible for deleting the list of points. - - @beginWxPythonOnly - The wxPython version of this method accepts a Python list of wxPoint - objects. - @endWxPythonOnly - */ - void DrawPolygon(const wxPointList* points, - wxCoord xoffset = 0, wxCoord yoffset = 0, - int fill_style = wxODDEVEN_RULE); - - /** - Draws two or more filled polygons using an array of @a points, adding - the optional offset coordinates. - - Notice that for the platforms providing a native implementation of this - function (Windows and PostScript-based wxDC currently), this is more - efficient than using DrawPolygon() in a loop. - - @a n specifies the number of polygons to draw, the array @e count of - size @a n specifies the number of points in each of the polygons in the - @a points array. - - The last argument specifies the fill rule: @b wxODDEVEN_RULE (the - default) or @b wxWINDING_RULE. - - The current pen is used for drawing the outline, and the current brush - for filling the shape. Using a transparent brush suppresses filling. - - The polygons maybe disjoint or overlapping. Each polygon specified in a - call to DrawPolyPolygon() must be closed. Unlike polygons created by - the DrawPolygon() member function, the polygons created by this - method are not closed automatically. - - @beginWxPythonOnly - Not implemented yet. - @endWxPythonOnly - */ - void DrawPolyPolygon(int n, int count[], wxPoint points[], - wxCoord xoffset = 0, wxCoord yoffset = 0, - int fill_style = wxODDEVEN_RULE); - - /** - Draws a rectangle with the given top left corner, and with the given - size. The current pen is used for the outline and the current brush - for filling the shape. - */ - void DrawRectangle(wxCoord x, wxCoord y, wxCoord width, wxCoord height); - - /** - Draws the text rotated by @a angle degrees. - - @note Under Win9x only TrueType fonts can be drawn by this function. In - particular, a font different from @c wxNORMAL_FONT should be used - as the latter is not a TrueType font. @c wxSWISS_FONT is an - example of a font which is. - - @see DrawText() - */ - void DrawRotatedText(const wxString& text, wxCoord x, wxCoord y, - double angle); - - /** - Draws a rectangle with the given top left corner, and with the given - size. The corners are quarter-circles using the given radius. The - current pen is used for the outline and the current brush for filling - the shape. - - If @a radius is positive, the value is assumed to be the radius of the - rounded corner. If @a radius is negative, the absolute value is assumed - to be the @e proportion of the smallest dimension of the rectangle. - This means that the corner can be a sensible size relative to the size - of the rectangle, and also avoids the strange effects X produces when - the corners are too big for the rectangle. - */ - void DrawRoundedRectangle(wxCoord x, wxCoord y, wxCoord width, - wxCoord height, double radius); - - //@{ - /** - Draws a spline between all given points using the current pen. - - @beginWxPythonOnly - The wxPython version of this method accepts a Python list of wxPoint - objects. - @endWxPythonOnly - */ - void DrawSpline(int n, wxPoint points[]); - void DrawSpline(const wxPointList* points); - void DrawSpline(wxCoord x1, wxCoord y1, wxCoord x2, wxCoord y2, - wxCoord x3, wxCoord y3); - //@} - - /** - Draws a text string at the specified point, using the current text - font, and the current text foreground and background colours. - - The coordinates refer to the top-left corner of the rectangle bounding - the string. See GetTextExtent() for how to get the dimensions of a text - string, which can be used to position the text more precisely. - - @note Under wxGTK, the current - @ref GetLogicalFunction() "logical function" is used by this - function but it is ignored by wxMSW. Thus, you should avoid using - logical functions with this function in portable programs. - */ - void DrawText(const wxString& text, wxCoord x, wxCoord y); - - /** - Ends a document (only relevant when outputting to a printer). - */ - void EndDoc(); - - /** - Ends a document page (only relevant when outputting to a printer). - */ - void EndPage(); - - /** - Flood fills the device context starting from the given point, using - the current brush colour, and using a style: - - - wxFLOOD_SURFACE: The flooding occurs until a colour other than the - given colour is encountered. - - wxFLOOD_BORDER: The area to be flooded is bounded by the given - colour. - - @return @false if the operation failed. - - @note The present implementation for non-Windows platforms may fail to - find colour borders if the pixels do not match the colour - exactly. However the function will still return @true. - */ - bool FloodFill(wxCoord x, wxCoord y, const wxColour& colour, - int style = wxFLOOD_SURFACE); - - /** - Gets the brush used for painting the background. - - @see wxDC::SetBackground() - */ - const wxBrush GetBackground() const; - - /** - Returns the current background mode: @c wxSOLID or @c wxTRANSPARENT. - - @see SetBackgroundMode() - */ - int GetBackgroundMode() const; - - /** - Gets the current brush. - - @see wxDC::SetBrush() - */ - const wxBrush GetBrush() const; - - /** - Gets the character height of the currently set font. - */ - wxCoord GetCharHeight(); - - /** - Gets the average character width of the currently set font. - */ - wxCoord GetCharWidth(); - - /** - Gets the rectangle surrounding the current clipping region. - - @beginWxPythonOnly - No arguments are required and the four values defining the rectangle - are returned as a tuple. - @endWxPythonOnly - */ - void GetClippingBox(wxCoord x, wxCoord y, wxCoord width, wxCoord height); - - /** - Returns the depth (number of bits/pixel) of this DC. - - @see wxDisplayDepth() - */ - int GetDepth() const; - - /** - Gets the current font. Notice that even although each device context - object has some default font after creation, this method would return a - wxNullFont initially and only after calling SetFont() a valid font is - returned. - */ - const wxFont GetFont() const; - - /** - Gets the current layout direction of the device context. On platforms - where RTL layout is supported, the return value will either be - @c wxLayout_LeftToRight or @c wxLayout_RightToLeft. If RTL layout is - not supported, the return value will be @c wxLayout_Default. - - @see SetLayoutDirection() - */ - wxLayoutDirection GetLayoutDirection() const; - - /** - Gets the current logical function. - - @see SetLogicalFunction() - */ - int GetLogicalFunction(); - - /** - Gets the mapping mode for the device context. - - @see SetMapMode() - */ - int GetMapMode(); - - /** - Gets the dimensions of the string using the currently selected font. - @a string is the text string to measure, @e heightLine, if non @NULL, - is where to store the height of a single line. - - The text extent is set in the given @a w and @a h pointers. - - If the optional parameter @a font is specified and valid, then it is - used for the text extent calculation, otherwise the currently selected - font is used. - - @note This function works with both single-line and multi-line strings. - - @see wxFont, SetFont(), GetPartialTextExtents(), GetTextExtent() - */ - void GetMultiLineTextExtent(const wxString& string, wxCoord* w, - wxCoord* h, - wxCoord* heightLine = NULL, - wxFont* font = NULL) const; - /** - Gets the dimensions of the string using the currently selected font. - @a string is the text string to measure, @e heightLine, if non @NULL, - is where to store the height of a single line. - - @return The text extent as a wxSize object. - - @note This function works with both single-line and multi-line strings. - - @see wxFont, SetFont(), GetPartialTextExtents(), GetTextExtent() - */ - const wxSize GetMultiLineTextExtent(const wxString& string) const; - - /** - Fills the @a widths array with the widths from the beginning of @a text - to the corresponding character of @a text. The generic version simply - builds a running total of the widths of each character using - GetTextExtent(), however if the various platforms have a native API - function that is faster or more accurate than the generic - implementation then it should be used instead. - - @beginWxPythonOnly - This method only takes the @a text parameter and returns a Python list - of integers. - @endWxPythonOnly - - @see GetMultiLineTextExtent(), GetTextExtent() - */ - bool GetPartialTextExtents(const wxString& text, - wxArrayInt& widths) const; - - /** - Gets the current pen. - - @see SetPen() - */ - const wxPen GetPen() const; - - /** - Gets in @a colour the colour at the specified location. Not available - for wxPostScriptDC or wxMetafileDC. - - @note Setting a pixel can be done using DrawPoint(). - - @beginWxPythonOnly - The wxColour value is returned and is not required as a parameter. - @endWxPythonOnly - */ - bool GetPixel(wxCoord x, wxCoord y, wxColour* colour); - - /** - Returns the resolution of the device in pixels per inch. - */ - wxSize GetPPI() const; - - //@{ - /** - This gets the horizontal and vertical resolution in device units. It - can be used to scale graphics to fit the page. - - For example, if @e maxX and @e maxY represent the maximum horizontal - and vertical 'pixel' values used in your application, the following - code will scale the graphic to fit on the printer page: - - @code - wxCoord w, h; - dc.GetSize(&w, &h); - double scaleX = (double)(maxX / w); - double scaleY = (double)(maxY / h); - dc.SetUserScale(min(scaleX, scaleY),min(scaleX, scaleY)); - @endcode - - @beginWxPythonOnly - In place of a single overloaded method name, wxPython implements the - following methods: - - GetSize() - Returns a wxSize. - - GetSizeWH() - Returns a 2-tuple (width, height). - @endWxPythonOnly - */ - void GetSize(wxCoord* width, wxCoord* height) const; - const wxSize GetSize() const; - //@} - - //@{ - /** - Returns the horizontal and vertical resolution in millimetres. - */ - void GetSizeMM(wxCoord* width, wxCoord* height) const; - const wxSize GetSizeMM() const; - //@} - - /** - Gets the current text background colour. - - @see SetTextBackground() - */ - const wxColour GetTextBackground() const; - - //@{ - /** - Gets the dimensions of the string using the currently selected font. - @a string is the text string to measure, @a descent is the dimension - from the baseline of the font to the bottom of the descender, and - @a externalLeading is any extra vertical space added to the font by the - font designer (usually is zero). - - The text extent is returned in @a w and @a h pointers or as a wxSize - object depending on which version of this function is used. - - If the optional parameter @a font is specified and valid, then it is - used for the text extent calculation. Otherwise the currently selected - font is. - - @note This function only works with single-line strings. - - @beginWxPythonOnly - The following methods are implemented in wxPython: - - GetTextExtent(string) - Returns a 2-tuple, (width, height). - - GetFullTextExtent(string, font=NULL) - - Returns a 4-tuple, (width, height, descent, externalLeading). - @endWxPythonOnly - - @see wxFont, SetFont(), GetPartialTextExtents(), - GetMultiLineTextExtent() - */ - void GetTextExtent(const wxString& string, wxCoord* w, wxCoord* h, - wxCoord* descent = NULL, - wxCoord* externalLeading = NULL, - const wxFont* font = NULL) const; - const wxSize GetTextExtent(const wxString& string) const; - //@} - - /** - Gets the current text foreground colour. - - @see SetTextForeground() - */ - const wxColour GetTextForeground() const; - - /** - Gets the current user scale factor. - - @see SetUserScale() - */ - void GetUserScale(double x, double y); - - //@{ - /** - Fill the area specified by rect with a radial gradient, starting from - @a initialColour at the centre of the circle and fading to - @a destColour on the circle outside. - - @a circleCenter are the relative coordinates of centre of the circle in - the specified @e rect. If not specified, the circle is placed at the - centre of rect. - - @note Currently this function is very slow, don't use it for real-time - drawing. - */ - void GradientFillConcentric(const wxRect& rect, - const wxColour& initialColour, - const wxColour& destColour); - void GradientFillConcentric(const wxRect& rect, - const wxColour& initialColour, - const wxColour& destColour, - const wxPoint& circleCenter); - //@} - - /** - Fill the area specified by @a rect with a linear gradient, starting - from @a initialColour and eventually fading to @e destColour. The - @a nDirection specifies the direction of the colour change, default is - to use @a initialColour on the left part of the rectangle and - @a destColour on the right one. - */ - void GradientFillLinear(const wxRect& rect, - const wxColour& initialColour, - const wxColour& destColour, - wxDirection nDirection = wxEAST); - - /** - Returns @true if the DC is ok to use. - */ - bool Ok(); - - /** - Converts logical X coordinate to device coordinate, using the current - mapping mode. - */ - virtual wxCoord LogicalToDeviceX(wxCoord x); - - /** - Converts logical X coordinate to relative device coordinate, using the - current mapping mode but ignoring the x axis orientation. Use this for - converting a width, for example. - */ - virtual wxCoord LogicalToDeviceXRel(wxCoord x); - - /** - Converts logical Y coordinate to device coordinate, using the current - mapping mode. - */ - virtual wxCoord LogicalToDeviceY(wxCoord y); - - /** - Converts logical Y coordinate to relative device coordinate, using the - current mapping mode but ignoring the y axis orientation. Use this for - converting a height, for example. - */ - virtual wxCoord LogicalToDeviceYRel(wxCoord y); - - /** - Gets the maximum horizontal extent used in drawing commands so far. - */ - wxCoord MaxX(); - - /** - Gets the maximum vertical extent used in drawing commands so far. - */ - wxCoord MaxY(); - - /** - Gets the minimum horizontal extent used in drawing commands so far. - */ - wxCoord MinX(); - - /** - Gets the minimum vertical extent used in drawing commands so far. - */ - wxCoord MinY(); - - /** - Resets the bounding box: after a call to this function, the bounding - box doesn't contain anything. - - @see CalcBoundingBox() - */ - void ResetBoundingBox(); - - /** - Sets the x and y axis orientation (i.e., the direction from lowest to - highest values on the axis). The default orientation is x axis from - left to right and y axis from top down. - - @param xLeftRight - True to set the x axis orientation to the natural left to right - orientation, @false to invert it. - @param yBottomUp - True to set the y axis orientation to the natural bottom up - orientation, @false to invert it. - */ - void SetAxisOrientation(bool xLeftRight, bool yBottomUp); - - /** - Sets the current background brush for the DC. - */ - void SetBackground(const wxBrush& brush); - - /** - @a mode may be one of wxSOLID and wxTRANSPARENT. This setting - determines whether text will be drawn with a background colour or not. - */ - void SetBackgroundMode(int mode); - - /** - Sets the current brush for the DC. - - If the argument is wxNullBrush, the current brush is selected out of - the device context (leaving wxDC without any valid brush), allowing the - current brush to be destroyed safely. - - @see wxBrush, wxMemoryDC (for the interpretation of colours when - drawing into a monochrome bitmap) - */ - void SetBrush(const wxBrush& brush); - - //@{ - /** - Sets the clipping region for this device context to the intersection of - the given region described by the parameters of this method and the - previously set clipping region. You should call DestroyClippingRegion() - if you want to set the clipping region exactly to the region specified. - - The clipping region is an area to which drawing is restricted. Possible - uses for the clipping region are for clipping text or for speeding up - window redraws when only a known area of the screen is damaged. - - @see DestroyClippingRegion(), wxRegion - */ - void SetClippingRegion(wxCoord x, wxCoord y, wxCoord width, - wxCoord height); - void SetClippingRegion(const wxPoint& pt, const wxSize& sz); - void SetClippingRegion(const wxRect& rect); - //@} - - /** - Sets the clipping region for this device context. - - Unlike SetClippingRegion(), this function works with physical - coordinates and not with the logical ones. - */ - void SetDeviceClippingRegion(const wxRegion& region); - - /** - Sets the device origin (i.e., the origin in pixels after scaling has - been applied). This function may be useful in Windows printing - operations for placing a graphic on a page. - */ - void SetDeviceOrigin(wxCoord x, wxCoord y); - - /** - Sets the current font for the DC. It must be a valid font, in - particular you should not pass wxNullFont to this method. - - @see wxFont - */ - void SetFont(const wxFont& font); - - /** - Sets the current layout direction for the device context. @a dir may be - either @c wxLayout_Default, @c wxLayout_LeftToRight or - @c wxLayout_RightToLeft. - - @see GetLayoutDirection() - */ - void SetLayoutDirection(wxLayoutDirection dir); - - /** - Sets the current logical function for the device context. This - determines how a source pixel (from a pen or brush colour, or source - device context if using Blit()) combines with a destination pixel in - the current device context. - - The possible values and their meaning in terms of source and - destination pixel values are as follows: - - @verbatim - wxAND src AND dst - wxAND_INVERT (NOT src) AND dst - wxAND_REVERSE src AND (NOT dst) - wxCLEAR 0 - wxCOPY src - wxEQUIV (NOT src) XOR dst - wxINVERT NOT dst - wxNAND (NOT src) OR (NOT dst) - wxNOR (NOT src) AND (NOT dst) - wxNO_OP dst - wxOR src OR dst - wxOR_INVERT (NOT src) OR dst - wxOR_REVERSE src OR (NOT dst) - wxSET 1 - wxSRC_INVERT NOT src - wxXOR src XOR dst - @endverbatim - - The default is wxCOPY, which simply draws with the current colour. The - others combine the current colour and the background using a logical - operation. wxINVERT is commonly used for drawing rubber bands or moving - outlines, since drawing twice reverts to the original colour. - */ - void SetLogicalFunction(int function); - - /** - The mapping mode of the device context defines the unit of measurement - used to convert logical units to device units. Note that in X, text - drawing isn't handled consistently with the mapping mode; a font is - always specified in point size. However, setting the user scale (see - SetUserScale()) scales the text appropriately. In Windows, scalable - TrueType fonts are always used; in X, results depend on availability of - fonts, but usually a reasonable match is found. - - The coordinate origin is always at the top left of the screen/printer. - - Drawing to a Windows printer device context uses the current mapping - mode, but mapping mode is currently ignored for PostScript output. - - The mapping mode can be one of the following: - - wxMM_TWIPS: Each logical unit is 1/20 of a point, or 1/1440 of an - inch. - - wxMM_POINTS: Each logical unit is a point, or 1/72 of an inch. - - wxMM_METRIC: Each logical unit is 1 mm. - - wxMM_LOMETRIC: Each logical unit is 1/10 of a mm. - - wxMM_TEXT: Each logical unit is 1 device pixel. - */ - void SetMapMode(int mode); - - /** - If this is a window DC or memory DC, assigns the given palette to the - window or bitmap associated with the DC. If the argument is - wxNullPalette, the current palette is selected out of the device - context, and the original palette restored. - - @see wxPalette - */ - void SetPalette(const wxPalette& palette); - - /** - Sets the current pen for the DC. If the argument is wxNullPen, the - current pen is selected out of the device context (leaving wxDC without - any valid pen), allowing the current brush to be destroyed safely. - - @see wxMemoryDC for the interpretation of colours when drawing into a - monochrome bitmap. - */ - void SetPen(const wxPen& pen); - - /** - Sets the current text background colour for the DC. - */ - void SetTextBackground(const wxColour& colour); - - /** - Sets the current text foreground colour for the DC. - - @see wxMemoryDC for the interpretation of colours when drawing into a - monochrome bitmap. - */ - void SetTextForeground(const wxColour& colour); - - /** - Sets the user scaling factor, useful for applications which require - 'zooming'. - */ - void SetUserScale(double xScale, double yScale); - - /** - Starts a document (only relevant when outputting to a printer). - @a message is a message to show while printing. - */ - bool StartDoc(const wxString& message); - - /** - Starts a document page (only relevant when outputting to a printer). - */ - bool StartPage(); - - /** - Copy from a source DC to this DC, specifying the destination - coordinates, destination size, source DC, source coordinates, size of - source area to copy, logical function, whether to use a bitmap mask, - and mask source position. - - @param xdest - Destination device context x position. - @param ydest - Destination device context y position. - @param dstWidth - Width of destination area. - @param dstHeight - Height of destination area. - @param source - Source device context. - @param xsrc - Source device context x position. - @param ysrc - Source device context y position. - @param srcWidth - Width of source area to be copied. - @param srcHeight - Height of source area to be copied. - @param logicalFunc - Logical function to use, see SetLogicalFunction(). - @param useMask - If @true, Blit does a transparent blit using the mask that is - associated with the bitmap selected into the source device context. - The Windows implementation does the following if MaskBlt cannot be - used: -
    -
  1. Creates a temporary bitmap and copies the destination area into - it.
    2. -
  2. Copies the source area into the temporary bitmap using the - specified logical function.
    3. -
  3. Sets the masked area in the temporary bitmap to BLACK by ANDing - the mask bitmap with the temp bitmap with the foreground colour - set to WHITE and the bg colour set to BLACK.
    4. -
  4. Sets the unmasked area in the destination area to BLACK by - ANDing the mask bitmap with the destination area with the - foreground colour set to BLACK and the background colour set to - WHITE.
    5. -
  5. ORs the temporary bitmap with the destination area.
    6. -
  6. Deletes the temporary bitmap.
    7. -
- This sequence of operations ensures that the source's transparent - area need not be black, and logical functions are supported. - @n @b Note: on Windows, blitting with masks can be speeded up - considerably by compiling wxWidgets with the wxUSE_DC_CACHE option - enabled. You can also influence whether MaskBlt or the explicit - mask blitting code above is used, by using wxSystemOptions and - setting the @c no-maskblt option to 1. - @param xsrcMask - Source x position on the mask. If both xsrcMask and ysrcMask are - -1, xsrc and ysrc will be assumed for the mask source position. - Currently only implemented on Windows. - @param ysrcMask - Source y position on the mask. If both xsrcMask and ysrcMask are - -1, xsrc and ysrc will be assumed for the mask source position. - Currently only implemented on Windows. - - There is partial support for Blit() in wxPostScriptDC, under X. - - StretchBlit() is only implemented under wxMAC and wxMSW. - - See wxMemoryDC for typical usage. - - @since 2.9.0 - - @see Blit(), wxMemoryDC, wxBitmap, wxMask - */ - bool StretchBlit(wxCoord xdest, wxCoord ydest, - wxCoord dstWidth, wxCoord dstHeight, - wxDC* source, wxCoord xsrc, wxCoord ysrc, - wxCoord srcWidth, wxCoord srcHeight, - int logicalFunc = wxCOPY, - bool useMask = false, - wxCoord xsrcMask = -1, wxCoord ysrcMask = -1); -}; - - - -/** - @class wxDCClipper - @wxheader{dc.h} - - wxDCClipper is a small helper class for setting a clipping region on a wxDC - and unsetting it automatically. An object of wxDCClipper class is typically - created on the stack so that it is automatically destroyed when the object - goes out of scope. A typical usage example: - - @code - void MyFunction(wxDC& dc) - { - wxDCClipper clip(dc, rect); - // ... drawing functions here are affected by clipping rect ... - } - - void OtherFunction() - { - wxDC dc; - MyFunction(dc); - // ... drawing functions here are not affected by clipping rect ... - } - @endcode - - @library{wxcore} - @category{gdi} - - @see wxDC::SetClippingRegion() -*/ -class wxDCClipper -{ -public: - //@{ - /** - Sets the clipping region to the specified region/coordinates. - - The clipping region is automatically unset when this object is destroyed. - */ - wxDCClipper(wxDC& dc, const wxRegion& r); - wxDCClipper(wxDC& dc, const wxRect& rect); - wxDCClipper(wxDC& dc, int x, int y, int w, int h); - //@} -}; - diff --git a/interface/dcbuffer.h b/interface/dcbuffer.h deleted file mode 100644 index 569ccdba03..0000000000 --- a/interface/dcbuffer.h +++ /dev/null @@ -1,180 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: dcbuffer.h -// Purpose: interface of wxBufferedDC -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxBufferedDC - @wxheader{dcbuffer.h} - - This class provides a simple way to avoid flicker: when drawing on it, - everything is in fact first drawn on an in-memory buffer (a wxBitmap) and - then copied to the screen, using the associated wxDC, only once, when this - object is destroyed. wxBufferedDC itself is typically associated with - wxClientDC, if you want to use it in your @c EVT_PAINT handler, you should - look at wxBufferedPaintDC instead. - - When used like this, a valid @e DC must be specified in the constructor - while the @e buffer bitmap doesn't have to be explicitly provided, by - default this class will allocate the bitmap of required size itself. - However using a dedicated bitmap can speed up the redrawing process by - eliminating the repeated creation and destruction of a possibly big bitmap. - Otherwise, wxBufferedDC can be used in the same way as any other device - context. - - There is another possible use for wxBufferedDC is to use it to maintain a - backing store for the window contents. In this case, the associated @e DC - may be @NULL but a valid backing store bitmap should be specified. - - Finally, please note that GTK+ 2.0 as well as OS X provide double buffering - themselves natively. You can either use wxWindow::IsDoubleBuffered() to - determine whether you need to use buffering or not, or use - wxAutoBufferedPaintDC to avoid needless double buffering on the systems - which already do it automatically. - - @library{wxcore} - @category{dc} - - @see wxDC, wxMemoryDC, wxBufferedPaintDC, wxAutoBufferedPaintDC -*/ -class wxBufferedDC : public wxMemoryDC -{ -public: - /** - Default constructor. You must call one of the Init() methods later in - order to use the device context. - */ - wxBufferedDC(); - - //@{ - /** - Creates a buffer for the provided @dc. Init() must not be called when - using this constructor. - - @param dc - The underlying DC: everything drawn to this object will be flushed - to this DC when this object is destroyed. You may pass @NULL in - order to just initialize the buffer, and not flush it. - @param area - The size of the bitmap to be used for buffering (this bitmap is - created internally when it is not given explicitly). - @param buffer - Explicitly provided bitmap to be used for buffering: this is the - most efficient solution as the bitmap doesn't have to be recreated - each time but it also requires more memory as the bitmap is never - freed. The bitmap should have appropriate size, anything drawn - outside of its bounds is clipped. - @param style - wxBUFFER_CLIENT_AREA to indicate that just the client area of the - window is buffered, or wxBUFFER_VIRTUAL_AREA to indicate that the - buffer bitmap covers the virtual area. - */ - wxBufferedDC(wxDC* dc, const wxSize& area, - int style = wxBUFFER_CLIENT_AREA); - wxBufferedDC(wxDC* dc, wxBitmap& buffer, - int style = wxBUFFER_CLIENT_AREA); - //@} - - /** - Copies everything drawn on the DC so far to the underlying DC - associated with this object, if any. - */ - ~wxBufferedDC(); - - //@{ - /** - Initializes the object created using the default constructor. Please - see the constructors for parameter details. - */ - void Init(wxDC* dc, const wxSize& area, - int style = wxBUFFER_CLIENT_AREA); - void Init(wxDC* dc, wxBitmap& buffer, - int style = wxBUFFER_CLIENT_AREA); - //@} -}; - - - -/** - @class wxAutoBufferedPaintDC - @wxheader{dcbuffer.h} - - This wxDC derivative can be used inside of an @c EVT_PAINT() event handler - to achieve double-buffered drawing. Just use this class instead of - wxPaintDC and make sure wxWindow::SetBackgroundStyle() is called with - wxBG_STYLE_CUSTOM somewhere in the class initialization code, and that's - all you have to do to (mostly) avoid flicker. - - The difference between wxBufferedPaintDC and this class is that this class - won't double-buffer on platforms which have native double-buffering - already, avoiding any unneccessary buffering to avoid flicker. - - wxAutoBufferedPaintDC is simply a typedef of wxPaintDC on platforms that - have native double-buffering, otherwise, it is a typedef of - wxBufferedPaintDC. - - @library{wxbase} - @category{dc} - - @see wxDC, wxBufferedPaintDC, wxPaintDC -*/ -class wxAutoBufferedPaintDC : public wxBufferedPaintDC -{ -public: - /** - Constructor. Pass a pointer to the window on which you wish to paint. - */ - wxAutoBufferedPaintDC(wxWindow* window); -}; - - - -/** - @class wxBufferedPaintDC - @wxheader{dcbuffer.h} - - This is a subclass of wxBufferedDC which can be used inside of an - @c EVT_PAINT() event handler to achieve double-buffered drawing. Just use - this class instead of wxPaintDC and make sure - wxWindow::SetBackgroundStyle() is called with wxBG_STYLE_CUSTOM somewhere - in the class initialization code, and that's all you have to do to (mostly) - avoid flicker. The only thing to watch out for is that if you are using - this class together with wxScrolled, you probably do @b not want to call - wxScrolled::PrepareDC() on it as it already does this internally for the - real underlying wxPaintDC. - - @library{wxcore} - @category{dc} - - @see wxDC, wxBufferedDC, wxAutoBufferedPaintDC, wxPaintDC -*/ -class wxBufferedPaintDC : public wxBufferedDC -{ -public: - //@{ - /** - As with wxBufferedDC, you may either provide the bitmap to be used for - buffering or let this object create one internally (in the latter case, - the size of the client part of the window is used). - - Pass wxBUFFER_CLIENT_AREA for the @a style parameter to indicate that - just the client area of the window is buffered, or - wxBUFFER_VIRTUAL_AREA to indicate that the buffer bitmap covers the - virtual area. - */ - wxBufferedPaintDC(wxWindow* window, wxBitmap& buffer, - int style = wxBUFFER_CLIENT_AREA); - wxBufferedPaintDC(wxWindow* window, - int style = wxBUFFER_CLIENT_AREA); - //@} - - /** - Copies everything drawn on the DC so far to the window associated with - this object, using a wxPaintDC. - */ - ~wxBufferedPaintDC(); -}; - diff --git a/interface/dcclient.h b/interface/dcclient.h deleted file mode 100644 index 17f39ca1a8..0000000000 --- a/interface/dcclient.h +++ /dev/null @@ -1,112 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: dcclient.h -// Purpose: interface of wxClientDC and wxPaintDC -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxPaintDC - @wxheader{dcclient.h} - - A wxPaintDC must be constructed if an application wishes to paint on the - client area of a window from within an EVT_PAINT() event handler. This - should normally be constructed as a temporary stack object; don't store a - wxPaintDC object. If you have an EVT_PAINT() handler, you @e must create a - wxPaintDC object within it even if you don't actually use it. - - Using wxPaintDC within your EVT_PAINT() handler is important because it - automatically sets the clipping area to the damaged area of the window. - Attempts to draw outside this area do not appear. - - To draw on a window from outside your EVT_PAINT() handler, construct a - wxClientDC object. - - To draw on the whole window including decorations, construct a wxWindowDC - object (Windows only). - - A wxPaintDC object is initialized to use the same font and colours as the - window it is associated with. - - @library{wxcore} - @category{dc} - - @see wxDC, wxClientDC, wxMemoryDC, wxWindowDC, wxScreenDC -*/ -class wxPaintDC : public wxWindowDC -{ -public: - /** - Constructor. Pass a pointer to the window on which you wish to paint. - */ - wxPaintDC(wxWindow* window); -}; - - - -/** - @class wxClientDC - @wxheader{dcclient.h} - - A wxClientDC must be constructed if an application wishes to paint on the - client area of a window from outside an EVT_PAINT() handler. This should - normally be constructed as a temporary stack object; don't store a - wxClientDC object. - - To draw on a window from within an EVT_PAINT() handler, construct a - wxPaintDC object instead. - - To draw on the whole window including decorations, construct a wxWindowDC - object (Windows only). - - A wxClientDC object is initialized to use the same font and colours as the - window it is associated with. - - @library{wxcore} - @category{dc} - - @see wxDC, wxMemoryDC, wxPaintDC, wxWindowDC, wxScreenDC -*/ -class wxClientDC : public wxWindowDC -{ -public: - /** - Constructor. Pass a pointer to the window on which you wish to paint. - */ - wxClientDC(wxWindow* window); -}; - - - -/** - @class wxWindowDC - @wxheader{dcclient.h} - - A wxWindowDC must be constructed if an application wishes to paint on the - whole area of a window (client and decorations). This should normally be - constructed as a temporary stack object; don't store a wxWindowDC object. - - To draw on a window from inside an EVT_PAINT() handler, construct a - wxPaintDC object instead. - - To draw on the client area of a window from outside an EVT_PAINT() handler, - construct a wxClientDC object. - - A wxWindowDC object is initialized to use the same font and colours as the - window it is associated with. - - @library{wxcore} - @category{dc} - - @see wxDC, wxMemoryDC, wxPaintDC, wxClientDC, wxScreenDC -*/ -class wxWindowDC : public wxDC -{ -public: - /** - Constructor. Pass a pointer to the window on which you wish to paint. - */ - wxWindowDC(wxWindow* window); -}; - diff --git a/interface/dcgraph.h b/interface/dcgraph.h deleted file mode 100644 index e4d4459bfc..0000000000 --- a/interface/dcgraph.h +++ /dev/null @@ -1,44 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: dcgraph.h -// Purpose: interface of wxGCDC -// Author: wxWidgets team -// RCS-ID: $Id: $ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxGCDC - @wxheader{dcgraph.h} - - wxGCDC is a device context that draws on a wxGraphicsContext. - - @library{wxcore} - @category{dc} - - @see wxDC, wxGraphicsContext -*/ - -class wxGCDC: public wxDC -{ -public: - /** - Constructs a wxGCDC from a wxWindowDC. - */ - wxGCDC( const wxWindowDC& dc ); - - /** - Constructs a wxGCDC from a wxMemoryDC. - */ - wxGCDC( const wxMemoryDC& dc ); - - /** - Constructs a wxGCDC from a wxPrinterDC. - */ - wxGCDC( const wxPrinterDC& dc ); - - /** - Retrieves associated wxGraphicsContext - */ - wxGraphicsContext* GetGraphicsContext(); -}; - diff --git a/interface/dcmemory.h b/interface/dcmemory.h deleted file mode 100644 index e1e6a998eb..0000000000 --- a/interface/dcmemory.h +++ /dev/null @@ -1,99 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: dcmemory.h -// Purpose: interface of wxMemoryDC -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxMemoryDC - @wxheader{dcmemory.h} - - A memory device context provides a means to draw graphics onto a bitmap. - When drawing in to a mono-bitmap, using @c wxWHITE, @c wxWHITE_PEN and - @c wxWHITE_BRUSH will draw the background colour (i.e. 0) whereas all other - colours will draw the foreground colour (i.e. 1). - - A bitmap must be selected into the new memory DC before it may be used for - anything. Typical usage is as follows: - - @code - // Create a memory DC - wxMemoryDC temp_dc; - temp_dc.SelectObject(test_bitmap); - - // We can now draw into the memory DC... - // Copy from this DC to another DC. - old_dc.Blit(250, 50, BITMAP_WIDTH, BITMAP_HEIGHT, temp_dc, 0, 0); - @endcode - - Note that the memory DC must be deleted (or the bitmap selected out of it) - before a bitmap can be reselected into another memory DC. - - And, before performing any other operations on the bitmap data, the bitmap - must be selected out of the memory DC: - - @code - temp_dc.SelectObject(wxNullBitmap); - @endcode - - This happens automatically when wxMemoryDC object goes out of scope. - - @library{wxcore} - @category{dc} - - @see wxBitmap, wxDC -*/ -class wxMemoryDC : public wxDC -{ -public: - /** - Constructs a new memory device context. - - Use the wxDC::Ok() member to test whether the constructor was - successful in creating a usable device context. Don't forget to select - a bitmap into the DC before drawing on it. - */ - wxMemoryDC(); - /** - Constructs a new memory device context and calls SelectObject() with - the given bitmap. - - Use the wxDC::Ok() member to test whether the constructor was - successful in creating a usable device context. - */ - wxMemoryDC(wxBitmap& bitmap); - - /** - Works exactly like SelectObjectAsSource() but this is the function you - should use when you select a bitmap because you want to modify it, e.g. - drawing on this DC. - - Using SelectObjectAsSource() when modifying the bitmap may incurr some - problems related to wxBitmap being a reference counted object (see - @ref overview_refcount). - - Also, before using the updated bitmap data, make sure to select it out - of context first (for example by selecting wxNullBitmap into the device - context). - - @see wxDC::DrawBitmap() - */ - void SelectObject(wxBitmap& bitmap); - - /** - Selects the given bitmap into the device context, to use as the memory - bitmap. Selecting the bitmap into a memory DC allows you to draw into - the DC (and therefore the bitmap) and also to use wxDC::Blit() to copy - the bitmap to a window. For this purpose, you may find wxDC::DrawIcon() - easier to use instead. - - If the argument is wxNullBitmap (or some other uninitialised wxBitmap) - the current bitmap is selected out of the device context, and the - original bitmap restored, allowing the current bitmap to be destroyed - safely. - */ - void SelectObjectAsSource(const wxBitmap& bitmap); -}; - diff --git a/interface/dcmirror.h b/interface/dcmirror.h deleted file mode 100644 index d15af962f0..0000000000 --- a/interface/dcmirror.h +++ /dev/null @@ -1,37 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: dcmirror.h -// Purpose: interface of wxMirrorDC -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxMirrorDC - @wxheader{dcmirror.h} - - wxMirrorDC is a simple wrapper class which is always associated with a real - wxDC object and either forwards all of its operations to it without changes - (no mirroring takes place) or exchanges @e x and @e y coordinates which - makes it possible to reuse the same code to draw a figure and its mirror -- - i.e. reflection related to the diagonal line x == y. - - @since 2.5.0 - - @library{wxcore} - @category{dc} -*/ -class wxMirrorDC : public wxDC -{ -public: - /** - Creates a (maybe) mirrored DC associated with the real @a dc. - Everything drawn on wxMirrorDC will appear (and maybe mirrored) on - @a dc. - - @a mirror specifies if we do mirror (if it is @true) or not (if it is - @false). - */ - wxMirrorDC(wxDC& dc, bool mirror); -}; - diff --git a/interface/dcprint.h b/interface/dcprint.h deleted file mode 100644 index db6c74f0eb..0000000000 --- a/interface/dcprint.h +++ /dev/null @@ -1,60 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: dcprint.h -// Purpose: interface of wxPrinterDC -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxPrinterDC - @wxheader{dcprint.h} - - A printer device context is specific to MSW and Mac, and allows access to - any printer with a Windows or Macintosh driver. See wxDC for further - information on device contexts, and wxDC::GetSize() for advice on achieving - the correct scaling for the page. - - @library{wxcore} - @category{printing} - - @see @ref overview_printing, wxDC -*/ -class wxPrinterDC : public wxDC -{ -public: - /** - Constructor. Pass a wxPrintData object with information necessary for - setting up a suitable printer device context. This is the recommended - way to construct a wxPrinterDC. Make sure you specify a reference to a - wxPrintData object, not a pointer - you may not even get a warning if - you pass a pointer instead. - */ - wxPrinterDC(const wxPrintData& printData); - /** - Constructor. With empty strings for the first three arguments, the - default printer dialog is displayed. @a device indicates the type of - printer and @a output is an optional file for printing to. The - @a driver parameter is currently unused. Use the wxDC::Ok() member to - test whether the constructor was successful in creating a usable device - context. - - @deprecated This constructor is deprecated and retained only for - backward compatibility. - */ - wxPrinterDC(const wxString& driver, const wxString& device, - const wxString& output, const bool interactive = true, - int orientation = wxPORTRAIT); - - /** - Return the rectangle in device coordinates that corresponds to the full - paper area, including the nonprinting regions of the paper. The point - (0,0) in device coordinates is the top left corner of the page - rectangle, which is the printable area on MSW and Mac. The coordinates - of the top left corner of the paper rectangle will therefore have small - negative values, while the bottom right coordinates will be somewhat - larger than the values returned by wxDC::GetSize(). - */ - wxRect wxPrinterDC::GetPaperRect(); -}; - diff --git a/interface/dcps.h b/interface/dcps.h deleted file mode 100644 index 34630fb92f..0000000000 --- a/interface/dcps.h +++ /dev/null @@ -1,58 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: dcps.h -// Purpose: interface of wxPostScriptDC -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxPostScriptDC - @wxheader{dcps.h} - - This defines the wxWidgets Encapsulated PostScript device context, which - can write PostScript files on any platform. See wxDC for descriptions of - the member functions. - - @library{wxbase} - @category{dc} -*/ -class wxPostScriptDC : public wxDC -{ -public: - /** - Constructs a PostScript printer device context from a wxPrintData - object. - */ - wxPostScriptDC(const wxPrintData& printData); - /** - Constructor. @a output is an optional file for printing to, and if - @a interactive is @true a dialog box will be displayed for adjusting - various parameters. @a parent is the parent of the printer dialog box. - - Use the wxDC::Ok() member to test whether the constructor was - successful in creating a usable device context. - - See wxPrintData for various functions to set and get PostScript - printing settings. - - @deprecated This constructor is deprecated. - */ - wxPostScriptDC(const wxString& output, - bool interactive = true, - wxWindow* parent); - - /** - Return resolution used in PostScript output. - - @see SetResolution() - */ - static int GetResolution(); - - /** - Set resolution (in pixels per inch) that will be used in PostScript - output. Default is 720ppi. - */ - static void SetResolution(int ppi); -}; - diff --git a/interface/dcscreen.h b/interface/dcscreen.h deleted file mode 100644 index 80e4c9ec66..0000000000 --- a/interface/dcscreen.h +++ /dev/null @@ -1,83 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: dcscreen.h -// Purpose: interface of wxScreenDC -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxScreenDC - @wxheader{dcscreen.h} - - A wxScreenDC can be used to paint on the screen. This should normally be - constructed as a temporary stack object; don't store a wxScreenDC object. - - @library{wxcore} - @category{dc} - - @see wxDC, wxMemoryDC, wxPaintDC, wxClientDC, wxWindowDC -*/ -class wxScreenDC : public wxDC -{ -public: - /** - Constructor. - */ - wxScreenDC(); - - /** - Use this in conjunction with StartDrawingOnTop(). - - This function destroys the temporary window created to implement on-top - drawing (X only). - */ - bool EndDrawingOnTop(); - - /** - Use this in conjunction with EndDrawingOnTop() to ensure that drawing - to the screen occurs on top of existing windows. Without this, some - window systems (such as X) only allow drawing to take place underneath - other windows. - - This version of StartDrawingOnTop() is used to specify that the area - that will be drawn on coincides with the given window. It is - recommended that an area of the screen is specified with - StartDrawingOnTop(wxRect*) because with large regions, flickering - effects are noticeable when destroying the temporary transparent window - used to implement this feature. - - You might use this function when implementing a drag feature, for - example as in the wxSplitterWindow implementation. - - @remarks This function is probably obsolete since the X implementations - allow drawing directly on the screen now. However, the fact - that this function allows the screen to be refreshed - afterwards, may be useful to some applications. - */ - bool StartDrawingOnTop(wxWindow* window); - /** - Use this in conjunction with EndDrawingOnTop() to ensure that drawing - to the screen occurs on top of existing windows. Without this, some - window systems (such as X) only allow drawing to take place underneath - other windows. - - This version of StartDrawingOnTop() is used to specify an area of the - screen which is to be drawn on. If @NULL is passed, the whole screen is - available. It is recommended that an area of the screen is specified - with this function rather than with StartDrawingOnTop(wxWindow*), - because with large regions, flickering effects are noticeable when - destroying the temporary transparent window used to implement this - feature. - - You might use this function when implementing a drag feature, for - example as in the wxSplitterWindow implementation. - - @remarks This function is probably obsolete since the X implementations - allow drawing directly on the screen now. However, the fact - that this function allows the screen to be refreshed - afterwards, may be useful to some applications. - */ - bool StartDrawingOnTop(wxRect* rect = NULL); -}; - diff --git a/interface/dcsvg.h b/interface/dcsvg.h deleted file mode 100644 index bae993d5a3..0000000000 --- a/interface/dcsvg.h +++ /dev/null @@ -1,660 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: dcsvg.h -// Purpose: interface of wxSVGFileDC -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxSVGFileDC - @wxheader{dcsvg.h} - - A wxSVGFileDC is a device context onto which graphics and text can be - drawn, and the output produced as a vector file, in SVG format (see the W3C - SVG Specifications ). This - format can be read by a range of programs, including a Netscape plugin - (Adobe), full details are given in the SVG Implementation and Resource - Directory . Vector formats may often be smaller than - raster formats. - - The intention behind wxSVGFileDC is that it can be used to produce a file - corresponding to the screen display context, wxSVGFileDC, by passing the - wxSVGFileDC as a parameter instead of a wxSVGFileDC. Thus the wxSVGFileDC - is a write-only class. - - As the wxSVGFileDC is a vector format, raster operations like GetPixel() - are unlikely to be supported. However, the SVG specification allows for PNG - format raster files to be embedded in the SVG, and so bitmaps, icons and - blit operations in wxSVGFileDC are supported. - - A more substantial SVG library (for reading and writing) is available at - the wxArt2D website . - - @library{wxcore} - @category{dc} -*/ -class wxSVGFileDC : public wxDC -{ -public: - /** - Initializes a wxSVGFileDC with the given @a f filename with a default - size (340x240) at 72.0 dots per inch (a frequent screen resolution). - */ - wxSVGFileDC(wxString f); - /** - Initializes a wxSVGFileDC with the given @a f filename with the given - @a Width and @a Height at 72.0 dots per inch. - */ - wxSVGFileDC(wxString f, int Width, int Height); - /** - Initializes a wxSVGFileDC with the given @a f filename with the given - @a Width and @a Height at @a dpi resolution. - */ - wxSVGFileDC(wxString f, int Width, int Height, float dpi); - - /** - Destructor. - */ - ~wxSVGFileDC(); - - /** - Copies from a source DC to this DC, specifying the destination - coordinates, size of area to copy, source DC, source coordinates, - logical function, whether to use a bitmap mask, and mask source - position. - - @see wxDC::Blit() - */ - bool Blit(wxCoord xdest, wxCoord ydest, wxCoord width, wxCoord height, - wxSVGFileDC* source, wxCoord xsrc, wxCoord ysrc, - int logicalFunc = wxCOPY, bool useMask = FALSE, - wxCoord xsrcMask = -1, wxCoord ysrcMask = -1); - - /** - Adds the specified point to the bounding box which can be retrieved - with wxDC::MinX(), wxDC::MaxX() and wxDC::MinY(), wxDC::MaxY() - functions. - */ - void CalcBoundingBox(wxCoord x, wxCoord y); - - /** - This makes no sense in wxSVGFileDC and does nothing. - */ - void Clear(); - - /** - Not Implemented. - */ - void CrossHair(wxCoord x, wxCoord y); - - /** - Not Implemented. - */ - void DestroyClippingRegion(); - - /** - Convert device X coordinate to logical coordinate, using the current - mapping mode. - */ - wxCoord DeviceToLogicalX(wxCoord x); - - /** - Convert device X coordinate to relative logical coordinate, using the - current mapping mode but ignoring the x axis orientation. Use this - function for converting a width, for example. - */ - wxCoord DeviceToLogicalXRel(wxCoord x); - - /** - Converts device Y coordinate to logical coordinate, using the current - mapping mode. - */ - wxCoord DeviceToLogicalY(wxCoord y); - - /** - Convert device Y coordinate to relative logical coordinate, using the - current mapping mode but ignoring the y axis orientation. Use this - function for converting a height, for example. - */ - wxCoord DeviceToLogicalYRel(wxCoord y); - - /** - Draws an arc of a circle, centred on (@a xc, @a yc), with starting - point (@a x1, @a y1) and ending at (@a x2, @a y2). The current pen is - used for the outline and the current brush for filling the shape. - - The arc is drawn in a counter-clockwise direction from the start point - to the end point. - */ - void DrawArc(wxCoord x1, wxCoord y1, wxCoord x2, wxCoord y2, - wxCoord xc, wxCoord yc); - - /** - Draw a bitmap on the device context at the specified point. If - @a transparent is @true and the bitmap has a transparency mask, the - bitmap will be drawn transparently. - - When drawing a mono-bitmap, the current text foreground colour will be - used to draw the foreground of the bitmap (all bits set to 1), and the - current text background colour to draw the background (all bits set to - 0). - - @see wxDC::SetTextForeground(), wxDC::SetTextBackground(), wxMemoryDC - */ - void DrawBitmap(const wxBitmap& bitmap, wxCoord x, wxCoord y, - bool transparent); - - //@{ - /** - Draws a check mark inside the given rectangle. - */ - void DrawCheckMark(wxCoord x, wxCoord y, wxCoord width, wxCoord height); - void DrawCheckMark(const wxRect& rect); - //@} - - //@{ - /** - Draws a circle with the given centre and radius. - - @see wxDC::DrawEllipse() - */ - void DrawCircle(wxCoord x, wxCoord y, wxCoord radius); - void DrawCircle(const wxPoint& pt, wxCoord radius); - //@} - - //@{ - /** - Draws an ellipse contained in the rectangle specified either with the - given top left corner and the given size or directly. The current pen - is used for the outline and the current brush for filling the shape. - - @see wxDC::DrawCircle() - */ - void DrawEllipse(wxCoord x, wxCoord y, wxCoord width, wxCoord height); - void DrawEllipse(const wxPoint& pt, const wxSize& size); - void DrawEllipse(const wxRect& rect); - //@} - - /** - Draws an arc of an ellipse. The current pen is used for drawing the arc - and the current brush is used for drawing the pie. - - @a x and @a y specify the x and y coordinates of the upper-left corner - of the rectangle that contains the ellipse. - - @a width and @a height specify the width and height of the rectangle - that contains the ellipse. - - @a start and @a end specify the start and end of the arc relative to - the three-o'clock position from the center of the rectangle. Angles are - specified in degrees (360 is a complete circle). Positive values mean - counter-clockwise motion. If @a start is equal to @a end, a complete - ellipse will be drawn. - */ - void DrawEllipticArc(wxCoord x, wxCoord y, wxCoord width, wxCoord height, - double start, double end); - - /** - Draw an icon on the display (does nothing if the device context is - PostScript). This can be the simplest way of drawing bitmaps on a - window. - */ - void DrawIcon(const wxIcon& icon, wxCoord x, wxCoord y); - - /** - Draws a line from the first point to the second. The current pen is - used for drawing the line. - */ - void DrawLine(wxCoord x1, wxCoord y1, wxCoord x2, wxCoord y2); - - //@{ - /** - Draws lines using an array of @a points of size @a n, or list of - pointers to points, adding the optional offset coordinate. The current - pen is used for drawing the lines. The programmer is responsible for - deleting the list of points. - */ - void DrawLines(int n, wxPoint points[], wxCoord xoffset = 0, - wxCoord yoffset = 0); - void DrawLines(wxList* points, wxCoord xoffset = 0, - wxCoord yoffset = 0); - //@} - - /** - Draws a point using the current pen. - */ - void DrawPoint(wxCoord x, wxCoord y); - - //@{ - /** - Draws a filled polygon using an array of @a points of size @a n, - or list of pointers to points, adding the optional offset coordinate. - wxWidgets automatically closes the first and last points. - - The last argument specifies the fill rule: @c wxODDEVEN_RULE (the - default) or @c wxWINDING_RULE. - - The current pen is used for drawing the outline, and the current brush - for filling the shape. Using a transparent brush suppresses filling. - - The programmer is responsible for deleting the list of points. - */ - void DrawPolygon(int n, wxPoint points[], wxCoord xoffset = 0, - wxCoord yoffset = 0, int fill_style = wxODDEVEN_RULE); - void DrawPolygon(wxList* points, wxCoord xoffset = 0, - wxCoord yoffset = 0, int fill_style = wxODDEVEN_RULE); - //@} - - /** - Draws a rectangle with the given top left corner, and with the given - size. The current pen is used for the outline and the current brush - for filling the shape. - */ - void DrawRectangle(wxCoord x, wxCoord y, wxCoord width, wxCoord height); - - /** - Draws the text rotated by @a angle degrees. - - The wxMSW wxDC and wxSVGFileDC rotate the text around slightly - different points, depending on the size of the font. - */ - void DrawRotatedText(const wxString& text, wxCoord x, wxCoord y, - double angle); - - /** - Draws a rectangle with the given top left corner, and with the given - size. The corners are quarter-circles using the given radius. The - current pen is used for the outline and the current brush for filling - the shape. - - If @a radius is positive, the value is assumed to be the radius of the - rounded corner. If @a radius is negative, the absolute value is assumed - to be the @e proportion of the smallest dimension of the rectangle. - This means that the corner can be a sensible size relative to the size - of the rectangle, and also avoids the strange effects X produces when - the corners are too big for the rectangle. - */ - void DrawRoundedRectangle(wxCoord x, wxCoord y, wxCoord width, - wxCoord height, double radius = 20); - - /** - Draws a spline between all given control points, using the current pen. - The programmer is responsible for deleting the list of points. The - spline is drawn using a series of lines, using an algorithm taken from - the X drawing program "XFIG". - */ - void DrawSpline(wxList* points); - /** - @param string - The text string to measure. - Draws a three-point spline using the current pen. - */ - void DrawSpline(wxCoord x1, wxCoord y1, wxCoord x2, wxCoord y2, - wxCoord x3, wxCoord y3); - - /** - Draws a text string at the specified point, using the current text - font, and the current text foreground and background colours. - - The coordinates refer to the top-left corner of the rectangle bounding - the string. See wxDC::GetTextExtent() for how to get the dimensions of - a text string, which can be used to position the text more precisely. - */ - void DrawText(const wxString& text, wxCoord x, wxCoord y); - - /** - Does nothing. - */ - void EndDoc(); - - /** - Does nothing. - */ - void EndDrawing(); - - /** - Does nothing. - */ - void EndPage(); - - /** - Not implemented. - */ - void FloodFill(wxCoord x, wxCoord y, const wxColour& colour, - int style = wxFLOOD_SURFACE); - - //@{ - /** - Gets the brush used for painting the background. - - @see SetBackground() - */ - wxBrush GetBackground() const; - const wxBrush GetBackground() const; - //@} - - /** - Returns the current background mode: @c wxSOLID or @c wxTRANSPARENT. - - @see SetBackgroundMode() - */ - int GetBackgroundMode() const; - - //@{ - /** - Gets the current brush. - - @see SetBrush() - */ - wxBrush GetBrush() const; - const wxBrush GetBrush() const; - //@} - - /** - Gets the character height of the currently set font. - */ - wxCoord GetCharHeight(); - - /** - Gets the average character width of the currently set font. - */ - wxCoord GetCharWidth(); - - /** - Not implemented. - */ - void GetClippingBox(wxCoord x, wxCoord y, wxCoord width, wxCoord height); - - //@{ - /** - Gets the current font. - - @see SetFont() - */ - wxFont GetFont() const; - const wxFont GetFont() const; - //@} - - /** - Gets the current logical function. - - @see SetLogicalFunction() - */ - int GetLogicalFunction(); - - /** - Gets the mapping mode for the device context. - - @see SetMapMode() - */ - int GetMapMode(); - - //@{ - /** - Gets the current pen. - - @see SetPen() - */ - wxPen GetPen() const; - const wxPen GetPen() const; - //@} - - /** - Not implemented. - */ - bool GetPixel(wxCoord x, wxCoord y, wxColour* colour); - - /** - For a Windows printer device context, this gets the horizontal and - vertical resolution. - */ - void GetSize(wxCoord* width, wxCoord* height); - - //@{ - /** - Gets the current text background colour. - - @see SetTextBackground() - */ - wxColour GetTextBackground() const; - const wxColour GetTextBackground() const; - //@} - - /** - Gets the dimensions of the string using the currently selected font. - - @param string - The text string to measure. - @param w - This value will be set to the width after this call. - @param h - This value will be set to the height after this call. - @param descent - The dimension from the baseline of the font to the bottom of the - descender. - @param externalLeading - Any extra vertical space added to the font by the font designer - (usually is zero). - - The optional parameter @a font specifies an alternative to the - currently selected font: but note that this does not yet work under - Windows, so you need to set a font for the device context first. - - @see wxFont, SetFont() - */ - void GetTextExtent(const wxString& string, wxCoord* w, wxCoord* h, - wxCoord* descent = NULL, - wxCoord* externalLeading = NULL, - wxFont* font = NULL); - - //@{ - /** - Gets the current text foreground colour. - - @see SetTextForeground() - */ - wxColour GetTextForeground() const; - const wxColour GetTextForeground() const; - //@} - - /** - Gets the current user scale factor. - - @see SetUserScale() - */ - void GetUserScale(double x, double y); - - /** - Converts logical X coordinate to device coordinate, using the current - mapping mode. - */ - wxCoord LogicalToDeviceX(wxCoord x); - - /** - Converts logical X coordinate to relative device coordinate, using the - current mapping mode but ignoring the x axis orientation. Use this for - converting a width, for example. - */ - wxCoord LogicalToDeviceXRel(wxCoord x); - - /** - Converts logical Y coordinate to device coordinate, using the current - mapping mode. - */ - wxCoord LogicalToDeviceY(wxCoord y); - - /** - Converts logical Y coordinate to relative device coordinate, using the - current mapping mode but ignoring the y axis orientation. Use this for - converting a height, for example. - */ - wxCoord LogicalToDeviceYRel(wxCoord y); - - /** - Gets the maximum horizontal extent used in drawing commands so far. - */ - wxCoord MaxX(); - - /** - Gets the maximum vertical extent used in drawing commands so far. - */ - wxCoord MaxY(); - - /** - Gets the minimum horizontal extent used in drawing commands so far. - */ - wxCoord MinX(); - - /** - Gets the minimum vertical extent used in drawing commands so far. - */ - wxCoord MinY(); - - /** - Returns @true if the DC is ok to use. @false values arise from being - unable to write the file. - */ - bool Ok(); - - /** - Resets the bounding box. After a call to this function, the bounding - box doesn't contain anything. - - @see CalcBoundingBox() - */ - void ResetBoundingBox(); - - /** - Sets the x and y axis orientation (i.e., the direction from lowest to - highest values on the axis). The default orientation is the natural - orientation, e.g. x axis from left to right and y axis from bottom up. - - @param xLeftRight - @true to set the x axis orientation to the natural left to right - orientation, @false to invert it. - @param yBottomUp - @true to set the y axis orientation to the natural bottom up - orientation, @false to invert it. - */ - void SetAxisOrientation(bool xLeftRight, bool yBottomUp); - - /** - Sets the current background brush for the DC. - */ - void SetBackground(const wxBrush& brush); - - /** - @a mode may be one of wxSOLID and wxTRANSPARENT. This setting determines - whether text will be drawn with a background colour or not. - */ - void SetBackgroundMode(int mode); - - /** - Sets the current brush for the DC. If the argument is wxNullBrush, the - current brush is selected out of the device context, and the original - brush restored, allowing the current brush to be destroyed safely. - - @see wxBrush, wxMemoryDC (for the interpretation of colours - when drawing into a monochrome bitmap). - */ - void SetBrush(const wxBrush& brush); - - //@{ - /** - Not implemented. - */ - void SetClippingRegion(wxCoord x, wxCoord y, wxCoord width, - wxCoord height); - void SetClippingRegion(const wxPoint& pt, const wxSize& sz); - void SetClippingRegion(const wxRect& rect); - void SetClippingRegion(const wxRegion& region); - //@} - - /** - Sets the device origin (i.e., the origin in pixels after scaling has - been applied). This function may be useful in Windows printing - operations for placing a graphic on a page. - */ - void SetDeviceOrigin(wxCoord x, wxCoord y); - - /** - Sets the current font for the DC. It must be a valid font, in - particular you should not pass @c wxNullFont to this method. - - @see wxFont - */ - void SetFont(const wxFont& font); - - /** - Does the same as wxDC::SetLogicalFunction(), except that only wxCOPY is - avalaible. Trying to set one of the othe values will fail. - */ - void SetLogicalFunction(int function); - - /** - The mapping mode of the device context defines the unit of measurement - used to convert logical units to device units. Note that in X, text - drawing isn't handled consistently with the mapping mode; a font is - always specified in point size. However, setting the user scale scales - the text appropriately. In Windows, scalable TrueType fonts are always - used; in X, results depend on availability of fonts, but usually a - reasonable match is found. - - Note that the coordinate origin should ideally be selectable, but for - now is always at the top left of the screen/printer. - - Drawing to a Windows printer device context under UNIX uses the current - mapping mode, but mapping mode is currently ignored for PostScript - output. - - The mapping mode can be one of the following: - - wxMM_TWIPS - Each logical unit is 1/20 of a point, or 1/1440 of an - inch. - - wxMM_POINTS - Each logical unit is a point, or 1/72 of an inch. - - wxMM_METRIC - Each logical unit is 1 mm. - - wxMM_LOMETRIC - Each logical unit is 1/10 of a mm. - - wxMM_TEXT - Each logical unit is 1 pixel. - */ - void SetMapMode(int mode); - - /** - Not implemented. - */ - void SetPalette(const wxPalette& palette); - - /** - Sets the current pen for the DC. If the argument is wxNullPen, the - current pen is selected out of the device context, and the original pen - restored. - - @see wxMemoryDC (for the interpretation of colours when drawing into a - monochrome bitmap) - */ - void SetPen(const wxPen& pen); - - /** - Sets the current text background colour for the DC. - */ - void SetTextBackground(const wxColour& colour); - - /** - Sets the current text foreground colour for the DC. - - @see wxMemoryDC (for the interpretation of colours when drawing into a - monochrome bitmap) - */ - void SetTextForeground(const wxColour& colour); - - /** - Sets the user scaling factor, useful for applications which require - "zooming". - */ - void SetUserScale(double xScale, double yScale); - - /** - Does nothing. - */ - bool StartDoc(const wxString& message); -}; - diff --git a/interface/dde.h b/interface/dde.h deleted file mode 100644 index 66b979df74..0000000000 --- a/interface/dde.h +++ /dev/null @@ -1,352 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: dde.h -// Purpose: interface of wxDDEConnection -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxDDEConnection - @wxheader{dde.h} - - A wxDDEConnection object represents the connection between a client and a - server. It can be created by making a connection using a wxDDEClient - object, or by the acceptance of a connection by a wxDDEServer object. The - bulk of a DDE (Dynamic Data Exchange) conversation is controlled by calling - members in a wxDDEConnection object or by overriding its members. - - An application should normally derive a new connection class from - wxDDEConnection, in order to override the communication event handlers to - do something interesting. - - This DDE-based implementation is available on Windows only, but a - platform-independent, socket-based version of this API is available using - wxTCPConnection. - - @library{wxbase} - @category{ipc} - - @see wxConnectionBase, wxDDEClient, wxDDEServer, @ref overview_ipc -*/ -class wxDDEConnection : public wxConnectionBase -{ -public: - /** - Constructs a connection object. If no user-defined connection object is - to be derived from wxDDEConnection, then the constructor should not be - called directly, since the default connection object will be provided - on requesting (or accepting) a connection. However, if the user defines - his or her own derived connection object, the - wxDDEServer::OnAcceptConnection() and/or - wxDDEClient::OnMakeConnection() members should be replaced by functions - which construct the new connection object. - - A default buffer will be associated with this connection. - */ - wxDDEConnection(); - /** - Constructs a connection object. If no user-defined connection object is - to be derived from wxDDEConnection, then the constructor should not be - called directly, since the default connection object will be provided - on requesting (or accepting) a connection. However, if the user defines - his or her own derived connection object, the - wxDDEServer::OnAcceptConnection() and/or - wxDDEClient::OnMakeConnection() members should be replaced by functions - which construct the new connection object. - - @param buffer - Buffer for this connection object to use in transactions. - @param size - Size of the buffer given. - */ - wxDDEConnection(void* buffer, size_t size); - - //@{ - /** - Called by the server application to advise the client of a change in - the data associated with the given item. Causes the client connection's - OnAdvise() member to be called. - - @return @true if successful. - */ - bool Advise(const wxString& item, const void* data, size_t size, - wxIPCFormat format = wxIPC_PRIVATE); - bool Advise(const wxString& item, const char* data); - bool Advise(const wxString& item, const wchar_t* data); - bool Advise(const wxString& item, const wxString data); - //@} - - /** - Called by the client or server application to disconnect from the other - program; it causes the OnDisconnect() message to be sent to the - corresponding connection object in the other program. The default - behaviour of OnDisconnect() is to delete the connection, but the - calling application must explicitly delete its side of the connection - having called Disconnect(). - - @return @true if successful. - */ - bool Disconnect(); - - //@{ - /** - Called by the client application to execute a command on the server. - Can also be used to transfer arbitrary data to the server (similar to - Poke() in that respect). Causes the server connection's OnExecute() - member to be called. - - @return @true if successful. - */ - bool Execute(const void* data, size_t size, - wxIPCFormat format = wxIPC_PRIVATE); - bool Execute(const char* data); - bool Execute(const wchar_t* data); - bool Execute(const wxString data); - //@} - - /** - Message sent to the client application when the server notifies it of a - change in the data associated with the given item. - */ - virtual bool OnAdvise(const wxString& topic, const wxString& item, - const void* data, size_t size, wxIPCFormat format); - - /** - Message sent to the client or server application when the other - application notifies it to delete the connection. Default behaviour is - to delete the connection object. - */ - virtual bool OnDisconnect(); - - /** - Message sent to the server application when the client notifies it to - execute the given data. Note that there is no item associated with - this message. - */ - virtual bool OnExecute(const wxString& topic, const void* data, - size_t size, wxIPCFormat format); - - /** - Message sent to the server application when the client notifies it to - accept the given data. - */ - virtual bool OnPoke(const wxString& topic, const wxString& item, - const void* data, size_t size, wxIPCFormat format); - - /** - Message sent to the server application when the client calls Request(). - The server should respond by returning a character string from - OnRequest(), or @NULL to indicate no data. - */ - virtual const void* OnRequest(const wxString& topic, - const wxString& item, size_t* size, - wxIPCFormat format); - - /** - Message sent to the server application by the client, when the client - wishes to start an "advise loop" for the given topic and item. The - server can refuse to participate by returning @false. - */ - virtual bool OnStartAdvise(const wxString& topic, const wxString& item); - - /** - Message sent to the server application by the client, when the client - wishes to stop an "advise loop" for the given topic and item. The - server can refuse to stop the advise loop by returning @false, although - this doesn't have much meaning in practice. - */ - virtual bool OnStopAdvise(const wxString& topic, const wxString& item); - - //@{ - /** - Called by the client application to poke data into the server. Can be - used to transfer arbitrary data to the server. Causes the server - connection's OnPoke() member to be called. - - @return @true if successful. - */ - bool Poke(const wxString& item, const void* data, size_t size, - wxIPCFormat format = wxIPC_PRIVATE); - bool Poke(const wxString& item, const char* data); - bool Poke(const wxString& item, const wchar_t* data); - bool Poke(const wxString& item, const wxString data); - //@} - - /** - Called by the client application to request data from the server. - Causes the server connection's OnRequest() member to be called. - - @return A character string (actually a pointer to the connection's - buffer) if successful, @NULL otherwise. - */ - const void* Request(const wxString& item, size_t* size, - wxIPCFormat format = wxIPC_TEXT); - - /** - Called by the client application to ask if an advise loop can be - started with the server. Causes the server connection's OnStartAdvise() - member to be called. - - @return @true if the server okays it, @false otherwise. - */ - bool StartAdvise(const wxString& item); - - /** - Called by the client application to ask if an advise loop can be - stopped. Causes the server connection's OnStopAdvise() member to be - called. - - @return @true if the server okays it, @false otherwise. - */ - bool StopAdvise(const wxString& item); -}; - - - -/** - @class wxDDEClient - @wxheader{dde.h} - - A wxDDEClient object represents the client part of a client-server DDE - (Dynamic Data Exchange) conversation. - - To create a client which can communicate with a suitable server, you need - to derive a class from wxDDEConnection and another from wxDDEClient. The - custom wxDDEConnection class will intercept communications in a - "conversation" with a server, and the custom wxDDEServer is required so - that a user-overridden OnMakeConnection() member can return a - wxDDEConnection of the required class, when a connection is made. - - This DDE-based implementation is available on Windows only, but a - platform-independent, socket-based version of this API is available using - wxTCPClient. - - @library{wxbase} - @category{ipc} - - @see wxDDEServer, wxDDEConnection, @ref overview_ipc -*/ -class wxDDEClient : public wxObject -{ -public: - /** - Constructs a client object. - */ - wxDDEClient(); - - /** - Tries to make a connection with a server specified by the host (machine - name under UNIX, ignored under Windows), service name (must contain an - integer port number under UNIX), and topic string. If the server allows - a connection, a wxDDEConnection object will be returned. - - The type of wxDDEConnection returned can be altered by overriding the - OnMakeConnection() member to return your own derived connection object. - */ - wxConnectionBase* MakeConnection(const wxString& host, - const wxString& service, - const wxString& topic); - - /** - The type of wxDDEConnection returned from a MakeConnection() call can - be altered by deriving the OnMakeConnection() member to return your own - derived connection object. By default, a wxDDEConnection object is - returned. - - The advantage of deriving your own connection class is that it will - enable you to intercept messages initiated by the server, such as - wxDDEConnection::OnAdvise(). You may also want to store - application-specific data in instances of the new class. - */ - wxConnectionBase* OnMakeConnection(); - - /** - Returns @true if this is a valid host name, @false otherwise. This - always returns @true under MS Windows. - */ - bool ValidHost(const wxString& host); -}; - - - -/** - @class wxDDEServer - @wxheader{dde.h} - - A wxDDEServer object represents the server part of a client-server DDE - (Dynamic Data Exchange) conversation. - - This DDE-based implementation is available on Windows only, but a - platform-independent, socket-based version of this API is available using - wxTCPServer. - - @library{wxbase} - @category{ipc} - - @see wxDDEClient, wxDDEConnection, @ref overview_ipc -*/ -class wxDDEServer -{ -public: - /** - Constructs a server object. - */ - wxDDEServer(); - - /** - Registers the server using the given service name. Under UNIX, the - string must contain an integer id which is used as an Internet port - number. @false is returned if the call failed (for example, if the port - number is already in use). - */ - bool Create(const wxString& service); - - /** - When a client calls wxDDEClient::MakeConnection(), the server receives - the message and this member is called. The application should derive a - member to intercept this message and return a connection object of - either the standard wxDDEConnection type, or of a user-derived type. - - If the @a topic is "STDIO", the application may wish to refuse the - connection. Under UNIX, when a server is created the - OnAcceptConnection() message is always sent for standard input and - output, but in the context of DDE messages it doesn't make a lot of - sense. - */ - virtual wxConnectionBase* OnAcceptConnection(const wxString& topic); -}; - - - -// ============================================================================ -// Global functions/macros -// ============================================================================ - -/** @ingroup group_funcmacro_misc */ -//@{ - -/** - Called when wxWidgets exits, to clean up the DDE system. This no longer - needs to be called by the application. - - @see wxDDEInitialize() - - @header{wx/dde.h} -*/ -void wxDDECleanUp(); - -/** - Initializes the DDE system. May be called multiple times without harm. - - This no longer needs to be called by the application: it will be called by - wxWidgets if necessary. - - @see wxDDEServer, wxDDEClient, wxDDEConnection, wxDDECleanUp() - - @header{wx/dde.h} -*/ -void wxDDEInitialize(); - -//@} - diff --git a/interface/debug.h b/interface/debug.h deleted file mode 100644 index 6338b91479..0000000000 --- a/interface/debug.h +++ /dev/null @@ -1,220 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: debug.h -// Purpose: interface of global functions -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** @ingroup group_funcmacro_debug */ -//@{ - -/** - Assert macro. An error message will be generated if the condition is @false in - debug mode, but nothing will be done in the release build. - Please note that the condition in wxASSERT() should have no side effects - because it will not be executed in release mode at all. - - @see wxASSERT_MSG(), wxCOMPILE_TIME_ASSERT() - - @header{wx/debug.h} -*/ -#define wxASSERT( condition ) - -/** - This macro results in a - @ref overview_wxcompiletimeassert "compile time assertion failure" if the - size of the given @c type is less than @c size bits. - - You may use it like this, for example: - - @code - // we rely on the int being able to hold values up to 2^32 - wxASSERT_MIN_BITSIZE(int, 32); - - // can't work with the platforms using UTF-8 for wchar_t - wxASSERT_MIN_BITSIZE(wchar_t, 16); - @endcode - - @header{wx/debug.h} -*/ -#define wxASSERT_MIN_BITSIZE( type, size ) - -/** - Assert macro with message. An error message will be generated if the - condition is @false. - - @see wxASSERT(), wxCOMPILE_TIME_ASSERT() - - @header{wx/debug.h} -*/ -#define wxASSERT_MSG( condition, message ) - -/** - Checks that the condition is @true, returns with the given return value if - not (stops execution in debug mode). This check is done even in release - mode. - - @header{wx/debug.h} -*/ -#define wxCHECK( condition, retValue ) - -/** - Checks that the condition is @true, returns with the given return value if - not (stops execution in debug mode). This check is done even in release - mode. - - This macro may be only used in non-void functions, see also wxCHECK_RET(). - - @header{wx/debug.h} -*/ -#define wxCHECK_MSG( condition, retValue, message ) - -/** - Checks that the condition is @true, and returns if not (stops execution - with the given error message in debug mode). This check is done even in - release mode. - - This macro should be used in void functions instead of wxCHECK_MSG(). - - @header{wx/debug.h} -*/ -#define wxCHECK_RET( condition, message ) - -/** - Checks that the condition is @true, and if not, it will wxFAIL() and - execute the given @c operation if it is not. This is a generalisation of - wxCHECK() and may be used when something else than just returning from the - function must be done when the @c condition is @false. This check is done - even in release mode. - - @header{wx/debug.h} -*/ -#define wxCHECK2(condition, operation) - -/** - This is the same as wxCHECK2(), but wxFAIL_MSG() with the specified - @c message is called instead of wxFAIL() if the @c condition is @false. - - @header{wx/debug.h} -*/ -#define wxCHECK2_MSG( condition, operation, message ) - -/** - Using wxCOMPILE_TIME_ASSERT() results in a compilation error if the - specified @c condition is @false. The compiler error message should include - the @c message identifier - please note that it must be a valid C++ - identifier and not a string unlike in the other cases. - - This macro is mostly useful for testing the expressions involving the - @c sizeof operator as they can't be tested by the preprocessor but it is - sometimes desirable to test them at the compile time. - - Note that this macro internally declares a struct whose name it tries to - make unique by using the @c __LINE__ in it but it may still not work if you - use it on the same line in two different source files. In this case you may - either change the line in which either of them appears on or use the - wxCOMPILE_TIME_ASSERT2() macro. - - Also note that Microsoft Visual C++ has a bug which results in compiler - errors if you use this macro with 'Program Database For Edit And Continue' - (@c /ZI) option, so you shouldn't use it ('Program Database' (@c /Zi) is ok - though) for the code making use of this macro. - - @see wxASSERT_MSG(), wxASSERT_MIN_BITSIZE() - - @header{wx/debug.h} -*/ -#define wxCOMPILE_TIME_ASSERT( condition, message ) - -/** - This macro is identical to wxCOMPILE_TIME_ASSERT() except that it allows - you to specify a unique @c name for the struct internally defined by this - macro to avoid getting the compilation errors described for - wxCOMPILE_TIME_ASSERT(). - - @header{wx/debug.h} -*/ -#define wxCOMPILE_TIME_ASSERT2(condition, message, name) - -/** - Will always generate an assert error if this code is reached (in debug - mode). - - @see wxFAIL_MSG() - - @header{wx/debug.h} -*/ -#define wxFAIL() - -/** - Will always generate an assert error with specified message if this code is - reached (in debug mode). - - This macro is useful for marking unreachable" code areas, for example it - may be used in the "default:" branch of a switch statement if all possible - cases are processed above. - - @see wxFAIL() - - @header{wx/debug.h} -*/ -#define wxFAIL_MSG( message ) - -/** - Returns @true if the program is running under debugger, @false otherwise. - - Please note that this function is currently only implemented for Win32 and - Mac builds using CodeWarrior and always returns @false elsewhere. - - @header{wx/debug.h} -*/ -bool wxIsDebuggerRunning(); - -/** - This function is called whenever one of debugging macros fails (i.e. - condition is @false in an assertion). It is only defined in the debug mode, - in release builds the wxCHECK() failures don't result in anything. - - To override the default behaviour in the debug builds which is to show the - user a dialog asking whether he wants to abort the program, continue or - continue ignoring any subsequent assert failures, you may override - wxApp::OnAssertFailure() which is called by this function if the global - application object exists. - - @header{wx/debug.h} -*/ -void wxOnAssert( const char* fileName, - int lineNumber, - const char* function, - const char* condition, - const char* message = NULL ); - -/** - In debug mode (when @c __WXDEBUG__ is defined) this function generates a - debugger exception meaning that the control is passed to the debugger if - one is attached to the process. Otherwise the program just terminates - abnormally. In release mode this function does nothing. - - @header{wx/debug.h} -*/ -void wxTrap(); - -//@} - - - -/** @ingroup group_funcmacro_misc */ -//@{ - -/** - This macro expands to the name of the current function if the compiler - supports any of @c __FUNCTION__, @c __func__ or equivalent variables or - macros or to @NULL if none of them is available. - - @header{wx/debug.h} -*/ -#define __WXFUNCTION__ - -//@} - diff --git a/interface/debugrpt.h b/interface/debugrpt.h deleted file mode 100644 index bb40cb1997..0000000000 --- a/interface/debugrpt.h +++ /dev/null @@ -1,351 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: debugrpt.h -// Purpose: interface of wxDebugReport* -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxDebugReportPreview - @wxheader{debugrpt.h} - - This class presents the debug report to the user and allows him to veto - report entirely or remove some parts of it. Although not mandatory, using - this class is strongly recommended as data included in the debug report - might contain sensitive private information and the user should be notified - about it as well as having a possibility to examine the data which had been - gathered to check whether this is effectively the case and discard the - debug report if it is. - - wxDebugReportPreview is an abstract base class, currently the only concrete - class deriving from it is wxDebugReportPreviewStd. - - @library{wxqa} - @category{debugging} -*/ -class wxDebugReportPreview -{ -public: - /** - Default constructor. - */ - wxDebugReportPreview(); - - /** - Destructor is trivial as well but should be virtual for a base class. - */ - virtual ~wxDebugReportPreview(); - - /** - Present the report to the user and allow him to modify it by removing - some or all of the files and, potentially, adding some notes. - - @return @true if the report should be processed or @false if the user - chose to cancel report generation or removed all files from - it. - */ - virtual bool Show(wxDebugReport& dbgrpt) const; -}; - - - -/** - @class wxDebugReportCompress - @wxheader{debugrpt.h} - - wxDebugReportCompress is a wxDebugReport which compresses all the files in - this debug report into a single ZIP file in its wxDebugReport::Process() - function. - - @library{wxqa} - @category{debugging} -*/ -class wxDebugReportCompress : public wxDebugReport -{ -public: - /** - Default constructor does nothing special. - */ - wxDebugReportCompress(); - - /** - Returns the full path of the compressed file (empty if creation - failed). - */ - const wxString GetCompressedFileName() const; -}; - - - -/** - @class wxDebugReport - @wxheader{debugrpt.h} - - wxDebugReport is used to generate a debug report, containing information - about the program current state. It is usually used from - wxApp::OnFatalException() as shown in the @ref page_samples_debugrpt. - - A wxDebugReport object contains one or more files. A few of them can be - created by the class itself but more can be created from the outside and - then added to the report. Also note that several virtual functions may be - overridden to further customize the class behaviour. - - Once a report is fully assembled, it can simply be left in the temporary - directory so that the user can email it to the developers (in which case - you should still use wxDebugReportCompress to compress it in a single file) - or uploaded to a Web server using wxDebugReportUpload (setting up the Web - server to accept uploads is your responsibility, of course). Other - handlers, for example for automatically emailing the report, can be defined - as well but are not currently included in wxWidgets. - - A typical usage example: - - @code - wxDebugReport report; - wxDebugReportPreviewStd preview; - - report.AddCurrentContext(); // could also use AddAll() - report.AddCurrentDump(); // to do both at once - - if ( preview.Show(report) ) - report.Process(); - @endcode - - @library{wxqa} - @category{debugging} -*/ -class wxDebugReport -{ -public: - /** - This enum is used for functions that report either the current state or - the state during the last (fatal) exception. - */ - enum Context { - Context_Current, - Context_Exception - }; - - /** - The constructor creates a temporary directory where the files that will - be included in the report are created. Use IsOk() to check for errors. - */ - wxDebugReport(); - - /** - The destructor normally destroys the temporary directory created in the - constructor with all the files it contains. Call Reset() to prevent - this from happening. - */ - ~wxDebugReport(); - - /** - Adds all available information to the report. Currently this includes a - text (XML) file describing the process context and, under Win32, a - minidump file. - */ - void AddAll(Context context = Context_Exception); - - /** - Add an XML file containing the current or exception context and the - stack trace. - */ - bool AddContext(Context ctx); - - /** - The same as calling AddContext(Context_Current). - */ - bool AddCurrentContext(); - - /** - The same as calling AddDump(Context_Current). - */ - bool AddCurrentDump(); - - /** - Adds the minidump file to the debug report. - - Minidumps are only available under recent Win32 versions - (@c dbghlp32.dll can be installed under older systems to make minidumps - available). - */ - bool AddDump(Context ctx); - - /** - The same as calling AddContext(Context_Exception). - */ - bool AddExceptionContext(); - - /** - The same as calling AddDump(Context_Exception). - */ - bool AddExceptionDump(); - - /** - Add another file to the report. If @a filename is an absolute path, it - is copied to a file in the debug report directory with the same name. - Otherwise the file should already exist in this directory - @a description only exists to be displayed to the user in the report - summary shown by wxDebugReportPreview. - - @see GetDirectory(), AddText() - */ - void AddFile(const wxString& filename, const wxString& description); - - /** - This is a convenient wrapper around AddFile(). It creates the file with - the given @a name and writes @a text to it, then adds the file to the - report. The @a filename shouldn't contain the path. - - @return @true if file could be added successfully, @false if an IO - error occurred. - */ - bool AddText(const wxString& filename, const wxString& text, - const wxString& description); - - /** - This function may be overridden to add arbitrary custom context to the - XML context file created by AddContext(). By default, it does nothing. - */ - void DoAddCustomContext(wxXmlNode* nodeRoot); - - /** - This function may be overridden to modify the contents of the exception - tag in the XML context file. - */ - bool DoAddExceptionInfo(wxXmlNode* nodeContext); - - /** - This function may be overridden to modify the contents of the modules - tag in the XML context file. - */ - bool DoAddLoadedModules(wxXmlNode* nodeModules); - - /** - This function may be overridden to modify the contents of the system - tag in the XML context file. - */ - bool DoAddSystemInfo(wxXmlNode* nodeSystemInfo); - - /** - This method should be used to construct the full name of the files - which you wish to add to the report using AddFile(). - - @return The name of the temporary directory used for the files in this - report. - */ - const wxString GetDirectory() const; - - /** - Retrieves the name (relative to GetDirectory()) and the description of - the file with the given index. If @a n is greater than or equal to the - number of filse, @false is returned. - */ - bool GetFile(size_t n, wxString* name, wxString* desc) const; - - /** - Gets the current number files in this report. - */ - size_t GetFilesCount() const; - - /** - Gets the name used as a base name for various files, by default - wxApp::GetAppName() is used. - */ - wxString GetReportName() const; - - /** - Returns @true if the object was successfully initialized. If this - method returns @false the report can't be used. - */ - bool IsOk() const; - - /** - Processes this report: the base class simply notifies the user that the - report has been generated. This is usually not enough -- instead you - should override this method to do something more useful to you. - */ - bool Process(); - - /** - Removes the file from report: this is used by wxDebugReportPreview to - allow the user to remove files potentially containing private - information from the report. - */ - void RemoveFile(const wxString& name); - - /** - Resets the directory name we use. The object can't be used any more - after this as it becomes uninitialized and invalid. - */ - void Reset(); -}; - - - -/** - @class wxDebugReportPreviewStd - @wxheader{debugrpt.h} - - wxDebugReportPreviewStd is a standard debug report preview window. It - displays a dialog allowing the user to examine the contents of a debug - report, remove files from and add notes to it. - - @library{wxqa} - @category{debugging} -*/ -class wxDebugReportPreviewStd : public wxDebugReportPreview -{ -public: - /** - Trivial default constructor. - */ - wxDebugReportPreviewStd(); - - /** - Shows the dialog. - - @see wxDebugReportPreview::Show() - */ - bool Show(wxDebugReport& dbgrpt) const; -}; - - - -/** - @class wxDebugReportUpload - @wxheader{debugrpt.h} - - This class is used to upload a compressed file using HTTP POST request. As - this class derives from wxDebugReportCompress, before upload the report is - compressed in a single ZIP file. - - @library{wxqa} - @category{debugging} -*/ -class wxDebugReportUpload : public wxDebugReportCompress -{ -public: - /** - This class will upload the compressed file created by its base class to - an HTML multipart/form-data form at the specified address. The @a url - is the upload page address, @a input is the name of the @c "type=file" - control on the form used for the file name and @a action is the value - of the form action field. The report is uploaded using the @e curl - program which should be available, the @e curl parameter may be used to - specify the full path to it. - */ - wxDebugReportUpload(const wxString& url, const wxString& input, - const wxString& action, - const wxString& curl = "curl"); - - /** - This function may be overridden in a derived class to show the output - from curl: this may be an HTML page or anything else that the server - returned. Value returned by this function becomes the return value of - wxDebugReport::Process(). - */ - bool OnServerReply(const wxArrayString& reply); -}; - diff --git a/interface/defs.h b/interface/defs.h deleted file mode 100644 index 61b05d3599..0000000000 --- a/interface/defs.h +++ /dev/null @@ -1,362 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: defs.h -// Purpose: interface of global functions -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - Item kinds for use with wxMenu, wxMenuItem, and wxToolBar. - - @see wxMenu::Append(), wxMenuItem::wxMenuItem(), wxToolBar::AddTool() -*/ -enum wxItemKind -{ - wxITEM_SEPARATOR = -1, - - /** - Normal tool button / menu item. - - @see wxToolBar::AddTool(), wxMenu::AppendItem(). - */ - wxITEM_NORMAL, - - /** - Check (or toggle) tool button / menu item. - - @see wxToolBar::AddCheckTool(), wxMenu::AppendCheckItem(). - */ - wxITEM_CHECK, - - /** - Radio tool button / menu item. - - @see wxToolBar::AddRadioTool(), wxMenu::AppendRadioItem(). - */ - wxITEM_RADIO, - - /** - Normal tool button with a dropdown arrow next to it. Clicking the - dropdown arrow sends a @c wxEVT_COMMAND_TOOL_DROPDOWN_CLICKED event and may - also display the menu previously associated with the item with - wxToolBar::SetDropdownMenu(). Currently this type of tools is supported - under MSW and GTK. - */ - wxITEM_DROPDOWN, - - wxITEM_MAX -}; - - -/** - Paper size types for use with the printing framework. - - @see overview_printing, wxPrintData::SetPaperId() -*/ -enum wxPaperSize -{ - wxPAPER_NONE, ///< Use specific dimensions - wxPAPER_LETTER, ///< Letter, 8 1/2 by 11 inches - wxPAPER_LEGAL, ///< Legal, 8 1/2 by 14 inches - wxPAPER_A4, ///< A4 Sheet, 210 by 297 millimeters - wxPAPER_CSHEET, ///< C Sheet, 17 by 22 inches - wxPAPER_DSHEET, ///< D Sheet, 22 by 34 inches - wxPAPER_ESHEET, ///< E Sheet, 34 by 44 inches - wxPAPER_LETTERSMALL, ///< Letter Small, 8 1/2 by 11 inches - wxPAPER_TABLOID, ///< Tabloid, 11 by 17 inches - wxPAPER_LEDGER, ///< Ledger, 17 by 11 inches - wxPAPER_STATEMENT, ///< Statement, 5 1/2 by 8 1/2 inches - wxPAPER_EXECUTIVE, ///< Executive, 7 1/4 by 10 1/2 inches - wxPAPER_A3, ///< A3 sheet, 297 by 420 millimeters - wxPAPER_A4SMALL, ///< A4 small sheet, 210 by 297 millimeters - wxPAPER_A5, ///< A5 sheet, 148 by 210 millimeters - wxPAPER_B4, ///< B4 sheet, 250 by 354 millimeters - wxPAPER_B5, ///< B5 sheet, 182-by-257-millimeter paper - wxPAPER_FOLIO, ///< Folio, 8-1/2-by-13-inch paper - wxPAPER_QUARTO, ///< Quarto, 215-by-275-millimeter paper - wxPAPER_10X14, ///< 10-by-14-inch sheet - wxPAPER_11X17, ///< 11-by-17-inch sheet - wxPAPER_NOTE, ///< Note, 8 1/2 by 11 inches - wxPAPER_ENV_9, ///< #9 Envelope, 3 7/8 by 8 7/8 inches - wxPAPER_ENV_10, ///< #10 Envelope, 4 1/8 by 9 1/2 inches - wxPAPER_ENV_11, ///< #11 Envelope, 4 1/2 by 10 3/8 inches - wxPAPER_ENV_12, ///< #12 Envelope, 4 3/4 by 11 inches - wxPAPER_ENV_14, ///< #14 Envelope, 5 by 11 1/2 inches - wxPAPER_ENV_DL, ///< DL Envelope, 110 by 220 millimeters - wxPAPER_ENV_C5, ///< C5 Envelope, 162 by 229 millimeters - wxPAPER_ENV_C3, ///< C3 Envelope, 324 by 458 millimeters - wxPAPER_ENV_C4, ///< C4 Envelope, 229 by 324 millimeters - wxPAPER_ENV_C6, ///< C6 Envelope, 114 by 162 millimeters - wxPAPER_ENV_C65, ///< C65 Envelope, 114 by 229 millimeters - wxPAPER_ENV_B4, ///< B4 Envelope, 250 by 353 millimeters - wxPAPER_ENV_B5, ///< B5 Envelope, 176 by 250 millimeters - wxPAPER_ENV_B6, ///< B6 Envelope, 176 by 125 millimeters - wxPAPER_ENV_ITALY, ///< Italy Envelope, 110 by 230 millimeters - wxPAPER_ENV_MONARCH, ///< Monarch Envelope, 3 7/8 by 7 1/2 inches - wxPAPER_ENV_PERSONAL, ///< 6 3/4 Envelope, 3 5/8 by 6 1/2 inches - wxPAPER_FANFOLD_US, ///< US Std Fanfold, 14 7/8 by 11 inches - wxPAPER_FANFOLD_STD_GERMAN, ///< German Std Fanfold, 8 1/2 by 12 inches - wxPAPER_FANFOLD_LGL_GERMAN, ///< German Legal Fanfold, 8 1/2 by 13 inches - - // Windows 95 Only - - wxPAPER_ISO_B4, ///< B4 (ISO) 250 x 353 mm - wxPAPER_JAPANESE_POSTCARD, ///< Japanese Postcard 100 x 148 mm - wxPAPER_9X11, ///< 9 x 11 in - wxPAPER_10X11, ///< 10 x 11 in - wxPAPER_15X11, ///< 15 x 11 in - wxPAPER_ENV_INVITE, ///< Envelope Invite 220 x 220 mm - wxPAPER_LETTER_EXTRA, ///< Letter Extra 9 \275 x 12 in - wxPAPER_LEGAL_EXTRA, ///< Legal Extra 9 \275 x 15 in - wxPAPER_TABLOID_EXTRA, ///< Tabloid Extra 11.69 x 18 in - wxPAPER_A4_EXTRA, ///< A4 Extra 9.27 x 12.69 in - wxPAPER_LETTER_TRANSVERSE, ///< Letter Transverse 8 \275 x 11 in - wxPAPER_A4_TRANSVERSE, ///< A4 Transverse 210 x 297 mm - wxPAPER_LETTER_EXTRA_TRANSVERSE, ///< Letter Extra Transverse 9\275 x 12 in - wxPAPER_A_PLUS, ///< SuperA/SuperA/A4 227 x 356 mm - wxPAPER_B_PLUS, ///< SuperB/SuperB/A3 305 x 487 mm - wxPAPER_LETTER_PLUS, ///< Letter Plus 8.5 x 12.69 in - wxPAPER_A4_PLUS, ///< A4 Plus 210 x 330 mm - wxPAPER_A5_TRANSVERSE, ///< A5 Transverse 148 x 210 mm - wxPAPER_B5_TRANSVERSE, ///< B5 (JIS) Transverse 182 x 257 mm - wxPAPER_A3_EXTRA, ///< A3 Extra 322 x 445 mm - wxPAPER_A5_EXTRA, ///< A5 Extra 174 x 235 mm - wxPAPER_B5_EXTRA, ///< B5 (ISO) Extra 201 x 276 mm - wxPAPER_A2, ///< A2 420 x 594 mm - wxPAPER_A3_TRANSVERSE, ///< A3 Transverse 297 x 420 mm - wxPAPER_A3_EXTRA_TRANSVERSE, ///< A3 Extra Transverse 322 x 445 mm - - wxPAPER_DBL_JAPANESE_POSTCARD, ///< Japanese Double Postcard 200 x 148 mm - wxPAPER_A6, ///< A6 105 x 148 mm - wxPAPER_JENV_KAKU2, ///< Japanese Envelope Kaku #2 - wxPAPER_JENV_KAKU3, ///< Japanese Envelope Kaku #3 - wxPAPER_JENV_CHOU3, ///< Japanese Envelope Chou #3 - wxPAPER_JENV_CHOU4, ///< Japanese Envelope Chou #4 - wxPAPER_LETTER_ROTATED, ///< Letter Rotated 11 x 8 1/2 in - wxPAPER_A3_ROTATED, ///< A3 Rotated 420 x 297 mm - wxPAPER_A4_ROTATED, ///< A4 Rotated 297 x 210 mm - wxPAPER_A5_ROTATED, ///< A5 Rotated 210 x 148 mm - wxPAPER_B4_JIS_ROTATED, ///< B4 (JIS) Rotated 364 x 257 mm - wxPAPER_B5_JIS_ROTATED, ///< B5 (JIS) Rotated 257 x 182 mm - wxPAPER_JAPANESE_POSTCARD_ROTATED, ///< Japanese Postcard Rotated 148 x 100 mm - wxPAPER_DBL_JAPANESE_POSTCARD_ROTATED, ///< Double Japanese Postcard Rotated 148 x 200 mm - wxPAPER_A6_ROTATED, ///< A6 Rotated 148 x 105 mm - wxPAPER_JENV_KAKU2_ROTATED, ///< Japanese Envelope Kaku #2 Rotated - wxPAPER_JENV_KAKU3_ROTATED, ///< Japanese Envelope Kaku #3 Rotated - wxPAPER_JENV_CHOU3_ROTATED, ///< Japanese Envelope Chou #3 Rotated - wxPAPER_JENV_CHOU4_ROTATED, ///< Japanese Envelope Chou #4 Rotated - wxPAPER_B6_JIS, ///< B6 (JIS) 128 x 182 mm - wxPAPER_B6_JIS_ROTATED, ///< B6 (JIS) Rotated 182 x 128 mm - wxPAPER_12X11, ///< 12 x 11 in - wxPAPER_JENV_YOU4, ///< Japanese Envelope You #4 - wxPAPER_JENV_YOU4_ROTATED, ///< Japanese Envelope You #4 Rotated - wxPAPER_P16K, ///< PRC 16K 146 x 215 mm - wxPAPER_P32K, ///< PRC 32K 97 x 151 mm - wxPAPER_P32KBIG, ///< PRC 32K(Big) 97 x 151 mm - wxPAPER_PENV_1, ///< PRC Envelope #1 102 x 165 mm - wxPAPER_PENV_2, ///< PRC Envelope #2 102 x 176 mm - wxPAPER_PENV_3, ///< PRC Envelope #3 125 x 176 mm - wxPAPER_PENV_4, ///< PRC Envelope #4 110 x 208 mm - wxPAPER_PENV_5, ///< PRC Envelope #5 110 x 220 mm - wxPAPER_PENV_6, ///< PRC Envelope #6 120 x 230 mm - wxPAPER_PENV_7, ///< PRC Envelope #7 160 x 230 mm - wxPAPER_PENV_8, ///< PRC Envelope #8 120 x 309 mm - wxPAPER_PENV_9, ///< PRC Envelope #9 229 x 324 mm - wxPAPER_PENV_10, ///< PRC Envelope #10 324 x 458 mm - wxPAPER_P16K_ROTATED, ///< PRC 16K Rotated - wxPAPER_P32K_ROTATED, ///< PRC 32K Rotated - wxPAPER_P32KBIG_ROTATED, ///< PRC 32K(Big) Rotated - wxPAPER_PENV_1_ROTATED, ///< PRC Envelope #1 Rotated 165 x 102 mm - wxPAPER_PENV_2_ROTATED, ///< PRC Envelope #2 Rotated 176 x 102 mm - wxPAPER_PENV_3_ROTATED, ///< PRC Envelope #3 Rotated 176 x 125 mm - wxPAPER_PENV_4_ROTATED, ///< PRC Envelope #4 Rotated 208 x 110 mm - wxPAPER_PENV_5_ROTATED, ///< PRC Envelope #5 Rotated 220 x 110 mm - wxPAPER_PENV_6_ROTATED, ///< PRC Envelope #6 Rotated 230 x 120 mm - wxPAPER_PENV_7_ROTATED, ///< PRC Envelope #7 Rotated 230 x 160 mm - wxPAPER_PENV_8_ROTATED, ///< PRC Envelope #8 Rotated 309 x 120 mm - wxPAPER_PENV_9_ROTATED, ///< PRC Envelope #9 Rotated 324 x 229 mm - wxPAPER_PENV_10_ROTATED ///< PRC Envelope #10 Rotated 458 x 324 m -}; - - -/** @ingroup group_funcmacro_byteorder */ -//@{ - -/** - This macro will swap the bytes of the @a value variable from little endian - to big endian or vice versa unconditionally, i.e. independently of the - current platform. - - @header{wx/defs.h} -*/ -#define wxINT32_SWAP_ALWAYS( wxInt32 value ) -#define wxUINT32_SWAP_ALWAYS( wxUint32 value ) -#define wxINT16_SWAP_ALWAYS( wxInt16 value ) -#define wxUINT16_SWAP_ALWAYS( wxUint16 value ) - -//@} - -/** @ingroup group_funcmacro_byteorder */ -//@{ - -/** - This macro will swap the bytes of the @a value variable from little endian - to big endian or vice versa if the program is compiled on a big-endian - architecture (such as Sun work stations). If the program has been compiled - on a little-endian architecture, the value will be unchanged. - - Use these macros to read data from and write data to a file that stores - data in little-endian (for example Intel i386) format. - - @header{wx/defs.h} -*/ -#define wxINT32_SWAP_ON_BE( wxInt32 value ) -#define wxUINT32_SWAP_ON_BE( wxUint32 value ) -#define wxINT16_SWAP_ON_BE( wxInt16 value ) -#define wxUINT16_SWAP_ON_BE( wxUint16 value ) - -//@} - -/** @ingroup group_funcmacro_byteorder */ -//@{ - -/** - This macro will swap the bytes of the @a value variable from little endian - to big endian or vice versa if the program is compiled on a little-endian - architecture (such as Intel PCs). If the program has been compiled on a - big-endian architecture, the value will be unchanged. - - Use these macros to read data from and write data to a file that stores - data in big-endian format. - - @header{wx/defs.h} -*/ -#define wxINT32_SWAP_ON_LE( wxInt32 value ) -#define wxUINT32_SWAP_ON_LE( wxUint32 value ) -#define wxINT16_SWAP_ON_LE( wxInt16 value ) -#define wxUINT16_SWAP_ON_LE( wxUint16 value ) - -//@} - - - -/** @ingroup group_funcmacro_misc */ -//@{ - -/** - This macro can be used around a function declaration to generate warnings - indicating that this function is deprecated (i.e. obsolete and planned to - be removed in the future) when it is used. Only Visual C++ 7 and higher and - g++ compilers currently support this functionality. - - Example of use: - - @code - // old function, use wxString version instead - wxDEPRECATED( void wxGetSomething(char *buf, size_t len) ); - - // ... - wxString wxGetSomething(); - @endcode - - @header{wx/defs.h} -*/ -#define wxDEPRECATED(function) - -/** - This is a special version of wxDEPRECATED() macro which only does something - when the deprecated function is used from the code outside wxWidgets itself - but doesn't generate warnings when it is used from wxWidgets. - - It is used with the virtual functions which are called by the library - itself -- even if such function is deprecated the library still has to call - it to ensure that the existing code overriding it continues to work, but - the use of this macro ensures that a deprecation warning will be generated - if this function is used from the user code or, in case of Visual C++, even - when it is simply overridden. - - @header{wx/defs.h} -*/ -#define wxDEPRECATED_BUT_USED_INTERNALLY(function) - -/** - This macro is similar to wxDEPRECATED() but can be used to not only declare - the function @a function as deprecated but to also provide its (inline) - implementation @a body. - - It can be used as following: - - @code - class wxFoo - { - public: - // OldMethod() is deprecated, use NewMethod() instead - void NewMethod(); - wxDEPRECATED_INLINE( void OldMethod(), NewMethod() ); - }; - @endcode - - @header{wx/defs.h} -*/ -#define wxDEPRECATED_INLINE(func, body) - -/** - @c wxEXPLICIT is a macro which expands to the C++ @c explicit keyword if - the compiler supports it or nothing otherwise. Thus, it can be used even in - the code which might have to be compiled with an old compiler without - support for this language feature but still take advantage of it when it is - available. - - @header{wx/defs.h} -*/ -#define wxEXPLICIT - -/** - GNU C++ compiler gives a warning for any class whose destructor is private - unless it has a friend. This warning may sometimes be useful but it doesn't - make sense for reference counted class which always delete themselves - (hence destructor should be private) but don't necessarily have any - friends, so this macro is provided to disable the warning in such case. The - @a name parameter should be the name of the class but is only used to - construct a unique friend class name internally. - - Example of using the macro: - - @code - class RefCounted - { - public: - RefCounted() { m_nRef = 1; } - void IncRef() { m_nRef++ ; } - void DecRef() { if ( !--m_nRef ) delete this; } - - private: - ~RefCounted() { } - - wxSUPPRESS_GCC_PRIVATE_DTOR(RefCounted) - }; - @endcode - - Notice that there should be no semicolon after this macro. - - @header{wx/defs.h} -*/ -#define wxSUPPRESS_GCC_PRIVATE_DTOR_WARNING(name) - -/** - This macro is the same as the standard C99 @c va_copy for the compilers - which support it or its replacement for those that don't. It must be used - to preserve the value of a @c va_list object if you need to use it after - passing it to another function because it can be modified by the latter. - - As with @c va_start, each call to @c wxVaCopy must have a matching - @c va_end. - - @header{wx/defs.h} -*/ -void wxVaCopy(va_list argptrDst, va_list argptrSrc); - -//@} - - diff --git a/interface/dialog.h b/interface/dialog.h deleted file mode 100644 index 3052b2e0e5..0000000000 --- a/interface/dialog.h +++ /dev/null @@ -1,613 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: dialog.h -// Purpose: interface of wxDialog -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - Modes used for wxDialog::SetLayoutAdaptationMode(). -*/ -enum wxDialogLayoutAdaptationMode -{ - wxDIALOG_ADAPTATION_MODE_DEFAULT = 0, ///< Use global adaptation enabled status. - wxDIALOG_ADAPTATION_MODE_ENABLED = 1, ///< Enable this dialog overriding global status. - wxDIALOG_ADAPTATION_MODE_DISABLED = 2 ///< Disable this dialog overriding global status. -}; - -/** - @class wxDialog - @wxheader{dialog.h} - - A dialog box is a window with a title bar and sometimes a system menu, - which can be moved around the screen. It can contain controls and other - windows and is often used to allow the user to make some choice or to - answer a question. - - Dialogs can be made scrollable, automatically, for computers with low - resolution screens: please see @ref overview_dialog_autoscrolling for - further details. - - Dialogs usually contains either a single button allowing to close the - dialog or two buttons, one accepting the changes and the other one - discarding them (such button, if present, is automatically activated if the - user presses the "Esc" key). By default, buttons with the standard wxID_OK - and wxID_CANCEL identifiers behave as expected. Starting with wxWidgets 2.7 - it is also possible to use a button with a different identifier instead, - see SetAffirmativeId() and SetEscapeId(). - - Also notice that the CreateButtonSizer() should be used to create the - buttons appropriate for the current platform and positioned correctly - (including their order which is platform-dependent). - - @section dialog_modal Modal and Modeless - - There are two kinds of dialog, modal and modeless. A modal dialog blocks - program flow and user input on other windows until it is dismissed, whereas - a modeless dialog behaves more like a frame in that program flow continues, - and input in other windows is still possible. To show a modal dialog you - should use the ShowModal() method while to show a dialog modelessly you - simply use Show(), just as with frames. - - Note that the modal dialog is one of the very few examples of - wxWindow-derived objects which may be created on the stack and not on the - heap. In other words, while most windows would be created like this: - - @code - void AskUser() - { - MyAskDialog *dlg = new MyAskDialog(...); - if ( dlg->ShowModal() == wxID_OK ) - // ... - //else: dialog was cancelled or some another button pressed - - dlg->Destroy(); - } - @endcode - - You can achieve the same result with dialogs by using simpler code: - - @code - void AskUser() - { - MyAskDialog dlg(...); - if ( dlg.ShowModal() == wxID_OK ) - // ... - - // no need to call Destroy() here - } - @endcode - - An application can define a wxCloseEvent handler for the dialog to respond - to system close events. - - @beginStyleTable - @style{wxCAPTION} - Puts a caption on the dialog box. - @style{wxDEFAULT_DIALOG_STYLE} - Equivalent to a combination of wxCAPTION, wxCLOSE_BOX and - wxSYSTEM_MENU (the last one is not used under Unix). - @style{wxRESIZE_BORDER} - Display a resizeable frame around the window. - @style{wxSYSTEM_MENU} - Display a system menu. - @style{wxCLOSE_BOX} - Displays a close box on the frame. - @style{wxMAXIMIZE_BOX} - Displays a maximize box on the dialog. - @style{wxMINIMIZE_BOX} - Displays a minimize box on the dialog. - @style{wxTHICK_FRAME} - Display a thick frame around the window. - @style{wxSTAY_ON_TOP} - The dialog stays on top of all other windows. - @style{wxNO_3D} - Under Windows, specifies that the child controls should not have 3D - borders unless specified in the control. - @style{wxDIALOG_NO_PARENT} - By default, a dialog created with a @NULL parent window will be - given the @ref wxApp::GetTopWindow() "application's top level window" - as parent. Use this style to prevent this from happening and create - an orphan dialog. This is not recommended for modal dialogs. - @style{wxDIALOG_EX_CONTEXTHELP} - Under Windows, puts a query button on the caption. When pressed, - Windows will go into a context-sensitive help mode and wxWidgets - will send a wxEVT_HELP event if the user clicked on an application - window. Note that this is an extended style and must be set by - calling SetExtraStyle() before Create is called (two-step - construction). - @style{wxDIALOG_EX_METAL} - On Mac OS X, frames with this style will be shown with a metallic - look. This is an extra style. - @endStyleTable - - Under Unix or Linux, MWM (the Motif Window Manager) or other window - managers recognizing the MHM hints should be running for any of these - styles to have an effect. - - @library{wxcore} - @category{cmndlg} - - @see @ref overview_dialog, wxFrame, @ref overview_validator -*/ -class wxDialog : public wxTopLevelWindow -{ -public: - /** - Default constructor. - */ - wxDialog(); - /** - Constructor. - - @param parent - Can be @NULL, a frame or another dialog box. - @param id - An identifier for the dialog. A value of -1 is taken to mean a - default. - @param title - The title of the dialog. - @param pos - The dialog position. The value wxDefaultPosition indicates a - default position, chosen by either the windowing system or - wxWidgets, depending on platform. - @param size - The dialog size. The value wxDefaultSize indicates a default size, - chosen by either the windowing system or wxWidgets, depending on - platform. - @param style - The window style. - @param name - Used to associate a name with the window, allowing the application - user to set Motif resource values for individual dialog boxes. - - @see Create() - */ - wxDialog(wxWindow* parent, wxWindowID id, const wxString& title, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = wxDEFAULT_DIALOG_STYLE, - const wxString& name = "dialogBox"); - - /** - Destructor. Deletes any child windows before deleting the physical - window. - */ - ~wxDialog(); - - /** - Adds an identifier to be regarded as a main button for the - non-scrolling area of a dialog. - - @see @ref overview_dialog_autoscrolling (for more on layout adaptation) - */ - void AddMainButtonId(wxWindowID id); - - /** - Returns @true if this dialog can and should perform layout adaptation - using DoLayoutAdaptation(), usually if the dialog is too large to fit - on the display. - - @see @ref overview_dialog_autoscrolling (for more on layout adaptation) - */ - bool CanDoLayoutAdapation(); - - /** - Centres the dialog box on the display. - - @param direction - May be wxHORIZONTAL, wxVERTICAL or wxBOTH. - */ - void Centre(int direction = wxBOTH); - - /** - Used for two-step dialog box construction. - - @see wxDialog() - */ - bool Create(wxWindow* parent, wxWindowID id, const wxString& title, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = wxDEFAULT_DIALOG_STYLE, - const wxString& name = "dialogBox"); - - /** - Creates a sizer with standard buttons. @a flags is a bit list of the - following flags: wxOK, wxCANCEL, wxYES, wxNO, wxAPPLY, wxCLOSE, wxHELP, - wxNO_DEFAULT. - - The sizer lays out the buttons in a manner appropriate to the platform. - - This function uses CreateStdDialogButtonSizer() internally for most - platforms but doesn't create the sizer at all for the platforms with - hardware buttons (such as smartphones) for which it sets up the - hardware buttons appropriately and returns @NULL, so don't forget to - test that the return value is valid before using it. - */ - wxSizer* CreateButtonSizer(long flags); - - /** - Creates a sizer with standard buttons using CreateButtonSizer() - separated from the rest of the dialog contents by a horizontal - wxStaticLine. - - @note Just like CreateButtonSizer(), this function may return @NULL if - no buttons were created. - */ - wxSizer* CreateSeparatedButtonSizer(long flags); - - /** - Creates a wxStdDialogButtonSizer with standard buttons. @a flags is a - bit list of the following flags: wxOK, wxCANCEL, wxYES, wxNO, wxAPPLY, - wxCLOSE, wxHELP, wxNO_DEFAULT. - - The sizer lays out the buttons in a manner appropriate to the platform. - */ - wxStdDialogButtonSizer* CreateStdDialogButtonSizer(long flags); - - /** - Performs layout adaptation, usually if the dialog is too large to fit - on the display. - - @see @ref overview_dialog_autoscrolling (for more on layout adaptation) - */ - bool DoLayoutAdapation(); - - /** - This function is called when the titlebar OK button is pressed - (PocketPC only). A command event for the identifier returned by - GetAffirmativeId() is sent by default. You can override this function. - If the function returns @false, wxWidgets will call Close() for the - dialog. - */ - virtual bool DoOK(); - - /** - A static function enabling or disabling layout adaptation for all - dialogs. - - @see @ref overview_dialog_autoscrolling (for more on layout adaptation) - */ - static void EnableLayoutAdaptation(bool enable); - - /** - Ends a modal dialog, passing a value to be returned from the - ShowModal() invocation. - - @param retCode - The value that should be returned by ShowModal. - - @see ShowModal(), GetReturnCode(), SetReturnCode() - */ - void EndModal(int retCode); - - /** - Gets the identifier of the button which works like standard OK button - in this dialog. - - @see SetAffirmativeId() - */ - int GetAffirmativeId() const; - - /** - Override this to return a window containing the main content of the - dialog. This is particularly useful when the dialog implements pages, - such as wxPropertySheetDialog, and allows the - @ref overview_dialog "layout adaptation code" to know that only the - pages need to be made scrollable. - */ - wxWindow* GetContentWindow() const; - - /** - Gets the identifier of the button to map presses of @c ESC button to. - - @see SetEscapeId() - */ - int GetEscapeId() const; - - /** - Returns @true if the dialog has been adapted, usually by making it - scrollable to work with a small display. - - @see @ref overview_dialog_autoscrolling (for more on layout adaptation) - */ - bool GetLayoutAdaptationDone() const; - - /** - Gets a value representing the aggressiveness of search for buttons and - sizers to be in the non-scrolling part of a layout-adapted dialog. Zero - switches off adaptation, and 3 allows search for standard buttons - anywhere in the dialog. - - @see @ref overview_dialog_autoscrolling (for more on layout adaptation) - */ - int GetLayoutAdaptationLevel(); - - /** - Gets the adaptation mode, overriding the global adaptation flag. - - @see @ref overview_dialog_autoscrolling (for more on layout adaptation) - */ - wxDialogLayoutAdaptationMode GetLayoutAdaptationMode() const; - - /** - A static function getting the current layout adapter object. - - @see @ref overview_dialog_autoscrolling (for more on layout adaptation) - */ - static wxDialogLayoutAdapter* GetLayoutAdapter(); - - /** - Returns an array of identifiers to be regarded as the main buttons for - the non-scrolling area of a dialog. - - @see @ref overview_dialog_autoscrolling (for more on layout adaptation) - */ - wxArrayInt GetMainButtonIds(); - - /** - Gets the return code for this window. - - @remarks A return code is normally associated with a modal dialog, - where ShowModal() returns a code to the application. - - @see SetReturnCode(), ShowModal(), EndModal() - */ - int GetReturnCode(); - - /** - On PocketPC, a dialog is automatically provided with an empty toolbar. - This function allows you to access the toolbar and add tools to it. - Removing tools and adding arbitrary controls are not currently - supported. - - This function is not available on any other platform. - */ - wxToolBar* GetToolBar() const; - - /** - Iconizes or restores the dialog. Windows only. - - @param iconize - If @true, iconizes the dialog box; if @false, shows and restores it. - - @remarks Note that in Windows, iconization has no effect since dialog - boxes cannot be iconized. However, applications may need to - explicitly restore dialog boxes under Motif which have - user-iconizable frames, and under Windows calling - Iconize(@false) will bring the window to the front, as does - Show(@true). - */ - void Iconize(bool iconize); - - /** - Returns @true if the dialog box is iconized. Windows only. - - @remarks Always returns @false under Windows since dialogs cannot be - iconized. - */ - bool IsIconized() const; - - /** - A static function returning @true if layout adaptation is enabled for - all dialogs. - - @see @ref overview_dialog_autoscrolling (for more on layout adaptation) - */ - static bool IsLayoutAdaptationEnabled(); - - /** - Returns @true if @a id is in the array of identifiers to be regarded as - the main buttons for the non-scrolling area of a dialog. - - @see @ref overview_dialog_autoscrolling (for more on layout adaptation) - */ - bool IsMainButton(wxWindowID& id) const; - - /** - Returns @true if the dialog box is modal, @false otherwise. - */ - bool IsModal() const; - - /** - The default handler for wxEVT_SYS_COLOUR_CHANGED. - - @param event - The colour change event. - - @remarks Changes the dialog's colour to conform to the current settings - (Windows only). Add an event table entry for your dialog 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 the notification - to child windows and controls. - - @see wxSysColourChangedEvent - */ - void OnSysColourChanged(wxSysColourChangedEvent& event); - - /** - Sets the identifier to be used as OK button. When the button with this - identifier is pressed, the dialog calls wxWindow::Validate() and - wxWindow::TransferDataFromWindow() and, if they both return @true, - closes the dialog with wxID_OK return code. - - Also, when the user presses a hardware OK button on the devices having - one or the special OK button in the PocketPC title bar, an event with - this id is generated. - - By default, the affirmative id is wxID_OK. - - @see GetAffirmativeId(), SetEscapeId() - */ - void SetAffirmativeId(int id); - - /** - Sets the identifier of the button which should work like the standard - "Cancel" button in this dialog. When the button with this id is - clicked, the dialog is closed. Also, when the user presses @c ESC key - in the dialog or closes the dialog using the close button in the title - bar, this is mapped to the click of the button with the specified id. - - By default, the escape id is the special value wxID_ANY meaning that - wxID_CANCEL button is used if it's present in the dialog and otherwise - the button with GetAffirmativeId() is used. Another special value for - @a id is wxID_NONE meaning that @c ESC presses should be ignored. If - any other value is given, it is interpreted as the id of the button to - map the escape key to. - */ - void SetEscapeId(int id); - - /** - Sets the icon for this dialog. - - @param icon - The icon to associate with this dialog. - - @see wxIcon - */ - void SetIcon(const wxIcon& icon); - - /** - Sets the icons for this dialog. - - @param icons - The icons to associate with this dialog. - - @see wxIconBundle - */ - void SetIcons(const wxIconBundle& icons); - - /** - Marks the dialog as having been adapted, usually by making it - scrollable to work with a small display. - - @see @ref overview_dialog_autoscrolling (for more on layout adaptation) - */ - void SetLayoutAdaptationDone(bool done); - - /** - Sets the aggressiveness of search for buttons and sizers to be in the - non-scrolling part of a layout-adapted dialog. Zero switches off - adaptation, and 3 allows search for standard buttons anywhere in the - dialog. - - @see @ref overview_dialog_autoscrolling (for more on layout adaptation) - */ - void SetLayoutAdaptationLevel(int level); - - /** - Sets the adaptation mode, overriding the global adaptation flag. - - @see wxDialogLayoutAdaptationMode, @ref overview_dialog_autoscrolling - (for more on layout adaptation) - */ - void SetLayoutAdaptationMode(wxDialogLayoutAdaptationMode mode); - - /** - A static function for setting the current layout adapter object, - returning the old adapter. If you call this, you should delete the old - adapter object. - - @see wxDialogLayoutAdapter, @ref overview_dialog_autoscrolling - */ - static wxDialogLayoutAdapter* SetLayoutAdapter(wxDialogLayoutAdapter* adapter); - - /** - @deprecated This function doesn't work for all ports, just use - ShowModal() to show a modal dialog instead. - - Allows the programmer to specify whether the dialog box is modal - (Show() blocks control until the dialog is hidden) or modeless (control - returns immediately). - - @param flag - If @true, the dialog will be modal, otherwise it will be modeless. - */ - void SetModal(bool flag); - - /** - Sets the return code for this window. - - A return code is normally associated with a modal dialog, where - ShowModal() returns a code to the application. The function EndModal() - calls SetReturnCode(). - - @param retCode - The integer return code, usually a control identifier. - - @see GetReturnCode(), ShowModal(), EndModal() - */ - void SetReturnCode(int retCode); - - /** - Hides or shows the dialog. The preferred way of dismissing a modal - dialog is to use EndModal(). - - @param show - If @true, the dialog box is shown and brought to the front, - otherwise the box is hidden. If @false and the dialog is modal, - control is returned to the calling program. - */ - bool Show(bool show); - - /** - Shows a modal dialog. - - Program flow does not return until the dialog has been dismissed with - EndModal(). - - Notice that it is possible to call ShowModal() for a dialog which had - been previously shown with Show(), this allows to make an existing - modeless dialog modal. However ShowModal() can't be called twice - without intervening EndModal() calls. - - @return The value set with SetReturnCode(). - - @see EndModal(), GetReturnCode(), SetReturnCode() - */ - int ShowModal(); -}; - - - -/** - @class wxDialogLayoutAdapter - @wxheader{dialog.h} - - This abstract class is the base for classes that help wxWidgets peform - run-time layout adaptation of dialogs. Principally, this is to cater for - small displays by making part of the dialog scroll, but the application - developer may find other uses for layout adaption. - - By default, there is one instance of wxStandardDialogLayoutAdapter which - can perform adaptation for most custom dialogs and dialogs with book - controls such as wxPropertySheetDialog. - - @library{wxcore} - @category{winlayout} - - @see @ref overview_dialog_autoscrolling -*/ -class wxDialogLayoutAdapter -{ -public: - /** - Default constructor. - */ - wxDialogLayoutAdapter(); - - /** - Override this to returns @true if adaptation can and should be done. - */ - bool CanDoLayoutAdaptation(wxDialog* dialog); - - /** - Override this to perform layout adaptation, such as making parts of the - dialog scroll and resizing the dialog to fit the display. Normally this - function will be called just before the dialog is shown. - */ - bool DoLayoutAdaptation(wxDialog* dialog); -}; - diff --git a/interface/dialup.h b/interface/dialup.h deleted file mode 100644 index 849d21cbbd..0000000000 --- a/interface/dialup.h +++ /dev/null @@ -1,217 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: dialup.h -// Purpose: interface of wxDialUpManager -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxDialUpManager - @wxheader{dialup.h} - - This class encapsulates functions dealing with verifying the connection - status of the workstation (connected to the Internet via a direct - connection, connected through a modem or not connected at all) and to - establish this connection if possible/required (i.e. in the case of the - modem). - - The program may also wish to be notified about the change in the connection - status (for example, to perform some action when the user connects to the - network the next time or, on the contrary, to stop receiving data from the - net when the user hangs up the modem). For this, you need to use one of the - event macros described below. - - This class is different from other wxWidgets classes in that there is at - most one instance of this class in the program accessed via Create() and - you can't create the objects of this class directly. - - @beginEventTable{wxDialUpEvent} - @event{EVT_DIALUP_CONNECTED(func)} - A connection with the network was established. - @event{EVT_DIALUP_DISCONNECTED(func)} - The connection with the network was lost. - @endEventTable - - @library{wxcore} - @category{net} - - @see @ref page_samples_dialup, wxDialUpEvent -*/ -class wxDialUpManager -{ -public: - /** - Destructor. - */ - ~wxDialUpManager(); - - /** - Cancel dialing the number initiated with Dial() with async parameter - equal to @true. - - @note This won't result in a DISCONNECTED event being sent. - - @see IsDialing() - */ - bool CancelDialing(); - - /** - This function should create and return the object of the - platform-specific class derived from wxDialUpManager. You should delete - the pointer when you are done with it. - */ - wxDialUpManager* Create(); - - /** - Dial the given ISP, use @a username and @a password to authenticate. - - The parameters are only used under Windows currently, for Unix you - should use SetConnectCommand() to customize this functions behaviour. - - If no @a nameOfISP is given, the function will select the default one - (proposing the user to choose among all connections defined on this - machine) and if no username and/or password are given, the function - will try to do without them, but will ask the user if really needed. - - If @a async parameter is @false, the function waits until the end of - dialing and returns @true upon successful completion. - - If @a async is @true, the function only initiates the connection and - returns immediately - the result is reported via events (an event is - sent anyhow, but if dialing failed it will be a DISCONNECTED one). - */ - bool Dial(const wxString& nameOfISP = wxEmptyString, - const wxString& username = wxEmptyString, - const wxString& password = wxEmptyString, - bool async = true); - - /** - Disable automatic check for connection status change - notice that the - @c wxEVT_DIALUP_XXX events won't be sent any more neither. - */ - void DisableAutoCheckOnlineStatus(); - - /** - Enable automatic checks for the connection status and sending of - wxEVT_DIALUP_CONNECTED/wxEVT_DIALUP_DISCONNECTED events. The interval - parameter is only for Unix where we do the check manually and specifies - how often should we repeat the check (each minute by default). Under - Windows, the notification about the change of connection status is sent - by the system and so we don't do any polling and this parameter is - ignored. - - @return @false if couldn't set up automatic check for online status. - */ - bool EnableAutoCheckOnlineStatus(size_t nSeconds = 60); - - /** - This function is only implemented under Windows. - - Fills the array with the names of all possible values for the first - parameter to Dial() on this machine and returns their number (may be - 0). - */ - size_t GetISPNames(wxArrayString& names) const; - - /** - Hang up the currently active dial up connection. - */ - bool HangUp(); - - /** - Returns @true if the computer has a permanent network connection (i.e. - is on a LAN) and so there is no need to use Dial() function to go - online. - - @note This function tries to guess the result and it is not always - guaranteed to be correct, so it is better to ask user for - confirmation or give him a possibility to override it. - */ - bool IsAlwaysOnline() const; - - /** - Returns @true if (async) dialing is in progress. - - @see Dial() - */ - bool IsDialing() const; - - /** - Returns @true if the dialup manager was initialized correctly. If this - function returns @false, no other functions will work neither, so it is - a good idea to call this function and check its result before calling - any other wxDialUpManager methods. - */ - bool IsOk() const; - - /** - Returns @true if the computer is connected to the network: under - Windows, this just means that a RAS connection exists, under Unix we - check that the "well-known host" (as specified by SetWellKnownHost()) - is reachable. - */ - bool IsOnline() const; - - /** - This method is for Unix only. - - Sets the commands to start up the network and to hang up again. - */ - void SetConnectCommand(const wxString& commandDial = "/usr/bin/pon", - const wxString& commandHangup = "/usr/bin/poff") const; - - /** - Sometimes the built-in logic for determining the online status may - fail, so, in general, the user should be allowed to override it. This - function allows to forcefully set the online status - whatever our - internal algorithm may think about it. - - @see IsOnline() - */ - void SetOnlineStatus(bool isOnline = true); - - /** - This method is for Unix only. - - Under Unix, the value of well-known host is used to check whether we're - connected to the internet. It is unused under Windows, but this - function is always safe to call. The default value is - @c "www.yahoo.com:80". - */ - void SetWellKnownHost(const wxString& hostname, int portno = 80); -}; - - - -/** - @class wxDialUpEvent - @wxheader{dialup.h} - - This is the event class for the dialup events sent by wxDialUpManager. - - @library{wxcore} - @category{events} -*/ -class wxDialUpEvent : public wxEvent -{ -public: - /** - Constructor is only used by wxDialUpManager. - */ - wxDialUpEvent(bool isConnected, bool isOwnEvent); - - /** - Is this a @c CONNECTED or @c DISCONNECTED event? In other words, does - it notify about transition from offline to online state or vice versa? - */ - bool IsConnectedEvent() const; - - /** - Does this event come from wxDialUpManager::Dial() or from some extrenal - process (i.e. does it result from our own attempt to establish the - connection)? - */ - bool IsOwnEvent() const; -}; - diff --git a/interface/dir.h b/interface/dir.h deleted file mode 100644 index 82b40531ca..0000000000 --- a/interface/dir.h +++ /dev/null @@ -1,292 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: dir.h -// Purpose: interface of wxDir and wxDirTraverser -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - Possible return values of wxDirTraverser callback functions. -*/ -enum wxDirTraverseResult -{ - wxDIR_IGNORE = -1, ///< Ignore this directory but continue with others. - wxDIR_STOP, ///< Stop traversing. - wxDIR_CONTINUE ///< Continue into this directory. -}; - -/** - @class wxDirTraverser - @wxheader{dir.h} - - wxDirTraverser is an abstract interface which must be implemented by - objects passed to wxDir::Traverse() function. - - Example of use (this works almost like wxDir::GetAllFiles()): - - @code - class wxDirTraverserSimple : public wxDirTraverser - { - public: - wxDirTraverserSimple(wxArrayString& files) : m_files(files) { } - - virtual wxDirTraverseResult OnFile(const wxString& filename) - { - m_files.Add(filename); - return wxDIR_CONTINUE; - } - - virtual wxDirTraverseResult OnDir(const wxString& WXUNUSED(dirname)) - { - return wxDIR_CONTINUE; - } - - private: - wxArrayString& m_files; - }; - - // get the names of all files in the array - wxArrayString files; - wxDirTraverserSimple traverser(files); - - wxDir dir(dirname); - dir.Traverse(traverser); - @endcode - - @library{wxbase} - @category{file} -*/ -class wxDirTraverser -{ -public: - /** - This function is called for each directory. It may return ::wxDIR_STOP - to abort traversing completely, ::wxDIR_IGNORE to skip this directory - but continue with others or ::wxDIR_CONTINUE to enumerate all files and - subdirectories in this directory. - - This is a pure virtual function and must be implemented in the derived - class. - */ - virtual wxDirTraverseResult OnDir(const wxString& dirname); - - /** - This function is called for each file. It may return ::wxDIR_STOP to - abort traversing (for example, if the file being searched is found) or - ::wxDIR_CONTINUE to proceed. - - This is a pure virtual function and must be implemented in the derived - class. - */ - virtual wxDirTraverseResult OnFile(const wxString& filename); - - /** - This function is called for each directory which we failed to open for - enumerating. It may return ::wxDIR_STOP to abort traversing completely, - ::wxDIR_IGNORE to skip this directory but continue with others or - ::wxDIR_CONTINUE to retry opening this directory once again. - - The base class version always returns ::wxDIR_IGNORE. - */ - virtual wxDirTraverseResult OnOpenError(const wxString& openerrorname); -}; - - - -/** - These flags define what kind of filenames are included in the list of files - enumerated by wxDir::GetFirst() and wxDir::GetNext(). -*/ -enum -{ - wxDIR_FILES = 0x0001, ///< Includes files. - wxDIR_DIRS = 0x0002, ///< Includes directories. - wxDIR_HIDDEN = 0x0004, ///< Includes hidden files. - wxDIR_DOTDOT = 0x0008, ///< Includes "." and "..". - - wxDIR_DEFAULT = wxDIR_FILES | wxDIR_DIRS | wxDIR_HIDDEN -}; - -/** - @class wxDir - @wxheader{dir.h} - - wxDir is a portable equivalent of Unix open/read/closedir functions which - allow enumerating of the files in a directory. wxDir allows to enumerate - files as well as directories. - - wxDir also provides a flexible way to enumerate files recursively using - Traverse() or a simpler GetAllFiles() function. - - Example of use: - - @code - wxDir dir(wxGetCwd()); - - if ( !dir.IsOpened() ) - { - // deal with the error here - wxDir would already log an error message - // explaining the exact reason of the failure - return; - } - - puts("Enumerating object files in current directory:"); - - wxString filename; - - bool cont = dir.GetFirst(&filename, filespec, flags); - while ( cont ) - { - printf("%s\n", filename.c_str()); - - cont = dir.GetNext(&filename); - } - @endcode - - @library{wxbase} - @category{file} -*/ -class wxDir -{ -public: - /** - Default constructor, use Open() afterwards. - */ - wxDir(); - /** - Opens the directory for enumeration, use IsOpened() to test for errors. - */ - wxDir(const wxString& dir); - - /** - Destructor cleans up the associated resources. It is not virtual and so - this class is not meant to be used polymorphically. - */ - ~wxDir(); - - /** - Test for existence of a directory with the given name. - */ - static bool Exists(const wxString& dir); - - /** - The function returns the path of the first file matching the given - @a filespec or an empty string if there are no files matching it. - - The @a flags parameter may or may not include ::wxDIR_FILES, the - function always behaves as if it were specified. By default, @a flags - includes ::wxDIR_DIRS and so the function recurses into the - subdirectories but if this flag is not specified, the function - restricts the search only to the directory @a dirname itself. - - @see Traverse() - */ - static wxString FindFirst(const wxString& dirname, - const wxString& filespec, - int flags = wxDIR_DEFAULT); - - /** - The function appends the names of all the files under directory - @a dirname to the array @a files (note that its old content is - preserved). Only files matching the @a filespec are taken, with empty - spec matching all the files. - - The @a flags parameter should always include ::wxDIR_FILES or the array - would be unchanged and should include ::wxDIR_DIRS flag to recurse into - subdirectories (both flags are included in the value by default). - - @see Traverse() - */ - static size_t GetAllFiles(const wxString& dirname, wxArrayString* files, - const wxString& filespec = wxEmptyString, - int flags = wxDIR_DEFAULT); - - /** - Start enumerating all files matching @a filespec (or all files if it is - empty) and @e flags, return @true on success. - */ - bool GetFirst(wxString* filename, - const wxString& filespec = wxEmptyString, - int flags = wxDIR_DEFAULT) const; - - /** - Returns the name of the directory itself. The returned string does not - have the trailing path separator (slash or backslash). - */ - wxString GetName() const; - - /** - Continue enumerating files which satisfy the criteria specified by the - last call to GetFirst(). - */ - bool GetNext(wxString* filename) const; - - /** - Returns the size (in bytes) of all files recursively found in @c dir or - @c wxInvalidSize in case of error. - - In case it happens that while traversing folders a file's size can not - be read, that file is added to the @a filesSkipped array, if not @NULL, - and then skipped. This usually happens with some special folders which - are locked by the operating system or by another process. Remember that - when the size of @a filesSkipped is not zero, then the returned value - is not 100% accurate and, if the skipped files were big, it could be - far from real size of the directory. - - @see wxFileName::GetHumanReadableSize(), wxGetDiskSpace() - */ - static wxULongLong GetTotalSize(const wxString& dir, - wxArrayString* filesSkipped = NULL); - - /** - Returns @true if the directory contains any files matching the given - @a filespec. If @a filespec is empty, look for any files at all. In any - case, even hidden files are taken into account. - */ - bool HasFiles(const wxString& filespec = wxEmptyString) const; - - /** - Returns @true if the directory contains any subdirectories (if a non - empty @a filespec is given, only check for directories matching it). - The hidden subdirectories are taken into account as well. - */ - bool HasSubDirs(const wxString& dirspec = wxEmptyString) const; - - /** - Returns @true if the directory was successfully opened by a previous - call to Open(). - */ - bool IsOpened() const; - - /** - Open the directory for enumerating, returns @true on success or @false - if an error occurred. - */ - bool Open(const wxString& dir); - - /** - Enumerate all files and directories under the given directory - recursively calling the element of the provided wxDirTraverser object - for each of them. - - More precisely, the function will really recurse into subdirectories if - @a flags contains ::wxDIR_DIRS flag. It will ignore the files (but - still possibly recurse into subdirectories) if ::wxDIR_FILES flag is - given. - - For each found directory, @ref wxDirTraverser::OnDir() "sink.OnDir()" - is called and @ref wxDirTraverser::OnFile() "sink.OnFile()" is called - for every file. Depending on the return value, the enumeration may - continue or stop. - - The function returns the total number of files found or @c "(size_t)-1" - on error. - - @see GetAllFiles() - */ - size_t Traverse(wxDirTraverser& sink, - const wxString& filespec = wxEmptyString, - int flags = wxDIR_DEFAULT); -}; - diff --git a/interface/dirctrl.h b/interface/dirctrl.h deleted file mode 100644 index b83c4248df..0000000000 --- a/interface/dirctrl.h +++ /dev/null @@ -1,190 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: dirctrl.h -// Purpose: interface of wxGenericDirCtrl -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxGenericDirCtrl - @wxheader{dirctrl.h} - - This control can be used to place a directory listing (with optional - files) on an arbitrary window. - - The control contains a wxTreeCtrl window representing the directory - hierarchy, and optionally, a wxChoice window containing a list of filters. - - @beginStyleTable - @style{wxDIRCTRL_DIR_ONLY} - Only show directories, and not files. - @style{wxDIRCTRL_3D_INTERNAL} - Use 3D borders for internal controls. - @style{wxDIRCTRL_SELECT_FIRST} - When setting the default path, select the first file in the - directory. - @style{wxDIRCTRL_EDIT_LABELS} - Allow the folder and file labels to be editable. - @endStyleTable - - @library{wxbase} - @category{ctrl} - -*/ -class wxGenericDirCtrl : public wxControl -{ -public: - /** - Default constructor. - */ - wxGenericDirCtrl(); - /** - Main constructor. - - @param parent - Parent window. - @param id - Window identifier. - @param dir - Initial folder. - @param pos - Position. - @param size - Size. - @param style - Window style. Please see wxGenericDirCtrl for a list of possible - styles. - @param filter - A filter string, using the same syntax as that for wxFileDialog. - This may be empty if filters are not being used. Example: - @c "All files (*.*)|*.*|JPEG files (*.jpg)|*.jpg" - @param defaultFilter - The zero-indexed default filter setting. - @param name - The window name. - */ - wxGenericDirCtrl(wxWindow* parent, const wxWindowID id = -1, - const wxString& dir = wxDirDialogDefaultFolderStr, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = wxDIRCTRL_3D_INTERNAL|wxBORDER_SUNKEN, - const wxString& filter = wxEmptyString, - int defaultFilter = 0, - const wxString& name = wxTreeCtrlNameStr); - - /** - Destructor. - */ - ~wxGenericDirCtrl(); - - /** - Collapse the given @a path. - */ - bool CollapsePath(const wxString& path); - - /** - Collapses the entire tree. - */ - void CollapseTree(); - - /** - Create function for two-step construction. See wxGenericDirCtrl() for - details. - */ - bool Create(wxWindow* parent, const wxWindowID id = -1, - const wxString& dir = wxDirDialogDefaultFolderStr, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = wxDIRCTRL_3D_INTERNAL|wxBORDER_SUNKEN, - const wxString& filter = wxEmptyString, - int defaultFilter = 0, - const wxString& name = wxTreeCtrlNameStr); - - /** - Tries to expand as much of the given @a path as possible, so that the - filename or directory is visible in the tree control. - */ - bool ExpandPath(const wxString& path); - - /** - Gets the default path. - */ - wxString GetDefaultPath() const; - - /** - Gets selected filename path only (else empty string). - - This function doesn't count a directory as a selection. - */ - wxString GetFilePath() const; - - /** - Returns the filter string. - */ - wxString GetFilter() const; - - /** - Returns the current filter index (zero-based). - */ - int GetFilterIndex() const; - - /** - Returns a pointer to the filter list control (if present). - */ - wxDirFilterListCtrl* GetFilterListCtrl() const; - - /** - Gets the currently-selected directory or filename. - */ - wxString GetPath() const; - - /** - Returns the root id for the tree control. - */ - wxTreeItemId GetRootId(); - - /** - Returns a pointer to the tree control. - */ - wxTreeCtrl* GetTreeCtrl() const; - - /** - Initializes variables. - */ - void Init(); - - /** - Collapse and expand the tree, thus re-creating it from scratch. May be - used to update the displayed directory content. - */ - void ReCreateTree(); - - /** - Sets the default path. - */ - void SetDefaultPath(const wxString& path); - - /** - Sets the filter string. - */ - void SetFilter(const wxString& filter); - - /** - Sets the current filter index (zero-based). - */ - void SetFilterIndex(int n); - - /** - Sets the current path. - */ - void SetPath(const wxString& path); - - /** - @param show - If @true, hidden folders and files will be displayed by the - control. If @false, they will not be displayed. - */ - void ShowHidden(bool show); -}; - diff --git a/interface/dirdlg.h b/interface/dirdlg.h deleted file mode 100644 index 4d21deac85..0000000000 --- a/interface/dirdlg.h +++ /dev/null @@ -1,132 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: dirdlg.h -// Purpose: interface of wxDirDialog -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxDirDialog - @wxheader{dirdlg.h} - - This class represents the directory chooser dialog. - - @beginStyleTable - @style{wxDD_DEFAULT_STYLE} - Equivalent to a combination of wxDEFAULT_DIALOG_STYLE and - wxRESIZE_BORDER (the last one is not used under wxWinCE). - @style{wxDD_DIR_MUST_EXIST} - The dialog will allow the user to choose only an existing folder. - When this style is not given, a "Create new directory" button is - added to the dialog (on Windows) or some other way is provided to - the user to type the name of a new folder. - @style{wxDD_CHANGE_DIR} - Change the current working directory to the directory chosen by the - user. - @endStyleTable - - @note On Windows the new directory button is only available with recent - versions of the common dialogs. - - @library{wxcore} - @category{cmndlg} - - @see @ref overview_cmndlg_dir, wxFileDialog -*/ -class wxDirDialog : public wxDialog -{ -public: - /** - Constructor. Use ShowModal() to show the dialog. - - @param parent - Parent window. - @param message - Message to show on the dialog. - @param defaultPath - The default path, or the empty string. - @param style - The dialog style. See wxDirDialog - @param pos - Dialog position. Ignored under Windows. - @param size - Dialog size. Ignored under Windows. - @param name - The dialog name, not used. - */ - wxDirDialog(wxWindow* parent, - const wxString& message = "Choose a directory", - const wxString& defaultPath = "", - long style = wxDD_DEFAULT_STYLE, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - const wxString& name = "wxDirCtrl"); - - /** - Destructor. - */ - ~wxDirDialog(); - - /** - Returns the message that will be displayed on the dialog. - */ - wxString GetMessage() const; - - /** - Returns the default or user-selected path. - */ - wxString GetPath() const; - - /** - Sets the message that will be displayed on the dialog. - */ - void SetMessage(const wxString& message); - - /** - Sets the default path. - */ - void SetPath(const wxString& path); - - /** - Shows the dialog, returning wxID_OK if the user pressed OK, and - wxID_CANCEL otherwise. - */ - int ShowModal(); -}; - - - -// ============================================================================ -// Global functions/macros -// ============================================================================ - -/** @ingroup group_funcmacro_dialog */ -//@{ - -/** - Pops up a directory selector dialog. The arguments have the same meaning - as those of wxDirDialog::wxDirDialog(). The message is displayed at the - top, and the default_path, if specified, is set as the initial selection. - - The application must check for an empty return value (if the user pressed - Cancel). For example: - - @code - const wxString& dir = wxDirSelector("Choose a folder"); - if ( !dir.empty() ) - { - ... - } - @endcode - - @header{wx/dirdlg.h} -*/ -wxString wxDirSelector(const wxString& message = wxDirSelectorPromptStr, - const wxString& default_path = "", - long style = 0, - const wxPoint& pos = wxDefaultPosition, - wxWindow* parent = NULL); - -//@} - diff --git a/interface/display.h b/interface/display.h deleted file mode 100644 index 71eeeba4f5..0000000000 --- a/interface/display.h +++ /dev/null @@ -1,128 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: display.h -// Purpose: interface of wxDisplay -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxDisplay - @wxheader{display.h} - - Determines the sizes and locations of displays connected to the system. - - @library{wxcore} - @category{misc} - - @see wxClientDisplayRect(), wxDisplaySize(), wxDisplaySizeMM() -*/ -class wxDisplay -{ -public: - /** - Constructor, setting up a wxDisplay instance with the specified - display. - - @param index - The index of the display to use. This must be non-negative and - lower than the value returned by GetCount(). - */ - wxDisplay(unsigned index = 0); - - /** - Destructor. - */ - ~wxDisplay(); - - /** - Changes the video mode of this display to the mode specified in the - mode parameter. - - If wxDefaultVideoMode is passed in as the mode parameter, the defined - behaviour is that wxDisplay will reset the video mode to the default - mode used by the display. On Windows, the behavior is normal. However, - there are differences on other platforms. On Unix variations using X11 - extensions it should behave as defined, but some irregularities may - occur. - - On wxMac passing in wxDefaultVideoMode as the mode parameter does - nothing. This happens because carbon no longer has access to - @c DMUseScreenPrefs(), an undocumented function that changed the video - mode to the system default by using the system's "scrn" resource. - */ - bool ChangeMode(const wxVideoMode& mode = wxDefaultVideoMode); - - /** - Returns the client area of the display. The client area is the part of - the display available for the normal (non full screen) windows, usually - it is the same as GetGeometry() but it could be less if there is a - taskbar (or equivalent) on this display. - */ - wxRect GetClientArea() const; - - /** - Returns the number of connected displays. - */ - static unsigned GetCount(); - - /** - Returns the current video mode that this display is in. - */ - wxVideoMode GetCurrentMode() const; - - /** - Returns the bit depth of the display whose index was passed to the - constructor. - */ - int GetDepth() const; - - /** - Returns the index of the display on which the given point lies, or - @c wxNOT_FOUND if the point is not on any connected display. - - @param pt - The point to locate. - */ - static int GetFromPoint(const wxPoint& pt); - - /** - Returns the index of the display on which the given window lies. - - If the window is on more than one display it gets the display that - overlaps the window the most. - - Returns @c wxNOT_FOUND if the window is not on any connected display. - - @param win - The window to locate. - */ - static int GetFromWindow(const wxWindow* win); - - /** - Returns the bounding rectangle of the display whose index was passed to - the constructor. - - @see GetClientArea(), wxDisplaySize() - */ - wxRect GetGeometry() const; - - /** - Fills and returns an array with all the video modes that are supported - by this display, or video modes that are supported by this display and - match the mode parameter (if mode is not wxDefaultVideoMode). - */ - wxArrayVideoModes GetModes(const wxVideoMode& mode = wxDefaultVideoMode) const; - - /** - Returns the display's name. A name is not available on all platforms. - */ - wxString GetName() const; - - /** - Returns @true if the display is the primary display. The primary - display is the one whose index is 0. - */ - bool IsPrimary(); -}; - diff --git a/interface/dnd.h b/interface/dnd.h deleted file mode 100644 index a6d5890f2d..0000000000 --- a/interface/dnd.h +++ /dev/null @@ -1,359 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: dnd.h -// Purpose: interface of wxDropSource and wx*DropTarget -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxTextDropTarget - @wxheader{dnd.h} - - A predefined drop target for dealing with text data. - - @library{wxcore} - @category{dnd} - - @see @ref overview_dnd, wxDropSource, wxDropTarget, wxFileDropTarget -*/ -class wxTextDropTarget : public wxDropTarget -{ -public: - /** - Constructor. - */ - wxTextDropTarget(); - - /** - See wxDropTarget::OnDrop(). This function is implemented appropriately - for text, and calls OnDropText(). - */ - virtual bool OnDrop(long x, long y, const void data, size_t size); - - /** - Override this function to receive dropped text. - - @param x - The x coordinate of the mouse. - @param y - The y coordinate of the mouse. - @param data - The data being dropped: a wxString. - - Return @true to accept the data, or @false to veto the operation. - */ - virtual bool OnDropText(wxCoord x, wxCoord y, const wxString& data); -}; - - - -/** - Result returned from a wxDropSource::DoDragDrop() call. -*/ -enum wxDragResult -{ - wxDragError, ///< Error prevented the D&D operation from completing. - wxDragNone, ///< Drag target didn't accept the data. - wxDragCopy, ///< The data was successfully copied. - wxDragMove, ///< The data was successfully moved (MSW only). - wxDragLink, ///< Operation is a drag-link. - wxDragCancel ///< The operation was cancelled by user (not an error). -}; - -/** - @class wxDropTarget - @wxheader{dnd.h} - - This class represents a target for a drag and drop operation. A - wxDataObject can be associated with it and by default, this object will be - filled with the data from the drag source, if the data formats supported by - the data object match the drag source data format. - - There are various virtual handler functions defined in this class which may - be overridden to give visual feedback or react in a more fine-tuned way, - e.g. by not accepting data on the whole window area, but only a small - portion of it. The normal sequence of calls is OnEnter(), OnDragOver() - possibly many times, OnDrop() and finally OnData(). - - @library{wxcore} - @category{dnd} - - @see @ref overview_dnd, @ref overview_dataobject, wxDropSource, - wxTextDropTarget, wxFileDropTarget, wxDataFormat, wxDataObject -*/ -class wxDropTarget -{ -public: - /** - Constructor. @a data is the data to be associated with the drop target. - */ - wxDropTarget(wxDataObject* data = NULL); - - /** - Destructor. Deletes the associated data object, if any. - */ - ~wxDropTarget(); - - /** - This method may only be called from within OnData(). By default, this - method copies the data from the drop source to the wxDataObject - associated with this drop target, calling its wxDataObject::SetData() - method. - */ - virtual void GetData(); - - /** - Called after OnDrop() returns @true. By default this will usually - GetData() and will return the suggested default value @a def. - */ - virtual wxDragResult OnData(wxCoord x, wxCoord y, wxDragResult def); - - /** - Called when the mouse is being dragged over the drop target. By - default, this calls functions return the suggested return value @a def. - - @param x - The x coordinate of the mouse. - @param y - The y coordinate of the mouse. - @param def - Suggested value for return value. Determined by SHIFT or CONTROL - key states. - - @return The desired operation or wxDragNone. This is used for optical - feedback from the side of the drop source, typically in form - of changing the icon. - */ - virtual wxDragResult OnDragOver(wxCoord x, wxCoord y, wxDragResult def); - - /** - Called when the user drops a data object on the target. Return @false - to veto the operation. - - @param x - The x coordinate of the mouse. - @param y - The y coordinate of the mouse. - - @return @true to accept the data, or @false to veto the operation. - */ - virtual bool OnDrop(wxCoord x, wxCoord y); - - /** - Called when the mouse enters the drop target. By default, this calls - OnDragOver(). - - @param x - The x coordinate of the mouse. - @param y - The y coordinate of the mouse. - @param def - Suggested default for return value. Determined by SHIFT or CONTROL - key states. - - @return The desired operation or wxDragNone. This is used for optical - feedback from the side of the drop source, typically in form - of changing the icon. - */ - virtual wxDragResult OnEnter(wxCoord x, wxCoord y, wxDragResult def); - - /** - Called when the mouse leaves the drop target. - */ - virtual void OnLeave(); - - /** - Sets the data wxDataObject associated with the drop target and deletes - any previously associated data object. - */ - void SetDataObject(wxDataObject* data); -}; - - - -/** - @class wxDropSource - @wxheader{dnd.h} - - This class represents a source for a drag and drop operation. - - @library{wxcore} - @category{dnd} - - @see @ref overview_dnd, @ref overview_dataobject, wxDropTarget, - wxTextDropTarget, wxFileDropTarget -*/ -class wxDropSource -{ -public: - /** - This constructor requires that you must call SetData() later. - - Note that the exact type of @a iconCopy and subsequent parameters - differs between wxMSW and wxGTK: these are cursors under Windows but - icons for GTK. You should use the macro wxDROP_ICON() in portable - programs instead of directly using either of these types. - - @param win - The window which initiates the drag and drop operation. - @param iconCopy - The icon or cursor used for feedback for copy operation. - @param iconMove - The icon or cursor used for feedback for move operation. - @param iconNone - The icon or cursor used for feedback when operation can't be done. - */ - wxDropSource(wxWindow* win = NULL, - const wxIconOrCursor& iconCopy = wxNullIconOrCursor, - const wxIconOrCursor& iconMove = wxNullIconOrCursor, - const wxIconOrCursor& iconNone = wxNullIconOrCursor); - /** - Note that the exact type of @a iconCopy and subsequent parameters - differs between wxMSW and wxGTK: these are cursors under Windows but - icons for GTK. You should use the macro wxDROP_ICON() in portable - programs instead of directly using either of these types. - - @param win - The window which initiates the drag and drop operation. - @param iconCopy - The icon or cursor used for feedback for copy operation. - @param iconMove - The icon or cursor used for feedback for move operation. - @param iconNone - The icon or cursor used for feedback when operation can't be done. - */ - wxDropSource(wxDataObject& data, wxWindow* win = NULL, - const wxIconOrCursor& iconCopy = wxNullIconOrCursor, - const wxIconOrCursor& iconMove = wxNullIconOrCursor, - const wxIconOrCursor& iconNone = wxNullIconOrCursor); - - /** - Default constructor. - */ - ~wxDropSource(); - - /** - Starts the drag-and-drop operation which will terminate when the user - releases the mouse. Call this in response to a mouse button press, for - example. - - @param flags - If wxDrag_AllowMove is included in the flags, data may be moved and - not only copied (default). If wxDrag_DefaultMove is specified - (which includes the previous flag), this is even the default - operation. - - @return The operation requested by the user, may be ::wxDragCopy, - ::wxDragMove, ::wxDragLink, ::wxDragCancel or ::wxDragNone if - an error occurred. - */ - virtual wxDragResult DoDragDrop(int flags = wxDrag_CopyOnly); - - /** - Returns the wxDataObject object that has been assigned previously. - */ - wxDataObject* GetDataObject(); - - /** - You may give some custom UI feedback during the drag and drop operation - by overriding this function. It is called on each mouse move, so your - implementation must not be too slow. - - @param effect - The effect to implement. One of ::wxDragCopy, ::wxDragMove, - ::wxDragLink and ::wxDragNone. - @param scrolling - @true if the window is scrolling. MSW only. - - @return @false if you want default feedback, or @true if you implement - your own feedback. The return values is ignored under GTK. - */ - virtual bool GiveFeedback(wxDragResult effect); - - /** - Set the icon to use for a certain drag result. - - @param res - The drag result to set the icon for. - @param cursor - The ion to show when this drag result occurs. - */ - void SetCursor(wxDragResult res, const wxCursor& cursor); - - /** - Sets the data wxDataObject associated with the drop source. This will - not delete any previously associated data. - */ - void SetData(wxDataObject& data); -}; - - - -/** - @class wxFileDropTarget - @wxheader{dnd.h} - - This is a drop target which accepts files (dragged from File Manager or - Explorer). - - @library{wxcore} - @category{dnd} - - @see @ref overview_dnd, wxDropSource, wxDropTarget, wxTextDropTarget -*/ -class wxFileDropTarget : public wxDropTarget -{ -public: - /** - Constructor. - */ - wxFileDropTarget(); - - /** - See wxDropTarget::OnDrop(). This function is implemented appropriately - for files, and calls OnDropFiles(). - */ - virtual bool OnDrop(long x, long y, const void data, size_t size); - - /** - Override this function to receive dropped files. - - @param x - The x coordinate of the mouse. - @param y - The y coordinate of the mouse. - @param filenames - An array of filenames. - - Return @true to accept the data, or @false to veto the operation. - */ - virtual bool OnDropFiles(wxCoord x, wxCoord y, - const wxArrayString& filenames); -}; - - - -// ============================================================================ -// Global functions/macros -// ============================================================================ - -/** @ingroup group_funcmacro_gdi */ -//@{ - -/** - This macro creates either a cursor (MSW) or an icon (elsewhere) with the - given @a name (of type const char*). Under MSW, the cursor is - loaded from the resource file and the icon is loaded from XPM file under - other platforms. - - This macro should be used with wxDropSource::wxDropSource(). - - @return wxCursor on MSW, otherwise returns a wxIcon - - @header{wx/dnd.h} -*/ -#define wxDROP_ICON(name) - -//@} - diff --git a/interface/docmdi.h b/interface/docmdi.h deleted file mode 100644 index 758fba89b6..0000000000 --- a/interface/docmdi.h +++ /dev/null @@ -1,149 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: docmdi.h -// Purpose: interface of wxDocMDIParentFrame and wxDocMDIChildFrame -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxDocMDIParentFrame - @wxheader{docmdi.h} - - The wxDocMDIParentFrame class provides a default top-level frame for - applications using the document/view framework. This class can only be used - for MDI parent frames. - - It cooperates with the wxView, wxDocument, wxDocManager and wxDocTemplate - classes. - - @library{wxcore} - @category{docview} - - @see @ref overview_docview, @ref page_samples_docview, wxMDIParentFrame -*/ -class wxDocMDIParentFrame : public wxMDIParentFrame -{ -public: - //@{ - /** - Constructor. - */ - wxDocMDIParentFrame(); - wxDocMDIParentFrame(wxDocManager* manager, wxFrame* parent, - wxWindowID id, - const wxString& title, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = wxDEFAULT_FRAME_STYLE, - const wxString& name = "frame"); - //@} - - /** - Destructor. - */ - ~wxDocMDIParentFrame(); - - /** - Creates the window. - */ - bool Create(wxDocManager* manager, wxFrame* parent, - wxWindowID id, const wxString& title, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = wxDEFAULT_FRAME_STYLE, - const wxString& name = "frame"); - - /** - Deletes all views and documents. If no user input cancelled the - operation, the frame will be destroyed and the application will exit. - - Since understanding how document/view clean-up takes place can be - difficult, the implementation of this function is shown below: - - @code - void wxDocParentFrame::OnCloseWindow(wxCloseEvent& event) - { - if (m_docManager->Clear(!event.CanVeto())) - { - this->Destroy(); - } - else - event.Veto(); - } - @endcode - */ - void OnCloseWindow(wxCloseEvent& event); -}; - - - -/** - @class wxDocMDIChildFrame - @wxheader{docmdi.h} - - The wxDocMDIChildFrame class provides a default frame for displaying - documents on separate windows. This class can only be used for MDI child - frames. - - The class is part of the document/view framework supported by wxWidgets, - and cooperates with the wxView, wxDocument, wxDocManager and wxDocTemplate - classes. - - @library{wxcore} - @category{docview} - - @see @ref overview_docview, @ref page_samples_docview, wxMDIChildFrame -*/ -class wxDocMDIChildFrame : public wxMDIChildFrame -{ -public: - /** - Constructor. - */ - wxDocMDIChildFrame(wxDocument* doc, wxView* view, - wxFrame* parent, wxWindowID id, - const wxString& title, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = wxDEFAULT_FRAME_STYLE, - const wxString& name = "frame"); - - /** - Destructor. - */ - ~wxDocMDIChildFrame(); - - /** - Returns the document associated with this frame. - */ - wxDocument* GetDocument() const; - - /** - Returns the view associated with this frame. - */ - wxView* GetView() const; - - /** - Sets the currently active view to be the frame's view. You may need - to override (but still call) this function in order to set the keyboard - focus for your subwindow. - */ - void OnActivate(wxActivateEvent event); - - /** - Closes and deletes the current view and document. - */ - void OnCloseWindow(wxCloseEvent& event); - - /** - Sets the document for this frame. - */ - void SetDocument(wxDocument* doc); - - /** - Sets the view for this frame. - */ - void SetView(wxView* view); -}; - diff --git a/interface/docview.h b/interface/docview.h deleted file mode 100644 index b41ae9b3a8..0000000000 --- a/interface/docview.h +++ /dev/null @@ -1,1475 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: docview.h -// Purpose: interface of various doc/view framework classes -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxDocTemplate - @wxheader{docview.h} - - The wxDocTemplate class is used to model the relationship between a - document class and a view class. - - @library{wxcore} - @category{docview} - - @see @ref overview_docview_wxdoctemplate, wxDocument, wxView -*/ -class wxDocTemplate : public wxObject -{ -public: - /** - Constructor. Create instances dynamically near the start of your - application after creating a wxDocManager instance, and before doing - any document or view operations. - - @param manager - The document manager object which manages this template. - @param descr - A short description of what the template is for. This string will - be displayed in the file filter list of Windows file selectors. - @param filter - An appropriate file filter such as "*.txt". - @param dir - The default directory to use for file selectors. - @param ext - The default file extension (such as "txt"). - @param docTypeName - A name that should be unique for a given type of document, used for - gathering a list of views relevant to a particular document. - @param viewTypeName - A name that should be unique for a given view. - @param docClassInfo - A pointer to the run-time document class information as returned by - the CLASSINFO() macro, e.g. CLASSINFO(MyDocumentClass). If this is - not supplied, you will need to derive a new wxDocTemplate class and - override the CreateDocument() member to return a new document - instance on demand. - @param viewClassInfo - A pointer to the run-time view class information as returned by the - CLASSINFO() macro, e.g. CLASSINFO(MyViewClass). If this is not - supplied, you will need to derive a new wxDocTemplate class and - override the CreateView() member to return a new view instance on - demand. - @param flags - A bit list of the following: - - wxTEMPLATE_VISIBLE - The template may be displayed to the - user in dialogs. - - wxTEMPLATE_INVISIBLE - The template may not be displayed to - the user in dialogs. - - wxDEFAULT_TEMPLATE_FLAGS - Defined as wxTEMPLATE_VISIBLE. - */ - wxDocTemplate(wxDocManager* manager, const wxString& descr, - const wxString& filter, const wxString& dir, - const wxString& ext, const wxString& docTypeName, - const wxString& viewTypeName, - wxClassInfo* docClassInfo = NULL, - wxClassInfo* viewClassInfo = NULL, - long flags = wxDEFAULT_TEMPLATE_FLAGS); - - /** - Destructor. - */ - ~wxDocTemplate(); - - /** - Creates a new instance of the associated document class. If you have - not supplied a wxClassInfo parameter to the template constructor, you - will need to override this function to return an appropriate document - instance. - - This function calls InitDocument() which in turns calls - wxDocument::OnCreate(). - */ - wxDocument* CreateDocument(const wxString& path, long flags = 0); - - /** - Creates a new instance of the associated view class. If you have not - supplied a wxClassInfo parameter to the template constructor, you will - need to override this function to return an appropriate view instance. - */ - wxView* CreateView(wxDocument* doc, long flags = 0); - - /** - Returns the default file extension for the document data, as passed to - the document template constructor. - */ - wxString GetDefaultExtension(); - - /** - Returns the text description of this template, as passed to the - document template constructor. - */ - wxString GetDescription(); - - /** - Returns the default directory, as passed to the document template - constructor. - */ - wxString GetDirectory(); - - /** - Returns a pointer to the document manager instance for which this - template was created. - */ - wxDocManager* GetDocumentManager(); - - /** - Returns the document type name, as passed to the document template - constructor. - */ - wxString GetDocumentName(); - - /** - Returns the file filter, as passed to the document template - constructor. - */ - wxString GetFileFilter(); - - /** - Returns the flags, as passed to the document template constructor. - */ - long GetFlags(); - - /** - Returns the view type name, as passed to the document template - constructor. - */ - wxString GetViewName(); - - /** - Initialises the document, calling wxDocument::OnCreate(). This is - called from CreateDocument(). - */ - bool InitDocument(wxDocument* doc, const wxString& path, long flags = 0); - - /** - Returns @true if the document template can be shown in user dialogs, - @false otherwise. - */ - bool IsVisible(); - - /** - Sets the default file extension. - */ - void SetDefaultExtension(const wxString& ext); - - /** - Sets the template description. - */ - void SetDescription(const wxString& descr); - - /** - Sets the default directory. - */ - void SetDirectory(const wxString& dir); - - /** - Sets the pointer to the document manager instance for which this - template was created. Should not be called by the application. - */ - void SetDocumentManager(wxDocManager* manager); - - /** - Sets the file filter. - */ - void SetFileFilter(const wxString& filter); - - /** - Sets the internal document template flags (see the constructor - description for more details). - */ - void SetFlags(long flags); - - /** - The default extension for files of this type. - */ - wxString m_defaultExt; - - /** - A short description of this template. - */ - wxString m_description; - - /** - The default directory for files of this type. - */ - wxString m_directory; - - /** - Run-time class information that allows document instances to be - constructed dynamically. - */ - wxClassInfo* m_docClassInfo; - - /** - The named type of the document associated with this template. - */ - wxString m_docTypeName; - - /** - A pointer to the document manager for which this template was created. - */ - wxDocTemplate* m_documentManager; - - /** - The file filter (such as "*.txt") to be used in file selector dialogs. - */ - wxString m_fileFilter; - - /** - The flags passed to the constructor. - */ - long m_flags; - - /** - Run-time class information that allows view instances to be constructed - dynamically. - */ - wxClassInfo* m_viewClassInfo; - - /** - The named type of the view associated with this template. - */ - wxString m_viewTypeName; -}; - - - -/** - @class wxDocManager - @wxheader{docview.h} - - The wxDocManager class is part of the document/view framework supported by - wxWidgets, and cooperates with the wxView, wxDocument and wxDocTemplate - classes. - - @library{wxcore} - @category{docview} - - @see @ref overview_docview_wxdocmanager, wxDocument, wxView, wxDocTemplate, - wxFileHistory -*/ -class wxDocManager : public wxEvtHandler -{ -public: - /** - Constructor. Create a document manager instance dynamically near the - start of your application before doing any document or view operations. - - @a flags is currently unused. - - If @a initialize is @true, the Initialize() function will be called to - create a default history list object. If you derive from wxDocManager, - you may wish to call the base constructor with @false, and then call - Initialize() in your own constructor, to allow your own Initialize() or - OnCreateFileHistory functions to be called. - */ - wxDocManager(long flags = wxDEFAULT_DOCMAN_FLAGS, - bool initialize = true); - - /** - Destructor. - */ - ~wxDocManager(); - - /** - Sets the current view. - */ - void ActivateView(wxView* doc, bool activate = true); - - /** - Adds the document to the list of documents. - */ - void AddDocument(wxDocument* doc); - - /** - Adds a file to the file history list, if we have a pointer to an - appropriate file menu. - */ - void AddFileToHistory(const wxString& filename); - - /** - Adds the template to the document manager's template list. - */ - void AssociateTemplate(wxDocTemplate* temp); - - /** - Closes all currently opened documents. - */ - bool CloseDocuments(bool force = true); - - /** - Creates a new document in a manner determined by the @a flags - parameter, which can be: - - - wxDOC_NEW - Creates a fresh document. - - wxDOC_SILENT - Silently loads the given document file. - - If wxDOC_NEW is present, a new document will be created and returned, - possibly after asking the user for a template to use if there is more - than one document template. If wxDOC_SILENT is present, a new document - will be created and the given file loaded into it. If neither of these - flags is present, the user will be presented with a file selector for - the file to load, and the template to use will be determined by the - extension (Windows) or by popping up a template choice list (other - platforms). - - If the maximum number of documents has been reached, this function will - delete the oldest currently loaded document before creating a new one. - */ - wxDocument* CreateDocument(const wxString& path, long flags); - - /** - Creates a new view for the given document. If more than one view is - allowed for the document (by virtue of multiple templates mentioning - the same document type), a choice of view is presented to the user. - */ - wxView* CreateView(wxDocument* doc, long flags); - - /** - Removes the template from the list of templates. - */ - void DisassociateTemplate(wxDocTemplate* temp); - - /** - Appends the files in the history list to all menus managed by the file - history object. - */ - void FileHistoryAddFilesToMenu(); - /** - Appends the files in the history list to the given @a menu only. - */ - void FileHistoryAddFilesToMenu(wxMenu* menu); - - /** - Loads the file history from a config object. - - @see wxConfigBase - */ - void FileHistoryLoad(const wxConfigBase& config); - - /** - Removes the given menu from the list of menus managed by the file - history object. - */ - void FileHistoryRemoveMenu(wxMenu* menu); - - /** - Saves the file history into a config object. This must be called - explicitly by the application. - - @see wxConfigBase - */ - void FileHistorySave(wxConfigBase& resourceFile); - - /** - Use this menu for appending recently-visited document filenames, for - convenient access. Calling this function with a valid menu pointer - enables the history list functionality. - - @note You can add multiple menus using this function, to be managed by - the file history object. - */ - void FileHistoryUseMenu(wxMenu* menu); - - /** - Given a path, try to find template that matches the extension. This is - only an approximate method of finding a template for creating a - document. - */ - wxDocTemplate* FindTemplateForPath(const wxString& path); - - /** - Returns the document associated with the currently active view (if - any). - */ - wxDocument* GetCurrentDocument(); - - /** - Returns the currently active view - */ - wxView* GetCurrentView(); - - /** - Returns a reference to the list of documents. - */ - wxList GetDocuments(); - - /** - Returns a pointer to file history. - */ - wxFileHistory* GetFileHistory(); - - /** - Returns the number of files currently stored in the file history. - */ - size_t GetHistoryFilesCount(); - - /** - Returns the directory last selected by the user when opening a file. - Initially empty. - */ - wxString GetLastDirectory() const; - - /** - Returns the number of documents that can be open simultaneously. - */ - int GetMaxDocsOpen(); - - /** - Returns a reference to the list of associated templates. - */ - wxList GetTemplates(); - - /** - Initializes data; currently just calls OnCreateFileHistory(). - - Some data cannot always be initialized in the constructor because the - programmer must be given the opportunity to override functionality. If - OnCreateFileHistory() was called from the constructor, an overridden - virtual OnCreateFileHistory() would not be called due to C++'s - 'interesting' constructor semantics. In fact Initialize() @e is called - from the wxDocManager constructor, but this can be vetoed by passing - @false to the second argument, allowing the derived class's constructor - to call Initialize(), possibly calling a different - OnCreateFileHistory() from the default. - - The bottom line: if you're not deriving from Initialize(), forget it - and construct wxDocManager with no arguments. - */ - bool Initialize(); - - /** - Return a string containing a suitable default name for a new document. - By default this is implemented by appending an integer counter to the - string @b unnamed but can be overridden in the derived classes to do - something more appropriate. - */ - wxString MakeNewDocumentName(); - - /** - A hook to allow a derived class to create a different type of file - history. Called from Initialize(). - */ - wxFileHistory* OnCreateFileHistory(); - - /** - Closes and deletes the currently active document. - */ - void OnFileClose(wxCommandEvent& event); - - /** - Closes and deletes all the currently opened documents. - */ - void OnFileCloseAll(wxCommandEvent& event); - - /** - Creates a document from a list of templates (if more than one - template). - */ - void OnFileNew(wxCommandEvent& event); - - /** - Creates a new document and reads in the selected file. - */ - void OnFileOpen(wxCommandEvent& event); - - /** - Reverts the current document by calling wxDocument::Revert() for the - current document. - */ - void OnFileRevert(wxCommandEvent& event); - - /** - Saves the current document by calling wxDocument::Save() for the - current document. - */ - void OnFileSave(wxCommandEvent& event); - - /** - Calls wxDocument::SaveAs() for the current document. - */ - void OnFileSaveAs(wxCommandEvent& event); - - /** - Removes the document from the list of documents. - */ - void RemoveDocument(wxDocument* doc); - - /** - Under Windows, pops up a file selector with a list of filters - corresponding to document templates. The wxDocTemplate corresponding to - the selected file's extension is returned. - - On other platforms, if there is more than one document template a - choice list is popped up, followed by a file selector. - - This function is used in CreateDocument(). - */ - wxDocTemplate* SelectDocumentPath(wxDocTemplate** templates, - int noTemplates, wxString& path, - long flags, bool save); - - /** - Returns a document template by asking the user (if there is more than - one template). This function is used in CreateDocument(). - - @param templates - Pointer to an array of templates from which to choose a desired - template. - @param noTemplates - Number of templates being pointed to by the templates pointer. - @param sort - If more than one template is passed in in templates, then this - parameter indicates whether the list of templates that the user - will have to choose from is sorted or not when shown the choice box - dialog. Default is @false. - */ - wxDocTemplate* SelectDocumentType(wxDocTemplate** templates, - int noTemplates, bool sort = false); - - /** - Returns a document template by asking the user (if there is more than - one template), displaying a list of valid views. This function is used - in CreateView(). The dialog normally will not appear because the array - of templates only contains those relevant to the document in question, - and often there will only be one such. - - @param templates - Pointer to an array of templates from which to choose a desired - template. - @param noTemplates - Number of templates being pointed to by the templates pointer. - @param sort - If more than one template is passed in in templates, then this - parameter indicates whether the list of templates that the user - will have to choose from is sorted or not when shown the choice box - dialog. Default is @false. - */ - wxDocTemplate* SelectViewType(wxDocTemplate** templates, - int noTemplates, bool sort = false); - - /** - Sets the directory to be displayed to the user when opening a file. - Initially this is empty. - */ - void SetLastDirectory(const wxString& dir); - - /** - Sets the maximum number of documents that can be open at a time. By - default, this is 10,000. If you set it to 1, existing documents will be - saved and deleted when the user tries to open or create a new one - (similar to the behaviour of Windows Write, for example). Allowing - multiple documents gives behaviour more akin to MS Word and other - Multiple Document Interface applications. - */ - void SetMaxDocsOpen(int n); - - /** - The currently active view. - */ - wxView* m_currentView; - - /** - Stores the integer to be used for the next default document name. - */ - int m_defaultDocumentNameCounter; - - /** - A list of all documents. - */ - wxList m_docs; - - /** - A pointer to an instance of wxFileHistory, which manages the history of - recently-visited files on the File menu. - */ - wxFileHistory* m_fileHistory; - - /** - Stores the flags passed to the constructor. - */ - long m_flags; - - /** - The directory last selected by the user when opening a file. - */ - wxFileHistory* m_fileHistory; - - /** - Stores the maximum number of documents that can be opened before - existing documents are closed. By default, this is 10,000. - */ - int m_maxDocsOpen; -}; - - - -/** - @class wxView - @wxheader{docview.h} - - The view class can be used to model the viewing and editing component of - an application's file-based data. It is part of the document/view framework - supported by wxWidgets, and cooperates with the wxDocument, wxDocTemplate - and wxDocManager classes. - - @library{wxcore} - @category{docview} - - @see @ref overview_docview_wxview, wxDocument, wxDocTemplate, wxDocManager -*/ -class wxView : public wxEvtHandler -{ -public: - /** - Constructor. Define your own default constructor to initialize - application-specific data. - */ - wxView(); - - /** - Destructor. Removes itself from the document's list of views. - */ - ~wxView(); - - /** - Call this from your view frame's wxDocChildFrame::OnActivate() member - to tell the framework which view is currently active. If your windowing - system doesn't call wxDocChildFrame::OnActivate(), you may need to call - this function from any place where you know the view must be active, - and the framework will need to get the current view. - - The prepackaged view frame wxDocChildFrame calls Activate() from its - wxDocChildFrame::OnActivate() member. - - This function calls OnActivateView(). - */ - virtual void Activate(bool activate); - - /** - Closes the view by calling OnClose(). If @a deleteWindow is @true, this - function should delete the window associated with the view. - */ - virtual bool Close(bool deleteWindow = true); - - /** - Gets a pointer to the document associated with the view. - */ - wxDocument* GetDocument() const; - - /** - Returns a pointer to the document manager instance associated with this - view. - */ - wxDocManager* GetDocumentManager() const; - - /** - Gets the frame associated with the view (if any). Note that this - "frame" is not a wxFrame at all in the generic MDI implementation which - uses notebook pages instead of frames and this is why this method - returns a wxWindow and not a wxFrame. - */ - wxWindow* GetFrame(); - - /** - Gets the name associated with the view (passed to the wxDocTemplate - constructor). Not currently used by the framework. - */ - wxString GetViewName() const; - - /** - Called when a view is activated by means of Activate(). The default - implementation does nothing. - */ - virtual void OnActivateView(bool activate, wxView* activeView, - wxView* deactiveView); - - /** - Called when the filename has changed. The default implementation - constructs a suitable title and sets the title of the view frame (if - any). - */ - virtual void OnChangeFilename(); - - /** - Implements closing behaviour. The default implementation calls - wxDocument::Close() to close the associated document. Does not delete - the view. The application may wish to do some cleaning up operations in - this function, @e if a call to wxDocument::Close() succeeded. For - example, if your views all share the same window, you need to - disassociate the window from the view and perhaps clear the window. If - @a deleteWindow is @true, delete the frame associated with the view. - */ - virtual bool OnClose(bool deleteWindow); - - /** - Override this to clean up the view when the document is being closed. - */ - virtual void OnClosingDocument(); - - /** - wxDocManager or wxDocument creates a wxView via a wxDocTemplate. Just - after the wxDocTemplate creates the wxView, it calls OnCreate(). The - wxView can create a wxDocChildFrame (or derived class) in its - wxView::OnCreate() member function. This wxDocChildFrame provides user - interface elements to view and/or edit the contents of the wxDocument. - - By default, simply returns @true. If the function returns @false, the - view will be deleted. - */ - virtual bool OnCreate(wxDocument* doc, long flags); - - /** - If the printing framework is enabled in the library, this function - returns a wxPrintout object for the purposes of printing. It should - create a new object every time it is called; the framework will delete - objects it creates. - - By default, this function returns an instance of wxDocPrintout, which - prints and previews one page by calling OnDraw(). - - Override to return an instance of a class other than wxDocPrintout. - */ - virtual wxPrintout* OnCreatePrintout(); - - /** - Override this function to render the view on the given device context. - */ - virtual void OnDraw(wxDC* dc); - - /** - Called when the view should be updated. - - @param sender - A pointer to the wxView that sent the update request, or @NULL if - no single view requested the update (for instance, when the - document is opened). - @param hint - This is unused currently, but may in future contain - application-specific information for making updating more - efficient. - */ - virtual void OnUpdate(wxView* sender, wxObject* hint); - - /** - Associates the given document with the view. Normally called by the - framework. - */ - void SetDocument(wxDocument* doc); - - /** - Sets the frame associated with this view. The application should call - this if possible, to tell the view about the frame. - - See GetFrame() for the explanation about the mismatch between the - "Frame" in the method name and the type of its parameter. - */ - void SetFrame(wxWindow* frame); - - /** - Sets the view type name. Should only be called by the framework. - */ - void SetViewName(const wxString& name); - - /** - The document associated with this view. There may be more than one view - per document, but there can never be more than one document for one - view. - */ - wxDocument* m_viewDocument; - - /** - Frame associated with the view, if any. - */ - wxFrame* m_viewFrame; - - /** - The view type name given to the wxDocTemplate constructor, copied to - this variable when the view is created. Not currently used by the - framework. - */ - wxString m_viewTypeName; -}; - - - -/** - @class wxDocChildFrame - @wxheader{docview.h} - - The wxDocChildFrame class provides a default frame for displaying documents - on separate windows. This class can only be used for SDI (not MDI) child - frames. - - The class is part of the document/view framework supported by wxWidgets, - and cooperates with the wxView, wxDocument, wxDocManager and wxDocTemplate - classes. - - @library{wxcore} - @category{docview} - - @see @ref overview_docview, @ref page_samples_docview, wxFrame -*/ -class wxDocChildFrame : public wxFrame -{ -public: - /** - Constructor. - */ - wxDocChildFrame(wxDocument* doc, wxView* view, wxFrame* parent, - wxWindowID id, const wxString& title, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = wxDEFAULT_FRAME_STYLE, - const wxString& name = "frame"); - - /** - Destructor. - */ - ~wxDocChildFrame(); - - /** - Returns the document associated with this frame. - */ - wxDocument* GetDocument() const; - - /** - Returns the view associated with this frame. - */ - wxView* GetView() const; - - /** - Sets the currently active view to be the frame's view. You may need to - override (but still call) this function in order to set the keyboard - focus for your subwindow. - */ - void OnActivate(wxActivateEvent event); - - /** - Closes and deletes the current view and document. - */ - void OnCloseWindow(wxCloseEvent& event); - - /** - Sets the document for this frame. - */ - void SetDocument(wxDocument* doc); - - /** - Sets the view for this frame. - */ - void SetView(wxView* view); - - /** - The document associated with the frame. - */ - wxDocument* m_childDocument; - - /** - The view associated with the frame. - */ - wxView* m_childView; -}; - - - -/** - @class wxDocParentFrame - @wxheader{docview.h} - - The wxDocParentFrame class provides a default top-level frame for - applications using the document/view framework. This class can only be used - for SDI (not MDI) parent frames. - - It cooperates with the wxView, wxDocument, wxDocManager and wxDocTemplate - classes. - - @library{wxcore} - @category{docview} - - @see @ref overview_docview, @ref page_samples_docview, wxFrame -*/ -class wxDocParentFrame : public wxFrame -{ -public: - /** - Default constructor. - */ - wxDocParentFrame(); - /** - Constructor. - */ - wxDocParentFrame(wxDocManager* manager, wxFrame* parent, - wxWindowID id, const wxString& title, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = wxDEFAULT_FRAME_STYLE, - const wxString& name = "frame"); - - /** - Destructor. - */ - ~wxDocParentFrame(); - - /** - Used in two-step construction. - */ - bool Create(wxDocManager* manager, wxFrame* parent, - wxWindowID id, const wxString& title, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = wxDEFAULT_FRAME_STYLE, - const wxString& name = "frame"); - - /** - Returns the associated document manager object. - */ - wxDocManager* GetDocumentManager() const; - - /** - Deletes all views and documents. If no user input cancelled the - operation, the frame will be destroyed and the application will exit. - Since understanding how document/view clean-up takes place can be - difficult, the implementation of this function is shown below: - - @code - void wxDocParentFrame::OnCloseWindow(wxCloseEvent& event) - { - if (m_docManager->Clear(!event.CanVeto())) - { - this->Destroy(); - } - else - event.Veto(); - } - @endcode - */ - void OnCloseWindow(wxCloseEvent& event); -}; - - - -/** - @class wxDocument - @wxheader{docview.h} - - The document class can be used to model an application's file-based data. - It is part of the document/view framework supported by wxWidgets, and - cooperates with the wxView, wxDocTemplate and wxDocManager classes. - - @library{wxcore} - @category{docview} - - @see @ref overview_docview, wxView, wxDocTemplate, wxDocManager -*/ -class wxDocument : public wxEvtHandler -{ -public: - /** - Constructor. Define your own default constructor to initialize - application-specific data. - */ - wxDocument(); - - /** - Destructor. Removes itself from the document manager. - */ - ~wxDocument(); - - /** - If the view is not already in the list of views, adds the view and - calls OnChangedViewList(). - */ - virtual bool AddView(wxView* view); - - /** - Closes the document, by calling OnSaveModified() and then (if this - returned @true) OnCloseDocument(). This does not normally delete the - document object, use DeleteAllViews() to do this implicitly. - */ - virtual bool Close(); - - /** - Calls wxView::Close() and deletes each view. Deleting the final view - will implicitly delete the document itself, because the wxView - destructor calls RemoveView(). This in turns calls OnChangedViewList(), - whose default implemention is to save and delete the document if no - views exist. - */ - virtual bool DeleteAllViews(); - - /** - Returns a pointer to the command processor associated with this - document. - - @see wxCommandProcessor - */ - wxCommandProcessor* GetCommandProcessor() const; - - /** - Gets a pointer to the associated document manager. - */ - wxDocManager* GetDocumentManager() const; - - /** - Gets the document type name for this document. See the comment for - @ref m_documentTypeName. - */ - wxString GetDocumentName() const; - - /** - Gets a pointer to the template that created the document. - */ - wxDocTemplate* GetDocumentTemplate() const; - - /** - Intended to return a suitable window for using as a parent for - document-related dialog boxes. By default, uses the frame associated - with the first view. - */ - wxWindow* GetDocumentWindow() const; - - /** - Gets the filename associated with this document, or "" if none is - associated. - */ - wxString GetFilename() const; - - /** - A convenience function to get the first view for a document, because in - many cases a document will only have a single view. - - @see GetViews() - */ - wxView* GetFirstView() const; - - /** - Gets the title for this document. The document title is used for an - associated frame (if any), and is usually constructed by the framework - from the filename. - */ - wxString GetTitle() const; - - /** - Return the document name suitable to be shown to the user. The default - implementation uses the document title, if any, of the name part of the - document filename if it was set or, otherwise, the string @b unnamed. - */ - virtual wxString GetUserReadableName() const; - - /** - Returns the list whose elements are the views on the document. - - @see GetFirstView() - */ - wxList GetViews() const; - - /** - Returns @true if the document has been modified since the last save, - @false otherwise. You may need to override this if your document view - maintains its own record of being modified. - - @see Modify() - */ - virtual bool IsModified() const; - - //@{ - /** - Override this function and call it from your own LoadObject() before - streaming your own data. LoadObject() is called by the framework - automatically when the document contents need to be loaded. - - @note This version of LoadObject() may not exist depending on how - wxWidgets was configured. - */ - virtual istream& LoadObject(istream& stream); - virtual wxInputStream& LoadObject(wxInputStream& stream); - //@} - - /** - Call with @true to mark the document as modified since the last save, - @false otherwise. You may need to override this if your document view - maintains its own record of being modified. - - @see IsModified() - */ - virtual void Modify(bool modify); - - /** - Called when a view is added to or deleted from this document. The - default implementation saves and deletes the document if no views exist - (the last one has just been removed). - */ - virtual void OnChangedViewList(); - - /** - The default implementation calls DeleteContents() (an empty - implementation) and sets the modified flag to @false. Override this to - supply additional behaviour when the document is closed with Close(). - */ - virtual bool OnCloseDocument(); - - /** - Called just after the document object is created to give it a chance to - initialize itself. The default implementation uses the template - associated with the document to create an initial view. If this - function returns @false, the document is deleted. - */ - virtual bool OnCreate(const wxString& path, long flags); - - /** - Override this function if you want a different (or no) command - processor to be created when the document is created. By default, it - returns an instance of wxCommandProcessor. - - @see wxCommandProcessor - */ - virtual wxCommandProcessor* OnCreateCommandProcessor(); - - /** - The default implementation calls OnSaveModified() and DeleteContents(), - makes a default title for the document, and notifies the views that the - filename (in fact, the title) has changed. - */ - virtual bool OnNewDocument(); - - /** - Constructs an input file stream for the given filename (which must not - be empty), and calls LoadObject(). If LoadObject() returns @true, the - document is set to unmodified; otherwise, an error message box is - displayed. The document's views are notified that the filename has - changed, to give windows an opportunity to update their titles. All of - the document's views are then updated. - */ - virtual bool OnOpenDocument(const wxString& filename); - - /** - Constructs an output file stream for the given filename (which must not - be empty), and calls SaveObject(). If SaveObject() returns @true, the - document is set to unmodified; otherwise, an error message box is - displayed. - */ - virtual bool OnSaveDocument(const wxString& filename); - - /** - If the document has been modified, prompts the user to ask if the - changes should be changed. If the user replies Yes, the Save() function - is called. If No, the document is marked as unmodified and the function - succeeds. If Cancel, the function fails. - */ - virtual bool OnSaveModified(); - - /** - Removes the view from the document's list of views, and calls - OnChangedViewList(). - */ - virtual bool RemoveView(wxView* view); - - /** - Saves the document by calling OnSaveDocument() if there is an - associated filename, or SaveAs() if there is no filename. - */ - virtual bool Save(); - - /** - Prompts the user for a file to save to, and then calls - OnSaveDocument(). - */ - virtual bool SaveAs(); - - //@{ - /** - Override this function and call it from your own SaveObject() before - streaming your own data. SaveObject() is called by the framework - automatically when the document contents need to be saved. - - @note This version of SaveObject() may not exist depending on how - wxWidgets was configured. - */ - virtual ostream& SaveObject(ostream& stream); - virtual wxOutputStream& SaveObject(wxOutputStream& stream); - //@} - - /** - Sets the command processor to be used for this document. The document - will then be responsible for its deletion. Normally you should not call - this; override OnCreateCommandProcessor() instead. - - @see wxCommandProcessor - */ - virtual void SetCommandProcessor(wxCommandProcessor* processor); - - /** - Sets the document type name for this document. See the comment for - @ref m_documentTypeName. - */ - void SetDocumentName(const wxString& name); - - /** - Sets the pointer to the template that created the document. Should only - be called by the framework. - */ - void SetDocumentTemplate(wxDocTemplate* templ); - - /** - Sets the filename for this document. Usually called by the framework. - - If @a notifyViews is @true, wxView::OnChangeFilename() is called for - all views. - */ - void SetFilename(const wxString& filename, bool notifyViews = false); - - /** - Sets the title for this document. The document title is used for an - associated frame (if any), and is usually constructed by the framework - from the filename. - */ - void SetTitle(const wxString& title); - - /** - Updates all views. If @a sender is non-@NULL, does not update this - view. @a hint represents optional information to allow a view to - optimize its update. - */ - void UpdateAllViews(wxView* sender = NULL, wxObject* hint = NULL); - -protected: - /** - This method is called by OnSaveDocument() to really save the document - contents to the specified file. - - Base class version creates a file-based stream and calls SaveObject(). - Override this if you need to do something else or prefer not to use - SaveObject() at all. - */ - virtual bool DoSaveDocument(const wxString& file); - - /** - This method is called by OnOpenDocument() to really load the document - contents from the specified file. - - Base class version creates a file-based stream and calls LoadObject(). - Override this if you need to do something else or prefer not to use - LoadObject() at all. - */ - virtual bool DoOpenDocument(const wxString& file); - - /** - A pointer to the command processor associated with this document. - */ - wxCommandProcessor* m_commandProcessor; - - /** - Filename associated with this document ("" if none). - */ - wxString m_documentFile; - - /** - @true if the document has been modified, @false otherwise. - */ - bool m_documentModified; - - /** - A pointer to the template from which this document was created. - */ - wxDocTemplate* m_documentTemplate; - - /** - Document title. The document title is used for an associated frame (if - any), and is usually constructed by the framework from the filename. - */ - wxString m_documentTitle; - - /** - The document type name given to the wxDocTemplate constructor, copied - to this variable when the document is created. If several document - templates are created that use the same document type, this variable is - used in wxDocManager::CreateView() to collate a list of alternative - view types that can be used on this kind of document. Do not change the - value of this variable. - */ - wxString m_documentTypeName; - - /** - List of wxView instances associated with this document. - */ - wxList m_documentViews; -}; - - - -/** - @class wxFileHistory - @wxheader{docview.h} - - The wxFileHistory encapsulates a user interface convenience, the list of - most recently visited files as shown on a menu (usually the File menu). - - wxFileHistory can manage one or more file menus. More than one menu may be - required in an MDI application, where the file history should appear on - each MDI child menu as well as the MDI parent frame. - - @library{wxcore} - @category{docview} - - @see @ref overview_docview, wxDocManager -*/ -class wxFileHistory : public wxObject -{ -public: - /** - Constructor. Pass the maximum number of files that should be stored and - displayed. - - @a idBase defaults to wxID_FILE1 and represents the id given to the - first history menu item. Since menu items can't share the same ID you - should change @a idBase (to one of your own defined IDs) when using - more than one wxFileHistory in your application. - */ - wxFileHistory(size_t maxFiles = 9, wxWindowID idBase = wxID_FILE1); - - /** - Destructor. - */ - ~wxFileHistory(); - - /** - Adds a file to the file history list, if the object has a pointer to an - appropriate file menu. - */ - void AddFileToHistory(const wxString& filename); - - /** - Appends the files in the history list, to all menus managed by the file - history object. - */ - void AddFilesToMenu(); - /** - Appends the files in the history list, to the given menu only. - */ - void AddFilesToMenu(wxMenu* menu); - - /** - Returns the base identifier for the range used for appending items. - */ - wxWindowID GetBaseId() const; - - /** - Returns the number of files currently stored in the file history. - */ - size_t GetCount() const; - - /** - Returns the file at this index (zero-based). - */ - wxString GetHistoryFile(size_t index) const; - - /** - Returns the maximum number of files that can be stored. - */ - int GetMaxFiles() const; - - /** - Returns the list of menus that are managed by this file history object. - - @see UseMenu() - */ - const wxList& GetMenus() const; - - /** - Loads the file history from the given config object. This function - should be called explicitly by the application. - - @see wxConfigBase - */ - void Load(const wxConfigBase& config); - - /** - Removes the specified file from the history. - */ - void RemoveFileFromHistory(size_t i); - - /** - Removes this menu from the list of those managed by this object. - */ - void RemoveMenu(wxMenu* menu); - - /** - Saves the file history into the given config object. This must be - called explicitly by the application. - - @see wxConfigBase - */ - void Save(wxConfigBase& config); - - /** - Sets the base identifier for the range used for appending items. - */ - void SetBaseId(wxWindowID baseId); - - /** - Adds this menu to the list of those menus that are managed by this file - history object. Also see AddFilesToMenu() for initializing the menu - with filenames that are already in the history when this function is - called, as this is not done automatically. - */ - void UseMenu(wxMenu* menu); - - /** - A character array of strings corresponding to the most recently opened - files. - */ - char** m_fileHistory; - - /** - The number of files stored in the history array. - */ - size_t m_fileHistoryN; - - /** - The maximum number of files to be stored and displayed on the menu. - */ - size_t m_fileMaxFiles; - - /** - The file menu used to display the file history list (if enabled). - */ - wxMenu* m_fileMenu; -}; - - - -// ============================================================================ -// Global functions/macros -// ============================================================================ - -/** @ingroup group_funcmacro_file */ -//@{ - -/** - Copies the given file to @a stream. Useful when converting an old - application to use streams (within the document/view framework, for - example). - - @header{wx/docview.h} -*/ -bool wxTransferFileToStream(const wxString& filename, - ostream& stream); - -/** - Copies the given stream to the file @a filename. Useful when converting an - old application to use streams (within the document/view framework, for - example). - - @header{wx/docview.h} -*/ -bool wxTransferStreamToFile(istream& stream, - const wxString& filename); - -//@} - diff --git a/interface/dragimag.h b/interface/dragimag.h deleted file mode 100644 index 9de1317021..0000000000 --- a/interface/dragimag.h +++ /dev/null @@ -1,262 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: dragimag.h -// Purpose: interface of wxDragImage -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxDragImage - @wxheader{dragimag.h} - - This class is used when you wish to drag an object on the screen, and a - simple cursor is not enough. - - On Windows, the Win32 API is used to achieve smooth dragging. On other - platforms, wxGenericDragImage is used. Applications may also prefer to use - wxGenericDragImage on Windows, too. - - @beginWxPythonOnly - wxPython uses wxGenericDragImage on all platforms, but uses the wxDragImage - name. - @endWxPythonOnly - - To use this class, when you wish to start dragging an image, create a - wxDragImage object and store it somewhere you can access it as the drag - progresses. Call BeginDrag() to start, and EndDrag() to stop the drag. To - move the image, initially call Show() and then Move(). If you wish to - update the screen contents during the drag (for example, highlight an item - as in the dragimag sample), first call Hide(), update the screen, call - Move(), and then call Show(). - - You can drag within one window, or you can use full-screen dragging either - across the whole screen, or just restricted to one area of the screen to - save resources. If you want the user to drag between two windows, then you - will need to use full-screen dragging. - - If you wish to draw the image yourself, use wxGenericDragImage and override - DoDrawImage() and GetImageRect(). - - @library{wxcore} - @category{dnd} - - @see @ref page_samples_dragimag -*/ -class wxDragImage : public wxObject -{ -public: - /** - Default constructor. - */ - wxDragImage(); - /** - Constructs a drag image from a bitmap and optional cursor. - - @param image - Bitmap to be used as the drag image. The bitmap can have a mask. - @param cursor - Optional cursor to combine with the image. - @param cursorHotspot - This parameter is deprecated. - */ - wxDragImage(const wxBitmap& image, const wxCursor& cursor = wxNullCursor, - const wxPoint& cursorHotspot = wxPoint(0, 0)); - /** - Constructs a drag image from an icon and optional cursor. - - @param image - Icon to be used as the drag image. - @param cursor - Optional cursor to combine with the image. - @param cursorHotspot - This parameter is deprecated. - - @beginWxPythonOnly - This constructor is called wxDragIcon in wxPython. - @endWxPythonOnly - */ - wxDragImage(const wxIcon& image, const wxCursor& cursor = wxNullCursor, - const wxPoint& cursorHotspot = wxPoint(0, 0)); - /** - Constructs a drag image from a text string and optional cursor. - - @param text - Text used to construct a drag image. - @param cursor - Optional cursor to combine with the image. - @param cursorHotspot - This parameter is deprecated. - - @beginWxPythonOnly - This constructor is called wxDragString in wxPython. - @endWxPythonOnly - */ - wxDragImage(const wxString& text, const wxCursor& cursor = wxNullCursor, - const wxPoint& cursorHotspot = wxPoint(0, 0)); - /** - Constructs a drag image from the text in the given tree control item, - and optional cursor. - - @param treeCtrl - Tree control for constructing a tree drag image. - @param id - Tree control item id. - - @beginWxPythonOnly - This constructor is called wxDragTreeItem in wxPython. - @endWxPythonOnly - */ - wxDragImage(const wxTreeCtrl& treeCtrl, wxTreeItemId& id); - /** - Constructs a drag image from the text in the given list control item, - and optional cursor. - - @param listCtrl - List control for constructing a list drag image. - @param id - List control item id. - - @beginWxPythonOnly - This constructor is called wxDragListItem in wxPython. - @endWxPythonOnly - */ - wxDragImage(const wxListCtrl& listCtrl, long id); - /** - Constructs a drag image an optional cursor. This constructor is only - available for wxGenericDragImage, and can be used when the application - supplies DoDrawImage() and GetImageRect(). - - @param cursor - Optional cursor to combine with the image. - @param cursorHotspot - This parameter is deprecated. - */ - wxDragImage(const wxCursor& cursor = wxNullCursor, - const wxPoint& cursorHotspot = wxPoint(0, 0)); - - /** - Start dragging the image, in a window or full screen. - - You need to then call Show() and Move() to show the image on the - screen. Call EndDrag() when the drag has finished. - - Note that this call automatically calls CaptureMouse(). - - @param hotspot - The location of the drag position relative to the upper-left corner - of the image. - @param window - The window that captures the mouse, and within which the dragging - is limited unless fullScreen is @true. - @param fullScreen - If @true, specifies that the drag will be visible over the full - screen, or over as much of the screen as is specified by rect. Note - that the mouse will still be captured in window. - @param rect - If non-@NULL, specifies the rectangle (in screen coordinates) that - bounds the dragging operation. Specifying this can make the - operation more efficient by cutting down on the area under - consideration, and it can also make a visual difference since the - drag is clipped to this area. - */ - bool BeginDrag(const wxPoint& hotspot, wxWindow* window, - bool fullScreen = false, wxRect* rect = NULL); - /** - Start dragging the image, using the first window to capture the mouse - and the second to specify the bounding area. This form is equivalent to - using the first form, but more convenient than working out the bounding - rectangle explicitly. - - You need to then call Show() and Move() to show the image on the - screen. Call EndDrag() when the drag has finished. - - Note that this call automatically calls CaptureMouse(). - - @param hotspot - The location of the drag position relative to the upper-left corner - of the image. - @param window - The window that captures the mouse, and within which the dragging - is limited. - @param boundingWindow - Specifies the area within which the drag occurs. - */ - bool BeginDrag(const wxPoint& hotspot, wxWindow* window, - wxWindow* boundingWindow); - - /** - Draws the image on the device context with top-left corner at the given - position. - - This function is only available with wxGenericDragImage, to allow - applications to draw their own image instead of using an actual bitmap. - If you override this function, you must also override GetImageRect(). - */ - virtual bool DoDrawImage(wxDC& dc, const wxPoint& pos); - - /** - Call this when the drag has finished. - - @note This function automatically releases mouse capture. - */ - bool EndDrag(); - - /** - Returns the rectangle enclosing the image, assuming that the image is - drawn with its top-left corner at the given point. - - This function is available in wxGenericDragImage only, and may be - overridden (together with DoDrawImage()) to provide a virtual drawing - capability. - */ - virtual wxRect GetImageRect(const wxPoint& pos) const; - - /** - Hides the image. You may wish to call this before updating the window - contents (perhaps highlighting an item). Then call Move() and Show(). - */ - bool Hide(); - - /** - Call this to move the image to a new position. The image will only be - shown if Show() has been called previously (for example at the start of - the drag). - - @param pt - The position in client coordinates (relative to the window - specified in BeginDrag()). - - You can move the image either when the image is hidden or shown, but in - general dragging will be smoother if you move the image when it is - shown. - */ - bool Move(const wxPoint& pt); - - /** - Shows the image. Call this at least once when dragging. - */ - bool Show(); - - /** - Override this if you wish to draw the window contents to the backing - bitmap yourself. This can be desirable if you wish to avoid flicker by - not having to redraw the updated window itself just before dragging, - which can cause a flicker just as the drag starts. Instead, paint the - drag image's backing bitmap to show the appropriate graphic @e minus - the objects to be dragged, and leave the window itself to be updated by - the drag image. This can provide eerily smooth, flicker-free drag - behaviour. - - The default implementation copies the window contents to the backing - bitmap. A new implementation will normally copy information from - another source, such as from its own backing bitmap if it has one, or - directly from internal data structures. - - This function is available in wxGenericDragImage only. - */ - bool UpdateBackingFromWindow(wxDC& windowDC, wxMemoryDC& destDC, - const wxRect& sourceRect, - const wxRect& destRect) const; -}; - diff --git a/interface/dynarray.h b/interface/dynarray.h deleted file mode 100644 index d5d16b352c..0000000000 --- a/interface/dynarray.h +++ /dev/null @@ -1,772 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: dynarray.h -// Purpose: interface of wxArray -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @wxheader{dynarray.h} - - This section describes the so called @e "dynamic arrays". This is a C - array-like type safe data structure i.e. the member access time is constant - (and not linear according to the number of container elements as for linked - lists). However, these arrays are dynamic in the sense that they will - automatically allocate more memory if there is not enough of it for adding - a new element. They also perform range checking on the index values but in - debug mode only, so please be sure to compile your application in debug - mode to use it (see @ref overview_debugging for details). So, unlike the - arrays in some other languages, attempt to access an element beyond the - arrays bound doesn't automatically expand the array but provokes an - assertion failure instead in debug build and does nothing (except possibly - crashing your program) in the release build. - - The array classes were designed to be reasonably efficient, both in terms - of run-time speed and memory consumption and the executable size. The speed - of array item access is, of course, constant (independent of the number of - elements) making them much more efficient than linked lists (wxList). - Adding items to the arrays is also implemented in more or less constant - time, but the price is preallocating the memory in advance. In the - "memory management" function section, you may find some useful hints about - optimizing wxArray memory usage. As for executable size, all wxArray - functions are inline, so they do not take @e any space at all. - - wxWidgets has three different kinds of array. All of them derive from - wxBaseArray class which works with untyped data and can not be used - directly. The standard macros WX_DEFINE_ARRAY(), WX_DEFINE_SORTED_ARRAY() - and WX_DEFINE_OBJARRAY() are used to define a new class deriving from it. - The classes declared will be called in this documentation wxArray, - wxSortedArray and wxObjArray but you should keep in mind that no classes - with such names actually exist, each time you use one of the - WX_DEFINE_XXXARRAY() macros, you define a class with a new name. In fact, - these names are "template" names and each usage of one of the macros - mentioned above creates a template specialization for the given element - type. - - wxArray is suitable for storing integer types and pointers which it does - not treat as objects in any way, i.e. the element pointed to by the pointer - is not deleted when the element is removed from the array. It should be - noted that all of wxArray's functions are inline, so it costs strictly - nothing to define as many array types as you want (either in terms of the - executable size or the speed) as long as at least one of them is defined - and this is always the case because wxArrays are used by wxWidgets - internally. This class has one serious limitation: it can only be used for - storing integral types (bool, char, short, int, long and their unsigned - variants) or pointers (of any kind). An attempt to use with objects of - @c sizeof() greater than @c sizeof(long) will provoke a runtime assertion - failure, however declaring a wxArray of floats will not (on the machines - where @c "sizeof(float) <= sizeof(long)"), yet it will @b not work, please - use wxObjArray for storing floats and doubles. - - wxSortedArray is a wxArray variant which should be used when searching in - the array is a frequently used operation. It requires you to define an - additional function for comparing two elements of the array element type - and always stores its items in the sorted order (according to this - function). Thus, its Index() function execution time is @c "O(log(N))" - instead of @c "O(N)" for the usual arrays but the Add() method is slower: - it is @c "O(log(N))" instead of constant time (neglecting time spent in - memory allocation routine). However, in a usual situation elements are - added to an array much less often than searched inside it, so wxSortedArray - may lead to huge performance improvements compared to wxArray. Finally, it - should be noticed that, as wxArray, wxSortedArray can be only used for - storing integral types or pointers. - - wxObjArray class treats its elements like "objects". It may delete them - when they are removed from the array (invoking the correct destructor) and - copies them using the objects copy constructor. In order to implement this - behaviour the definition of the wxObjArray arrays is split in two parts: - first, you should declare the new wxObjArray class using the - WX_DECLARE_OBJARRAY() macro and then you must include the file defining the - implementation of template type: @ and define the array - class with the WX_DEFINE_OBJARRAY() macro from a point where the full (as - opposed to 'forward') declaration of the array elements class is in scope. - As it probably sounds very complicated here is an example: - - @code - #include - - // We must forward declare the array because it is used - // inside the class declaration. - class MyDirectory; - class MyFile; - - // This defines two new types: ArrayOfDirectories and ArrayOfFiles which - // can be now used as shown below. - WX_DECLARE_OBJARRAY(MyDirectory, ArrayOfDirectories); - WX_DECLARE_OBJARRAY(MyFile, ArrayOfFiles); - - class MyDirectory - { - // ... - ArrayOfDirectories m_subdirectories; // All subdirectories - ArrayOfFiles m_files; // All files in this directory - }; - - // ... - - // Now that we have MyDirectory declaration in scope we may finish the - // definition of ArrayOfDirectories -- note that this expands into some C++ - // code and so should only be compiled once (i.e., don't put this in the - // header, but into a source file or you will get linking errors) - #include // This is a magic incantation which must be done! - WX_DEFINE_OBJARRAY(ArrayOfDirectories); - - // that's all! - @endcode - - It is not as elegant as writing this: - - @code - typedef std::vector ArrayOfDirectories; - @endcode - - But is not that complicated and allows the code to be compiled with any, - however dumb, C++ compiler in the world. - - Remember to include @ just before each - WX_DEFINE_OBJARRAY() ocurrence in your code, even if you have several in - the same file. - - Things are much simpler for wxArray and wxSortedArray however: it is enough - just to write: - - @code - WX_DEFINE_ARRAY_INT(int, ArrayOfInts); - WX_DEFINE_SORTED_ARRAY_INT(int, ArrayOfSortedInts); - @endcode - - There is only one @c DEFINE macro and no need for separate @c DECLARE one. - For the arrays of the primitive types, the macros - @c WX_DEFINE_ARRAY_CHAR/SHORT/INT/SIZE_T/LONG/DOUBLE should be used - depending on the sizeof of the values (notice that storing values of - smaller type, e.g. shorts, in an array of larger one, e.g. @c ARRAY_INT, - does not work on all architectures!). - - - @section array_macros Macros for Template Array Definition - - To use an array you must first define the array class. This is done with - the help of the macros in this section. The class of array elements must be - (at least) forward declared for WX_DEFINE_ARRAY(), WX_DEFINE_SORTED_ARRAY() - and WX_DECLARE_OBJARRAY() macros and must be fully declared before you use - WX_DEFINE_OBJARRAY() macro. - - - WX_DEFINE_ARRAY() - - WX_DEFINE_EXPORTED_ARRAY() - - WX_DEFINE_USER_EXPORTED_ARRAY() - - WX_DEFINE_SORTED_ARRAY() - - WX_DEFINE_SORTED_EXPORTED_ARRAY() - - WX_DEFINE_SORTED_USER_EXPORTED_ARRAY() - - WX_DECLARE_EXPORTED_OBJARRAY() - - WX_DECLARE_USER_EXPORTED_OBJARRAY() - - WX_DEFINE_OBJARRAY() - - WX_DEFINE_EXPORTED_OBJARRAY() - - WX_DEFINE_USER_EXPORTED_OBJARRAY() - - To slightly complicate the matters even further, the operator "->" defined - by default for the array iterators by these macros only makes sense if the - array element type is not a pointer itself and, although it still works, - this provokes warnings from some compilers and to avoid them you should use - the @c _PTR versions of the macros above. For example, to define an array - of pointers to @c double you should use: - - @code - WX_DEFINE_ARRAY_PTR(double *, MyArrayOfDoublePointers); - @endcode - - Note that the above macros are generally only useful for wxObject types. - There are separate macros for declaring an array of a simple type, such as - an int. - - The following simple types are supported: - - @c int - - @c long - - @c size_t - - @c double - - To create an array of a simple type, simply append the type you want in - CAPS to the array definition. - - For example, you'd use one of the following variants for an integer array: - - - WX_DEFINE_ARRAY_INT() - - WX_DEFINE_EXPORTED_ARRAY_INT() - - WX_DEFINE_USER_EXPORTED_ARRAY_INT() - - WX_DEFINE_SORTED_ARRAY_INT() - - WX_DEFINE_SORTED_EXPORTED_ARRAY_INT() - - WX_DEFINE_SORTED_USER_EXPORTED_ARRAY_INT() - - - @library{wxbase} - @category{containers} - - @see @ref overview_container, wxList, wxVector -*/ -class wxArray -{ -public: - /** - @name Constructors and Destructors - - Array classes are 100% C++ objects and as such they have the - appropriate copy constructors and assignment operators. Copying wxArray - just copies the elements but copying wxObjArray copies the arrays - items. However, for memory-efficiency sake, neither of these classes - has virtual destructor. It is not very important for wxArray which has - trivial destructor anyhow, but it does mean that you should avoid - deleting wxObjArray through a wxBaseArray pointer (as you would never - use wxBaseArray anyhow it shouldn't be a problem) and that you should - not derive your own classes from the array classes. - */ - //@{ - - /** - Default constructor. - */ - wxArray(); - /** - Default constructor initializes an empty array object. - */ - wxObjArray(); - /** - There is no default constructor for wxSortedArray classes - you must - initialize it with a function to use for item comparison. It is a - function which is passed two arguments of type @c T where @c T is the - array element type and which should return a negative, zero or positive - value according to whether the first element passed to it is less than, - equal to or greater than the second one. - */ - wxSortedArray(int (*)(T first, T second)compareFunction); - - /** - Performs a shallow array copy (i.e. doesn't copy the objects pointed to - even if the source array contains the items of pointer type). - */ - wxArray(const wxArray& array); - /** - Performs a shallow array copy (i.e. doesn't copy the objects pointed to - even if the source array contains the items of pointer type). - */ - wxSortedArray(const wxSortedArray& array); - /** - Performs a deep copy (i.e. the array element are copied too). - */ - wxObjArray(const wxObjArray& array); - - /** - Performs a shallow array copy (i.e. doesn't copy the objects pointed to - even if the source array contains the items of pointer type). - */ - wxArray& operator=(const wxArray& array); - /** - Performs a shallow array copy (i.e. doesn't copy the objects pointed to - even if the source array contains the items of pointer type). - */ - wxSortedArray& operator=(const wxSortedArray& array); - /** - Performs a deep copy (i.e. the array element are copied too). - */ - wxObjArray& operator=(const wxObjArray& array); - - /** - This destructor does not delete all the items owned by the array, you - may use the WX_CLEAR_ARRAY() macro for this. - */ - ~wxArray(); - /** - This destructor does not delete all the items owned by the array, you - may use the WX_CLEAR_ARRAY() macro for this. - */ - ~wxSortedArray(); - /** - This destructor deletes all the items owned by the array. - */ - ~wxObjArray(); - - //@} - - - /** - @name Memory Management - - Automatic array memory management is quite trivial: the array starts by - preallocating some minimal amount of memory (defined by - @c WX_ARRAY_DEFAULT_INITIAL_SIZE) and when further new items exhaust - already allocated memory it reallocates it adding 50% of the currently - allocated amount, but no more than some maximal number which is defined - by the @c ARRAY_MAXSIZE_INCREMENT constant. Of course, this may lead to - some memory being wasted (@c ARRAY_MAXSIZE_INCREMENT in the worst case, - i.e. 4Kb in the current implementation), so the Shrink() function is - provided to deallocate the extra memory. The Alloc() function can also - be quite useful if you know in advance how many items you are going to - put in the array and will prevent the array code from reallocating the - memory more times than needed. - */ - //@{ - - /** - Preallocates memory for a given number of array elements. It is worth - calling when the number of items which are going to be added to the - array is known in advance because it will save unneeded memory - reallocation. If the array already has enough memory for the given - number of items, nothing happens. In any case, the existing contents of - the array is not modified. - */ - void Alloc(size_t count); - - /** - Frees all memory unused by the array. If the program knows that no new - items will be added to the array it may call Shrink() to reduce its - memory usage. However, if a new item is added to the array, some extra - memory will be allocated again. - */ - void Shrink(); - - //@} - - - /** - @name Number of Elements and Simple Item Access - - Functions in this section return the total number of array elements and - allow to retrieve them - possibly using just the C array indexing [] - operator which does exactly the same as the Item() method. - */ - //@{ - - /** - Return the number of items in the array. - */ - size_t GetCount() const; - - /** - Returns @true if the array is empty, @false otherwise. - */ - bool IsEmpty() const; - - /** - Returns the item at the given position in the array. If @a index is out - of bounds, an assert failure is raised in the debug builds but nothing - special is done in the release build. - - The returned value is of type "reference to the array element type" for - all of the array classes. - */ - T& Item(size_t index) const; - - /** - Returns the last element in the array, i.e. is the same as calling - "Item(GetCount() - 1)". An assert failure is raised in the debug mode - if the array is empty. - - The returned value is of type "reference to the array element type" for - all of the array classes. - */ - T& Last() const; - - //@} - - - /** - @name Adding Items - */ - //@{ - - /** - Appends the given number of @a copies of the @a item to the array - consisting of the elements of type @c T. - - This version is used with wxArray. - - You may also use WX_APPEND_ARRAY() macro to append all elements of one - array to another one but it is more efficient to use the @a copies - parameter and modify the elements in place later if you plan to append - a lot of items. - */ - void Add(T item, size_t copies = 1); - /** - Appends the @a item to the array consisting of the elements of type - @c T. - - This version is used with wxSortedArray, returning the index where - @a item is stored. - */ - size_t Add(T item); - /** - Appends the @a item to the array consisting of the elements of type - @c T. - - This version is used with wxObjArray. The array will take ownership of - the @item, deleting it when the item is deleted from the array. Note - that you cannot append more than one pointer as reusing it would lead - to deleting it twice (or more) resulting in a crash. - - You may also use WX_APPEND_ARRAY() macro to append all elements of one - array to another one but it is more efficient to use the @a copies - parameter and modify the elements in place later if you plan to append - a lot of items. - */ - void Add(T* item); - /** - Appends the given number of @a copies of the @a item to the array - consisting of the elements of type @c T. - - This version is used with wxObjArray. The array will make a copy of the - item and will not take ownership of the original item. - - You may also use WX_APPEND_ARRAY() macro to append all elements of one - array to another one but it is more efficient to use the @a copies - parameter and modify the elements in place later if you plan to append - a lot of items. - */ - void Add(T& item, size_t copies = 1); - - /** - Inserts the given @a item into the array in the specified @e index - position. - - Be aware that you will set out the order of the array if you give a - wrong position. - - This function is useful in conjunction with IndexForInsert() for a - common operation of "insert only if not found". - */ - void AddAt(T item, size_t index); - - /** - Insert the given number of @a copies of the @a item into the array - before the existing item @a n - thus, @e Insert(something, 0u) will - insert an item in such way that it will become the first array element. - - wxSortedArray doesn't have this function because inserting in wrong - place would break its sorted condition. - - Please see Add() for an explanation of the differences between the - overloaded versions of this function. - */ - void Insert(T item, size_t n, size_t copies = 1); - /** - Insert the @a item into the array before the existing item @a n - thus, - @e Insert(something, 0u) will insert an item in such way that it will - become the first array element. - - wxSortedArray doesn't have this function because inserting in wrong - place would break its sorted condition. - - Please see Add() for an explanation of the differences between the - overloaded versions of this function. - */ - void Insert(T* item, size_t n); - /** - Insert the given number of @a copies of the @a item into the array - before the existing item @a n - thus, @e Insert(something, 0u) will - insert an item in such way that it will become the first array element. - - wxSortedArray doesn't have this function because inserting in wrong - place would break its sorted condition. - - Please see Add() for an explanation of the differences between the - overloaded versions of this function. - */ - void Insert(T& item, size_t n, size_t copies = 1); - - /** - This function ensures that the number of array elements is at least - @a count. If the array has already @a count or more items, nothing is - done. Otherwise, @a count - GetCount() elements are added and - initialized to the value @a defval. - - @see GetCount() - */ - void SetCount(size_t count, T defval = T(0)); - - //@} - - - /** - @name Removing Items - */ - //@{ - - /** - This function does the same as Empty() and additionally frees the - memory allocated to the array. - */ - void Clear(); - - /** - Removes the element from the array, but unlike Remove(), it doesn't - delete it. The function returns the pointer to the removed element. - */ - T* Detach(size_t index); - - /** - Empties the array. For wxObjArray classes, this destroys all of the - array elements. For wxArray and wxSortedArray this does nothing except - marking the array of being empty - this function does not free the - allocated memory, use Clear() for this. - */ - void Empty(); - - /** - Removes an element from the array by value: the first item of the array - equal to @a item is removed, an assert failure will result from an - attempt to remove an item which doesn't exist in the array. - - When an element is removed from wxObjArray it is deleted by the array - - use Detach() if you don't want this to happen. On the other hand, when - an object is removed from a wxArray nothing happens - you should delete - it manually if required: - - @code - T *item = array[n]; - delete item; - array.Remove(n); - @endcode - - See also WX_CLEAR_ARRAY() macro which deletes all elements of a wxArray - (supposed to contain pointers). - */ - Remove(T item); - - /** - Removes @a count elements starting at @a index from the array. When an - element is removed from wxObjArray it is deleted by the array - use - Detach() if you don't want this to happen. On the other hand, when an - object is removed from a wxArray nothing happens - you should delete it - manually if required: - - @code - T *item = array[n]; - delete item; - array.RemoveAt(n); - @endcode - - See also WX_CLEAR_ARRAY() macro which deletes all elements of a wxArray - (supposed to contain pointers). - */ - RemoveAt(size_t index, size_t count = 1); - - //@} - - - /** - @name Searching and Sorting - */ - //@{ - - /** - This version of Index() is for wxArray and wxObjArray only. - - Searches the element in the array, starting from either beginning or - the end depending on the value of @a searchFromEnd parameter. - @c wxNOT_FOUND is returned if the element is not found, otherwise the - index of the element is returned. - - @note Even for wxObjArray classes, the operator "==" of the elements in - the array is @b not used by this function. It searches exactly - the given element in the array and so will only succeed if this - element had been previously added to the array, but fail even if - another, identical, element is in the array. - */ - int Index(T& item, bool searchFromEnd = false) const; - /** - This version of Index() is for wxSortedArray only. - - Searches the element in the array, starting from either beginning or - the end depending on the value of @a searchFromEnd parameter. - @c wxNOT_FOUND is returned if the element is not found, otherwise the - index of the element is returned. - */ - const int Index(T& item) const; - - /** - Search for a place to insert @a item into the sorted array (binary - search). The index returned is just before the first existing item that - is greater or equal (according to the compare function) to the given - @a item. - - You have to do extra work to know if the @a item already exists in - array. - - This function is useful in conjunction with AddAt() for a common - operation of "insert only if not found". - */ - size_t IndexForInsert(T item) const; - - /** - The notation @c "CMPFUNCT" should be read as if we had the following - declaration: - - @code - template int CMPFUNC(T *first, T *second); - @endcode - - Where @e T is the type of the array elements. I.e. it is a function - returning @e int which is passed two arguments of type @e T*. - - Sorts the array using the specified compare function: this function - should return a negative, zero or positive value according to whether - the first element passed to it is less than, equal to or greater than - the second one. - - wxSortedArray doesn't have this function because it is always sorted. - */ - void Sort(CMPFUNC compareFunction); - - //@} -}; - - -/** - This macro may be used to append all elements of the @a other array to the - @a array. The two arrays must be of the same type. -*/ -#define WX_APPEND_ARRAY(wxArray& array, wxArray& other) - -/** - This macro may be used to delete all elements of the array before emptying - it. It can not be used with wxObjArrays - but they will delete their - elements anyway when you call Empty(). -*/ -#define WX_CLEAR_ARRAY(wxArray& array) - -//@{ -/** - This macro declares a new object array class named @a name and containing - the elements of type @e T. - - An exported array is used when compiling wxWidgets as a DLL under Windows - and the array needs to be visible outside the DLL. An user exported array - needed for exporting an array from a user DLL. - - Example: - - @code - class MyClass; - WX_DECLARE_OBJARRAY(MyClass, wxArrayOfMyClass); // note: not "MyClass *"! - @endcode - - You must use WX_DEFINE_OBJARRAY() macro to define the array class, - otherwise you would get link errors. -*/ -#define WX_DECLARE_OBJARRAY(T, name) -#define WX_DECLARE_EXPORTED_OBJARRAY(T, name) -#define WX_DECLARE_USER_EXPORTED_OBJARRAY(T, name) -//@} - -//@{ -/** - This macro defines a new array class named @a name and containing the - elements of type @a T. - - An exported array is used when compiling wxWidgets as a DLL under Windows - and the array needs to be visible outside the DLL. An user exported array - needed for exporting an array from a user DLL. - - Example: - - @code - WX_DEFINE_ARRAY_INT(int, MyArrayInt); - - class MyClass; - WX_DEFINE_ARRAY(MyClass *, ArrayOfMyClass); - @endcode - - Note that wxWidgets predefines the following standard array classes: - @b wxArrayInt, @b wxArrayLong, @b wxArrayShort, @b wxArrayDouble, - @b wxArrayPtrVoid. -*/ -#define WX_DEFINE_ARRAY(T, name) -#define WX_DEFINE_EXPORTED_ARRAY(T, name) -#define WX_DEFINE_USER_EXPORTED_ARRAY(T, name, exportspec) -//@} - -//@{ -/** - This macro defines the methods of the array class @a name not defined by - the WX_DECLARE_OBJARRAY() macro. You must include the file - @ before using this macro and you must have the full - declaration of the class of array elements in scope! If you forget to do - the first, the error will be caught by the compiler, but, unfortunately, - many compilers will not give any warnings if you forget to do the second - - but the objects of the class will not be copied correctly and their real - destructor will not be called. - - An exported array is used when compiling wxWidgets as a DLL under Windows - and the array needs to be visible outside the DLL. An user exported array - needed for exporting an array from a user DLL. - - Example of usage: - - @code - // first declare the class! - class MyClass - { - public: - MyClass(const MyClass&); - - // ... - - virtual ~MyClass(); - }; - - #include - WX_DEFINE_OBJARRAY(wxArrayOfMyClass); - @endcode -*/ -#define WX_DEFINE_OBJARRAY(name) -#define WX_DEFINE_EXPORTED_OBJARRAY(name) -#define WX_DEFINE_USER_EXPORTED_OBJARRAY(name) -//@} - -//@{ -/** - This macro defines a new sorted array class named @a name and containing - the elements of type @e T. - - An exported array is used when compiling wxWidgets as a DLL under Windows - and the array needs to be visible outside the DLL. An user exported array - needed for exporting an array from a user DLL. - - Example: - - @code - WX_DEFINE_SORTED_ARRAY_INT(int, MySortedArrayInt); - - class MyClass; - WX_DEFINE_SORTED_ARRAY(MyClass *, ArrayOfMyClass); - @endcode - - You will have to initialize the objects of this class by passing a - comparison function to the array object constructor like this: - - @code - int CompareInts(int n1, int n2) - { - return n1 - n2; - } - - MySortedArrayInt sorted(CompareInts); - - int CompareMyClassObjects(MyClass *item1, MyClass *item2) - { - // sort the items by their address... - return Stricmp(item1->GetAddress(), item2->GetAddress()); - } - - ArrayOfMyClass another(CompareMyClassObjects); - @endcode -*/ -#define WX_DEFINE_SORTED_ARRAY(T, name) -#define WX_DEFINE_SORTED_EXPORTED_ARRAY(T, name) -#define WX_DEFINE_SORTED_USER_EXPORTED_ARRAY(T, name) -//@} - -/** - This macro may be used to prepend all elements of the @a other array to the - @a array. The two arrays must be of the same type. -*/ -#define WX_PREPEND_ARRAY(wxArray& array, wxArray& other) - diff --git a/interface/dynlib.h b/interface/dynlib.h deleted file mode 100644 index 3392ef4f19..0000000000 --- a/interface/dynlib.h +++ /dev/null @@ -1,259 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: dynlib.h -// Purpose: interface of wxDynamicLibrary and wxDynamicLibraryDetails -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxDynamicLibraryDetails - @wxheader{dynlib.h} - - This class is used for the objects returned by the - wxDynamicLibrary::ListLoaded() method and contains the information about a - single module loaded into the address space of the current process. A - module in this context may be either a dynamic library or the main program - itself. - - @library{wxbase} - @category{appmanagement} -*/ -class wxDynamicLibraryDetails -{ -public: - /** - Retrieves the load address and the size of this module. - - @param addr - The pointer to the location to return load address in, may be - @NULL. - @param len - Pointer to the location to return the size of this module in - memory in, may be @NULL. - - @return @true if the load address and module size were retrieved, - @false if this information is not available. - */ - bool GetAddress(void** addr, size_t len) const; - - /** - Returns the base name of this module, e.g. @c "kernel32.dll" or - @c "libc-2.3.2.so". - */ - wxString GetName() const; - - /** - Returns the full path of this module if available, e.g. - @c "c:\windows\system32\kernel32.dll" or @c "/lib/libc-2.3.2.so". - */ - wxString GetPath() const; - - /** - Returns the version of this module, e.g. @c "5.2.3790.0" or @c "2.3.2". - The returned string is empty if the version information is not - available. - */ - wxString GetVersion() const; -}; - - - -/** - Dynamic library category used with wxDynamicLibrary::CanonicalizeName(). -*/ -enum wxDynamicLibraryCategory -{ - wxDL_LIBRARY, ///< Standard library. - wxDL_MODULE ///< Loadable module/plugin. -}; - -/** - Dynamic library plugin category used with - wxDynamicLibrary::CanonicalizePluginName(). -*/ -enum wxPluginCategory -{ - wxDL_PLUGIN_GUI, ///< Plugin that uses GUI classes. - wxDL_PLUGIN_BASE ///< wxBase-only plugin. -}; - -/** - @class wxDynamicLibrary - @wxheader{dynlib.h} - - wxDynamicLibrary is a class representing dynamically loadable library - (Windows DLL, shared library under Unix etc.). Just create an object of - this class to load a library and don't worry about unloading it -- it will - be done in the objects destructor automatically. - - The following flags can be used with wxDynamicLibrary() or Load(): - - @beginStyleTable - @style{wxDL_LAZY} - Equivalent of RTLD_LAZY under Unix, ignored elsewhere. - @style{wxDL_NOW} - Equivalent of RTLD_NOW under Unix, ignored elsewhere. - @style{wxDL_GLOBAL} - Equivalent of RTLD_GLOBAL under Unix, ignored elsewhere. - @style{wxDL_VERBATIM} - Don't try to append the appropriate extension to the library name - (this is done by default). - @style{wxDL_DEFAULT} - Default flags, same as wxDL_NOW currently. - @style{wxDL_QUIET} - Don't log an error message if the library couldn't be loaded. - @endStyleTable - - @library{wxbase} - @category{appmanagement} -*/ -class wxDynamicLibrary -{ -public: - /** - Default constructor. - */ - wxDynamicLibrary(); - /** - Constructor. Calls Load() with the given @a name. - */ - wxDynamicLibrary(const wxString& name, int flags = wxDL_DEFAULT); - - /** - Returns the platform-specific full name for the library called @a name. - E.g. it adds a @c ".dll" extension under Windows and @c "lib" prefix - and @c ".so", @c ".sl" or @c ".dylib" extension under Unix. - - @see CanonicalizePluginName() - */ - static wxString CanonicalizeName(const wxString& name, - wxDynamicLibraryCategory cat = wxDL_LIBRARY); - - /** - This function does the same thing as CanonicalizeName() but for - wxWidgets plugins. The only difference is that compiler and version - information are added to the name to ensure that the plugin which is - going to be loaded will be compatible with the main program. - */ - static wxString CanonicalizePluginName(const wxString& name, - wxPluginCategory cat = wxDL_PLUGIN_GUI); - - /** - Detaches this object from its library handle, i.e. the object will not - unload the library any longer in its destructor but it is now the - callers responsibility to do this using Unload(). - */ - wxDllType Detach(); - - /** - Return a valid handle for the main program itself or @NULL if symbols - from the main program can't be loaded on this platform. - */ - static wxDllType GetProgramHandle(); - - /** - Returns pointer to symbol @a name in the library or @NULL if the - library contains no such symbol. - - @see wxDYNLIB_FUNCTION() - */ - void* GetSymbol(const wxString& name) const; - - /** - This function is available only under Windows as it is only useful when - dynamically loading symbols from standard Windows DLLs. Such functions - have either @c 'A' (in ANSI build) or @c 'W' (in Unicode, or wide - character build) suffix if they take string parameters. Using this - function, you can use just the base name of the function and the - correct suffix is appended automatically depending on the current - build. Otherwise, this method is identical to GetSymbol(). - */ - void* GetSymbolAorW(const wxString& name) const; - - /** - Returns @true if the symbol with the given @a name is present in the - dynamic library, @false otherwise. Unlike GetSymbol(), this function - doesn't log an error message if the symbol is not found. - - @since 2.5.4 - */ - bool HasSymbol(const wxString& name) const; - - /** - Returns @true if the library was successfully loaded, @false otherwise. - */ - bool IsLoaded() const; - - /** - This static method returns a wxArray containing the details of all - modules loaded into the address space of the current project. The array - elements are objects of the type: wxDynamicLibraryDetails. The array - will be empty if an error occurred. - - This method is currently implemented only under Win32 and Linux and is - useful mostly for diagnostics purposes. - */ - static wxDynamicLibraryDetailsArray ListLoaded(); - - /** - Loads DLL with the given @a name into memory. The @a flags argument can - be a combination of the styles outlined in the class description. - - Returns @true if the library was successfully loaded, @false otherwise. - */ - bool Load(const wxString& name, int flags = wxDL_DEFAULT); - - /** - Unloads the library from memory. wxDynamicLibrary object automatically - calls this method from its destructor if it had been successfully - loaded. - */ - void Unload(); - /** - Unloads the library from memory. wxDynamicLibrary object automatically - calls this method from its destructor if it had been successfully - loaded. - - This version of Unload() is only used if you need to keep the library - in memory during a longer period of time than the scope of the - wxDynamicLibrary object. In this case you may call Detach() and store - the handle somewhere and call this static method later to unload it. - */ - static void Unload(wxDllType handle); -}; - - - -// ============================================================================ -// Global functions/macros -// ============================================================================ - -/** @ingroup group_funcmacro_misc */ -//@{ - -/** - When loading a function from a DLL you always have to cast the returned - void * pointer to the correct type and, even more annoyingly, you - have to repeat this type twice if you want to declare and define a function - pointer all in one line. - - This macro makes this slightly less painful by allowing you to specify the - type only once, as the first parameter, and creating a variable of this - type named after the function but with @c pfn prefix and initialized with - the function @a name from the wxDynamicLibrary @a dynlib. - - @param type - The type of the function. - @param name - The name of the function to load, not a string (without quotes, it is - quoted automatically by the macro). - @param dynlib - The library to load the function from. - - @header{wx/dynlib.h} -*/ -#define wxDYNLIB_FUNCTION(type, name, dynlib) - -//@} - diff --git a/interface/editlbox.h b/interface/editlbox.h deleted file mode 100644 index ae0dcb2c22..0000000000 --- a/interface/editlbox.h +++ /dev/null @@ -1,98 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: editlbox.h -// Purpose: interface of wxEditableListBox -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxEditableListBox - @wxheader{editlbox.h} - - An editable listbox is composite control that lets the user easily enter, - delete and reorder a list of strings. - - @beginStyleTable - @style{wxEL_ALLOW_NEW} - Allows the user to enter new strings. - @style{wxEL_ALLOW_EDIT} - Allows the user to edit existing strings. - @style{wxEL_ALLOW_DELETE} - Allows the user to delete existing strings. - @style{wxEL_NO_REORDER} - Does not allow the user to reorder the strings. - @style{wxEL_DEFAULT_STYLE} - Default style: wxEL_ALLOW_NEW|wxEL_ALLOW_EDIT|wxEL_ALLOW_DELETE. - @endStyleTable - - @library{wxadv} - @category{ctrl} - - @see wxListBox -*/ -class wxEditableListBox : public wxPanel -{ -public: - /** - Default ctor. - */ - wxEditableListBox(); - - /** - Constructor, creating and showing a list box. - - @param parent - Parent window. Must not be @NULL. - @param id - Window identifier. The value wxID_ANY indicates a default value. - @param label - The text shown just before the list control. - @param pos - Window position. - @param size - Window size. If wxDefaultSize is specified then the window is sized - appropriately. - @param style - Window style. See wxEditableListBox. - @param name - Window name. - - @see Create() - */ - wxEditableListBox(wxWindow* parent, wxWindowID id, - const wxString& label, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = wxEL_DEFAULT_STYLE, - const wxString& name = "editableListBox"); - - /** - Destructor, destroying the list box. - */ - ~wxEditableListBox(); - - /** - Creates the editable listbox for two-step construction. - See wxEditableListBox() for further details. - */ - bool Create(wxWindow* parent, wxWindowID id, - const wxString& label, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = wxEL_DEFAULT_STYLE, - const wxString& name = "editableListBox"); - - /** - Replaces current contents with given strings. - */ - void SetStrings(const wxArrayString& strings); - - - /** - Returns in the given array the current contents of the control - (the array will be erased before control's contents are appended). - */ - void GetSelections(wxArrayString& strings) const; -}; - diff --git a/interface/encconv.h b/interface/encconv.h deleted file mode 100644 index a7821321ce..0000000000 --- a/interface/encconv.h +++ /dev/null @@ -1,187 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: encconv.h -// Purpose: interface of wxEncodingConverter -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxEncodingConverter - @wxheader{encconv.h} - - This class is capable of converting strings between two 8-bit encodings/charsets. - It can also convert from/to Unicode (but only if you compiled wxWidgets - with wxUSE_WCHAR_T set to 1). - - Only a limited subset of encodings is supported by wxEncodingConverter: - @c wxFONTENCODING_ISO8859_1..15, @c wxFONTENCODING_CP1250..1257 and - @c wxFONTENCODING_KOI8. - - @note - - Please use wxMBConv classes instead if possible. wxCSConv has much better - support for various encodings than wxEncodingConverter. - wxEncodingConverter is useful only if you rely on wxCONVERT_SUBSTITUTE mode - of operation (see wxEncodingConverter::Init()). - - @library{wxbase} - @category{misc} - - @see wxFontMapper, wxMBConv, @ref overview_nonenglish -*/ -class wxEncodingConverter : public wxObject -{ -public: - /** - Constructor. - */ - wxEncodingConverter(); - - /** - Return @true if (any text in) multibyte encoding @a encIn can be converted to - another one (@a encOut) losslessly. - - Do not call this method with @c wxFONTENCODING_UNICODE as either parameter, - it doesn't make sense (always works in one sense and always depends - on the text to convert in the other). - */ - static bool CanConvert(wxFontEncoding encIn, - wxFontEncoding encOut); - - /** - @name Conversion functions - - @{ - */ - /** - Convert input string according to settings passed to Init() and writes - the result to output. - - All the Convert() function overloads return @true if the conversion was - lossless and @false if at least one of the characters couldn't be converted - was and replaced with '?' in the output. - - Note that if @c wxCONVERT_SUBSTITUTE was passed to Init(), substitution is - considered a lossless operation. - - @note You must call Init() before using this method! - - @note wchar_t versions of the method are not available if wxWidgets was - compiled with @c wxUSE_WCHAR_T set to 0. - */ - bool Convert(const char* input, char* output) const; - bool Convert(const wchar_t* input, wchar_t* output) const; - bool Convert(const char* input, wchar_t* output) const; - bool Convert(const wchar_t* input, char* output) const; - - /** - Convert input string according to settings passed to Init() in-place, - i.e. write the result to the same memory area. - - See the Convert(const char*,char*) const overload for more info. - */ - bool Convert(char* str) const; - bool Convert(wchar_t* str) const; - - /** - Convert a wxString and return a new wxString object. - - See the Convert(const char*,char*) const overload for more info. - */ - wxString Convert(const wxString& input) const; - //@} - - - /** - Similar to GetPlatformEquivalents(), but this one will return ALL - equivalent encodings, regardless of the platform, and including itself. - - This platform's encodings are before others in the array. - And again, if @a enc is in the array, it is the very first item in it. - */ - static wxFontEncodingArray GetAllEquivalents(wxFontEncoding enc); - - /** - Return equivalents for given font that are used under given platform. - - Supported platforms: - @li wxPLATFORM_UNIX - @li wxPLATFORM_WINDOWS - @li wxPLATFORM_OS2 - @li wxPLATFORM_MAC - @li wxPLATFORM_CURRENT - - wxPLATFORM_CURRENT means the platform this binary was compiled for. - - Examples: - - @verbatim - current platform enc returned value - ---------------------------------------------- - unix CP1250 {ISO8859_2} - unix ISO8859_2 {ISO8859_2} - windows ISO8859_2 {CP1250} - unix CP1252 {ISO8859_1,ISO8859_15} - @endverbatim - - Equivalence is defined in terms of convertibility: two encodings are - equivalent if you can convert text between then without losing - information (it may - and will - happen that you lose special chars - like quotation marks or em-dashes but you shouldn't lose any diacritics - and language-specific characters when converting between equivalent encodings). - - Remember that this function does @b NOT check for presence of - fonts in system. It only tells you what are most suitable - encodings. (It usually returns only one encoding.) - - @note Note that argument enc itself may be present in the returned array, - so that you can, as a side-effect, detect whether the encoding is - native for this platform or not. - - @note Convert() is not limited to converting between equivalent encodings, - it can convert between two arbitrary encodings. - - @note If @a enc is present in the returned array, then it is always the first - item of it. - - @note Please note that the returned array may contain no items at all. - */ - static wxFontEncodingArray GetPlatformEquivalents(wxFontEncoding enc, - int platform = wxPLATFORM_CURRENT); - - /** - Initialize the conversion. - - Both output or input encoding may be wxFONTENCODING_UNICODE, but only - if wxUSE_ENCODING is set to 1. - - All subsequent calls to Convert() will interpret its argument - as a string in @a input_enc encoding and will output string in - @a output_enc encoding. - - You must call this method before calling Convert. You may call - it more than once in order to switch to another conversion. - - @a method affects behaviour of Convert() in case input character - cannot be converted because it does not exist in output encoding: - - @li @b wxCONVERT_STRICT: follow behaviour of GNU Recode - just copy - unconvertible characters to output and don't change them - (its integer value will stay the same) - @li @b wxCONVERT_SUBSTITUTE: try some (lossy) substitutions - e.g. - replace unconvertible latin capitals with acute by ordinary - capitals, replace en-dash or em-dash by '-' etc. - - Both modes guarantee that output string will have same length - as input string. - - @return @false if given conversion is impossible, @true otherwise - (conversion may be impossible either if you try to convert - to Unicode with non-Unicode build of wxWidgets or if input - or output encoding is not supported). - */ - bool Init(wxFontEncoding input_enc, wxFontEncoding output_enc, - int method = wxCONVERT_STRICT); -}; - diff --git a/interface/event.h b/interface/event.h deleted file mode 100644 index 8c051f00d8..0000000000 --- a/interface/event.h +++ /dev/null @@ -1,3390 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: event.h -// Purpose: interface of wxEventHandler, wxEventBlocker and many -// wxEvent-derived classes -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - - - -/** - @class wxEvent - @wxheader{event.h} - - An event is a structure holding information about an event passed to a - callback or member function. - - wxEvent used to be a multipurpose event object, and is an abstract base class - for other event classes (see below). - - For more information about events, see the @ref overview_eventhandling overview. - - @beginWxPerlOnly - In wxPerl custom event classes should be derived from - @c Wx::PlEvent and @c Wx::PlCommandEvent. - @endWxPerlOnly - - @library{wxbase} - @category{events} - - @see wxCommandEvent, wxMouseEvent -*/ -class wxEvent : public wxObject -{ -public: - /** - Constructor. Should not need to be used directly by an application. - */ - wxEvent(int id = 0, wxEventType eventType = wxEVT_NULL); - - /** - Returns a copy of the event. - - Any event that is posted to the wxWidgets event system for later action - (via wxEvtHandler::AddPendingEvent or wxPostEvent()) must implement - this method. - - All wxWidgets events fully implement this method, but any derived events - implemented by the user should also implement this method just in case they - (or some event derived from them) are ever posted. - - All wxWidgets events implement a copy constructor, so the easiest way of - implementing the Clone function is to implement a copy constructor for - a new event (call it MyEvent) and then define the Clone function like this: - - @code - wxEvent *Clone() const { return new MyEvent(*this); } - @endcode - */ - virtual wxEvent* Clone() const = 0; - - /** - Returns the object (usually a window) associated with the event, if any. - */ - wxObject* GetEventObject() const; - - /** - Returns the identifier of the given event type, such as @c wxEVT_COMMAND_BUTTON_CLICKED. - */ - wxEventType GetEventType() const; - - /** - Returns the identifier associated with this event, such as a button command id. - */ - int GetId() const; - - /** - Returns @true if the event handler should be skipped, @false otherwise. - */ - bool GetSkipped() const; - - /** - Gets the timestamp for the event. The timestamp is the time in milliseconds - since some fixed moment (not necessarily the standard Unix Epoch, so only - differences between the timestamps and not their absolute values usually make sense). - */ - long GetTimestamp() const; - - /** - Returns @true if the event is or is derived from wxCommandEvent else it returns @false. - - @note exists only for optimization purposes. - */ - bool IsCommandEvent() const; - - /** - Sets the propagation level to the given value (for example returned from an - earlier call to wxEvent::StopPropagation). - */ - void ResumePropagation(int propagationLevel); - - /** - Sets the originating object. - */ - void SetEventObject(wxObject* object); - - /** - Sets the event type. - */ - void SetEventType(wxEventType type); - - /** - Sets the identifier associated with this event, such as a button command id. - */ - void SetId(int id); - - /** - Sets the timestamp for the event. - */ - void SetTimestamp(long = 0); - - /** - Test if this event should be propagated or not, i.e. if the propagation level - is currently greater than 0. - */ - bool ShouldPropagate() const; - - /** - This method can be used inside an event handler to control whether further - event handlers bound to this event will be called after the current one returns. - - Without Skip() (or equivalently if Skip(@false) is used), the event will not - be processed any more. If Skip(@true) is called, the event processing system - continues searching for a further handler function for this event, even though - it has been processed already in the current handler. - - In general, it is recommended to skip all non-command events to allow the - default handling to take place. The command events are, however, normally not - skipped as usually a single command such as a button click or menu item - selection must only be processed by one handler. - */ - void Skip(bool skip = true); - - /** - Stop the event from propagating to its parent window. - - Returns the old propagation level value which may be later passed to - ResumePropagation() to allow propagating the event again. - */ - int StopPropagation(); - -protected: - /** - Indicates how many levels the event can propagate. - - This member is protected and should typically only be set in the constructors - of the derived classes. It may be temporarily changed by StopPropagation() - and ResumePropagation() and tested with ShouldPropagate(). - - The initial value is set to either @c wxEVENT_PROPAGATE_NONE (by default) - meaning that the event shouldn't be propagated at all or to - @c wxEVENT_PROPAGATE_MAX (for command events) meaning that it should be - propagated as much as necessary. - - Any positive number means that the event should be propagated but no more than - the given number of times. E.g. the propagation level may be set to 1 to - propagate the event to its parent only, but not to its grandparent. - */ - int m_propagationLevel; -}; - -/** - @class wxEventBlocker - @wxheader{event.h} - - This class is a special event handler which allows to discard - any event (or a set of event types) directed to a specific window. - - Example: - - @code - void MyWindow::DoSomething() - { - { - // block all events directed to this window while - // we do the 1000 FunctionWhichSendsEvents() calls - wxEventBlocker blocker(this); - - for ( int i = 0; i 1000; i++ ) - FunctionWhichSendsEvents(i); - - } // ~wxEventBlocker called, old event handler is restored - - // the event generated by this call will be processed: - FunctionWhichSendsEvents(0) - } - @endcode - - @library{wxcore} - @category{events} - - @see @ref overview_eventhandling, wxEvtHandler -*/ -class wxEventBlocker : public wxEvtHandler -{ -public: - /** - Constructs the blocker for the given window and for the given event type. - - If @a type is @c wxEVT_ANY, then all events for that window are blocked. - You can call Block() after creation to add other event types to the list - of events to block. - - Note that the @a win window @b must remain alive until the - wxEventBlocker object destruction. - */ - wxEventBlocker(wxWindow* win, wxEventType = wxEVT_ANY); - - /** - Destructor. The blocker will remove itself from the chain of event handlers for - the window provided in the constructor, thus restoring normal processing of events. - */ - virtual ~wxEventBlocker(); - - /** - Adds to the list of event types which should be blocked the given @a eventType. - */ - void Block(wxEventType eventType); -}; - - - -/** - @class wxEvtHandler - @wxheader{event.h} - - A class that can handle events from the windowing system. - wxWindow (and therefore all window classes) are derived from this class. - - When events are received, wxEvtHandler invokes the method listed in the - event table using itself as the object. When using multiple inheritance - it is imperative that the wxEvtHandler(-derived) class be the first - class inherited such that the "this" pointer for the overall object - will be identical to the "this" pointer for the wxEvtHandler portion. - - @library{wxbase} - @category{events} - - @see @ref overview_eventhandling -*/ -class wxEvtHandler : public wxObject -{ -public: - /** - Constructor. - */ - wxEvtHandler(); - - /** - Destructor. - - If the handler is part of a chain, the destructor will unlink itself and - restore the previous and next handlers so that they point to each other. - */ - virtual ~wxEvtHandler(); - - /** - Queue event for a later processing. - - This method is similar to ProcessEvent() but while the latter is - synchronous, i.e. the event is processed immediately, before the - function returns, this one is asynchronous and returns immediately - while the event will be processed at some later time (usually during - the next event loop iteration). - - Another important difference is that this method takes ownership of the - @a event parameter, i.e. it will delete it itself. This implies that - the event should be allocated on the heap and that the pointer can't be - used any more after the function returns (as it can be deleted at any - moment). - - QueueEvent() can be used for inter-thread communication from the worker - threads to the main thread, it is safe in the sense that it uses - locking internally and avoids the problem mentioned in AddPendingEvent() - documentation by ensuring that the @a event object is not used by the - calling thread any more. Care should still be taken to avoid that some - fields of this object are used by it, notably any wxString members of - the event object must not be shallow copies of another wxString object - as this would result in them still using the same string buffer behind - the scenes. For example - @code - void FunctionInAWorkerThread(const wxString& str) - { - wxCommandEvent* evt = new wxCommandEvent; - - // NOT evt->SetString(str) as this would be a shallow copy - evt->SetString(str.c_str()); // make a deep copy - - wxTheApp->QueueEvent( evt ); - } - @endcode - - Finally notice that this method automatically wakes up the event loop - if it is currently idle by calling ::wxWakeUpIdle() so there is no need - to do it manually when using it. - - @since 2.9.0 - - @param event - A heap-allocated event to be queued, QueueEvent() takes ownership - of it. This parameter shouldn't be @c NULL. - */ - virtual void QueueEvent(wxEvent *event); - - /** - Post an event to be processed later. - - This function is similar to QueueEvent() but can't be used to post - events from worker threads for the event objects with wxString fields - (i.e. in practice most of them) because of an unsafe use of the same - wxString object which happens because the wxString field in the - original @a event object and its copy made internally by this function - share the same string buffer internally. Use QueueEvent() to avoid - this. - - A copy of event is made by the function, so the original can be deleted - as soon as function returns (it is common that the original is created - on the stack). This requires that the wxEvent::Clone() method be - implemented by event so that it can be duplicated and stored until it - gets processed. - - @param event - Event to add to the pending events queue. - */ - virtual void AddPendingEvent(const wxEvent& event); - - /** - Connects the given function dynamically with the event handler, id and event type. - This is an alternative to the use of static event tables. - - See the @ref page_samples_event sample for usage. - - This specific overload allows you to connect an event handler to a @e range - of @e source IDs. - Do not confuse @e source IDs with event @e types: source IDs identify the - event generator objects (typically wxMenuItem or wxWindow objects) while the - event @e type identify which type of events should be handled by the - given @e function (an event generator object may generate many different - types of events!). - - @param id - The first ID of the identifier range to be associated with the event - handler function. - @param lastId - The last ID of the identifier range to be associated with the event - handler function. - @param eventType - The event type to be associated with this event handler. - @param function - The event handler function. Note that this function should - be explicitly converted to the correct type which can be done using a macro - called @c wxFooEventHandler for the handler for any @c wxFooEvent. - @param userData - Data to be associated with the event table entry. - @param eventSink - Object whose member function should be called. - If this is @NULL, @c *this will be used. - */ - void Connect(int id, int lastId, wxEventType eventType, - wxObjectEventFunction function, - wxObject* userData = NULL, - wxEvtHandler* eventSink = NULL); - - /** - See the Connect(int, int, wxEventType, wxObjectEventFunction, wxObject*, wxEvtHandler*) - overload for more info. - - This overload can be used to attach an event handler to a single source ID: - - Example: - @code - frame->Connect( wxID_EXIT, - wxEVT_COMMAND_MENU_SELECTED, - wxCommandEventHandler(MyFrame::OnQuit) ); - @endcode - */ - void Connect(int id, wxEventType eventType, - wxObjectEventFunction function, - wxObject* userData = NULL, - wxEvtHandler* eventSink = NULL); - - /** - See the Connect(int, int, wxEventType, wxObjectEventFunction, wxObject*, wxEvtHandler*) - overload for more info. - - This overload will connect the given event handler so that regardless of the - ID of the event source, the handler will be called. - */ - void Connect(wxEventType eventType, - wxObjectEventFunction function, - wxObject* userData = NULL, - wxEvtHandler* eventSink = NULL); - - /** - Disconnects the given function dynamically from the event handler, using the - specified parameters as search criteria and returning @true if a matching - function has been found and removed. - - This method can only disconnect functions which have been added using the - Connect() method. There is no way to disconnect functions connected using - the (static) event tables. - - @param eventType - The event type associated with this event handler. - @param function - The event handler function. - @param userData - Data associated with the event table entry. - @param eventSink - Object whose member function should be called. - */ - bool Disconnect(wxEventType eventType = wxEVT_NULL, - wxObjectEventFunction function = NULL, - wxObject* userData = NULL, - wxEvtHandler* eventSink = NULL); - - /** - See the Disconnect(wxEventType, wxObjectEventFunction, wxObject*, wxEvtHandler*) - overload for more info. - - This overload takes the additional @a id parameter. - */ - bool Disconnect(int id = wxID_ANY, - wxEventType eventType = wxEVT_NULL, - wxObjectEventFunction function = NULL, - wxObject* userData = NULL, - wxEvtHandler* eventSink = NULL); - - /** - See the Disconnect(wxEventType, wxObjectEventFunction, wxObject*, wxEvtHandler*) - overload for more info. - - This overload takes an additional range of source IDs. - */ - bool Disconnect(int id, int lastId = wxID_ANY, - wxEventType eventType = wxEVT_NULL, - wxObjectEventFunction function = NULL, - wxObject* userData = NULL, - wxEvtHandler* eventSink = NULL); - - /** - Returns user-supplied client data. - - @remarks Normally, any extra data the programmer wishes to associate with - the object should be made available by deriving a new class with - new data members. - - @see SetClientData() - */ - void* GetClientData() const; - - /** - Returns a pointer to the user-supplied client data object. - - @see SetClientObject(), wxClientData - */ - wxClientData* GetClientObject() const; - - /** - Returns @true if the event handler is enabled, @false otherwise. - - @see SetEvtHandlerEnabled() - */ - bool GetEvtHandlerEnabled() const; - - /** - Returns the pointer to the next handler in the chain. - - @see SetNextHandler(), GetPreviousHandler(), SetPreviousHandler(), - wxWindow::PushEventHandler, wxWindow::PopEventHandler - */ - wxEvtHandler* GetNextHandler() const; - - /** - Returns the pointer to the previous handler in the chain. - - @see SetPreviousHandler(), GetNextHandler(), SetNextHandler(), - wxWindow::PushEventHandler, wxWindow::PopEventHandler - */ - wxEvtHandler* GetPreviousHandler() const; - - /** - Processes an event, searching event tables and calling zero or more suitable - event handler function(s). - - Normally, your application would not call this function: it is called in the - wxWidgets implementation to dispatch incoming user interface events to the - framework (and application). - - However, you might need to call it if implementing new functionality - (such as a new control) where you define new event types, as opposed to - allowing the user to override virtual functions. - - An instance where you might actually override the ProcessEvent function is where - you want to direct event processing to event handlers not normally noticed by - wxWidgets. For example, in the document/view architecture, documents and views - are potential event handlers. When an event reaches a frame, ProcessEvent will - need to be called on the associated document and view in case event handler functions - are associated with these objects. The property classes library (wxProperty) also - overrides ProcessEvent for similar reasons. - - The normal order of event table searching is as follows: - -# If the object is disabled (via a call to wxEvtHandler::SetEvtHandlerEnabled) - the function skips to step (6). - -# If the object is a wxWindow, ProcessEvent() is recursively called on the - window's wxValidator. If this returns @true, the function exits. - -# SearchEventTable() is called for this event handler. If this fails, the base - class table is tried, and so on until no more tables exist or an appropriate - function was found, in which case the function exits. - -# The search is applied down the entire chain of event handlers (usually the - chain has a length of one). If this succeeds, the function exits. - -# If the object is a wxWindow and the event is a wxCommandEvent, ProcessEvent() - is recursively applied to the parent window's event handler. - If this returns true, the function exits. - -# Finally, ProcessEvent() is called on the wxApp object. - - @param event - Event to process. - - @return @true if a suitable event handler function was found and - executed, and the function did not call wxEvent::Skip. - - @see SearchEventTable() - */ - virtual bool ProcessEvent(wxEvent& event); - - /** - Processes an event by calling ProcessEvent() and handles any exceptions - that occur in the process. - If an exception is thrown in event handler, wxApp::OnExceptionInMainLoop is called. - - @param event - Event to process. - - @return @true if the event was processed, @false if no handler was found - or an exception was thrown. - - @see wxWindow::HandleWindowEvent - */ - bool SafelyProcessEvent(wxEvent& event); - - /** - Searches the event table, executing an event handler function if an appropriate - one is found. - - @param table - Event table to be searched. - @param event - Event to be matched against an event table entry. - - @return @true if a suitable event handler function was found and - executed, and the function did not call wxEvent::Skip. - - @remarks This function looks through the object's event table and tries - to find an entry that will match the event. - An entry will match if: - @li The event type matches, and - @li the identifier or identifier range matches, or the event table - entry's identifier is zero. - If a suitable function is called but calls wxEvent::Skip, this - function will fail, and searching will continue. - - @see ProcessEvent() - */ - virtual bool SearchEventTable(wxEventTable& table, - wxEvent& event); - - /** - Sets user-supplied client data. - - @param data - Data to be associated with the event handler. - - @remarks Normally, any extra data the programmer wishes to associate - with the object should be made available by deriving a new - class with new data members. You must not call this method - and SetClientObject on the same class - only one of them. - - @see GetClientData() - */ - void SetClientData(void* data); - - /** - Set the client data object. Any previous object will be deleted. - - @see GetClientObject(), wxClientData - */ - void SetClientObject(wxClientData* data); - - /** - Enables or disables the event handler. - - @param enabled - @true if the event handler is to be enabled, @false if it is to be disabled. - - @remarks You can use this function to avoid having to remove the event - handler from the chain, for example when implementing a - dialog editor and changing from edit to test mode. - - @see GetEvtHandlerEnabled() - */ - void SetEvtHandlerEnabled(bool enabled); - - /** - Sets the pointer to the next handler. - - @param handler - Event handler to be set as the next handler. - - @see GetNextHandler(), SetPreviousHandler(), GetPreviousHandler(), - wxWindow::PushEventHandler, wxWindow::PopEventHandler - */ - void SetNextHandler(wxEvtHandler* handler); - - /** - Sets the pointer to the previous handler. - - @param handler - Event handler to be set as the previous handler. - */ - void SetPreviousHandler(wxEvtHandler* handler); -}; - - -/** - @class wxKeyEvent - @wxheader{event.h} - - This event class contains information about keypress (character) events. - - Notice that there are three different kinds of keyboard events in wxWidgets: - key down and up events and char events. The difference between the first two - is clear - the first corresponds to a key press and the second to a key - release - otherwise they are identical. Just note that if the key is - maintained in a pressed state you will typically get a lot of (automatically - generated) down events but only one up so it is wrong to assume that there is - one up event corresponding to each down one. - - Both key events provide untranslated key codes while the char event carries - the translated one. The untranslated code for alphanumeric keys is always - an upper case value. For the other keys it is one of @c WXK_XXX values - from the @ref page_keycodes. - The translated key is, in general, the character the user expects to appear - as the result of the key combination when typing the text into a text entry - zone, for example. - - A few examples to clarify this (all assume that CAPS LOCK is unpressed - and the standard US keyboard): when the @c 'A' key is pressed, the key down - event key code is equal to @c ASCII A == 65. But the char event key code - is @c ASCII a == 97. On the other hand, if you press both SHIFT and - @c 'A' keys simultaneously , the key code in key down event will still be - just @c 'A' while the char event key code parameter will now be @c 'A' - as well. - - Although in this simple case it is clear that the correct key code could be - found in the key down event handler by checking the value returned by - wxKeyEvent::ShiftDown(), in general you should use @c EVT_CHAR for this as - for non-alphanumeric keys the translation is keyboard-layout dependent and - can only be done properly by the system itself. - - Another kind of translation is done when the control key is pressed: for - example, for CTRL-A key press the key down event still carries the - same key code @c 'a' as usual but the char event will have key code of 1, - the ASCII value of this key combination. - - You may discover how the other keys on your system behave interactively by - running the @ref page_samples_text wxWidgets sample and pressing some keys - in any of the text controls shown in it. - - @b Tip: be sure to call @c event.Skip() for events that you don't process in - key event function, otherwise menu shortcuts may cease to work under Windows. - - @note If a key down (@c EVT_KEY_DOWN) event is caught and the event handler - does not call @c event.Skip() then the corresponding char event - (@c EVT_CHAR) will not happen. - This is by design and enables the programs that handle both types of - events to be a bit simpler. - - @note For Windows programmers: The key and char events in wxWidgets are - similar to but slightly different from Windows @c WM_KEYDOWN and - @c WM_CHAR events. In particular, Alt-x combination will generate a - char event in wxWidgets (unless it is used as an accelerator). - - - @beginEventTable{wxKeyEvent} - @event{EVT_KEY_DOWN(func)} - Process a wxEVT_KEY_DOWN event (any key has been pressed). - @event{EVT_KEY_UP(func)} - Process a wxEVT_KEY_UP event (any key has been released). - @event{EVT_CHAR(func)} - Process a wxEVT_CHAR event. - @endEventTable - - @library{wxcore} - @category{events} -*/ -class wxKeyEvent : public wxEvent -{ -public: - /** - Constructor. - Currently, the only valid event types are @c wxEVT_CHAR and @c wxEVT_CHAR_HOOK. - */ - wxKeyEvent(wxEventType keyEventType = wxEVT_NULL); - - /** - Returns @true if the Alt key was down at the time of the key event. - - Notice that GetModifiers() is easier to use correctly than this function - so you should consider using it in new code. - */ - bool AltDown() const; - - /** - CMD is a pseudo key which is the same as Control for PC and Unix - platforms but the special APPLE (a.k.a as COMMAND) key under Macs: - it makes often sense to use it instead of, say, ControlDown() because Cmd - key is used for the same thing under Mac as Ctrl elsewhere (but Ctrl still - exists, just not used for this purpose under Mac). So for non-Mac platforms - this is the same as ControlDown() and under Mac this is the same as MetaDown(). - */ - bool CmdDown() const; - - /** - Returns @true if the control key was down at the time of the key event. - - Notice that GetModifiers() is easier to use correctly than this function - so you should consider using it in new code. - */ - bool ControlDown() const; - - /** - Returns the virtual key code. ASCII events return normal ASCII values, - while non-ASCII events return values such as @b WXK_LEFT for the left cursor - key. See @ref page_keycodes for a full list of the virtual key codes. - - Note that in Unicode build, the returned value is meaningful only if the - user entered a character that can be represented in current locale's default - charset. You can obtain the corresponding Unicode character using GetUnicodeKey(). - */ - int GetKeyCode() const; - - /** - Return the bitmask of modifier keys which were pressed when this event - happened. See @ref page_keymodifiers for the full list of modifiers. - - Notice that this function is easier to use correctly than, for example, - ControlDown() because when using the latter you also have to remember to - test that none of the other modifiers is pressed: - - @code - if ( ControlDown() && !AltDown() && !ShiftDown() && !MetaDown() ) - ... handle Ctrl-XXX ... - @endcode - - and forgetting to do it can result in serious program bugs (e.g. program - not working with European keyboard layout where ALTGR key which is seen by - the program as combination of CTRL and ALT is used). On the other hand, - you can simply write: - - @code - if ( GetModifiers() == wxMOD_CONTROL ) - ... handle Ctrl-XXX ... - @endcode - - with this function. - */ - int GetModifiers() const; - - //@{ - /** - Obtains the position (in client coordinates) at which the key was pressed. - */ - wxPoint GetPosition() const; - void GetPosition(long* x, long* y) const; - //@} - - /** - Returns the raw key code for this event. This is a platform-dependent scan code - which should only be used in advanced applications. - - @note Currently the raw key codes are not supported by all ports, use - @ifdef_ wxHAS_RAW_KEY_CODES to determine if this feature is available. - */ - wxUint32 GetRawKeyCode() const; - - /** - Returns the low level key flags for this event. The flags are - platform-dependent and should only be used in advanced applications. - - @note Currently the raw key flags are not supported by all ports, use - @ifdef_ wxHAS_RAW_KEY_CODES to determine if this feature is available. - */ - wxUint32 GetRawKeyFlags() const; - - /** - Returns the Unicode character corresponding to this key event. - - This function is only available in Unicode build, i.e. when - @c wxUSE_UNICODE is 1. - */ - wxChar GetUnicodeKey() const; - - /** - Returns the X position (in client coordinates) of the event. - */ - wxCoord GetX() const; - - /** - Returns the Y position (in client coordinates) of the event. - */ - wxCoord GetY() const; - - /** - Returns @true if either CTRL or ALT keys was down at the time of the - key event. - - Note that this function does not take into account neither SHIFT nor - META key states (the reason for ignoring the latter is that it is - common for NUMLOCK key to be configured as META under X but the key - presses even while NUMLOCK is on should be still processed normally). - */ - bool HasModifiers() const; - - /** - Returns @true if the Meta key was down at the time of the key event. - - Notice that GetModifiers() is easier to use correctly than this function - so you should consider using it in new code. - */ - bool MetaDown() const; - - /** - Returns @true if the shift key was down at the time of the key event. - - Notice that GetModifiers() is easier to use correctly than this function - so you should consider using it in new code. - */ - bool ShiftDown() const; -}; - - - -/** - @class wxJoystickEvent - @wxheader{event.h} - - This event class contains information about joystick events, particularly - events received by windows. - - @beginEventTable{wxJoystickEvent} - @style{EVT_JOY_BUTTON_DOWN(func)} - Process a wxEVT_JOY_BUTTON_DOWN event. - @style{EVT_JOY_BUTTON_UP(func)} - Process a wxEVT_JOY_BUTTON_UP event. - @style{EVT_JOY_MOVE(func)} - Process a wxEVT_JOY_MOVE event. - @style{EVT_JOY_ZMOVE(func)} - Process a wxEVT_JOY_ZMOVE event. - @style{EVT_JOYSTICK_EVENTS(func)} - Processes all joystick events. - @endEventTable - - @library{wxcore} - @category{events} - - @see wxJoystick -*/ -class wxJoystickEvent : public wxEvent -{ -public: - /** - Constructor. - */ - wxJoystickEvent(wxEventType eventType = wxEVT_NULL, int state = 0, - int joystick = wxJOYSTICK1, - int change = 0); - - /** - Returns @true if the event was a down event from the specified button - (or any button). - - @param button - Can be @c wxJOY_BUTTONn where @c n is 1, 2, 3 or 4; or @c wxJOY_BUTTON_ANY to - indicate any button down event. - */ - bool ButtonDown(int button = wxJOY_BUTTON_ANY) const; - - /** - Returns @true if the specified button (or any button) was in a down state. - - @param button - Can be @c wxJOY_BUTTONn where @c n is 1, 2, 3 or 4; or @c wxJOY_BUTTON_ANY to - indicate any button down event. - */ - bool ButtonIsDown(int button = wxJOY_BUTTON_ANY) const; - - /** - Returns @true if the event was an up event from the specified button - (or any button). - - @param button - Can be @c wxJOY_BUTTONn where @c n is 1, 2, 3 or 4; or @c wxJOY_BUTTON_ANY to - indicate any button down event. - */ - bool ButtonUp(int button = wxJOY_BUTTON_ANY) const; - - /** - Returns the identifier of the button changing state. - - This is a @c wxJOY_BUTTONn identifier, where @c n is one of 1, 2, 3, 4. - */ - int GetButtonChange() const; - - /** - Returns the down state of the buttons. - - This is a @c wxJOY_BUTTONn identifier, where @c n is one of 1, 2, 3, 4. - */ - int GetButtonState() const; - - /** - Returns the identifier of the joystick generating the event - one of - wxJOYSTICK1 and wxJOYSTICK2. - */ - int GetJoystick() const; - - /** - Returns the x, y position of the joystick event. - */ - wxPoint GetPosition() const; - - /** - Returns the z position of the joystick event. - */ - int GetZPosition() const; - - /** - Returns @true if this was a button up or down event - (@e not 'is any button down?'). - */ - bool IsButton() const; - - /** - Returns @true if this was an x, y move event. - */ - bool IsMove() const; - - /** - Returns @true if this was a z move event. - */ - bool IsZMove() const; -}; - - - -/** - @class wxScrollWinEvent - @wxheader{event.h} - - A scroll event holds information about events sent from scrolling windows. - - - @beginEventTable{wxScrollWinEvent} - You can use the EVT_SCROLLWIN* macros for intercepting scroll window events - from the receiving window. - @event{EVT_SCROLLWIN(func)} - Process all scroll events. - @event{EVT_SCROLLWIN_TOP(func)} - Process wxEVT_SCROLLWIN_TOP scroll-to-top events. - @event{EVT_SCROLLWIN_BOTTOM(func)} - Process wxEVT_SCROLLWIN_BOTTOM scroll-to-bottom events. - @event{EVT_SCROLLWIN_LINEUP(func)} - Process wxEVT_SCROLLWIN_LINEUP line up events. - @event{EVT_SCROLLWIN_LINEDOWN(func)} - Process wxEVT_SCROLLWIN_LINEDOWN line down events. - @event{EVT_SCROLLWIN_PAGEUP(func)} - Process wxEVT_SCROLLWIN_PAGEUP page up events. - @event{EVT_SCROLLWIN_PAGEDOWN(func)} - Process wxEVT_SCROLLWIN_PAGEDOWN page down events. - @event{EVT_SCROLLWIN_THUMBTRACK(func)} - Process wxEVT_SCROLLWIN_THUMBTRACK thumbtrack events - (frequent events sent as the user drags the thumbtrack). - @event{EVT_SCROLLWIN_THUMBRELEASE(func)} - Process wxEVT_SCROLLWIN_THUMBRELEASE thumb release events. - @endEventTable - - - @library{wxcore} - @category{events} - - @see wxScrollEvent, @ref overview_eventhandling -*/ -class wxScrollWinEvent : public wxEvent -{ -public: - /** - Constructor. - */ - wxScrollWinEvent(wxEventType commandType = wxEVT_NULL, int pos = 0, - int orientation = 0); - - /** - Returns wxHORIZONTAL or wxVERTICAL, depending on the orientation of the - scrollbar. - - @todo wxHORIZONTAL and wxVERTICAL should go in their own enum - */ - int GetOrientation() const; - - /** - Returns the position of the scrollbar for the thumb track and release events. - - Note that this field can't be used for the other events, you need to query - the window itself for the current position in that case. - */ - int GetPosition() const; -}; - - - -/** - @class wxSysColourChangedEvent - @wxheader{event.h} - - This class is used for system colour change events, which are generated - when the user changes the colour settings using the control panel. - This is only appropriate under Windows. - - @remarks - The default event handler for this event propagates the event to child windows, - since Windows only sends the events to top-level windows. - If intercepting this event for a top-level window, remember to call the base - class handler, or to pass the event on to the window's children explicitly. - - @beginEventTable{wxSysColourChangedEvent} - @event{EVT_SYS_COLOUR_CHANGED(func)} - Process a wxEVT_SYS_COLOUR_CHANGED event. - @endEventTable - - @library{wxcore} - @category{events} - - @see @ref overview_eventhandling -*/ -class wxSysColourChangedEvent : public wxEvent -{ -public: - /** - Constructor. - */ - wxSysColourChangedEvent(); -}; - - - -/** - @class wxWindowCreateEvent - @wxheader{event.h} - - This event is sent just after the actual window associated with a wxWindow - object has been created. - - Since it is derived from wxCommandEvent, the event propagates up - the window hierarchy. - - @beginEventTable{wxWindowCreateEvent} - @event{EVT_WINDOW_CREATE(func)} - Process a wxEVT_CREATE event. - @endEventTable - - @library{wxcore} - @category{events} - - @see @ref overview_eventhandling, wxWindowDestroyEvent -*/ -class wxWindowCreateEvent : public wxCommandEvent -{ -public: - /** - Constructor. - */ - wxWindowCreateEvent(wxWindow* win = NULL); -}; - - - -/** - @class wxPaintEvent - @wxheader{event.h} - - A paint event is sent when a window's contents needs to be repainted. - - Please notice that in general it is impossible to change the drawing of a - standard control (such as wxButton) and so you shouldn't attempt to handle - paint events for them as even if it might work on some platforms, this is - inherently not portable and won't work everywhere. - - @remarks - Note that in a paint event handler, the application must always create a - wxPaintDC object, even if you do not use it. Otherwise, under MS Windows, - refreshing for this and other windows will go wrong. - For example: - @code - void MyWindow::OnPaint(wxPaintEvent& event) - { - wxPaintDC dc(this); - - DrawMyDocument(dc); - } - @endcode - You can optimize painting by retrieving the rectangles that have been damaged - and only repainting these. The rectangles are in terms of the client area, - and are unscrolled, so you will need to do some calculations using the current - view position to obtain logical, scrolled units. - Here is an example of using the wxRegionIterator class: - @code - // Called when window needs to be repainted. - void MyWindow::OnPaint(wxPaintEvent& event) - { - wxPaintDC dc(this); - - // Find Out where the window is scrolled to - int vbX,vbY; // Top left corner of client - GetViewStart(&vbX,&vbY); - - int vX,vY,vW,vH; // Dimensions of client area in pixels - wxRegionIterator upd(GetUpdateRegion()); // get the update rect list - - while (upd) - { - vX = upd.GetX(); - vY = upd.GetY(); - vW = upd.GetW(); - vH = upd.GetH(); - - // Alternatively we can do this: - // wxRect rect(upd.GetRect()); - - // Repaint this rectangle - ...some code... - - upd ++ ; - } - } - @endcode - - - @beginEventTable{wxPaintEvent} - @event{EVT_PAINT(func)} - Process a wxEVT_PAINT event. - @endEventTable - - @library{wxcore} - @category{events} - - @see @ref overview_eventhandling -*/ -class wxPaintEvent : public wxEvent -{ -public: - /** - Constructor. - */ - wxPaintEvent(int id = 0); -}; - - - -/** - @class wxMaximizeEvent - @wxheader{event.h} - - An event being sent when a top level window is maximized. Notice that it is - not sent when the window is restored to its original size after it had been - maximized, only a normal wxSizeEvent is generated in this case. - - @beginEventTable{wxMaximizeEvent} - @event{EVT_MAXIMIZE(func)} - Process a wxEVT_MAXIMIZE event. - @endEventTable - - @library{wxcore} - @category{events} - - @see @ref overview_eventhandling, wxTopLevelWindow::Maximize, - wxTopLevelWindow::IsMaximized -*/ -class wxMaximizeEvent : public wxEvent -{ -public: - /** - Constructor. Only used by wxWidgets internally. - */ - wxMaximizeEvent(int id = 0); -}; - -/** - The possibles modes to pass to wxUpdateUIEvent::SetMode(). -*/ -enum wxUpdateUIMode -{ - /** Send UI update events to all windows. */ - wxUPDATE_UI_PROCESS_ALL, - - /** Send UI update events to windows that have - the wxWS_EX_PROCESS_UI_UPDATES flag specified. */ - wxUPDATE_UI_PROCESS_SPECIFIED -}; - - -/** - @class wxUpdateUIEvent - @wxheader{event.h} - - This class is used for pseudo-events which are called by wxWidgets - to give an application the chance to update various user interface elements. - - Without update UI events, an application has to work hard to check/uncheck, - enable/disable, show/hide, and set the text for elements such as menu items - and toolbar buttons. The code for doing this has to be mixed up with the code - that is invoked when an action is invoked for a menu item or button. - - With update UI events, you define an event handler to look at the state of the - application and change UI elements accordingly. wxWidgets will call your member - functions in idle time, so you don't have to worry where to call this code. - - In addition to being a clearer and more declarative method, it also means you don't - have to worry whether you're updating a toolbar or menubar identifier. The same - handler can update a menu item and toolbar button, if the identifier is the same. - Instead of directly manipulating the menu or button, you call functions in the event - object, such as wxUpdateUIEvent::Check. wxWidgets will determine whether such a - call has been made, and which UI element to update. - - These events will work for popup menus as well as menubars. Just before a menu is - popped up, wxMenu::UpdateUI is called to process any UI events for the window that - owns the menu. - - If you find that the overhead of UI update processing is affecting your application, - you can do one or both of the following: - @li Call wxUpdateUIEvent::SetMode with a value of wxUPDATE_UI_PROCESS_SPECIFIED, - and set the extra style wxWS_EX_PROCESS_UI_UPDATES for every window that should - receive update events. No other windows will receive update events. - @li Call wxUpdateUIEvent::SetUpdateInterval with a millisecond value to set the delay - between updates. You may need to call wxWindow::UpdateWindowUI at critical points, - for example when a dialog is about to be shown, in case the user sees a slight - delay before windows are updated. - - Note that although events are sent in idle time, defining a wxIdleEvent handler - for a window does not affect this because the events are sent from wxWindow::OnInternalIdle - which is always called in idle time. - - wxWidgets tries to optimize update events on some platforms. - On Windows and GTK+, events for menubar items are only sent when the menu is about - to be shown, and not in idle time. - - - @beginEventTable{wxUpdateUIEvent} - @event{EVT_UPDATE_UI(id, func)} - Process a wxEVT_UPDATE_UI event for the command with the given id. - @event{EVT_UPDATE_UI_RANGE(id1, id2, func)} - Process a wxEVT_UPDATE_UI event for any command with id included in the given range. - @endEventTable - - @library{wxcore} - @category{events} - - @see @ref overview_eventhandling -*/ -class wxUpdateUIEvent : public wxCommandEvent -{ -public: - /** - Constructor. - */ - wxUpdateUIEvent(wxWindowID commandId = 0); - - /** - Returns @true if it is appropriate to update (send UI update events to) - this window. - - This function looks at the mode used (see wxUpdateUIEvent::SetMode), - the wxWS_EX_PROCESS_UI_UPDATES flag in @a window, the time update events - were last sent in idle time, and the update interval, to determine whether - events should be sent to this window now. By default this will always - return @true because the update mode is initially wxUPDATE_UI_PROCESS_ALL - and the interval is set to 0; so update events will be sent as often as - possible. You can reduce the frequency that events are sent by changing the - mode and/or setting an update interval. - - @see ResetUpdateTime(), SetUpdateInterval(), SetMode() - */ - static bool CanUpdate(wxWindow* window); - - /** - Check or uncheck the UI element. - */ - void Check(bool check); - - /** - Enable or disable the UI element. - */ - void Enable(bool enable); - - /** - Returns @true if the UI element should be checked. - */ - bool GetChecked() const; - - /** - Returns @true if the UI element should be enabled. - */ - bool GetEnabled() const; - - /** - Static function returning a value specifying how wxWidgets will send update - events: to all windows, or only to those which specify that they will process - the events. - - @see SetMode() - */ - static wxUpdateUIMode GetMode(); - - /** - Returns @true if the application has called Check(). - For wxWidgets internal use only. - */ - bool GetSetChecked() const; - - /** - Returns @true if the application has called Enable(). - For wxWidgets internal use only. - */ - bool GetSetEnabled() const; - - /** - Returns @true if the application has called Show(). - For wxWidgets internal use only. - */ - bool GetSetShown() const; - - /** - Returns @true if the application has called SetText(). - For wxWidgets internal use only. - */ - bool GetSetText() const; - - /** - Returns @true if the UI element should be shown. - */ - bool GetShown() const; - - /** - Returns the text that should be set for the UI element. - */ - wxString GetText() const; - - /** - Returns the current interval between updates in milliseconds. - The value -1 disables updates, 0 updates as frequently as possible. - - @see SetUpdateInterval(). - */ - static long GetUpdateInterval(); - - /** - Used internally to reset the last-updated time to the current time. - - It is assumed that update events are normally sent in idle time, so this - is called at the end of idle processing. - - @see CanUpdate(), SetUpdateInterval(), SetMode() - */ - static void ResetUpdateTime(); - - /** - Specify how wxWidgets will send update events: to all windows, or only to - those which specify that they will process the events. - - @param mode - this parameter may be one of the ::wxUpdateUIMode enumeration values. - The default mode is wxUPDATE_UI_PROCESS_ALL. - */ - static void SetMode(wxUpdateUIMode mode); - - /** - Sets the text for this UI element. - */ - void SetText(const wxString& text); - - /** - Sets the interval between updates in milliseconds. - - Set to -1 to disable updates, or to 0 to update as frequently as possible. - The default is 0. - - Use this to reduce the overhead of UI update events if your application - has a lot of windows. If you set the value to -1 or greater than 0, - you may also need to call wxWindow::UpdateWindowUI at appropriate points - in your application, such as when a dialog is about to be shown. - */ - static void SetUpdateInterval(long updateInterval); - - /** - Show or hide the UI element. - */ - void Show(bool show); -}; - - - -/** - @class wxClipboardTextEvent - @wxheader{event.h} - - This class represents the events generated by a control (typically a - wxTextCtrl but other windows can generate these events as well) when its - content gets copied or cut to, or pasted from the clipboard. - - There are three types of corresponding events wxEVT_COMMAND_TEXT_COPY, - wxEVT_COMMAND_TEXT_CUT and wxEVT_COMMAND_TEXT_PASTE. - - If any of these events is processed (without being skipped) by an event - handler, the corresponding operation doesn't take place which allows to - prevent the text from being copied from or pasted to a control. It is also - possible to examine the clipboard contents in the PASTE event handler and - transform it in some way before inserting in a control -- for example, - changing its case or removing invalid characters. - - Finally notice that a CUT event is always preceded by the COPY event which - makes it possible to only process the latter if it doesn't matter if the - text was copied or cut. - - @note - These events are currently only generated by wxTextCtrl under GTK+. - They are generated by all controls under Windows. - - @beginEventTable{wxClipboardTextEvent} - @event{EVT_TEXT_COPY(id, func)} - Some or all of the controls content was copied to the clipboard. - @event{EVT_TEXT_CUT(id, func)} - Some or all of the controls content was cut (i.e. copied and - deleted). - @event{EVT_TEXT_PASTE(id, func)} - Clipboard content was pasted into the control. - @endEventTable - - - @library{wxcore} - @category{events} - - @see wxClipboard -*/ -class wxClipboardTextEvent : public wxCommandEvent -{ -public: - /** - Constructor. - */ - wxClipboardTextEvent(wxEventType commandType = wxEVT_NULL, int id = 0); -}; - - - -/** - @class wxMouseEvent - @wxheader{event.h} - - This event class contains information about the events generated by the mouse: - they include mouse buttons press and release events and mouse move events. - - All mouse events involving the buttons use @c wxMOUSE_BTN_LEFT for the - left mouse button, @c wxMOUSE_BTN_MIDDLE for the middle one and - @c wxMOUSE_BTN_RIGHT for the right one. And if the system supports more - buttons, the @c wxMOUSE_BTN_AUX1 and @c wxMOUSE_BTN_AUX2 events - can also be generated. Note that not all mice have even a middle button so a - portable application should avoid relying on the events from it (but the right - button click can be emulated using the left mouse button with the control key - under Mac platforms with a single button mouse). - - For the @c wxEVT_ENTER_WINDOW and @c wxEVT_LEAVE_WINDOW events - purposes, the mouse is considered to be inside the window if it is in the - window client area and not inside one of its children. In other words, the - parent window receives @c wxEVT_LEAVE_WINDOW event not only when the - mouse leaves the window entirely but also when it enters one of its children. - - @note Note that under Windows CE mouse enter and leave events are not natively - supported by the system but are generated by wxWidgets itself. This has several - drawbacks: the LEAVE_WINDOW event might be received some time after the mouse - left the window and the state variables for it may have changed during this time. - - @note Note the difference between methods like wxMouseEvent::LeftDown and - wxMouseEvent::LeftIsDown: the former returns @true when the event corresponds - to the left mouse button click while the latter returns @true if the left - mouse button is currently being pressed. For example, when the user is dragging - the mouse you can use wxMouseEvent::LeftIsDown to test whether the left mouse - button is (still) depressed. Also, by convention, if wxMouseEvent::LeftDown - returns @true, wxMouseEvent::LeftIsDown will also return @true in wxWidgets - whatever the underlying GUI behaviour is (which is platform-dependent). - The same applies, of course, to other mouse buttons as well. - - - @beginEventTable{wxMouseEvent} - @event{EVT_LEFT_DOWN(func)} - Process a wxEVT_LEFT_DOWN event. The handler of this event should normally - call event.Skip() to allow the default processing to take place as otherwise - the window under mouse wouldn't get the focus. - @event{EVT_LEFT_UP(func)} - Process a wxEVT_LEFT_UP event. - @event{EVT_LEFT_DCLICK(func)} - Process a wxEVT_LEFT_DCLICK event. - @event{EVT_MIDDLE_DOWN(func)} - Process a wxEVT_MIDDLE_DOWN event. - @event{EVT_MIDDLE_UP(func)} - Process a wxEVT_MIDDLE_UP event. - @event{EVT_MIDDLE_DCLICK(func)} - Process a wxEVT_MIDDLE_DCLICK event. - @event{EVT_RIGHT_DOWN(func)} - Process a wxEVT_RIGHT_DOWN event. - @event{EVT_RIGHT_UP(func)} - Process a wxEVT_RIGHT_UP event. - @event{EVT_RIGHT_DCLICK(func)} - Process a wxEVT_RIGHT_DCLICK event. - @event{EVT_MOUSE_AUX1_DOWN(func)} - Process a wxEVT_MOUSE_AUX1_DOWN event. - @event{EVT_MOUSE_AUX1_UP(func)} - Process a wxEVT_MOUSE_AUX1_UP event. - @event{EVT_MOUSE_AUX1_DCLICK(func)} - Process a wxEVT_MOUSE_AUX1_DCLICK event. - @event{EVT_MOUSE_AUX2_DOWN(func)} - Process a wxEVT_MOUSE_AUX2_DOWN event. - @event{EVT_MOUSE_AUX2_UP(func)} - Process a wxEVT_MOUSE_AUX2_UP event. - @event{EVT_MOUSE_AUX2_DCLICK(func)} - Process a wxEVT_MOUSE_AUX2_DCLICK event. - @event{EVT_MOTION(func)} - Process a wxEVT_MOTION event. - @event{EVT_ENTER_WINDOW(func)} - Process a wxEVT_ENTER_WINDOW event. - @event{EVT_LEAVE_WINDOW(func)} - Process a wxEVT_LEAVE_WINDOW event. - @event{EVT_MOUSEWHEEL(func)} - Process a wxEVT_MOUSEWHEEL event. - @event{EVT_MOUSE_EVENTS(func)} - Process all mouse events. - @endEventTable - - @library{wxcore} - @category{events} - - @see wxKeyEvent::CmdDown -*/ -class wxMouseEvent : public wxEvent -{ -public: - /** - Constructor. Valid event types are: - - @li wxEVT_ENTER_WINDOW - @li wxEVT_LEAVE_WINDOW - @li wxEVT_LEFT_DOWN - @li wxEVT_LEFT_UP - @li wxEVT_LEFT_DCLICK - @li wxEVT_MIDDLE_DOWN - @li wxEVT_MIDDLE_UP - @li wxEVT_MIDDLE_DCLICK - @li wxEVT_RIGHT_DOWN - @li wxEVT_RIGHT_UP - @li wxEVT_RIGHT_DCLICK - @li wxEVT_MOUSE_AUX1_DOWN - @li wxEVT_MOUSE_AUX1_UP - @li wxEVT_MOUSE_AUX1_DCLICK - @li wxEVT_MOUSE_AUX2_DOWN - @li wxEVT_MOUSE_AUX2_UP - @li wxEVT_MOUSE_AUX2_DCLICK - @li wxEVT_MOTION - @li wxEVT_MOUSEWHEEL - */ - wxMouseEvent(wxEventType mouseEventType = wxEVT_NULL); - - /** - Returns @true if the Alt key was down at the time of the event. - */ - bool AltDown() const; - - /** - Returns @true if the event was a first extra button double click. - */ - bool Aux1DClick() const; - - /** - Returns @true if the first extra button mouse button changed to down. - */ - bool Aux1Down() const; - - /** - Returns @true if the first extra button mouse button is currently down, - independent of the current event type. - */ - bool Aux1IsDown() const; - - /** - Returns @true if the first extra button mouse button changed to up. - */ - bool Aux1Up() const; - - /** - Returns @true if the event was a second extra button double click. - */ - bool Aux2DClick() const; - - /** - Returns @true if the second extra button mouse button changed to down. - */ - bool Aux2Down() const; - - /** - Returns @true if the second extra button mouse button is currently down, - independent of the current event type. - */ - bool Aux2IsDown() const; - - /** - Returns @true if the second extra button mouse button changed to up. - */ - bool Aux2Up() const; - - /** - Returns @true if the identified mouse button is changing state. - Valid values of @a button are: - - @li @c wxMOUSE_BTN_LEFT: check if left button was pressed - @li @c wxMOUSE_BTN_MIDDLE: check if middle button was pressed - @li @c wxMOUSE_BTN_RIGHT: check if right button was pressed - @li @c wxMOUSE_BTN_AUX1: check if the first extra button was pressed - @li @c wxMOUSE_BTN_AUX2: check if the second extra button was pressed - @li @c wxMOUSE_BTN_ANY: check if any button was pressed - - @todo introduce wxMouseButton enum - */ - bool Button(int button) const; - - /** - If the argument is omitted, this returns @true if the event was a mouse - double click event. Otherwise the argument specifies which double click event - was generated (see Button() for the possible values). - */ - bool ButtonDClick(int but = wxMOUSE_BTN_ANY) const; - - /** - If the argument is omitted, this returns @true if the event was a mouse - button down event. Otherwise the argument specifies which button-down event - was generated (see Button() for the possible values). - */ - bool ButtonDown(int = wxMOUSE_BTN_ANY) const; - - /** - If the argument is omitted, this returns @true if the event was a mouse - button up event. Otherwise the argument specifies which button-up event - was generated (see Button() for the possible values). - */ - bool ButtonUp(int = wxMOUSE_BTN_ANY) const; - - /** - Same as MetaDown() under Mac, same as ControlDown() elsewhere. - - @see wxKeyEvent::CmdDown - */ - bool CmdDown() const; - - /** - Returns @true if the control key was down at the time of the event. - */ - bool ControlDown() const; - - /** - Returns @true if this was a dragging event (motion while a button is depressed). - - @see Moving() - */ - bool Dragging() const; - - /** - Returns @true if the mouse was entering the window. - - @see Leaving() - */ - bool Entering() const; - - /** - Returns the mouse button which generated this event or @c wxMOUSE_BTN_NONE - if no button is involved (for mouse move, enter or leave event, for example). - Otherwise @c wxMOUSE_BTN_LEFT is returned for the left button down, up and - double click events, @c wxMOUSE_BTN_MIDDLE and @c wxMOUSE_BTN_RIGHT - for the same events for the middle and the right buttons respectively. - */ - int GetButton() const; - - /** - Returns the number of mouse clicks for this event: 1 for a simple click, 2 - for a double-click, 3 for a triple-click and so on. - - Currently this function is implemented only in wxMac and returns -1 for the - other platforms (you can still distinguish simple clicks from double-clicks as - they generate different kinds of events however). - - @since 2.9.0 - */ - int GetClickCount() const; - - /** - Returns the configured number of lines (or whatever) to be scrolled per - wheel action. Defaults to three. - */ - int GetLinesPerAction() const; - - /** - Returns the logical mouse position in pixels (i.e. translated according to the - translation set for the DC, which usually indicates that the window has been - scrolled). - */ - wxPoint GetLogicalPosition(const wxDC& dc) const; - - //@{ - /** - Sets *x and *y to the position at which the event occurred. - Returns the physical mouse position in pixels. - - Note that if the mouse event has been artificially generated from a special - keyboard combination (e.g. under Windows when the "menu" key is pressed), the - returned position is ::wxDefaultPosition. - */ - wxPoint GetPosition() const; - void GetPosition(wxCoord* x, wxCoord* y) const; - void GetPosition(long* x, long* y) const; - //@} - - /** - Get wheel delta, normally 120. - - This is the threshold for action to be taken, and one such action - (for example, scrolling one increment) should occur for each delta. - */ - int GetWheelDelta() const; - - /** - Get wheel rotation, positive or negative indicates direction of rotation. - - Current devices all send an event when rotation is at least +/-WheelDelta, but - finer resolution devices can be created in the future. - - Because of this you shouldn't assume that one event is equal to 1 line, but you - should be able to either do partial line scrolling or wait until several - events accumulate before scrolling. - */ - int GetWheelRotation() const; - - /** - Returns X coordinate of the physical mouse event position. - */ - wxCoord GetX() const; - - /** - Returns Y coordinate of the physical mouse event position. - */ - wxCoord GetY() const; - - /** - Returns @true if the event was a mouse button event (not necessarily a button - down event - that may be tested using ButtonDown()). - */ - bool IsButton() const; - - /** - Returns @true if the system has been setup to do page scrolling with - the mouse wheel instead of line scrolling. - */ - bool IsPageScroll() const; - - /** - Returns @true if the mouse was leaving the window. - - @see Entering(). - */ - bool Leaving() const; - - /** - Returns @true if the event was a left double click. - */ - bool LeftDClick() const; - - /** - Returns @true if the left mouse button changed to down. - */ - bool LeftDown() const; - - /** - Returns @true if the left mouse button is currently down, independent - of the current event type. - - Please notice that it is not the same as LeftDown() which returns @true if the - event was generated by the left mouse button being pressed. Rather, it simply - describes the state of the left mouse button at the time when the event was - generated (so while it will be @true for a left click event, it can also be @true - for a right click if it happened while the left mouse button was pressed). - - This event is usually used in the mouse event handlers which process "move - mouse" messages to determine whether the user is (still) dragging the mouse. - */ - bool LeftIsDown() const; - - /** - Returns @true if the left mouse button changed to up. - */ - bool LeftUp() const; - - /** - Returns @true if the Meta key was down at the time of the event. - */ - bool MetaDown() const; - - /** - Returns @true if the event was a middle double click. - */ - bool MiddleDClick() const; - - /** - Returns @true if the middle mouse button changed to down. - */ - bool MiddleDown() const; - - /** - Returns @true if the middle mouse button is currently down, independent - of the current event type. - */ - bool MiddleIsDown() const; - - /** - Returns @true if the middle mouse button changed to up. - */ - bool MiddleUp() const; - - /** - Returns @true if this was a motion event and no mouse buttons were pressed. - If any mouse button is held pressed, then this method returns @false and - Dragging() returns @true. - */ - bool Moving() const; - - /** - Returns @true if the event was a right double click. - */ - bool RightDClick() const; - - /** - Returns @true if the right mouse button changed to down. - */ - bool RightDown() const; - - /** - Returns @true if the right mouse button is currently down, independent - of the current event type. - */ - bool RightIsDown() const; - - /** - Returns @true if the right mouse button changed to up. - */ - bool RightUp() const; - - /** - Returns @true if the shift key was down at the time of the event. - */ - bool ShiftDown() const; -}; - - - -/** - @class wxDropFilesEvent - @wxheader{event.h} - - This class is used for drop files events, that is, when files have been dropped - onto the window. This functionality is currently only available under Windows. - - The window must have previously been enabled for dropping by calling - wxWindow::DragAcceptFiles(). - - Important note: this is a separate implementation to the more general drag and drop - implementation documented in the @ref overview_dnd. It uses the older, Windows - message-based approach of dropping files. - - @beginEventTable{wxDropFilesEvent} - @event{EVT_DROP_FILES(func)} - Process a wxEVT_DROP_FILES event. - @endEventTable - - @onlyfor{wxmsw} - - @library{wxcore} - @category{events} - - @see @ref overview_eventhandling -*/ -class wxDropFilesEvent : public wxEvent -{ -public: - /** - Constructor. - */ - wxDropFilesEvent(wxEventType id = 0, int noFiles = 0, - wxString* files = NULL); - - /** - Returns an array of filenames. - */ - wxString* GetFiles() const; - - /** - Returns the number of files dropped. - */ - int GetNumberOfFiles() const; - - /** - Returns the position at which the files were dropped. - Returns an array of filenames. - */ - wxPoint GetPosition() const; -}; - - - -/** - @class wxCommandEvent - @wxheader{event.h} - - This event class contains information about command events, which originate - from a variety of simple controls. - - More complex controls, such as wxTreeCtrl, have separate command event classes. - - @beginEventTable{wxCommandEvent} - @event{EVT_COMMAND(id, event, func)} - Process a command, supplying the window identifier, command event identifier, - and member function. - @event{EVT_COMMAND_RANGE(id1, id2, event, func)} - Process a command for a range of window identifiers, supplying the minimum and - maximum window identifiers, command event identifier, and member function. - @event{EVT_BUTTON(id, func)} - Process a wxEVT_COMMAND_BUTTON_CLICKED command, which is generated by a wxButton control. - @event{EVT_CHECKBOX(id, func)} - Process a wxEVT_COMMAND_CHECKBOX_CLICKED command, which is generated by a wxCheckBox control. - @event{EVT_CHOICE(id, func)} - Process a wxEVT_COMMAND_CHOICE_SELECTED command, which is generated by a wxChoice control. - @event{EVT_COMBOBOX(id, func)} - Process a wxEVT_COMMAND_COMBOBOX_SELECTED command, which is generated by a wxComboBox control. - @event{EVT_LISTBOX(id, func)} - Process a wxEVT_COMMAND_LISTBOX_SELECTED command, which is generated by a wxListBox control. - @event{EVT_LISTBOX_DCLICK(id, func)} - Process a wxEVT_COMMAND_LISTBOX_DOUBLECLICKED command, which is generated by a wxListBox control. - @event{EVT_MENU(id, func)} - Process a wxEVT_COMMAND_MENU_SELECTED command, which is generated by a menu item. - @event{EVT_MENU_RANGE(id1, id2, func)} - Process a wxEVT_COMMAND_MENU_RANGE command, which is generated by a range of menu items. - @event{EVT_CONTEXT_MENU(func)} - Process the event generated when the user has requested a popup menu to appear by - pressing a special keyboard key (under Windows) or by right clicking the mouse. - @event{EVT_RADIOBOX(id, func)} - Process a wxEVT_COMMAND_RADIOBOX_SELECTED command, which is generated by a wxRadioBox control. - @event{EVT_RADIOBUTTON(id, func)} - Process a wxEVT_COMMAND_RADIOBUTTON_SELECTED command, which is generated by a wxRadioButton control. - @event{EVT_SCROLLBAR(id, func)} - Process a wxEVT_COMMAND_SCROLLBAR_UPDATED command, which is generated by a wxScrollBar - control. This is provided for compatibility only; more specific scrollbar event macros - should be used instead (see wxScrollEvent). - @event{EVT_SLIDER(id, func)} - Process a wxEVT_COMMAND_SLIDER_UPDATED command, which is generated by a wxSlider control. - @event{EVT_TEXT(id, func)} - Process a wxEVT_COMMAND_TEXT_UPDATED command, which is generated by a wxTextCtrl control. - @event{EVT_TEXT_ENTER(id, func)} - Process a wxEVT_COMMAND_TEXT_ENTER command, which is generated by a wxTextCtrl control. - Note that you must use wxTE_PROCESS_ENTER flag when creating the control if you want it - to generate such events. - @event{EVT_TEXT_MAXLEN(id, func)} - Process a wxEVT_COMMAND_TEXT_MAXLEN command, which is generated by a wxTextCtrl control - when the user tries to enter more characters into it than the limit previously set - with SetMaxLength(). - @event{EVT_TOGGLEBUTTON(id, func)} - Process a wxEVT_COMMAND_TOGGLEBUTTON_CLICKED event. - @event{EVT_TOOL(id, func)} - Process a wxEVT_COMMAND_TOOL_CLICKED event (a synonym for wxEVT_COMMAND_MENU_SELECTED). - Pass the id of the tool. - @event{EVT_TOOL_RANGE(id1, id2, func)} - Process a wxEVT_COMMAND_TOOL_CLICKED event for a range of identifiers. Pass the ids of the tools. - @event{EVT_TOOL_RCLICKED(id, func)} - Process a wxEVT_COMMAND_TOOL_RCLICKED event. Pass the id of the tool. - @event{EVT_TOOL_RCLICKED_RANGE(id1, id2, func)} - Process a wxEVT_COMMAND_TOOL_RCLICKED event for a range of ids. Pass the ids of the tools. - @event{EVT_TOOL_ENTER(id, func)} - Process a wxEVT_COMMAND_TOOL_ENTER event. Pass the id of the toolbar itself. - The value of wxCommandEvent::GetSelection() is the tool id, or -1 if the mouse cursor - has moved off a tool. - @event{EVT_COMMAND_LEFT_CLICK(id, func)} - Process a wxEVT_COMMAND_LEFT_CLICK command, which is generated by a control (Windows 95 and NT only). - @event{EVT_COMMAND_LEFT_DCLICK(id, func)} - Process a wxEVT_COMMAND_LEFT_DCLICK command, which is generated by a control (Windows 95 and NT only). - @event{EVT_COMMAND_RIGHT_CLICK(id, func)} - Process a wxEVT_COMMAND_RIGHT_CLICK command, which is generated by a control (Windows 95 and NT only). - @event{EVT_COMMAND_SET_FOCUS(id, func)} - Process a wxEVT_COMMAND_SET_FOCUS command, which is generated by a control (Windows 95 and NT only). - @event{EVT_COMMAND_KILL_FOCUS(id, func)} - Process a wxEVT_COMMAND_KILL_FOCUS command, which is generated by a control (Windows 95 and NT only). - @event{EVT_COMMAND_ENTER(id, func)} - Process a wxEVT_COMMAND_ENTER command, which is generated by a control. - @endEventTable - - @library{wxcore} - @category{events} -*/ -class wxCommandEvent : public wxEvent -{ -public: - /** - Constructor. - */ - wxCommandEvent(wxEventType commandEventType = 0, int id = 0); - - /** - Returns client data pointer for a listbox or choice selection event - (not valid for a deselection). - */ - void* GetClientData() const; - - /** - Returns client object pointer for a listbox or choice selection event - (not valid for a deselection). - */ - wxClientData* GetClientObject() const; - - /** - Returns extra information dependant on the event objects type. - - If the event comes from a listbox selection, it is a boolean - determining whether the event was a selection (@true) or a - deselection (@false). A listbox deselection only occurs for - multiple-selection boxes, and in this case the index and string values - are indeterminate and the listbox must be examined by the application. - */ - long GetExtraLong() const; - - /** - Returns the integer identifier corresponding to a listbox, choice or - radiobox selection (only if the event was a selection, not a deselection), - or a boolean value representing the value of a checkbox. - */ - int GetInt() const; - - /** - Returns item index for a listbox or choice selection event (not valid for - a deselection). - */ - int GetSelection() const; - - /** - Returns item string for a listbox or choice selection event. If one - or several items have been deselected, returns the index of the first - deselected item. If some items have been selected and others deselected - at the same time, it will return the index of the first selected item. - */ - wxString GetString() const; - - /** - This method can be used with checkbox and menu events: for the checkboxes, the - method returns @true for a selection event and @false for a deselection one. - For the menu events, this method indicates if the menu item just has become - checked or unchecked (and thus only makes sense for checkable menu items). - - Notice that this method can not be used with wxCheckListBox currently. - */ - bool IsChecked() const; - - /** - For a listbox or similar event, returns @true if it is a selection, @false - if it is a deselection. If some items have been selected and others deselected - at the same time, it will return @true. - */ - bool IsSelection() const; - - /** - Sets the client data for this event. - */ - void SetClientData(void* clientData); - - /** - Sets the client object for this event. The client object is not owned by the - event object and the event object will not delete the client object in its destructor. - - The client object must be owned and deleted by another object (e.g. a control) - that has longer life time than the event object. - */ - void SetClientObject(wxClientData* clientObject); - - /** - Sets the @b m_extraLong member. - */ - void SetExtraLong(long extraLong); - - /** - Sets the @b m_commandInt member. - */ - void SetInt(int intCommand); - - /** - Sets the @b m_commandString member. - */ - void SetString(const wxString& string); -}; - - - -/** - @class wxActivateEvent - @wxheader{event.h} - - An activate event is sent when a window or application is being activated - or deactivated. - - @beginEventTable{wxActivateEvent} - @event{EVT_ACTIVATE(func)} - Process a wxEVT_ACTIVATE event. - @event{EVT_ACTIVATE_APP(func)} - Process a wxEVT_ACTIVATE_APP event. - @event{EVT_HIBERNATE(func)} - Process a hibernate event, supplying the member function. This event applies - to wxApp only, and only on Windows SmartPhone and PocketPC. - It is generated when the system is low on memory; the application should free - up as much memory as possible, and restore full working state when it receives - a wxEVT_ACTIVATE or wxEVT_ACTIVATE_APP event. - @endEventTable - - - @library{wxcore} - @category{events} - - @see @ref overview_eventhandling, wxApp::IsActive -*/ -class wxActivateEvent : public wxEvent -{ -public: - /** - Constructor. - */ - wxActivateEvent(wxEventType eventType = wxEVT_NULL, bool active = true, - int id = 0); - - /** - Returns @true if the application or window is being activated, @false otherwise. - */ - bool GetActive() const; -}; - - - -/** - @class wxContextMenuEvent - @wxheader{event.h} - - This class is used for context menu events, sent to give - the application a chance to show a context (popup) menu. - - Note that if wxContextMenuEvent::GetPosition returns wxDefaultPosition, this - means that the event originated from a keyboard context button event, and you - should compute a suitable position yourself, for example by calling wxGetMousePosition(). - - When a keyboard context menu button is pressed on Windows, a right-click event - with default position is sent first, and if this event is not processed, the - context menu event is sent. So if you process mouse events and you find your - context menu event handler is not being called, you could call wxEvent::Skip() - for mouse right-down events. - - @beginEventTable{wxContextMenuEvent} - @event{EVT_CONTEXT_MENU(func)} - A right click (or other context menu command depending on platform) has been detected. - @endEventTable - - - @library{wxcore} - @category{events} - - @see wxCommandEvent, @ref overview_eventhandling -*/ -class wxContextMenuEvent : public wxCommandEvent -{ -public: - /** - Constructor. - */ - wxContextMenuEvent(wxEventType id = wxEVT_NULL, int id = 0, - const wxPoint& pos = wxDefaultPosition); - - /** - Returns the position in screen coordinates at which the menu should be shown. - Use wxWindow::ScreenToClient to convert to client coordinates. - - You can also omit a position from wxWindow::PopupMenu in order to use - the current mouse pointer position. - - If the event originated from a keyboard event, the value returned from this - function will be wxDefaultPosition. - */ - const wxPoint& GetPosition() const; - - /** - Sets the position at which the menu should be shown. - */ - void SetPosition(const wxPoint& point); -}; - - - -/** - @class wxEraseEvent - @wxheader{event.h} - - An erase event is sent when a window's background needs to be repainted. - - On some platforms, such as GTK+, this event is simulated (simply generated just - before the paint event) and may cause flicker. It is therefore recommended that - you set the text background colour explicitly in order to prevent flicker. - The default background colour under GTK+ is grey. - - To intercept this event, use the EVT_ERASE_BACKGROUND macro in an event table - definition. - - You must call wxEraseEvent::GetDC and use the returned device context if it is - non-@NULL. If it is @NULL, create your own temporary wxClientDC object. - - @remarks - Use the device context returned by GetDC to draw on, don't create - a wxPaintDC in the event handler. - - @beginEventTable{wxEraseEvent} - @event{EVT_ERASE_BACKGROUND(func)} - Process a wxEVT_ERASE_BACKGROUND event. - @endEventTable - - @library{wxcore} - @category{events} - - @see @ref overview_eventhandling -*/ -class wxEraseEvent : public wxEvent -{ -public: - /** - Constructor. - */ - wxEraseEvent(int id = 0, wxDC* dc = NULL); - - /** - Returns the device context associated with the erase event to draw on. - */ - wxDC* GetDC() const; -}; - - - -/** - @class wxFocusEvent - @wxheader{event.h} - - A focus event is sent when a window's focus changes. The window losing focus - receives a "kill focus" event while the window gaining it gets a "set focus" one. - - Notice that the set focus event happens both when the user gives focus to the - window (whether using the mouse or keyboard) and when it is done from the - program itself using wxWindow::SetFocus. - - @beginEventTable{wxFocusEvent} - @event{EVT_SET_FOCUS(func)} - Process a wxEVT_SET_FOCUS event. - @event{EVT_KILL_FOCUS(func)} - Process a wxEVT_KILL_FOCUS event. - @endEventTable - - @library{wxcore} - @category{events} - - @see @ref overview_eventhandling -*/ -class wxFocusEvent : public wxEvent -{ -public: - /** - Constructor. - */ - wxFocusEvent(wxEventType eventType = wxEVT_NULL, int id = 0); - - /** - Returns the window associated with this event, that is the window which had the - focus before for the @c wxEVT_SET_FOCUS event and the window which is - going to receive focus for the @c wxEVT_KILL_FOCUS one. - - Warning: the window pointer may be @NULL! - */ - wxWindow *GetWindow() const; -}; - - - -/** - @class wxChildFocusEvent - @wxheader{event.h} - - A child focus event is sent to a (parent-)window when one of its child windows - gains focus, so that the window could restore the focus back to its corresponding - child if it loses it now and regains later. - - Notice that child window is the direct child of the window receiving event. - Use wxWindow::FindFocus() to retreive the window which is actually getting focus. - - @beginEventTable{wxChildFocusEvent} - @event{EVT_CHILD_FOCUS(func)} - Process a wxEVT_CHILD_FOCUS event. - @endEventTable - - @library{wxcore} - @category{events} - - @see @ref overview_eventhandling -*/ -class wxChildFocusEvent : public wxCommandEvent -{ -public: - /** - Constructor. - - @param win - The direct child which is (or which contains the window which is) receiving - the focus. - */ - wxChildFocusEvent(wxWindow* win = NULL); - - /** - Returns the direct child which receives the focus, or a (grand-)parent of the - control receiving the focus. - - To get the actually focused control use wxWindow::FindFocus. - */ - wxWindow *GetWindow() const; -}; - - - -/** - @class wxMouseCaptureLostEvent - @wxheader{event.h} - - An mouse capture lost event is sent to a window that obtained mouse capture, - which was subsequently loss due to "external" event, for example when a dialog - box is shown or if another application captures the mouse. - - If this happens, this event is sent to all windows that are on capture stack - (i.e. called CaptureMouse, but didn't call ReleaseMouse yet). The event is - not sent if the capture changes because of a call to CaptureMouse or - ReleaseMouse. - - This event is currently emitted under Windows only. - - @beginEventTable{wxMouseCaptureLostEvent} - @event{EVT_MOUSE_CAPTURE_LOST(func)} - Process a wxEVT_MOUSE_CAPTURE_LOST event. - @endEventTable - - @onlyfor{wxmsw} - - @library{wxcore} - @category{events} - - @see wxMouseCaptureChangedEvent, @ref overview_eventhandling, - wxWindow::CaptureMouse, wxWindow::ReleaseMouse, wxWindow::GetCapture -*/ -class wxMouseCaptureLostEvent : public wxEvent -{ -public: - /** - Constructor. - */ - wxMouseCaptureLostEvent(wxWindowID windowId = 0); -}; - - - -/** - @class wxNotifyEvent - @wxheader{event.h} - - This class is not used by the event handlers by itself, but is a base class - for other event classes (such as wxNotebookEvent). - - It (or an object of a derived class) is sent when the controls state is being - changed and allows the program to wxNotifyEvent::Veto() this change if it wants - to prevent it from happening. - - @library{wxcore} - @category{events} - - @see wxNotebookEvent -*/ -class wxNotifyEvent : public wxCommandEvent -{ -public: - /** - Constructor (used internally by wxWidgets only). - */ - wxNotifyEvent(wxEventType eventType = wxEVT_NULL, int id = 0); - - /** - This is the opposite of Veto(): it explicitly allows the event to be processed. - For most events it is not necessary to call this method as the events are allowed - anyhow but some are forbidden by default (this will be mentioned in the corresponding - event description). - */ - void Allow(); - - /** - Returns @true if the change is allowed (Veto() hasn't been called) or @false - otherwise (if it was). - */ - bool IsAllowed() const; - - /** - Prevents the change announced by this event from happening. - - It is in general a good idea to notify the user about the reasons for vetoing - the change because otherwise the applications behaviour (which just refuses to - do what the user wants) might be quite surprising. - */ - void Veto(); -}; - - - - -/** - Indicates how a wxHelpEvent was generated. -*/ -enum wxHelpEventOrigin -{ - wxHE_ORIGIN_UNKNOWN = -1, /**< unrecognized event source. */ - wxHE_ORIGIN_KEYBOARD, /**< event generated from F1 key press. */ - - /** event generated by wxContextHelp or from the [?] button on - the title bar (Windows). */ - wxHE_ORIGIN_HELPBUTTON -}; - -/** - @class wxHelpEvent - @wxheader{event.h} - - A help event is sent when the user has requested context-sensitive help. - This can either be caused by the application requesting context-sensitive help mode - via wxContextHelp, or (on MS Windows) by the system generating a WM_HELP message when - the user pressed F1 or clicked on the query button in a dialog caption. - - A help event is sent to the window that the user clicked on, and is propagated - up the window hierarchy until the event is processed or there are no more event - handlers. - - The application should call wxEvent::GetId to check the identity of the - clicked-on window, and then either show some suitable help or call wxEvent::Skip() - if the identifier is unrecognised. - - Calling Skip is important because it allows wxWidgets to generate further - events for ancestors of the clicked-on window. Otherwise it would be impossible to - show help for container windows, since processing would stop after the first window - found. - - @beginEventTable{wxHelpEvent} - @event{EVT_HELP(id, func)} - Process a wxEVT_HELP event. - @event{EVT_HELP_RANGE(id1, id2, func)} - Process a wxEVT_HELP event for a range of ids. - @endEventTable - - @library{wxcore} - @category{events} - - @see wxContextHelp, wxDialog, @ref overview_eventhandling -*/ -class wxHelpEvent : public wxCommandEvent -{ -public: - /** - Constructor. - */ - wxHelpEvent(wxEventType type = wxEVT_NULL, - wxWindowID winid = 0, - const wxPoint& pt = wxDefaultPosition, - wxHelpEventOrigin origin = wxHE_ORIGIN_UNKNOWN); - - /** - Returns the origin of the help event which is one of the ::wxHelpEventOrigin - values. - - The application may handle events generated using the keyboard or mouse - differently, e.g. by using wxGetMousePosition() for the mouse events. - - @see SetOrigin() - */ - wxHelpEventOrigin GetOrigin() const; - - /** - Returns the left-click position of the mouse, in screen coordinates. - This allows the application to position the help appropriately. - */ - const wxPoint& GetPosition() const; - - /** - Set the help event origin, only used internally by wxWidgets normally. - - @see GetOrigin() - */ - void SetOrigin(wxHelpEventOrigin); - - /** - Sets the left-click position of the mouse, in screen coordinates. - */ - void SetPosition(const wxPoint& pt); -}; - - - -/** - @class wxScrollEvent - @wxheader{event.h} - - A scroll event holds information about events sent from stand-alone - scrollbars (see wxScrollBar) and sliders (see wxSlider). - - Note that scrolled windows send the wxScrollWinEvent which does not derive from - wxCommandEvent, but from wxEvent directly - don't confuse these two kinds of - events and use the event table macros mentioned below only for the scrollbar-like - controls. - - @section wxscrollevent_diff The difference between EVT_SCROLL_THUMBRELEASE and EVT_SCROLL_CHANGED - - The EVT_SCROLL_THUMBRELEASE event is only emitted when actually dragging the thumb - using the mouse and releasing it (This EVT_SCROLL_THUMBRELEASE event is also followed - by an EVT_SCROLL_CHANGED event). - - The EVT_SCROLL_CHANGED event also occurs when using the keyboard to change the thumb - position, and when clicking next to the thumb (In all these cases the EVT_SCROLL_THUMBRELEASE - event does not happen). - - In short, the EVT_SCROLL_CHANGED event is triggered when scrolling/ moving has finished - independently of the way it had started. Please see the widgets sample ("Slider" page) - to see the difference between EVT_SCROLL_THUMBRELEASE and EVT_SCROLL_CHANGED in action. - - @remarks - Note that unless specifying a scroll control identifier, you will need to test for scrollbar - orientation with wxScrollEvent::GetOrientation, since horizontal and vertical scroll events - are processed using the same event handler. - - @beginEventTable{wxScrollEvent} - You can use EVT_COMMAND_SCROLL... macros with window IDs for when intercepting - scroll events from controls, or EVT_SCROLL... macros without window IDs for - intercepting scroll events from the receiving window -- except for this, the - macros behave exactly the same. - @event{EVT_SCROLL(func)} - Process all scroll events. - @event{EVT_SCROLL_TOP(func)} - Process wxEVT_SCROLL_TOP scroll-to-top events (minimum position). - @event{EVT_SCROLL_BOTTOM(func)} - Process wxEVT_SCROLL_BOTTOM scroll-to-bottom events (maximum position). - @event{EVT_SCROLL_LINEUP(func)} - Process wxEVT_SCROLL_LINEUP line up events. - @event{EVT_SCROLL_LINEDOWN(func)} - Process wxEVT_SCROLL_LINEDOWN line down events. - @event{EVT_SCROLL_PAGEUP(func)} - Process wxEVT_SCROLL_PAGEUP page up events. - @event{EVT_SCROLL_PAGEDOWN(func)} - Process wxEVT_SCROLL_PAGEDOWN page down events. - @event{EVT_SCROLL_THUMBTRACK(func)} - Process wxEVT_SCROLL_THUMBTRACK thumbtrack events (frequent events sent as the - user drags the thumbtrack). - @event{EVT_SCROLL_THUMBRELEASE(func)} - Process wxEVT_SCROLL_THUMBRELEASE thumb release events. - @event{EVT_SCROLL_CHANGED(func)} - Process wxEVT_SCROLL_CHANGED end of scrolling events (MSW only). - @event{EVT_COMMAND_SCROLL(id, func)} - Process all scroll events. - @event{EVT_COMMAND_SCROLL_TOP(id, func)} - Process wxEVT_SCROLL_TOP scroll-to-top events (minimum position). - @event{EVT_COMMAND_SCROLL_BOTTOM(id, func)} - Process wxEVT_SCROLL_BOTTOM scroll-to-bottom events (maximum position). - @event{EVT_COMMAND_SCROLL_LINEUP(id, func)} - Process wxEVT_SCROLL_LINEUP line up events. - @event{EVT_COMMAND_SCROLL_LINEDOWN(id, func)} - Process wxEVT_SCROLL_LINEDOWN line down events. - @event{EVT_COMMAND_SCROLL_PAGEUP(id, func)} - Process wxEVT_SCROLL_PAGEUP page up events. - @event{EVT_COMMAND_SCROLL_PAGEDOWN(id, func)} - Process wxEVT_SCROLL_PAGEDOWN page down events. - @event{EVT_COMMAND_SCROLL_THUMBTRACK(id, func)} - Process wxEVT_SCROLL_THUMBTRACK thumbtrack events (frequent events sent - as the user drags the thumbtrack). - @event{EVT_COMMAND_SCROLL_THUMBRELEASE(func)} - Process wxEVT_SCROLL_THUMBRELEASE thumb release events. - @event{EVT_COMMAND_SCROLL_CHANGED(func)} - Process wxEVT_SCROLL_CHANGED end of scrolling events (MSW only). - @endEventTable - - @library{wxcore} - @category{events} - - @see wxScrollBar, wxSlider, wxSpinButton, wxScrollWinEvent, @ref overview_eventhandling -*/ -class wxScrollEvent : public wxCommandEvent -{ -public: - /** - Constructor. - */ - wxScrollEvent(wxEventType commandType = wxEVT_NULL, int id = 0, int pos = 0, - int orientation = 0); - - /** - Returns wxHORIZONTAL or wxVERTICAL, depending on the orientation of the - scrollbar. - */ - int GetOrientation() const; - - /** - Returns the position of the scrollbar. - */ - int GetPosition() const; -}; - -/** - See wxIdleEvent::SetMode() for more info. -*/ -enum wxIdleMode -{ - /** Send idle events to all windows */ - wxIDLE_PROCESS_ALL, - - /** Send idle events to windows that have the wxWS_EX_PROCESS_IDLE flag specified */ - wxIDLE_PROCESS_SPECIFIED -}; - - -/** - @class wxIdleEvent - @wxheader{event.h} - - This class is used for idle events, which are generated when the system becomes - idle. Note that, unless you do something specifically, the idle events are not - sent if the system remains idle once it has become it, e.g. only a single idle - event will be generated until something else resulting in more normal events - happens and only then is the next idle event sent again. - - If you need to ensure a continuous stream of idle events, you can either use - wxIdleEvent::RequestMore method in your handler or call wxWakeUpIdle() periodically - (for example from a timer event handler), but note that both of these approaches - (and especially the first one) increase the system load and so should be avoided - if possible. - - By default, idle events are sent to all windows (and also wxApp, as usual). - If this is causing a significant overhead in your application, you can call - wxIdleEvent::SetMode with the value wxIDLE_PROCESS_SPECIFIED, and set the - wxWS_EX_PROCESS_IDLE extra window style for every window which should receive - idle events. - - @beginEventTable{wxIdleEvent} - @event{EVT_IDLE(func)} - Process a wxEVT_IDLE event. - @endEventTable - - @library{wxbase} - @category{events} - - @see @ref overview_eventhandling, wxUpdateUIEvent, wxWindow::OnInternalIdle -*/ -class wxIdleEvent : public wxEvent -{ -public: - /** - Constructor. - */ - wxIdleEvent(); - - /** - Returns @true if it is appropriate to send idle events to this window. - - This function looks at the mode used (see wxIdleEvent::SetMode), - and the wxWS_EX_PROCESS_IDLE style in @a window to determine whether idle - events should be sent to this window now. - - By default this will always return @true because the update mode is initially - wxIDLE_PROCESS_ALL. You can change the mode to only send idle events to - windows with the wxWS_EX_PROCESS_IDLE extra window style set. - - @see SetMode() - */ - static bool CanSend(wxWindow* window); - - /** - Static function returning a value specifying how wxWidgets will send idle - events: to all windows, or only to those which specify that they - will process the events. - - @see SetMode(). - */ - static wxIdleMode GetMode(); - - /** - Returns @true if the OnIdle function processing this event requested more - processing time. - - @see RequestMore() - */ - bool MoreRequested() const; - - /** - Tells wxWidgets that more processing is required. - - This function can be called by an OnIdle handler for a window or window event - handler to indicate that wxApp::OnIdle should forward the OnIdle event once - more to the application windows. - - If no window calls this function during OnIdle, then the application will - remain in a passive event loop (not calling OnIdle) until a new event is - posted to the application by the windowing system. - - @see MoreRequested() - */ - void RequestMore(bool needMore = true); - - /** - Static function for specifying how wxWidgets will send idle events: to - all windows, or only to those which specify that they will process the events. - - @param mode - Can be one of the ::wxIdleMode values. - The default is wxIDLE_PROCESS_ALL. - */ - static void SetMode(wxIdleMode mode); -}; - - - -/** - @class wxInitDialogEvent - @wxheader{event.h} - - A wxInitDialogEvent is sent as a dialog or panel is being initialised. - Handlers for this event can transfer data to the window. - - The default handler calls wxWindow::TransferDataToWindow. - - @beginEventTable{wxInitDialogEvent} - @event{EVT_INIT_DIALOG(func)} - Process a wxEVT_INIT_DIALOG event. - @endEventTable - - @library{wxcore} - @category{events} - - @see @ref overview_eventhandling -*/ -class wxInitDialogEvent : public wxEvent -{ -public: - /** - Constructor. - */ - wxInitDialogEvent(int id = 0); -}; - - - -/** - @class wxWindowDestroyEvent - @wxheader{event.h} - - This event is sent from the wxWindow destructor wxWindow::~wxWindow() when a - window is destroyed. - - When a class derived from wxWindow is destroyed its destructor will have - already run by the time this event is sent. Therefore this event will not - usually be received at all. - - To receive this event wxEvtHandler::Connect() must be used (using an event - table macro will not work). Since it is received after the destructor has run, - an object should not handle its own wxWindowDestroyEvent, but it can be used - to get notification of the destruction of another window. - - @library{wxcore} - @category{events} - - @see @ref overview_eventhandling, wxWindowCreateEvent -*/ -class wxWindowDestroyEvent : public wxCommandEvent -{ -public: - /** - Constructor. - */ - wxWindowDestroyEvent(wxWindow* win = NULL); -}; - - -/** - The possible flag values for a wxNavigationKeyEvent. -*/ -enum wxNavigationKeyEventFlags -{ - wxNKEF_IS_BACKWARD = 0x0000, - wxNKEF_IS_FORWARD = 0x0001, - wxNKEF_WINCHANGE = 0x0002, - wxNKEF_FROMTAB = 0x0004 -}; - - -/** - @class wxNavigationKeyEvent - @wxheader{event.h} - - This event class contains information about navigation events, - generated by navigation keys such as tab and page down. - - This event is mainly used by wxWidgets implementations. - A wxNavigationKeyEvent handler is automatically provided by wxWidgets - when you make a class into a control container with the macro - WX_DECLARE_CONTROL_CONTAINER. - - @beginEventTable{wxNavigationKeyEvent} - @event{EVT_NAVIGATION_KEY(func)} - Process a navigation key event. - @endEventTable - - @library{wxcore} - @category{events} - - @see wxWindow::Navigate, wxWindow::NavigateIn -*/ -class wxNavigationKeyEvent : public wxEvent -{ -public: - wxNavigationKeyEvent(); - wxNavigationKeyEvent(const wxNavigationKeyEvent& event); - - /** - Returns the child that has the focus, or @NULL. - */ - wxWindow* GetCurrentFocus() const; - - /** - Returns @true if the navigation was in the forward direction. - */ - bool GetDirection() const; - - /** - Returns @true if the navigation event was from a tab key. - This is required for proper navigation over radio buttons. - */ - bool IsFromTab() const; - - /** - Returns @true if the navigation event represents a window change - (for example, from Ctrl-Page Down in a notebook). - */ - bool IsWindowChange() const; - - /** - Sets the current focus window member. - */ - void SetCurrentFocus(wxWindow* currentFocus); - - /** - Sets the direction to forward if @a direction is @true, or backward - if @false. - */ - void SetDirection(bool direction); - - /** - Sets the flags for this event. - The @a flags can be a combination of the ::wxNavigationKeyEventFlags values. - */ - void SetFlags(long flags); - - /** - Marks the navigation event as from a tab key. - */ - void SetFromTab(bool fromTab); - - /** - Marks the event as a window change event. - */ - void SetWindowChange(bool windowChange); -}; - - - -/** - @class wxMouseCaptureChangedEvent - @wxheader{event.h} - - An mouse capture changed event is sent to a window that loses its - mouse capture. This is called even if wxWindow::ReleaseCapture - was called by the application code. Handling this event allows - an application to cater for unexpected capture releases which - might otherwise confuse mouse handling code. - - @onlyfor{wxmsw} - - @beginEventTable{wxMouseCaptureChangedEvent} - @event{EVT_MOUSE_CAPTURE_CHANGED(func)} - Process a wxEVT_MOUSE_CAPTURE_CHANGED event. - @endEventTable - - @library{wxcore} - @category{events} - - @see wxMouseCaptureLostEvent, @ref overview_eventhandling, - wxWindow::CaptureMouse, wxWindow::ReleaseMouse, wxWindow::GetCapture -*/ -class wxMouseCaptureChangedEvent : public wxEvent -{ -public: - /** - Constructor. - */ - wxMouseCaptureChangedEvent(wxWindowID windowId = 0, - wxWindow* gainedCapture = NULL); - - /** - Returns the window that gained the capture, or @NULL if it was a - non-wxWidgets window. - */ - wxWindow* GetCapturedWindow() const; -}; - - - -/** - @class wxCloseEvent - @wxheader{event.h} - - This event class contains information about window and session close events. - - The handler function for EVT_CLOSE is called when the user has tried to close a - a frame or dialog box using the window manager (X) or system menu (Windows). - It can also be invoked by the application itself programmatically, for example by - calling the wxWindow::Close function. - - You should check whether the application is forcing the deletion of the window - using wxCloseEvent::CanVeto. If this is @false, you @e must destroy the window - using wxWindow::Destroy. - - If the return value is @true, it is up to you whether you respond by destroying - the window. - - If you don't destroy the window, you should call wxCloseEvent::Veto to - let the calling code know that you did not destroy the window. - This allows the wxWindow::Close function to return @true or @false depending - on whether the close instruction was honoured or not. - - The EVT_END_SESSION event is slightly different as it is sent by the system - when the user session is ending (e.g. because of log out or shutdown) and - so all windows are being forcefully closed. At least under MSW, after the - handler for this event is executed the program is simply killed by the - system. Because of this, the default handler for this event provided by - wxWidgets calls all the usual cleanup code (including wxApp::OnExit()) so - that it could still be executed and exit()s the process itself, without - waiting for being killed. If this behaviour is for some reason undesirable, - make sure that you define a handler for this event in your wxApp-derived - class and do not call @c event.Skip() in it (but be aware that the system - will still kill your application). - - @beginEventTable{wxCloseEvent} - @event{EVT_CLOSE(func)} - Process a close event, supplying the member function. - This event applies to wxFrame and wxDialog classes. - @event{EVT_QUERY_END_SESSION(func)} - Process a query end session event, supplying the member function. - This event can be handled in wxApp-derived class only. - @event{EVT_END_SESSION(func)} - Process an end session event, supplying the member function. - This event can be handled in wxApp-derived class only. - @endEventTable - - @library{wxcore} - @category{events} - - @see wxWindow::Close, @ref overview_windowdeletion -*/ -class wxCloseEvent : public wxEvent -{ -public: - /** - Constructor. - */ - wxCloseEvent(wxEventType commandEventType = wxEVT_NULL, int id = 0); - - /** - Returns @true if you can veto a system shutdown or a window close event. - Vetoing a window close event is not possible if the calling code wishes to - force the application to exit, and so this function must be called to check this. - */ - bool CanVeto() const; - - /** - Returns @true if the user is just logging off or @false if the system is - shutting down. This method can only be called for end session and query end - session events, it doesn't make sense for close window event. - */ - bool GetLoggingOff() const; - - /** - Sets the 'can veto' flag. - */ - void SetCanVeto(bool canVeto); - - /** - Sets the 'force' flag. - */ - void SetForce(bool force) const; - - /** - Sets the 'logging off' flag. - */ - void SetLoggingOff(bool loggingOff); - - /** - Call this from your event handler to veto a system shutdown or to signal - to the calling application that a window close did not happen. - - You can only veto a shutdown if CanVeto() returns @true. - */ - void Veto(bool veto = true); -}; - - - -/** - @class wxMenuEvent - @wxheader{event.h} - - This class is used for a variety of menu-related events. Note that - these do not include menu command events, which are - handled using wxCommandEvent objects. - - The default handler for wxEVT_MENU_HIGHLIGHT displays help - text in the first field of the status bar. - - @beginEventTable{wxMenuEvent} - @event{EVT_MENU_OPEN(func)} - A menu is about to be opened. On Windows, this is only sent once for each - navigation of the menubar (up until all menus have closed). - @event{EVT_MENU_CLOSE(func)} - A menu has been just closed. - @event{EVT_MENU_HIGHLIGHT(id, func)} - The menu item with the specified id has been highlighted: used to show - help prompts in the status bar by wxFrame - @event{EVT_MENU_HIGHLIGHT_ALL(func)} - A menu item has been highlighted, i.e. the currently selected menu item has changed. - @endEventTable - - @library{wxcore} - @category{events} - - @see wxCommandEvent, @ref overview_eventhandling -*/ -class wxMenuEvent : public wxEvent -{ -public: - /** - Constructor. - */ - wxMenuEvent(wxEventType id = wxEVT_NULL, int id = 0, wxMenu* menu = NULL); - - /** - Returns the menu which is being opened or closed. This method should only be - used with the @c OPEN and @c CLOSE events and even for them the - returned pointer may be @NULL in some ports. - */ - wxMenu* GetMenu() const; - - /** - Returns the menu identifier associated with the event. - This method should be only used with the @c HIGHLIGHT events. - */ - int GetMenuId() const; - - /** - Returns @true if the menu which is being opened or closed is a popup menu, - @false if it is a normal one. - - This method should only be used with the @c OPEN and @c CLOSE events. - */ - bool IsPopup() const; -}; - -/** - @class wxShowEvent - @wxheader{event.h} - - An event being sent when the window is shown or hidden. - - Currently only wxMSW, wxGTK and wxOS2 generate such events. - - @onlyfor{wxmsw,wxgtk,wxos2} - - @beginEventTable{wxShowEvent} - @event{EVT_SHOW(func)} - Process a wxEVT_SHOW event. - @endEventTable - - @library{wxcore} - @category{events} - - @see @ref overview_eventhandling, wxWindow::Show, - wxWindow::IsShown -*/ - -class wxShowEvent : public wxEvent -{ -public: - /** - Constructor. - */ - wxShowEvent(int winid = 0, bool show = false); - - /** - Set whether the windows was shown or hidden. - */ - void SetShow(bool show); - - /** - Return @true if the window has been shown, @false if it has been - hidden. - */ - bool IsShown() const; - - /** - @deprecated This function is deprecated in favour of IsShown(). - */ - bool GetShow() const; -}; - - - -/** - @class wxIconizeEvent - @wxheader{event.h} - - An event being sent when the frame is iconized (minimized) or restored. - - Currently only wxMSW and wxGTK generate such events. - - @onlyfor{wxmsw,wxgtk} - - @beginEventTable{wxIconizeEvent} - @event{EVT_ICONIZE(func)} - Process a wxEVT_ICONIZE event. - @endEventTable - - @library{wxcore} - @category{events} - - @see @ref overview_eventhandling, wxTopLevelWindow::Iconize, - wxTopLevelWindow::IsIconized -*/ -class wxIconizeEvent : public wxEvent -{ -public: - /** - Constructor. - */ - wxIconizeEvent(int id = 0, bool iconized = true); - - /** - Returns @true if the frame has been iconized, @false if it has been - restored. - */ - bool IsIconized() const; - - /** - @deprecated This function is deprecated in favour of IsIconized(). - */ - bool Iconized() const; -}; - - - -/** - @class wxMoveEvent - @wxheader{event.h} - - A move event holds information about move change events. - - @beginEventTable{wxMoveEvent} - @event{EVT_MOVE(func)} - Process a wxEVT_MOVE event, which is generated when a window is moved. - @event{EVT_MOVE_START(func)} - Process a wxEVT_MOVE_START event, which is generated when the user starts - to move or size a window. wxMSW only. - @event{EVT_MOVE_END(func)} - Process a wxEVT_MOVE_END event, which is generated when the user stops - moving or sizing a window. wxMSW only. - @endEventTable - - @library{wxcore} - @category{events} - - @see wxPoint, @ref overview_eventhandling -*/ -class wxMoveEvent : public wxEvent -{ -public: - /** - Constructor. - */ - wxMoveEvent(const wxPoint& pt, int id = 0); - - /** - Returns the position of the window generating the move change event. - */ - wxPoint GetPosition() const; -}; - - -/** - @class wxSizeEvent - @wxheader{event.h} - - A size event holds information about size change events. - - The EVT_SIZE handler function will be called when the window has been resized. - - You may wish to use this for frames to resize their child windows as appropriate. - - Note that the size passed is of the whole window: call wxWindow::GetClientSize - for the area which may be used by the application. - - When a window is resized, usually only a small part of the window is damaged - and you may only need to repaint that area. However, if your drawing depends on the - size of the window, you may need to clear the DC explicitly and repaint the whole window. - In which case, you may need to call wxWindow::Refresh to invalidate the entire window. - - @beginEventTable{wxSizeEvent} - @event{EVT_SIZE(func)} - Process a wxEVT_SIZE event. - @endEventTable - - @library{wxcore} - @category{events} - - @see wxSize, @ref overview_eventhandling -*/ -class wxSizeEvent : public wxEvent -{ -public: - /** - Constructor. - */ - wxSizeEvent(const wxSize& sz, int id = 0); - - /** - Returns the entire size of the window generating the size change event. - */ - wxSize GetSize() const; -}; - - - -/** - @class wxSetCursorEvent - @wxheader{event.h} - - A SetCursorEvent is generated when the mouse cursor is about to be set as a - result of mouse motion. - - This event gives the application the chance to perform specific mouse cursor - processing based on the current position of the mouse within the window. - Use wxSetCursorEvent::SetCursor to specify the cursor you want to be displayed. - - @beginEventTable{wxSetCursorEvent} - @event{EVT_SET_CURSOR(func)} - Process a wxEVT_SET_CURSOR event. - @endEventTable - - @library{wxcore} - @category{events} - - @see ::wxSetCursor, wxWindow::wxSetCursor -*/ -class wxSetCursorEvent : public wxEvent -{ -public: - /** - Constructor, used by the library itself internally to initialize the event - object. - */ - wxSetCursorEvent(wxCoord x = 0, wxCoord y = 0); - - /** - Returns a reference to the cursor specified by this event. - */ - const wxCursor& GetCursor() const; - - /** - Returns the X coordinate of the mouse in client coordinates. - */ - wxCoord GetX() const; - - /** - Returns the Y coordinate of the mouse in client coordinates. - */ - wxCoord GetY() const; - - /** - Returns @true if the cursor specified by this event is a valid cursor. - - @remarks You cannot specify wxNullCursor with this event, as it is not - considered a valid cursor. - */ - bool HasCursor() const; - - /** - Sets the cursor associated with this event. - */ - void SetCursor(const wxCursor& cursor); -}; - - - -// ============================================================================ -// Global functions/macros -// ============================================================================ - -/** @ingroup group_funcmacro_misc */ -//@{ - -/** - In a GUI application, this function posts @a event to the specified @e dest - object using wxEvtHandler::AddPendingEvent(). - - Otherwise, it dispatches @a event immediately using - wxEvtHandler::ProcessEvent(). See the respective documentation for details - (and caveats). Because of limitation of wxEvtHandler::AddPendingEvent() - this function is not thread-safe for event objects having wxString fields, - use wxQueueEvent() instead. - - @header{wx/event.h} -*/ -void wxPostEvent(wxEvtHandler* dest, const wxEvent& event); - -/** - Queue an event for processing on the given object. - - This is a wrapper around wxEvtHandler::QueueEvent(), see its documentation - for more details. - - @header{wx/event.h} - - @param dest - The object to queue the event on, can't be @c NULL. - @param event - The heap-allocated and non-@c NULL event to queue, the function takes - ownership of it. - */ -void wxQueueEvent(wxEvtHandler* dest, wxEvent *event); - -//@} - diff --git a/interface/fdrepdlg.h b/interface/fdrepdlg.h deleted file mode 100644 index e704d00c4e..0000000000 --- a/interface/fdrepdlg.h +++ /dev/null @@ -1,210 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: fdrepdlg.h -// Purpose: interface of wxFindDialogEvent, wxFindReplaceDialog -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - - -/** - See wxFindDialogEvent::GetFlags(). -*/ -enum wxFindReplaceFlags -{ - /** downward search/replace selected (otherwise - upwards) */ - wxFR_DOWN = 1, - - /** whole word search/replace selected */ - wxFR_WHOLEWORD = 2, - - /** case sensitive search/replace selected (otherwise - case insensitive) */ - wxFR_MATCHCASE = 4 -} - - -/** - These flags can be specified in wxFindReplaceDialog ctor or Create(): -*/ -enum wxFindReplaceDialogStyles -{ - /** replace dialog (otherwise find dialog) */ - wxFR_REPLACEDIALOG = 1, - - /** don't allow changing the search direction */ - wxFR_NOUPDOWN = 2, - - /** don't allow case sensitive searching */ - wxFR_NOMATCHCASE = 4, - - /** don't allow whole word searching */ - wxFR_NOWHOLEWORD = 8 -} - - -/** - @class wxFindDialogEvent - @wxheader{fdrepdlg.h} - - wxFindReplaceDialog events - - @beginEventTable{wxFindDialogEvent} - @event{EVT_FIND(id, func)} - Find button was pressed in the dialog. - @event{EVT_FIND_NEXT(id, func)} - Find next button was pressed in the dialog. - @event{EVT_FIND_REPLACE(id, func)} - Replace button was pressed in the dialog. - @event{EVT_FIND_REPLACE_ALL(id, func)} - Replace all button was pressed in the dialog. - @event{EVT_FIND_CLOSE(id, func)} - The dialog is being destroyed, any pointers to it cannot be used any longer. - @endEventTable - - @library{wxcore} - @category{events} -*/ -class wxFindDialogEvent : public wxCommandEvent -{ -public: - /** - Constuctor used by wxWidgets only. - */ - wxFindDialogEvent(wxEventType commandType = wxEVT_NULL, - int id = 0); - - /** - Return the pointer to the dialog which generated this event. - */ - wxFindReplaceDialog* GetDialog() const; - - /** - Return the string to find (never empty). - */ - wxString GetFindString() const; - - /** - Get the currently selected flags: this is the combination of - the ::wxFindReplaceFlags enumeration values. - */ - int GetFlags() const; - - /** - Return the string to replace the search string with (only for replace and - replace all events). - */ - const wxString& GetReplaceString() const; -}; - - - -/** - @class wxFindReplaceData - @wxheader{fdrepdlg.h} - - wxFindReplaceData holds the data for wxFindReplaceDialog. - - It is used to initialize the dialog with the default values and will keep the - last values from the dialog when it is closed. It is also updated each time a - wxFindDialogEvent is generated so instead of using the wxFindDialogEvent - methods you can also directly query this object. - - Note that all @c SetXXX() methods may only be called before showing the - dialog and calling them has no effect later. - - @library{wxcore} - @category{data} -*/ -class wxFindReplaceData : public wxObject -{ -public: - /** - Constuctor initializes the flags to default value (0). - */ - wxFindReplaceData(wxUint32 flags = 0); - - /** - Get the string to find. - */ - const wxString GetFindString(); - - /** - Get the combination of @c wxFindReplaceFlags values. - */ - int GetFlags() const; - - /** - Get the replacement string. - */ - const wxString GetReplaceString(); - - /** - Set the string to find (used as initial value by the dialog). - */ - void SetFindString(const wxString& str); - - /** - Set the flags to use to initialize the controls of the dialog. - */ - void SetFlags(wxUint32 flags); - - /** - Set the replacement string (used as initial value by the dialog). - */ - void SetReplaceString(const wxString& str); -}; - - - -/** - @class wxFindReplaceDialog - @wxheader{fdrepdlg.h} - - wxFindReplaceDialog is a standard modeless dialog which is used to allow the - user to search for some text (and possibly replace it with something else). - - The actual searching is supposed to be done in the owner window which is the - parent of this dialog. Note that it means that unlike for the other standard - dialogs this one @b must have a parent window. Also note that there is no - way to use this dialog in a modal way; it is always, by design and - implementation, modeless. - - Please see the @ref page_samples_dialogs sample for an example of using it. - - @library{wxcore} - @category{cmndlg} -*/ -class wxFindReplaceDialog : public wxDialog -{ -public: - wxFindReplaceDialog(); - - /** - After using default constructor Create() must be called. - - The @a parent and @a data parameters must be non-@NULL. - */ - wxFindReplaceDialog(wxWindow* parent, - wxFindReplaceData* data, - const wxString& title, - int style = 0); - - /** - Destructor. - */ - ~wxFindReplaceDialog(); - - /** - Creates the dialog; use wxWindow::Show to show it on screen. - - The @a parent and @a data parameters must be non-@NULL. - */ - bool Create(wxWindow* parent, wxFindReplaceData* data, - const wxString& title, int style = 0); - - /** - Get the wxFindReplaceData object used by this dialog. - */ - const wxFindReplaceData* GetData() const; -}; - diff --git a/interface/ffile.h b/interface/ffile.h deleted file mode 100644 index a19619ff9a..0000000000 --- a/interface/ffile.h +++ /dev/null @@ -1,246 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: ffile.h -// Purpose: interface of wxFFile -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - - - -/** - Values used for both wxFile and wxFFile. - - @todo make the value names uppercase -*/ -enum wxSeekMode -{ - wxFromStart, - wxFromCurrent, - wxFromEnd -}; - -/** - See wxFFile::GetKind(). -*/ -enum wxFileKind -{ - wxFILE_KIND_UNKNOWN, - wxFILE_KIND_DISK, /**< A file supporting seeking to arbitrary offsets. */ - wxFILE_KIND_TERMINAL, /**< A terminal. */ - wxFILE_KIND_PIPE /**< A pipe. */ -}; - - -/** - @class wxFFile - @wxheader{ffile.h} - - wxFFile implements buffered file I/O. - - This is a very small class designed to minimize the overhead of using it - in fact, - there is hardly any overhead at all, but using it brings you automatic error checking - and hides differences between platforms and compilers. - - It wraps inside it a @c FILE * handle used by standard C IO library (also known as @c stdio). - - @library{wxbase} - @category{file} - - @see wxFFile::IsOpened -*/ -class wxFFile -{ -public: - wxFFile(); - - /** - Opens a file with the given file pointer, which has already been opened. - - @param fp - An existing file descriptor, such as stderr. - */ - wxFFile(FILE* fp); - - /** - Opens a file with the given mode. - As there is no way to return whether the operation was successful or not from - the constructor you should test the return value of IsOpened() to check that it - didn't fail. - - @param filename - The filename. - @param mode - The mode in which to open the file using standard C strings. - Note that you should use "b" flag if you use binary files under Windows - or the results might be unexpected due to automatic newline conversion done - for the text files. - */ - wxFFile(const wxString& filename, const wxString& mode = "r"); - - - /** - Destructor will close the file. - - @note it is not virtual so you should @e not derive from wxFFile! - */ - ~wxFFile(); - - /** - Attaches an existing file pointer to the wxFFile object. - - The descriptor should be already opened and it will be closed by wxFFile object. - */ - void Attach(FILE* fp); - - /** - Closes the file and returns @true on success. - */ - bool Close(); - - /** - Get back a file pointer from wxFFile object -- the caller is responsible for - closing the file if this descriptor is opened. - - IsOpened() will return @false after call to Detach(). - */ - void Detach(); - - /** - Returns @true if the an attempt has been made to read @e past - the end of the file. - - Note that the behaviour of the file descriptor based class wxFile is different as - wxFile::Eof() will return @true here as soon as the last byte of the file has been read. - - Also note that this method may only be called for opened files and may crash if - the file is not opened. - - @todo THIS METHOD MAY CRASH? DOESN'T SOUND GOOD - - @see IsOpened() - */ - bool Eof() const; - - /** - Returns @true if an error has occurred on this file, similar to the standard - @c ferror() function. - - Please note that this method may only be called for opened files and may crash - if the file is not opened. - - @todo THIS METHOD MAY CRASH? DOESN'T SOUND GOOD - - @see IsOpened() - */ - bool Error() const; - - /** - Flushes the file and returns @true on success. - */ - bool Flush(); - - /** - Returns the type of the file. - - @see wxFileKind - */ - wxFileKind GetKind() const; - - /** - Returns @true if the file is opened. - - Most of the methods of this class may only be used for an opened file. - */ - bool IsOpened() const; - - /** - Returns the length of the file. - */ - wxFileOffset Length() const; - - /** - Opens the file, returning @true if successful. - - @param filename - The filename. - @param mode - The mode in which to open the file. - */ - bool Open(const wxString& filename, const wxString& mode = "r"); - - /** - Reads the specified number of bytes into a buffer, returning the actual number read. - - @param buffer - A buffer to receive the data. - @param count - The number of bytes to read. - - @return The number of bytes read. - */ - size_t Read(void* buffer, size_t count); - - /** - Reads the entire contents of the file into a string. - - @param str - String to read data into. - @param conv - Conversion object to use in Unicode build; by default supposes - that file contents is encoded in UTF-8. - - @return @true if file was read successfully, @false otherwise. - */ - bool ReadAll(wxString* str, const wxMBConv& conv = wxConvAuto()); - - /** - Seeks to the specified position and returns @true on success. - - @param ofs - Offset to seek to. - @param mode - One of wxFromStart, wxFromEnd, wxFromCurrent. - */ - bool Seek(wxFileOffset ofs, wxSeekMode mode = wxFromStart); - - /** - Moves the file pointer to the specified number of bytes before the end of the - file and returns @true on success. - - @param ofs - Number of bytes before the end of the file. - */ - bool SeekEnd(wxFileOffset ofs = 0); - - /** - Returns the current position. - */ - wxFileOffset Tell() const; - - /** - Writes the contents of the string to the file, returns @true on success. - - The second argument is only meaningful in Unicode build of wxWidgets when - @a conv is used to convert @a str to multibyte representation. - */ - bool Write(const wxString& str, const wxMBConv& conv = wxConvAuto()); - - /** - Writes the specified number of bytes from a buffer. - - @param buffer - A buffer containing the data. - @param count - The number of bytes to write. - - @return The number of bytes written. - */ - size_t Write(const void* buffer, size_t count); - - /** - Returns the file pointer associated with the file. - */ - FILE* fp() const; -}; - diff --git a/interface/file.h b/interface/file.h deleted file mode 100644 index cb74e2dfa8..0000000000 --- a/interface/file.h +++ /dev/null @@ -1,325 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: file.h -// Purpose: interface of wxTempFile -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxTempFile - @wxheader{file.h} - - wxTempFile provides a relatively safe way to replace the contents of the - existing file. The name is explained by the fact that it may be also used as - just a temporary file if you don't replace the old file contents. - - Usually, when a program replaces the contents of some file it first opens it for - writing, thus losing all of the old data and then starts recreating it. This - approach is not very safe because during the regeneration of the file bad things - may happen: the program may find that there is an internal error preventing it - from completing file generation, the user may interrupt it (especially if file - generation takes long time) and, finally, any other external interrupts (power - supply failure or a disk error) will leave you without either the original file - or the new one. - - wxTempFile addresses this problem by creating a temporary file which is meant to - replace the original file - but only after it is fully written. So, if the user - interrupts the program during the file generation, the old file won't be lost. - Also, if the program discovers itself that it doesn't want to replace the old - file there is no problem - in fact, wxTempFile will @b not replace the old - file by default, you should explicitly call wxTempFile::Commit - to do it. Calling wxTempFile::Discard explicitly discards any - modifications: it closes and deletes the temporary file and leaves the original - file unchanged. If you don't call neither of Commit() and Discard(), the - destructor will call Discard() automatically. - - To summarize: if you want to replace another file, create an instance of - wxTempFile passing the name of the file to be replaced to the constructor (you - may also use default constructor and pass the file name to - wxTempFile::Open). Then you can wxTempFile::write - to wxTempFile using wxFile-like functions and later call - Commit() to replace the old file (and close this one) or call Discard() to - cancel - the modifications. - - @library{wxbase} - @category{file} -*/ -class wxTempFile -{ -public: - /** - Associates wxTempFile with the file to be replaced and opens it. You should use - IsOpened() to verify if the constructor succeeded. - */ - wxTempFile(const wxString& strName); - - /** - Destructor calls Discard() if temporary file - is still opened. - */ - ~wxTempFile(); - - /** - Validate changes: deletes the old file of name m_strName and renames the new - file to the old name. Returns @true if both actions succeeded. If @false is - returned it may unfortunately mean two quite different things: either that - either the old file couldn't be deleted or that the new file couldn't be renamed - to the old name. - */ - bool Commit(); - - /** - Discard changes: the old file contents is not changed, temporary file is - deleted. - */ - void Discard(); - - /** - Returns @true if the file was successfully opened. - */ - bool IsOpened() const; - - /** - Returns the length of the file. - */ - wxFileOffset Length() const; - - /** - Open the temporary file, returns @true on success, @false if an error - occurred. - @a strName is the name of file to be replaced. The temporary file is always - created in the directory where @a strName is. In particular, if - @a strName doesn't include the path, it is created in the current directory - and the program should have write access to it for the function to succeed. - */ - bool Open(const wxString& strName); - - /** - Seeks to the specified position. - */ - wxFileOffset Seek(wxFileOffset ofs, - wxSeekMode mode = wxFromStart); - - /** - Returns the current position or wxInvalidOffset if file is not opened or if - another - error occurred. - */ - wxFileOffset Tell() const; - - /** - Write to the file, return @true on success, @false on failure. - The second argument is only meaningful in Unicode build of wxWidgets when - @a conv is used to convert @a str to multibyte representation. - */ - bool Write(const wxString& str, - const wxMBConv& conv = wxConvUTF8); -}; - - - -/** - @class wxFile - @wxheader{file.h} - - A wxFile performs raw file I/O. This is a very small class designed to - minimize the overhead of using it - in fact, there is hardly any overhead at - all, but using it brings you automatic error checking and hides differences - between platforms and compilers. wxFile also automatically closes the file in - its destructor making it unnecessary to worry about forgetting to do it. - wxFile is a wrapper around @c file descriptor. - see also - wxFFile for a wrapper around @c FILE structure. - - @c wxFileOffset is used by the wxFile functions which require offsets as - parameter or return them. If the platform supports it, wxFileOffset is a typedef - for a native 64 bit integer, otherwise a 32 bit integer is used for - wxFileOffset. - - @library{wxbase} - @category{file} -*/ -class wxFile -{ -public: - //@{ - /** - Associates the file with the given file descriptor, which has already been - opened. - - @param filename - The filename. - @param mode - The mode in which to open the file. May be one of read(), write() and - wxFile::read_write. - @param fd - An existing file descriptor (see Attach() for the list of predefined - descriptors) - */ - wxFile(); - wxFile(const wxString& filename, - wxFile::OpenMode mode = wxFile::read); - wxFile(int fd); - //@} - - /** - Destructor will close the file. - @note it is not virtual so you should not use wxFile polymorphically. - */ - ~wxFile(); - - /** - This function verifies if we may access the given file in specified mode. Only - values of read() or write() really make sense here. - */ - static bool Access(const wxString& name, OpenMode mode); - - /** - Attaches an existing file descriptor to the wxFile object. Example of predefined - file descriptors are 0, 1 and 2 which correspond to stdin, stdout and stderr - (and - have symbolic names of @b wxFile::fd_stdin, @b wxFile::fd_stdout and @b - wxFile::fd_stderr). - The descriptor should be already opened and it will be closed by wxFile - object. - */ - void Attach(int fd); - - /** - Closes the file. - */ - void Close(); - - /** - Creates a file for writing. If the file already exists, setting @b overwrite to - @true - will ensure it is overwritten. - */ - bool Create(const wxString& filename, bool overwrite = false, - int access = wxS_DEFAULT); - - /** - Get back a file descriptor from wxFile object - the caller is responsible for - closing the file if this - descriptor is opened. IsOpened() will return @false after call to Detach(). - */ - void Detach(); - - /** - Returns @true if the end of the file has been reached. - Note that the behaviour of the file pointer based class - wxFFile is different as wxFFile::Eof - will return @true here only if an attempt has been made to read - @e past the last byte of the file, while wxFile::Eof() will return @true - even before such attempt is made if the file pointer is at the last position - in the file. - Note also that this function doesn't work on unseekable file descriptors - (examples include pipes, terminals and sockets under Unix) and an attempt to - use it will result in an error message in such case. So, to read the entire - file into memory, you should write a loop which uses - Read() repeatedly and tests its return condition instead - of using Eof() as this will not work for special files under Unix. - */ - bool Eof() const; - - /** - Returns @true if the given name specifies an existing regular file (not a - directory or a link) - */ - static bool Exists(const wxString& filename); - - /** - Flushes the file descriptor. - Note that Flush() is not implemented on some Windows compilers - due to a missing fsync function, which reduces the usefulness of this function - (it can still be called but it will do nothing on unsupported compilers). - */ - bool Flush(); - - /** - Returns the type of the file. Possible return values are: - */ - wxFileKind GetKind() const; - - /** - Returns @true if the file has been opened. - */ - bool IsOpened() const; - - /** - Returns the length of the file. - */ - wxFileOffset Length() const; - - /** - Opens the file, returning @true if successful. - - @param filename - The filename. - @param mode - The mode in which to open the file. May be one of read(), write() and - wxFile::read_write. - */ - bool Open(const wxString& filename, - wxFile::OpenMode mode = wxFile::read); - - //@{ - /** - if there was an error. - */ - size_t Read(void* buffer, size_t count); - Parameters Return value - The number of bytes read, or the symbol wxInvalidOffset(); - //@} - - /** - Seeks to the specified position. - - @param ofs - Offset to seek to. - @param mode - One of wxFromStart, wxFromEnd, wxFromCurrent. - - @return The actual offset position achieved, or wxInvalidOffset on - failure. - */ - wxFileOffset Seek(wxFileOffset ofs, - wxSeekMode mode = wxFromStart); - - /** - Moves the file pointer to the specified number of bytes relative to the end of - the file. For example, @c SeekEnd(-5) would position the pointer 5 - bytes before the end. - - @param ofs - Number of bytes before the end of the file. - - @return The actual offset position achieved, or wxInvalidOffset on - failure. - */ - wxFileOffset SeekEnd(wxFileOffset ofs = 0); - - /** - Returns the current position or wxInvalidOffset if file is not opened or if - another - error occurred. - */ - wxFileOffset Tell() const; - - /** - Writes the contents of the string to the file, returns @true on success. - The second argument is only meaningful in Unicode build of wxWidgets when - @a conv is used to convert @a s to multibyte representation. - Note that this method only works with @c NUL-terminated strings, if you want - to write data with embedded @c NULs to the file you should use the other - @ref write() "Write() overload". - */ - bool Write(const wxString& s, const wxMBConv& conv = wxConvUTF8); - - /** - Returns the file descriptor associated with the file. - */ - int fd() const; -}; - diff --git a/interface/fileconf.h b/interface/fileconf.h deleted file mode 100644 index cdef167a00..0000000000 --- a/interface/fileconf.h +++ /dev/null @@ -1,86 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: fileconf.h -// Purpose: interface of wxFileConfig -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxFileConfig - @wxheader{fileconf.h} - - wxFileConfig implements wxConfigBase interface for - storing and retrieving configuration information using plain text files. The - files have a simple format reminiscent of Windows INI files with lines of the - form @c "key = value" defining the keys and lines of special form - @c "[group]" indicating the start of each group. - - This class is used by default for wxConfig on Unix platforms but may also be - used explicitly if you want to use files and not the registry even under - Windows. - - @library{wxbase} - @category{misc} - - @see wxFileConfig::Save -*/ -class wxFileConfig : public wxConfigBase -{ -public: - /** - Read the config data from the specified stream instead of the associated file, - as usual. - - @see Save() - */ - wxFileConfig(wxInputStream& is, const wxMBConv& conv = wxConvAuto()); - - /** - Return the full path to the file which would be used by wxFileConfig as global, - system-wide, file if it were constructed with @a basename as "global filename" - parameter in the constructor. - - Notice that this function cannot be used if @a basename is already a full path name. - */ - static wxFileName GetGlobalFile(const wxString& basename); - - /** - Return the full path to the file which would be used by wxFileConfig as local, - user-specific, file if it were constructed with @a basename as "local filename" - parameter in the constructor. - - @a style has the same meaning as in @ref wxConfigBase::wxConfigBase "wxConfig constructor" - and can contain any combination of styles but only wxCONFIG_USE_SUBDIR bit is - examined by this function. - - Notice that this function cannot be used if @a basename is already a full path name. - */ - static wxFileName GetLocalFile(const wxString& basename, int style = 0); - - /** - Saves all config data to the given stream, returns @true if data was saved - successfully or @false on error. - - Note the interaction of this function with the internal "dirty flag": the - data is saved unconditionally, i.e. even if the object is not dirty. However - after saving it successfully, the dirty flag is reset so no changes will be - written back to the file this object is associated with until you change its - contents again. - - @see wxConfigBase::Flush - */ - bool Save(wxOutputStream& os, const wxMBConv& conv = wxConvAuto()); - - /** - Allows to set the mode to be used for the config file creation. For example, to - create a config file which is not readable by other users (useful if it stores - some sensitive information, such as passwords), you could use @c SetUmask(0077). - - This function doesn't do anything on non-Unix platforms. - - @see wxCHANGE_UMASK() - */ - void SetUmask(int mode); -}; - diff --git a/interface/filectrl.h b/interface/filectrl.h deleted file mode 100644 index dfbc382192..0000000000 --- a/interface/filectrl.h +++ /dev/null @@ -1,246 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: filectrl.h -// Purpose: interface of wxFileCtrl -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxFileCtrl - @wxheader{filectrl.h} - - This control allows the user to select a file. - - Two implemetations exist, one for Gtk and another generic one for anything - other than Gtk. It is only available if @c wxUSE_FILECTRL is set to 1. - - @beginStyleTable - @style{wxFC_DEFAULT_STYLE} - The default style: wxFC_OPEN - @style{wxFC_OPEN} - Creates an file control suitable for opening files. Cannot be - combined with wxFC_SAVE. - @style{wxFC_SAVE} - Creates an file control suitable for saving files. Cannot be - combined with wxFC_OPEN. - @style{wxFC_MULTIPLE} - For open control only, Allows selecting multiple files. Cannot be - combined with wxFC_SAVE - @style{wxFC_NOSHOWHIDDEN} - Hides the "Show Hidden Files" checkbox (Generic only) - @endStyleTable - - - @beginEventTable{wxFileCtrlEvent} - @event{EVT_FILECTRL_FILEACTIVATED(id, func)} - The user activated a file(by double-clicking or pressing Enter) - @event{EVT_FILECTRL_SELECTIONCHANGED(id, func)} - The user changed the current selection(by selecting or deselecting a file) - @event{EVT_FILECTRL_FOLDERCHANGED(id, func)} - The current folder of the file control has been changed - @endEventTable - - @nativeimpl{gtk} - - @library{wxbase} - @category{miscwnd} - - @see wxGenericDirCtrl -*/ -class wxFileCtrl : public wxWindow -{ -public: - wxFileCtrl(); - - /** - Constructs the window. - - @param parent - Parent window, must not be non-@NULL. - @param id - The identifier for the control. - @param defaultDirectory - The initial directory shown in the control. Must be - a valid path to a directory or the empty string. - In case it is the empty string, the current working directory is used. - @param defaultFilename - The default filename, or the empty string. - @param wildcard - A wildcard specifying which files can be selected, - such as "*.*" or "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif". - @param style - The window style, see wxFC_* flags. - @param pos - Initial position. - @param size - Initial size. - @param name - Control name. - - @return @true if the control was successfully created or @false if - creation failed. - */ - - wxFileCtrl(wxWindow* parent, wxWindowID id, - const wxString& defaultDirectory = wxEmptyString, - const wxString& defaultFilename = wxEmptyString, - const wxPoint& wildCard = wxFileSelectorDefaultWildcardStr, - long style = wxFC_DEFAULT_STYLE, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - const wxString& name = "filectrl"); - - /** - Create function for two-step construction. See wxFileCtrl() for details. - */ - bool Create(wxWindow* parent, wxWindowID id, - const wxString& defaultDirectory = wxEmptyString, - const wxString& defaultFilename = wxEmptyString, - const wxPoint& wildCard = wxFileSelectorDefaultWildcardStr, - long style = wxFC_DEFAULT_STYLE, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - const wxString& name = "filectrl"); - - /** - Returns the current directory of the file control (i.e. the directory shown by it). - */ - wxString GetDirectory() const; - - /** - Returns the currently selected filename. - - For the controls having the @c wxFC_MULTIPLE style, use GetFilenames() instead. - */ - wxString GetFilename() const; - - /** - Fills the array @a filenames with the filenames only of selected items. - - This function should only be used with the controls having the @c wxFC_MULTIPLE - style, use GetFilename() for the others. - - @remarks filenames is emptied first. - */ - void GetFilenames(wxArrayString& filenames) const; - - /** - Returns the zero-based index of the currently selected filter. - */ - int GetFilterIndex() const; - - /** - Returns the full path (directory and filename) of the currently selected file. - For the controls having the @c wxFC_MULTIPLE style, use GetPaths() instead. - */ - wxString GetPath() const; - - /** - Fills the array @a paths with the full paths of the files chosen. - - This function should be used with the controls having the @c wxFC_MULTIPLE style, - use GetPath() otherwise. - - @remarks paths is emptied first. - */ - void GetPaths(wxArrayString& paths) const; - - /** - Returns the current wildcard. - */ - wxString GetWildcard() const; - - /** - Sets(changes) the current directory displayed in the control. - - @return Returns @true on success, @false otherwise. - */ - bool SetDirectory(const wxString& directory); - - /** - Selects a certain file. - - @return Returns @true on success, @false otherwise - */ - bool SetFilename(const wxString& filename); - - /** - Sets the current filter index, starting from zero. - */ - void SetFilterIndex(int filterIndex); - - /** - Sets the wildcard, which can contain multiple file types, for example: - "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif" - */ - void SetWildcard(const wxString& wildCard); - - /** - Sets whether hidden files and folders are shown or not. - */ - void ShowHidden(const bool show); -}; - - - -/** - @class wxFileCtrlEvent - @wxheader{filectrl.h} - - A file control event holds information about events associated with - wxFileCtrl objects. - - @beginEventTable{wxFileCtrlEvent} - @event{EVT_FILECTRL_FILEACTIVATED(id, func)} - The user activated a file(by double-clicking or pressing Enter) - @event{EVT_FILECTRL_SELECTIONCHANGED(id, func)} - The user changed the current selection(by selecting or deselecting a file) - @event{EVT_FILECTRL_FOLDERCHANGED(id, func)} - The current folder of the file control has been changed - @endEventTable - - @library{wxbase} - @category{events} -*/ -class wxFileCtrlEvent : public wxCommandEvent -{ -public: - /** - Constructor. - */ - wxFileCtrlEvent(wxEventType type, wxObject evtObject, int id); - - /** - Returns the current directory. - - In case of a @b EVT_FILECTRL_FOLDERCHANGED, this method returns the new - directory. - */ - wxString GetDirectory() const; - - /** - Returns the file selected (assuming it is only one file). - */ - wxString GetFile() const; - - /** - Returns the files selected. - - In case of a @b EVT_FILECTRL_SELECTIONCHANGED, this method returns the - files selected after the event. - */ - wxArrayString GetFiles() const; - - /** - Sets the files changed by this event. - */ - void SetFiles(const wxArrayString files); - - - /** - Sets the directory of this event. - */ - void SetDirectory( const wxString &directory ); -}; - diff --git a/interface/filedlg.h b/interface/filedlg.h deleted file mode 100644 index ada7bba196..0000000000 --- a/interface/filedlg.h +++ /dev/null @@ -1,284 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: filedlg.h -// Purpose: interface of wxFileDialog -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxFileDialog - @wxheader{filedlg.h} - - This class represents the file chooser dialog. - - It pops up a file selector box (native for Windows and GTK2.4+). - - The path and filename are distinct elements of a full file pathname. - If path is "", the current directory will be used. If filename is "", no default - filename will be supplied. The wildcard determines what files are displayed in the - file selector, and file extension supplies a type extension for the required filename. - - @remarks - All implementations of the wxFileDialog provide a wildcard filter. Typing a filename - containing wildcards (*, ?) in the filename text item, and clicking on Ok, will - result in only those files matching the pattern being displayed. - The wildcard may be a specification for multiple types of file with a description - for each, such as: - "BMP and GIF files (*.bmp;*.gif)|*.bmp;*.gif|PNG files (*.png)|*.png" - It must be noted that wildcard support in the native Motif file dialog is quite - limited: only one alternative is supported, and it is displayed without the - descriptive test; "BMP files (*.bmp)|*.bmp" is displayed as "*.bmp", and both - "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif" and "Image files|*.bmp;*.gif" - are errors. - - @beginStyleTable - @style{wxFD_DEFAULT_STYLE} - Equivalent to wxFD_OPEN. - @style{wxFD_OPEN} - This is an open dialog; usually this means that the default - button's label of the dialog is "Open". Cannot be combined with wxFD_SAVE. - @style{wxFD_SAVE} - This is a save dialog; usually this means that the default button's - label of the dialog is "Save". Cannot be combined with wxFD_OPEN. - @style{wxFD_OVERWRITE_PROMPT} - For save dialog only: prompt for a confirmation if a file will be - overwritten. - @style{wxFD_FILE_MUST_EXIST} - For open dialog only: the user may only select files that actually exist. - @style{wxFD_MULTIPLE} - For open dialog only: allows selecting multiple files. - @style{wxFD_CHANGE_DIR} - Change the current working directory to the directory where the - file(s) chosen by the user are. - @style{wxFD_PREVIEW} - Show the preview of the selected files (currently only supported by - wxGTK using GTK+ 2.4 or later). - @endStyleTable - - @library{wxcore} - @category{cmndlg} - - @see @ref overview_wxfiledialog, ::wxFileSelector() -*/ -class wxFileDialog : public wxDialog -{ -public: - /** - Constructor. Use ShowModal() to show the dialog. - - @param parent - Parent window. - @param message - Message to show on the dialog. - @param defaultDir - The default directory, or the empty string. - @param defaultFile - The default filename, or the empty string. - @param wildcard - A wildcard, such as "*.*" or "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif". - Note that the native Motif dialog has some limitations with respect to - wildcards; see the Remarks section above. - @param style - A dialog style. See wxFD_* styles for more info. - @param pos - Dialog position. Not implemented. - @param size - Dialog size. Not implemented. - @param name - Dialog name. Not implemented. - */ - wxFileDialog(wxWindow* parent, - const wxString& message = "Choose a file", - const wxString& defaultDir = "", - const wxString& defaultFile = "", - const wxString& wildcard = ".", - long style = wxFD_DEFAULT_STYLE, - const wxPoint& pos = wxDefaultPosition, - const wxSize& sz = wxDefaultSize, - const wxString& name = "filedlg"); - - /** - Destructor. - */ - ~wxFileDialog(); - - /** - Returns the default directory. - */ - wxString GetDirectory() const; - - /** - If functions SetExtraControlCreator() and ShowModal() were called, - returns the extra window. Otherwise returns @NULL. - */ - wxWindow* GetExtraControl() const; - - /** - Returns the default filename. - */ - wxString GetFilename() const; - - /** - Fills the array @a filenames with the names of the files chosen. - - This function should only be used with the dialogs which have @c wxFD_MULTIPLE style, - use GetFilename() for the others. - - Note that under Windows, if the user selects shortcuts, the filenames - include paths, since the application cannot determine the full path - of each referenced file by appending the directory containing the shortcuts - to the filename. - */ - void GetFilenames(wxArrayString& filenames) const; - - /** - Returns the index into the list of filters supplied, optionally, in the - wildcard parameter. - - Before the dialog is shown, this is the index which will be used when the - dialog is first displayed. - - After the dialog is shown, this is the index selected by the user. - */ - int GetFilterIndex() const; - - /** - Returns the message that will be displayed on the dialog. - */ - wxString GetMessage() const; - - /** - Returns the full path (directory and filename) of the selected file. - */ - wxString GetPath() const; - - /** - Fills the array @a paths with the full paths of the files chosen. - - This function should only be used with the dialogs which have @c wxFD_MULTIPLE style, - use GetPath() for the others. - */ - void GetPaths(wxArrayString& paths) const; - - /** - Returns the file dialog wildcard. - */ - wxString GetWildcard() const; - - /** - Sets the default directory. - */ - void SetDirectory(const wxString& directory); - - /** - Customize file dialog by adding extra window, which is typically placed - below the list of files and above the buttons. - - SetExtraControlCreator() can be called only once, before calling ShowModal(). - - The @c creator function should take pointer to parent window (file dialog) - and should return a window allocated with operator new. - - Supported platforms: wxGTK, wxUniv. - */ - bool SetExtraControlCreator(t_extraControlCreator creator); - - /** - Sets the default filename. - */ - void SetFilename(const wxString& setfilename); - - /** - Sets the default filter index, starting from zero. - */ - void SetFilterIndex(int filterIndex); - - /** - Sets the message that will be displayed on the dialog. - */ - void SetMessage(const wxString& message); - - /** - Sets the path (the combined directory and filename that will be returned when - the dialog is dismissed). - */ - void SetPath(const wxString& path); - - /** - Sets the wildcard, which can contain multiple file types, for example: - "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif". - - Note that the native Motif dialog has some limitations with respect to - wildcards; see the Remarks section above. - */ - void SetWildcard(const wxString& wildCard); - - /** - Shows the dialog, returning wxID_OK if the user pressed OK, and wxID_CANCEL - otherwise. - */ - int ShowModal(); -}; - - - -// ============================================================================ -// Global functions/macros -// ============================================================================ - -/** @ingroup group_funcmacro_dialog */ -//@{ - -/** - Pops up a file selector box. In Windows, this is the common file selector - dialog. In X, this is a file selector box with the same functionality. The - path and filename are distinct elements of a full file pathname. If path - is empty, the current directory will be used. If filename is empty, no - default filename will be supplied. The wildcard determines what files are - displayed in the file selector, and file extension supplies a type - extension for the required filename. Flags may be a combination of - wxFD_OPEN, wxFD_SAVE, wxFD_OVERWRITE_PROMPT or wxFD_FILE_MUST_EXIST. - - @note wxFD_MULTIPLE can only be used with wxFileDialog and not here since - this function only returns a single file name. - - Both the Unix and Windows versions implement a wildcard filter. Typing a - filename containing wildcards (*, ?) in the filename text item, and - clicking on Ok, will result in only those files matching the pattern being - displayed. - - The wildcard may be a specification for multiple types of file with a - description for each, such as: - - @code - "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif" - @endcode - - The application must check for an empty return value (the user pressed - Cancel). For example: - - @code - wxString filename = wxFileSelector("Choose a file to open"); - if ( !filename.empty() ) - { - // work with the file - ... - } - //else: cancelled by user - @endcode - - @header{wx/filedlg.h} -*/ -wxString wxFileSelector(const wxString& message, - const wxString& default_path = "", - const wxString& default_filename = "", - const wxString& default_extension = "", - const wxString& wildcard = ".", - int flags = 0, - wxWindow* parent = NULL, - int x = -1, - int y = -1); - -//@} - diff --git a/interface/filefn.h b/interface/filefn.h deleted file mode 100644 index 533ee9b5a4..0000000000 --- a/interface/filefn.h +++ /dev/null @@ -1,458 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: filefn.h -// Purpose: interface of wxPathList and file functions -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxPathList - @wxheader{filefn.h} - - The path list is a convenient way of storing a number of directories, and - when presented with a filename without a directory, searching for an - existing file in those directories. - - Be sure to look also at wxStandardPaths if you only want to search files in - some standard paths. - - @library{wxbase} - @category{file} - - @see wxArrayString, wxStandardPaths, wxFileName -*/ -class wxPathList : public wxArrayString -{ -public: - wxPathList(); - - /** - Constructs the object calling the Add() function. - */ - wxPathList(const wxArrayString& arr); - - /** - Adds the given directory to the path list, if the @a path is not already in the list. - If the path cannot be normalized for some reason, it returns @false. - - The @a path is always considered to be a directory but no existence checks will be - done on it (because if it doesn't exist, it could be created later and thus result a - valid path when FindValidPath() is called). - - @note if the given path is relative, it won't be made absolute before adding it - (this is why FindValidPath() may return relative paths). - */ - bool Add(const wxString& path); - - /** - Adds all elements of the given array as paths. - */ - void Add(const wxArrayString& arr); - - /** - Finds the value of the given environment variable, and adds all paths - to the path list. - - Useful for finding files in the @c PATH variable, for example. - */ - void AddEnvList(const wxString& env_variable); - - /** - Given a full filename (with path), calls Add() with the path of the file. - */ - bool EnsureFileAccessible(const wxString& filename); - - /** - Like FindValidPath() but this function always returns an absolute path - (eventually prepending the current working directory to the value returned - wxPathList::FindValidPath()) or an empty string. - */ - wxString FindAbsoluteValidPath(const wxString& file) const; - - /** - Searches the given file in all paths stored in this class. - - The first path which concatenated to the given string points to an existing - file (see wxFileExists()) is returned. - - If the file wasn't found in any of the stored paths, an empty string is returned. - - The given string must be a file name, eventually with a path prefix (if the path - prefix is absolute, only its name will be searched); i.e. it must not end with - a directory separator (see wxFileName::GetPathSeparator) otherwise an assertion - will fail. - - The returned path may be relative to the current working directory. - - Note in fact that wxPathList can be used to store both relative and absolute - paths so that if you added relative paths, then the current working directory - (see wxGetCwd() and wxSetWorkingDirectory()) may affect the value returned - by this function! - */ - wxString FindValidPath(const wxString& file) const; -}; - - - -// ============================================================================ -// Global functions/macros -// ============================================================================ - -/** @ingroup group_funcmacro_file */ -//@{ - -/** - Under Unix this macro changes the current process umask to the given value, - unless it is equal to -1 in which case nothing is done, and restores it to - the original value on scope exit. It works by declaring a variable which - sets umask to @a mask in its constructor and restores it in its destructor. - Under other platforms this macro expands to nothing. - - @header{wx/filefn.h} -*/ -#define wxCHANGE_UMASK(int mask) - -/** - This function returns the total number of bytes and number of free bytes on - the disk containing the directory @a path (it should exist). Both @a total - and @a free parameters may be @NULL if the corresponding information is not - needed. - - @since 2.3.2 - - @note The generic Unix implementation depends on the system having the - @c statfs() or @c statvfs() function. - - @return @true on success, @false if an error occurred (for example, the - directory doesn’t exist). - - @header{wx/filefn.h} -*/ -bool wxGetDiskSpace(const wxString& path, - wxLongLong total = NULL, - wxLongLong free = NULL); - -/** - Returns the Windows directory under Windows; other platforms return an - empty string. - - @header{wx/filefn.h} -*/ -wxString wxGetOSDirectory(); - -/** - Parses the @a wildCard, returning the number of filters. Returns 0 if none - or if there's a problem. - - The arrays will contain an equal number of items found before the error. On - platforms where native dialogs handle only one filter per entry, entries in - arrays are automatically adjusted. @a wildCard is in the form: - - @code - "All files (*)|*|Image Files (*.jpeg *.png)|*.jpg;*.png" - @endcode - - @header{wx/filefn.h} -*/ -int wxParseCommonDialogsFilter(const wxString& wildCard, - wxArrayString& descriptions, - wxArrayString& filters); - -/** - Converts a DOS to a Unix filename by replacing backslashes with forward - slashes. - - @header{wx/filefn.h} -*/ -void wxDos2UnixFilename(wxChar* s); - -/** - @warning This function is deprecated, use wxFileName instead. - - Converts a Unix to a DOS filename by replacing forward slashes with - backslashes. - - @header{wx/filefn.h} -*/ -void wxUnix2DosFilename(wxChar* s); - -/** - Returns @true if @a dirname exists and is a directory. - - @header{wx/filefn.h} -*/ -bool wxDirExists(const wxString& dirname); - -/** - @warning This function is obsolete, please use wxFileName::SplitPath() - instead. - - This function splits a full file name into components: the path (including - possible disk/drive specification under Windows), the base name, and the - extension. Any of the output parameters (@a path, @a name or @a ext) may be - @NULL if you are not interested in the value of a particular component. - - wxSplitPath() will correctly handle filenames with both DOS and Unix path - separators under Windows, however it will not consider backslashes as path - separators under Unix (where backslash is a valid character in a filename). - - On entry, @a fullname should be non-@NULL (it may be empty though). - - On return, @a path contains the file path (without the trailing separator), - @a name contains the file name and @c ext contains the file extension - without leading dot. All three of them may be empty if the corresponding - component is. The old contents of the strings pointed to by these - parameters will be overwritten in any case (if the pointers are not @NULL). - - @header{wx/filefn.h} -*/ -void wxSplitPath(const wxString& fullname, - wxString* path, - wxString* name, - wxString* ext); - -/** - Returns time of last modification of given file. - - The function returns (time_t)-1 if an error occurred (e.g. file - not found). - - @header{wx/filefn.h} -*/ -time_t wxFileModificationTime(const wxString& filename); - -/** - Renames @a file1 to @e file2, returning @true if successful. - - If @a overwrite parameter is @true (default), the destination file is - overwritten if it exists, but if @a overwrite is @false, the functions - fails in this case. - - @header{wx/filefn.h} -*/ -bool wxRenameFile(const wxString& file1, - const wxString& file2, - bool overwrite = true); - -/** - Copies @a file1 to @e file2, returning @true if successful. If @a overwrite - parameter is @true (default), the destination file is overwritten if it - exists, but if @a overwrite is @false, the functions fails in this case. - - This function supports resources forks under Mac OS. - - @header{wx/filefn.h} -*/ -bool wxCopyFile(const wxString& file1, - const wxString& file2, - bool overwrite = true); - -/** - Returns @true if the file exists and is a plain file. - - @header{wx/filefn.h} -*/ -bool wxFileExists(const wxString& filename); - -/** - Returns @true if the @a pattern matches the @e text; if @a dot_special is - @true, filenames beginning with a dot are not matched with wildcard - characters. - - @see wxIsWild() - - @header{wx/filefn.h} -*/ -bool wxMatchWild(const wxString& pattern, - const wxString& text, - bool dot_special); - -/** - @warning This function is deprecated, use wxGetCwd() instead. - - Copies the current working directory into the buffer if supplied, or copies - the working directory into new storage (which you must delete yourself) if - the buffer is @NULL. - - @a sz is the size of the buffer if supplied. - - @header{wx/filefn.h} -*/ -wxString wxGetWorkingDirectory(char* buf = NULL, int sz = 1000); - -/** - Returns the directory part of the filename. - - @header{wx/filefn.h} -*/ -wxString wxPathOnly(const wxString& path); - -/** - Returns @true if the pattern contains wildcards. - - @see wxMatchWild() - - @header{wx/filefn.h} -*/ -bool wxIsWild(const wxString& pattern); - -/** - Returns @true if the argument is an absolute filename, i.e. with a slash - or drive name at the beginning. - - @header{wx/filefn.h} -*/ -bool wxIsAbsolutePath(const wxString& filename); - -/** - Returns a string containing the current (or working) directory. - - @header{wx/filefn.h} -*/ -wxString wxGetCwd(); - -/** - Sets the current working directory, returning @true if the operation - succeeded. Under MS Windows, the current drive is also changed if @a dir - contains a drive specification. - - @header{wx/filefn.h} -*/ -bool wxSetWorkingDirectory(const wxString& dir); - -/** - Concatenates @a file1 and @a file2 to @e file3, returning @true if - successful. - - @header{wx/filefn.h} -*/ -bool wxConcatFiles(const wxString& file1, - const wxString& file2, - const wxString& file3); - -/** - Removes @e file, returning @true if successful. - - @header{wx/filefn.h} -*/ -bool wxRemoveFile(const wxString& file); - -/** - Makes the directory @a dir, returning @true if successful. - - @a perm is the access mask for the directory for the systems on which it is - supported (Unix) and doesn't have any effect on the other ones. - - @header{wx/filefn.h} -*/ -bool wxMkdir(const wxString& dir, int perm = 0777); - -/** - Removes the directory @a dir, returning @true if successful. Does not work - under VMS. - - The @a flags parameter is reserved for future use. - - @note There is also a wxRmDir() function which simply wraps the standard - POSIX @c rmdir() function and so return an integer error code instead - of a boolean value (but otherwise is currently identical to - wxRmdir()), don't confuse these two functions. - - @header{wx/filefn.h} -*/ -bool wxRmdir(const wxString& dir, int flags = 0); - -/** - Returns the next file that matches the path passed to wxFindFirstFile(). - - See wxFindFirstFile() for an example. - - @header{wx/filefn.h} -*/ -wxString wxFindNextFile(); - -/** - This function does directory searching; returns the first file that matches - the path @a spec, or the empty string. Use wxFindNextFile() to get the next - matching file. Neither will report the current directory "." or the parent - directory "..". - - @warning As of 2.5.2, these functions are not thread-safe! (they use static - variables). You probably want to use wxDir::GetFirst() or - wxDirTraverser instead. - - @a spec may contain wildcards. - - @a flags may be wxDIR for restricting the query to directories, wxFILE for - files or zero for either. - - For example: - - @code - wxString f = wxFindFirstFile("/home/project/*.*"); - while ( !f.empty() ) - { - ... - f = wxFindNextFile(); - } - @endcode - - @header{wx/filefn.h} -*/ -wxString wxFindFirstFile(const wxString& spec, int flags = 0); - -/** - File kind enumerations returned from wxGetFileKind(). - - @header{wx/filefn.h} -*/ -enum wxFileKind -{ - wxFILE_KIND_UNKNOWN, ///< Unknown file kind, or unable to determine - wxFILE_KIND_DISK, ///< A file supporting seeking to arbitrary offsets - wxFILE_KIND_TERMINAL, ///< A tty - wxFILE_KIND_PIPE ///< A pipe -}; - -//@} - -/** @ingroup group_funcmacro_file */ -//@{ -/** - Returns the type of an open file. Possible return values are enumerations - of ::wxFileKind. - - @header{wx/filefn.h} -*/ -wxFileKind wxGetFileKind(int fd); -wxFileKind wxGetFileKind(FILE* fp); -//@} - -/** @ingroup group_funcmacro_file */ -//@{ -/** - @warning This function is obsolete, please use wxFileName::SplitPath() - instead. - - Returns the filename for a full path. The second form returns a pointer to - temporary storage that should not be deallocated. - - @header{wx/filefn.h} -*/ -wxString wxFileNameFromPath(const wxString& path); -char* wxFileNameFromPath(char* path); -//@} - -/** @ingroup group_funcmacro_file */ -//@{ -/** - @warning This function is obsolete, please use - wxFileName::CreateTempFileName() instead. - - @header{wx/filefn.h} -*/ -char* wxGetTempFileName(const wxString& prefix, char* buf = NULL); -bool wxGetTempFileName(const wxString& prefix, wxString& buf); -//@} - diff --git a/interface/filename.h b/interface/filename.h deleted file mode 100644 index 429cee3a8b..0000000000 --- a/interface/filename.h +++ /dev/null @@ -1,1004 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: filename.h -// Purpose: interface of wxFileName -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxFileName - @wxheader{filename.h} - - wxFileName encapsulates a file name. This class serves two purposes: first, it - provides the functions to split the file names into components and to recombine - these components in the full file name which can then be passed to the OS file - functions (and @ref overview_filefunctions "wxWidgets functions" wrapping them). - Second, it includes the functions for working with the files itself. Note that - to change the file data you should use wxFile class instead. - wxFileName provides functions for working with the file attributes. - - When working with directory names (i.e. without filename and extension) - make sure not to misuse the file name part of this class with the last - directory. Instead initialize the wxFileName instance like this: - - @code - wxFileName dirname( "C:\mydir", "" ); - MyMethod( dirname.GetPath() ); - @endcode - - The same can be done using the static method wxFileName::DirName: - - @code - wxFileName dirname = wxFileName::DirName( "C:\mydir" ); - MyMethod( dirname.GetPath() ); - @endcode - - Accordingly, methods dealing with directories or directory names - like wxFileName::IsDirReadable use - wxFileName::GetPath whereas methods dealing - with file names like wxFileName::IsFileReadable - use wxFileName::GetFullPath. - - If it is not known wether a string contains a directory name or - a complete file name (such as when interpreting user input) you need to use - the static function wxFileName::DirExists - (or its identical variants wxDir::Exists and - wxDirExists()) and construct the wxFileName - instance accordingly. This will only work if the directory actually exists, - of course: - - @code - wxString user_input; - // get input from user - - wxFileName fname; - if (wxDirExists(user_input)) - fname.AssignDir( user_input ); - else - fname.Assign( user_input ); - @endcode - - @library{wxbase} - @category{file} - - @see wxFileName::GetCwd -*/ -class wxFileName -{ -public: - //@{ - /** - Constructor from a volume name, a directory name, base file name and extension. - */ - wxFileName(); - wxFileName(const wxFileName& filename); - wxFileName(const wxString& fullpath, - wxPathFormat format = wxPATH_NATIVE); - wxFileName(const wxString& path, const wxString& name, - wxPathFormat format = wxPATH_NATIVE); - wxFileName(const wxString& path, const wxString& name, - const wxString& ext, - wxPathFormat format = wxPATH_NATIVE); - wxFileName(const wxString& volume, const wxString& path, - const wxString& name, - const wxString& ext, - wxPathFormat format = wxPATH_NATIVE); - //@} - - /** - Appends a directory component to the path. This component should contain a - single directory name level, i.e. not contain any path or volume separators nor - should it be empty, otherwise the function does nothing (and generates an - assert failure in debug build). - */ - void AppendDir(const wxString& dir); - - //@{ - /** - Creates the file name from various combinations of data. - */ - void Assign(const wxFileName& filepath); - void Assign(const wxString& fullpath, - wxPathFormat format = wxPATH_NATIVE); - void Assign(const wxString& volume, const wxString& path, - const wxString& name, - const wxString& ext, - bool hasExt, - wxPathFormat format = wxPATH_NATIVE); - void Assign(const wxString& volume, const wxString& path, - const wxString& name, - const wxString& ext, - wxPathFormat format = wxPATH_NATIVE); - void Assign(const wxString& path, const wxString& name, - wxPathFormat format = wxPATH_NATIVE); - void Assign(const wxString& path, const wxString& name, - const wxString& ext, - wxPathFormat format = wxPATH_NATIVE); - //@} - - /** - Makes this object refer to the current working directory on the specified - volume (or current volume if @a volume is empty). - - @see GetCwd() - */ - static void AssignCwd(const wxString& volume = wxEmptyString); - - /** - Sets this file name object to the given directory name. The name and extension - will be empty. - */ - void AssignDir(const wxString& dir, - wxPathFormat format = wxPATH_NATIVE); - - /** - Sets this file name object to the home directory. - */ - void AssignHomeDir(); - - /** - The function calls CreateTempFileName() to - create a temporary file and sets this object to the name of the file. If a - temporary file couldn't be created, the object is put into the - @ref isok() invalid state. - */ - void AssignTempFileName(const wxString& prefix, - wxFile* fileTemp = NULL); - - /** - Reset all components to default, uninitialized state. - */ - void Clear(); - - /** - Removes the extension from the file name resulting in a - file name with no trailing dot. - - @see SetExt(), SetEmptyExt() - */ - void SetClearExt(); - - /** - Returns a temporary file name starting with the given @e prefix. If - the @a prefix is an absolute path, the temporary file is created in this - directory, otherwise it is created in the default system directory for the - temporary files or in the current directory. - If the function succeeds, the temporary file is actually created. If - @a fileTemp is not @NULL, this file will be opened using the name of - the temporary file. When possible, this is done in an atomic way ensuring that - no race condition occurs between the temporary file name generation and opening - it which could often lead to security compromise on the multiuser systems. - If @a fileTemp is @NULL, the file is only created, but not opened. - Under Unix, the temporary file will have read and write permissions for the - owner only to minimize the security problems. - - @param prefix - Prefix to use for the temporary file name construction - @param fileTemp - The file to open or @NULL to just get the name - - @return The full temporary file name or an empty string on error. - */ - static wxString CreateTempFileName(const wxString& prefix, - wxFile* fileTemp = NULL); - - //@{ - /** - Returns @true if the directory with this name exists. - */ - bool DirExists(); - const static bool DirExists(const wxString& dir); - //@} - - /** - Returns the object corresponding to the directory with the given name. - The @a dir parameter may have trailing path separator or not. - */ - static wxFileName DirName(const wxString& dir, - wxPathFormat format = wxPATH_NATIVE); - - /** - These functions allow to examine and modify the individual directories of the - path: - AppendDir() - - InsertDir() - - GetDirCount() - PrependDir() - - RemoveDir() - - RemoveLastDir() - To change the components of the file name individually you can use the - following functions: - GetExt() - - GetName() - - GetVolume() - - HasExt() - - HasName() - - HasVolume() - - SetExt() - - ClearExt() - - SetEmptyExt() - - SetName() - - SetVolume() - */ - - - /** - You can initialize a wxFileName instance using one of the following functions: - @ref wxfilename() "wxFileName constructors" - - Assign() - - AssignCwd() - - AssignDir() - - AssignHomeDir() - - @ref assigntempfilename() AssignHomeTempFileName - - DirName() - - FileName() - - @ref operatorassign() "operator =" - */ - - - /** - wxFileName currently supports the file names in the Unix, DOS/Windows, Mac OS - and VMS formats. Although these formats are quite different, wxFileName tries - to treat them all in the same generic way. It supposes that all file names - consist of the following parts: the volume (also known as drive under Windows - or device under VMS), the path which is a sequence of directory names separated - by the @ref getpathseparators() "path separators" and the full - filename itself which, in turn, is composed from the base file name and the - extension. All of the individual components of the file name may be empty and, - for example, the volume name is always empty under Unix, but if they are all - empty simultaneously, the filename object is considered to be in an invalid - state and IsOk() returns @false for it. - File names can be case-sensitive or not, the function - IsCaseSensitive() allows to determine this. - The rules for determining whether the file name is absolute or relative also - depend on the file name format and the only portable way to answer this - question is to use IsAbsolute() or - IsRelative() method. Note that on Windows, "X:" - refers to the current working directory on drive X. Therefore, a wxFileName - instance constructed from for example "X:dir/file.ext" treats the portion - beyond drive separator as being relative to that directory. - To ensure that the filename is absolute, you may use - MakeAbsolute(). There is also an inverse - function MakeRelativeTo() which undoes - what @ref normalize() Normalize(wxPATH_NORM_DOTS) does. - Other functions returning information about the file format provided by this - class are GetVolumeSeparator(), - IsPathSeparator(). - */ - - - /** - Before doing other tests, you should use IsOk() to - verify that the filename is well defined. If it is, - FileExists() can be used to test whether a file - with such name exists and DirExists() can be used - to test for directory existence. - File names should be compared using SameAs() method - or @ref operatorequal() "operator ==". - For testing basic access modes, you can use: - IsDirWritable() - - IsDirReadable() - - IsFileWritable() - - IsFileReadable() - - IsFileExecutable() - */ - - - //@{ - /** - Returns @true if the file with this name exists. - - @see DirExists() - */ - bool FileExists(); - const static bool FileExists(const wxString& file); - //@} - - /** - Returns the file name object corresponding to the given @e file. This - function exists mainly for symmetry with DirName(). - */ - static wxFileName FileName(const wxString& file, - wxPathFormat format = wxPATH_NATIVE); - - /** - Retrieves the value of the current working directory on the specified volume. If - the volume is empty, the program's current working directory is returned for the - current volume. - - @return The string containing the current working directory or an empty - string on error. - - @see AssignCwd() - */ - static wxString GetCwd(const wxString& volume = ""); - - /** - Returns the number of directories in the file name. - */ - size_t GetDirCount() const; - - /** - Returns the directories in string array form. - */ - const wxArrayString GetDirs() const; - - /** - Returns the file name extension. - */ - wxString GetExt() const; - - /** - Returns the characters that can't be used in filenames and directory names for - the specified format. - */ - static wxString GetForbiddenChars(wxPathFormat format = wxPATH_NATIVE); - - /** - Returns the canonical path format for this platform. - */ - static wxPathFormat GetFormat(wxPathFormat format = wxPATH_NATIVE); - - /** - Returns the full name (including extension but excluding directories). - */ - wxString GetFullName() const; - - /** - Returns the full path with name and extension. - */ - wxString GetFullPath(wxPathFormat format = wxPATH_NATIVE) const; - - /** - Returns the home directory. - */ - static wxString GetHomeDir(); - - //@{ - /** - Returns the size of this file (first form) or the given number of bytes (second - form) - in a human-readable form. - If the size could not be retrieved the @c failmsg string is returned (first - form). - If @c bytes is @c wxInvalidSize or zero, then @c nullsize is returned (second - form). - In case of success, the returned string is a floating-point number with @c - precision decimal digits - followed by the size unit (B, kB, MB, GB, TB: respectively bytes, kilobytes, - megabytes, gigabytes, terabytes). - */ - wxString GetHumanReadableSize(const wxString& failmsg = "Not available", - int precision = 1); - const static wxString GetHumanReadableSize(const wxULongLong& bytes, - const wxString& nullsize = "Not available", - int precision = 1); - //@} - - /** - Return the long form of the path (returns identity on non-Windows platforms) - */ - wxString GetLongPath() const; - - /** - Returns the last time the file was last modified. - */ - wxDateTime GetModificationTime() const; - - /** - Returns the name part of the filename (without extension). - - @see GetFullName() - */ - wxString GetName() const; - - /** - Returns the path part of the filename (without the name or extension). The - possible flags values are: - - @b wxPATH_GET_VOLUME - - Return the path with the volume (does - nothing for the filename formats without volumes), otherwise the path without - volume part is returned. - - @b wxPATH_GET_SEPARATOR - - Return the path with the trailing - separator, if this flag is not given there will be no separator at the end of - the path. - */ - wxString GetPath(int flags = wxPATH_GET_VOLUME, - wxPathFormat format = wxPATH_NATIVE) const; - - /** - Returns the usually used path separator for this format. For all formats but - @c wxPATH_DOS there is only one path separator anyhow, but for DOS there - are two of them and the native one, i.e. the backslash is returned by this - method. - - @see GetPathSeparators() - */ - static wxChar GetPathSeparator(wxPathFormat format = wxPATH_NATIVE); - - /** - Returns the string containing all the path separators for this format. For all - formats but @c wxPATH_DOS this string contains only one character but for - DOS and Windows both @c '/' and @c '\' may be used as - separators. - - @see GetPathSeparator() - */ - static wxString GetPathSeparators(wxPathFormat format = wxPATH_NATIVE); - - /** - Returns the string of characters which may terminate the path part. This is the - same as GetPathSeparators() except for VMS - path format where ] is used at the end of the path part. - */ - static wxString GetPathTerminators(wxPathFormat format = wxPATH_NATIVE); - - /** - Returns the path with the trailing separator, useful for appending the name to - the given path. - This is the same as calling GetPath() - @c (wxPATH_GET_VOLUME | wxPATH_GET_SEPARATOR, format). - */ - wxString GetPathWithSep(wxPathFormat format = wxPATH_NATIVE) const; - - /** - Return the short form of the path (returns identity on non-Windows platforms). - */ - wxString GetShortPath() const; - - //@{ - /** - Returns the size of this file (first form) or the size of the given file - (second form). - If the file does not exist or its size could not be read (because e.g. the file - is locked - by another process) the returned value is @c wxInvalidSize. - */ - wxULongLong GetSize(); - const static wxULongLong GetSize(const wxString& filename); - //@} - - /** - Returns the directory used for temporary files. - */ - static wxString GetTempDir(); - - /** - Returns the last access, last modification and creation times. The last access - time is updated whenever the file is read or written (or executed in the case - of Windows), last modification time is only changed when the file is written - to. Finally, the creation time is indeed the time when the file was created - under Windows and the inode change time under Unix (as it is impossible to - retrieve the real file creation time there anyhow) which can also be changed - by many operations after the file creation. - If no filename or extension is specified in this instance of wxFileName - (and therefore IsDir() returns @true) then - this function will return the directory times of the path specified by - GetPath(), otherwise the file times of the - file specified by GetFullPath(). - Any of the pointers may be @NULL if the corresponding time is not - needed. - - @return @true on success, @false if we failed to retrieve the times. - */ - bool GetTimes(wxDateTime* dtAccess, wxDateTime* dtMod, - wxDateTime* dtCreate) const; - - /** - Returns the string containing the volume for this file name, empty if it - doesn't have one or if the file system doesn't support volumes at all (for - example, Unix). - */ - wxString GetVolume() const; - - /** - Returns the string separating the volume from the path for this format. - */ - static wxString GetVolumeSeparator(wxPathFormat format = wxPATH_NATIVE); - - /** - Returns @true if an extension is present. - */ - bool HasExt() const; - - /** - Returns @true if a name is present. - */ - bool HasName() const; - - /** - Returns @true if a volume specifier is present. - */ - bool HasVolume() const; - - /** - Inserts a directory component before the zero-based position in the directory - list. Please see AppendDir() for important notes. - */ - void InsertDir(size_t before, const wxString& dir); - - /** - Returns @true if this filename is absolute. - */ - bool IsAbsolute(wxPathFormat format = wxPATH_NATIVE); - - /** - Returns @true if the file names of this type are case-sensitive. - */ - static bool IsCaseSensitive(wxPathFormat format = wxPATH_NATIVE); - - /** - Returns @true if this object represents a directory, @false otherwise - (i.e. if it is a file). Note that this method doesn't test whether the - directory or file really exists, you should use - DirExists() or - FileExists() for this. - */ - bool IsDir() const; - - //@{ - /** - Returns @true if the directory component of this instance (or given @e dir) - is an existing directory and this process has read permissions on it. - Read permissions on a directory mean that you can list the directory contents - but it - doesn't imply that you have read permissions on the files contained. - */ - bool IsDirReadable(); - const static bool IsDirReadable(const wxString& dir); - //@} - - //@{ - /** - Returns @true if the directory component of this instance (or given @e dir) - is an existing directory and this process has write permissions on it. - Write permissions on a directory mean that you can create new files in the - directory. - */ - bool IsDirWritable(); - const static bool IsDirWritable(const wxString& dir); - //@} - - //@{ - /** - Returns @true if a file with this name exists and if this process has execute - permissions on it. - */ - bool IsFileExecutable(); - const static bool IsFileExecutable(const wxString& file); - //@} - - //@{ - /** - Returns @true if a file with this name exists and if this process has read - permissions on it. - */ - bool IsFileReadable(); - const static bool IsFileReadable(const wxString& file); - //@} - - //@{ - /** - Returns @true if a file with this name exists and if this process has write - permissions on it. - */ - bool IsFileWritable(); - const static bool IsFileWritable(const wxString& file); - //@} - - /** - Returns @true if the filename is valid, @false if it is not - initialized yet. The assignment functions and - Clear() may reset the object to the uninitialized, - invalid state (the former only do it on failure). - */ - bool IsOk() const; - - /** - Returns @true if the char is a path separator for this format. - */ - static bool IsPathSeparator(wxChar ch, - wxPathFormat format = wxPATH_NATIVE); - - /** - Returns @true if this filename is not absolute. - */ - bool IsRelative(wxPathFormat format = wxPATH_NATIVE); - - /** - On Mac OS, gets the common type and creator for the given extension. - */ - static bool MacFindDefaultTypeAndCreator(const wxString& ext, - wxUint32* type, - wxUint32* creator); - - /** - On Mac OS, registers application defined extensions and their default type and - creator. - */ - static void MacRegisterDefaultTypeAndCreator(const wxString& ext, - wxUint32 type, - wxUint32 creator); - - /** - On Mac OS, looks up the appropriate type and creator from the registration and - then sets it. - */ - bool MacSetDefaultTypeAndCreator(); - - /** - Make the file name absolute. This is a shortcut for - @c wxFileName::Normalize(wxPATH_NORM_DOTS | wxPATH_NORM_ABSOLUTE | - wxPATH_NORM_TILDE, cwd, format). - - @see MakeRelativeTo(), Normalize(), IsAbsolute() - */ - bool MakeAbsolute(const wxString& cwd = wxEmptyString, - wxPathFormat format = wxPATH_NATIVE); - - /** - This function tries to put this file name in a form relative to - - @param pathBase. - In other words, it returns the file name which should be used to access this - file if the current directory were pathBase. - - pathBase - the directory to use as root, current directory is used by - default - @param format - the file name format, native by default - - @return @true if the file name has been changed, @false if we failed to do - anything with it (currently this only happens if the - file name is on a volume different from the volume - specified by pathBase). - - @see Normalize() - */ - bool MakeRelativeTo(const wxString& pathBase = wxEmptyString, - wxPathFormat format = wxPATH_NATIVE); - - //@{ - /** - @param dir - the directory to create - @param parm - the permissions for the newly created directory - @param flags - if the flags contain wxPATH_MKDIR_FULL flag, - try to create each directory in the path and also don't return an error - if the target directory already exists. - - @return Returns @true if the directory was successfully created, @false - otherwise. - */ - bool Mkdir(int perm = 0777, int flags = 0); - static bool Mkdir(const wxString& dir, int perm = 0777, - int flags = 0); - //@} - - /** - Normalize the path. With the default flags value, the path will be - made absolute, without any ".." and "." and all environment - variables will be expanded in it. - - @param flags - The kind of normalization to do with the file name. It can be - any or-combination of the following constants: - - - - - - - wxPATH_NORM_ENV_VARS - - - - - replace env vars with their values - - - - - - wxPATH_NORM_DOTS - - - - - squeeze all .. and . when possible; if there are too many .. and thus they - cannot be all removed, @false will be returned - - - - - - wxPATH_NORM_CASE - - - - - if filesystem is case insensitive, transform to lower case - - - - - - wxPATH_NORM_ABSOLUTE - - - - - make the path absolute prepending cwd - - - - - - wxPATH_NORM_LONG - - - - - make the path the long form - - - - - - wxPATH_NORM_SHORTCUT - - - - - resolve if it is a shortcut (Windows only) - - - - - - wxPATH_NORM_TILDE - - - - - replace ~ and ~user (Unix only) - - - - - - wxPATH_NORM_ALL - - - - - all of previous flags except wxPATH_NORM_CASE - @param cwd - If not empty, this directory will be used instead of current - working directory in normalization (see wxPATH_NORM_ABSOLUTE). - @param format - The file name format to use when processing the paths, native by default. - - @return @true if normalization was successfully or @false otherwise. - */ - bool Normalize(int flags = wxPATH_NORM_ALL, - const wxString& cwd = wxEmptyString, - wxPathFormat format = wxPATH_NATIVE); - - /** - These methods allow to work with the file creation, access and modification - times. Note that not all filesystems under all platforms implement these times - in the same way. For example, the access time under Windows has a resolution of - one day (so it is really the access date and not time). The access time may be - updated when the file is executed or not depending on the platform. - GetModificationTime() - - GetTimes() - - SetTimes() - - Touch() - Other file system operations functions are: - Mkdir() - - Rmdir() - */ - - - /** - Prepends a directory to the file path. Please see - AppendDir() for important notes. - */ - void PrependDir(const wxString& dir); - - /** - Removes the specified directory component from the path. - - @see GetDirCount() - */ - void RemoveDir(size_t pos); - - /** - Removes last directory component from the path. - */ - void RemoveLastDir(); - - //@{ - /** - Deletes the specified directory from the file system. - */ - bool Rmdir(); - static bool Rmdir(const wxString& dir); - //@} - - /** - Compares the filename using the rules of this platform. - */ - bool SameAs(const wxFileName& filepath, - wxPathFormat format = wxPATH_NATIVE) const; - - //@{ - /** - Changes the current working directory. - */ - bool SetCwd(); - static bool SetCwd(const wxString& cwd); - //@} - - /** - Sets the extension of the file name to be an empty extension. - This is different from having no extension at all as the file - name will have a trailing dot after a call to this method. - - @see SetExt(), ClearExt() - */ - void SetEmptyExt(); - - /** - Sets the extension of the file name. Setting an empty string - as the extension will remove the extension resulting in a file - name without a trailing dot, unlike a call to - SetEmptyExt(). - - @see SetEmptyExt(), ClearExt() - */ - void SetExt(const wxString& ext); - - /** - The full name is the file name and extension (but without the path). - */ - void SetFullName(const wxString& fullname); - - /** - Sets the name part (without extension). - - @see SetFullName() - */ - void SetName(const wxString& name); - - /** - Sets the file creation and last access/modification times (any of the pointers - may be @NULL). - */ - bool SetTimes(const wxDateTime* dtAccess, - const wxDateTime* dtMod, - const wxDateTime* dtCreate); - - /** - Sets the volume specifier. - */ - void SetVolume(const wxString& volume); - - //@{ - /** - This function splits a full file name into components: the volume (with the - first version) path (including the volume in the second version), the base name - and the extension. Any of the output parameters (@e volume, @e path, - @a name or @e ext) may be @NULL if you are not interested in the - value of a particular component. Also, @a fullpath may be empty on entry. - On return, @a path contains the file path (without the trailing separator), - @a name contains the file name and @a ext contains the file extension - without leading dot. All three of them may be empty if the corresponding - component is. The old contents of the strings pointed to by these parameters - will be overwritten in any case (if the pointers are not @NULL). - Note that for a filename "foo." the extension is present, as indicated by the - trailing dot, but empty. If you need to cope with such cases, you should use - @a hasExt instead of relying on testing whether @a ext is empty or not. - */ - static void SplitPath(const wxString& fullpath, wxString* volume, - wxString* path, - wxString* name, - wxString* ext, - bool hasExt = NULL, - wxPathFormat format = wxPATH_NATIVE); - static void SplitPath(const wxString& fullpath, - wxString* volume, - wxString* path, - wxString* name, - wxString* ext, - wxPathFormat format = wxPATH_NATIVE); - static void SplitPath(const wxString& fullpath, - wxString* path, - wxString* name, - wxString* ext, - wxPathFormat format = wxPATH_NATIVE); - //@} - - /** - Splits the given @a fullpath into the volume part (which may be empty) and - the pure path part, not containing any volume. - - @see SplitPath() - */ - static void SplitVolume(const wxString& fullpath, - wxString* volume, - wxString* path, - wxPathFormat format = wxPATH_NATIVE); - - /** - Sets the access and modification times to the current moment. - */ - bool Touch(); - - //@{ - /** - Returns @true if the filenames are different. The string @e filenames - is interpreted as a path in the native filename format. - */ - bool operator operator!=(const wxFileName& filename) const; - const bool operator operator!=(const wxString& filename) const; - //@} - - //@{ - /** - Assigns the new value to this filename object. - */ - wxFileName& operator operator=(const wxFileName& filename); - wxFileName& operator operator=(const wxString& filename); - //@} - - //@{ - /** - Returns @true if the filenames are equal. The string @e filenames is - interpreted as a path in the native filename format. - */ - bool operator operator==(const wxFileName& filename) const; - const bool operator operator==(const wxString& filename) const; - //@} -}; - diff --git a/interface/filepicker.h b/interface/filepicker.h deleted file mode 100644 index 2cb91adc97..0000000000 --- a/interface/filepicker.h +++ /dev/null @@ -1,277 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: filepicker.h -// Purpose: interface of wxFilePickerCtrl -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxFilePickerCtrl - @wxheader{filepicker.h} - - This control allows the user to select a file. The generic implementation is - a button which brings up a wxFileDialog when clicked. Native implementation - may differ but this is usually a (small) widget which give access to the - file-chooser - dialog. - It is only available if @c wxUSE_FILEPICKERCTRL is set to 1 (the default). - - @beginStyleTable - @style{wxFLP_DEFAULT_STYLE} - The default style: includes wxFLP_OPEN | wxFLP_FILE_MUST_EXIST and, - under wxMSW only, wxFLP_USE_TEXTCTRL. - @style{wxFLP_USE_TEXTCTRL} - Creates a text control to the left of the picker button which is - completely managed by the wxFilePickerCtrl and which can be used by - the user to specify a path (see SetPath). The text control is - automatically synchronized with button's value. Use functions - defined in wxPickerBase to modify the text control. - @style{wxFLP_OPEN} - Creates a picker which allows the user to select a file to open. - @style{wxFLP_SAVE} - Creates a picker which allows the user to select a file to save. - @style{wxFLP_OVERWRITE_PROMPT} - Can be combined with wxFLP_SAVE only: ask confirmation to the user - before selecting a file. - @style{wxFLP_FILE_MUST_EXIST} - Can be combined with wxFLP_OPEN only: the selected file must be an - existing file. - @style{wxFLP_CHANGE_DIR} - Change current working directory on each user file selection change. - @endStyleTable - - @library{wxcore} - @category{pickers} - - - @see wxFileDialog, wxFileDirPickerEvent -*/ -class wxFilePickerCtrl : public wxPickerBase -{ -public: - /** - Initializes the object and calls Create() with - all the parameters. - */ - wxFilePickerCtrl(wxWindow* parent, wxWindowID id, - const wxString& path = wxEmptyString, - const wxString& message = "Select a file", - const wxString& wildcard = ".", - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = wxFLP_DEFAULT_STYLE, - const wxValidator& validator = wxDefaultValidator, - const wxString& name = "filepickerctrl"); - - /** - @param parent - Parent window, must not be non-@NULL. - @param id - The identifier for the control. - @param path - The initial file shown in the control. Must be a valid path to a file or - the empty string. - @param message - The message shown to the user in the wxFileDialog shown by the control. - @param wildcard - A wildcard which defines user-selectable files (use the same syntax as for - wxFileDialog's wildcards). - @param pos - Initial position. - @param size - Initial size. - @param style - The window style, see wxFLP_* flags. - @param validator - Validator which can be used for additional date checks. - @param name - Control name. - - @return @true if the control was successfully created or @false if - creation failed. - */ - bool Create(wxWindow* parent, wxWindowID id, - const wxString& path = wxEmptyString, - const wxString& message = "Select a file", - const wxString& wildcard = ".", - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = wxFLP_DEFAULT_STYLE, - const wxValidator& validator = wxDefaultValidator, - const wxString& name = "filepickerctrl"); - - /** - Similar to GetPath() but returns the path of - the currently selected file as a wxFileName object. - */ - wxFileName GetFileName() const; - - /** - Returns the absolute path of the currently selected file. - */ - wxString GetPath() const; - - /** - This method does the same thing as SetPath() but - takes a wxFileName object instead of a string. - */ - void SetFileName(const wxFileName& filename); - - /** - Sets the absolute path of the currently selected file. This must be a valid - file if - the @c wxFLP_FILE_MUST_EXIST style was given. - */ - void SetPath(const wxString& filename); -}; - - - -/** - @class wxDirPickerCtrl - @wxheader{filepicker.h} - - This control allows the user to select a directory. The generic implementation - is - a button which brings up a wxDirDialog when clicked. Native implementation - may differ but this is usually a (small) widget which give access to the - dir-chooser - dialog. - It is only available if @c wxUSE_DIRPICKERCTRL is set to 1 (the default). - - @beginStyleTable - @style{wxDIRP_DEFAULT_STYLE} - The default style: includes wxDIRP_DIR_MUST_EXIST and, under wxMSW - only, wxDIRP_USE_TEXTCTRL. - @style{wxDIRP_USE_TEXTCTRL} - Creates a text control to the left of the picker button which is - completely managed by the wxDirPickerCtrl and which can be used by - the user to specify a path (see SetPath). The text control is - automatically synchronized with button's value. Use functions - defined in wxPickerBase to modify the text control. - @style{wxDIRP_DIR_MUST_EXIST} - Creates a picker which allows to select only existing directories. - wxGTK control always adds this flag internally as it does not - support its absence. - @style{wxDIRP_CHANGE_DIR} - Change current working directory on each user directory selection - change. - @endStyleTable - - @library{wxcore} - @category{pickers} - - - @see wxDirDialog, wxFileDirPickerEvent -*/ -class wxDirPickerCtrl : public wxPickerBase -{ -public: - /** - Initializes the object and calls Create() with - all the parameters. - */ - wxDirPickerCtrl(wxWindow* parent, wxWindowID id, - const wxString& path = wxEmptyString, - const wxString& message = "Select a folder", - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = wxDIRP_DEFAULT_STYLE, - const wxValidator& validator = wxDefaultValidator, - const wxString& name = "dirpickerctrl"); - - /** - @param parent - Parent window, must not be non-@NULL. - @param id - The identifier for the control. - @param path - The initial directory shown in the control. Must be a valid path to a - directory or the empty string. - @param message - The message shown to the user in the wxDirDialog shown by the control. - @param pos - Initial position. - @param size - Initial size. - @param style - The window style, see wxDIRP_* flags. - @param validator - Validator which can be used for additional date checks. - @param name - Control name. - - @return @true if the control was successfully created or @false if - creation failed. - */ - bool Create(wxWindow* parent, wxWindowID id, - const wxString& path = wxEmptyString, - const wxString& message = "Select a folder", - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = wxDIRP_DEFAULT_STYLE, - const wxValidator& validator = wxDefaultValidator, - const wxString& name = "dirpickerctrl"); - - /** - Returns the absolute path of the currently selected directory as a wxFileName - object. - This function is equivalent to GetPath() - */ - wxFileName GetDirName() const; - - /** - Returns the absolute path of the currently selected directory. - */ - wxString GetPath() const; - - /** - Just like SetPath() but this function takes a - wxFileName object. - */ - void SetDirName(const wxFileName& dirname); - - /** - Sets the absolute path of (the default converter uses current locale's - charset)the currently selected directory. This must be a valid directory if - @c wxDIRP_DIR_MUST_EXIST style was given. - */ - void SetPath(const wxString& dirname); -}; - - - -/** - @class wxFileDirPickerEvent - @wxheader{filepicker.h} - - This event class is used for the events generated by - wxFilePickerCtrl and by wxDirPickerCtrl. - - @library{wxcore} - @category{FIXME} - - @see wxfilepickerctrl() -*/ -class wxFileDirPickerEvent : public wxCommandEvent -{ -public: - /** - The constructor is not normally used by the user code. - */ - wxFileDirPickerEvent(wxEventType type, wxObject* generator, - int id, - const wxString path); - - /** - Retrieve the absolute path of the file/directory the user has just selected. - */ - wxString GetPath() const; - - /** - Set the absolute path of the file/directory associated with the event. - */ - void SetPath(const wxString& path); -}; - diff --git a/interface/filesys.h b/interface/filesys.h deleted file mode 100644 index c9d534e86a..0000000000 --- a/interface/filesys.h +++ /dev/null @@ -1,450 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: filesys.h -// Purpose: interface of wxFileSystem, wxFileSystemHandler, wxFSFile -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - - -/** - Open Bit Flags -*/ -enum wxFileSystemOpenFlags -{ - wxFS_READ = 1, /**< Open for reading */ - wxFS_SEEKABLE = 4 /**< Returned stream will be seekable */ -}; - - -/** - @class wxFileSystem - @wxheader{filesys.h} - - This class provides an interface for opening files on different file systems. - It can handle absolute and/or local filenames. - - It uses a system of handlers (see wxFileSystemHandler) to provide access to - user-defined virtual file systems. - - @library{wxbase} - @category{vfs} - - @see wxFileSystemHandler, wxFSFile, @ref overview_fs -*/ -class wxFileSystem : public wxObject -{ -public: - /** - Constructor. - */ - wxFileSystem(); - - /** - This static function adds new handler into the list of handlers - (see wxFileSystemHandler) which provide access to virtual FS. - - Note that if two handlers for the same protocol are added, the last - added one takes precedence. - - @note You can call: - @code - wxFileSystem::AddHandler(new My_FS_Handler); - @endcode - This is because (a) AddHandler is a static method, and (b) the - handlers are deleted in wxFileSystem's destructor so that you - don't have to care about it. - */ - static void AddHandler(wxFileSystemHandler handler); - - /** - Sets the current location. @a location parameter passed to OpenFile() is - relative to this path. - - @remarks Unless @a is_dir is @true the @a location parameter is not the - directory name but the name of the file in this directory. - - All these commands change the path to "dir/subdir/": - - @code - ChangePathTo("dir/subdir/xh.htm"); - ChangePathTo("dir/subdir", true); - ChangePathTo("dir/subdir/", true); - @endcode - - Example: - @code - f = fs->OpenFile("hello.htm"); // opens file 'hello.htm' - fs->ChangePathTo("subdir/folder", true); - f = fs->OpenFile("hello.htm"); // opens file 'subdir/folder/hello.htm' !! - @endcode - - @param location - the new location. Its meaning depends on the value of is_dir - @param is_dir - if @true location is new directory. - If @false (the default) location is file in the new directory. - */ - void ChangePathTo(const wxString& location, bool is_dir = false); - - /** - Converts a wxFileName into an URL. - - @see URLToFileName(), wxFileName - */ - static wxString FileNameToURL(const wxFileName& filename); - - /** - Looks for the file with the given name @a file in a colon or semi-colon - (depending on the current platform) separated list of directories in @a path. - - If the file is found in any directory, returns @true and the full path - of the file in @a str, otherwise returns @false and doesn't modify @a str. - - @param str - Receives the full path of the file, must not be @NULL - @param path - wxPATH_SEP-separated list of directories - @param file - the name of the file to look for - */ - bool FindFileInPath(wxString str, const wxString& path, - const wxString& file); - - /** - Works like ::wxFindFirstFile(). - - Returns the name of the first filename (within filesystem's current path) - that matches @a wildcard. - - @param wildcard - The wildcard that the filename must match - @param flags - One of wxFILE (only files), wxDIR (only directories) or 0 (both). - */ - wxString FindFirst(const wxString& wildcard, int flags = 0); - - /** - Returns the next filename that matches the parameters passed to FindFirst(). - */ - wxString FindNext(); - - /** - Returns the actual path (set by wxFileSystem::ChangePathTo). - */ - wxString GetPath(); - - /** - This static function returns @true if there is a registered handler which can - open the given location. - */ - static bool HasHandlerForPath(const wxString& location); - - /** - Opens the file and returns a pointer to a wxFSFile object or @NULL if failed. - - It first tries to open the file in relative scope (based on value passed to - ChangePathTo() method) and then as an absolute path. - - Note that the user is responsible for deleting the returned wxFSFile. - @a flags can be one or more of the ::wxFileSystemOpenFlags values - combined together. - - A stream opened with just the default @e wxFS_READ flag may - or may not be seekable depending on the underlying source. - - Passing @e "wxFS_READ | wxFS_SEEKABLE" for @a flags will back - a stream that is not natively seekable with memory or a file - and return a stream that is always seekable. - */ - wxFSFile* OpenFile(const wxString& location, - int flags = wxFS_READ); - - /** - Converts URL into a well-formed filename. - The URL must use the @c file protocol. - */ - static wxFileName URLToFileName(const wxString& url); -}; - - - -/** - @class wxFSFile - @wxheader{filesys.h} - - This class represents a single file opened by wxFileSystem. - It provides more information than wxWindow's input stream - (stream, filename, mime type, anchor). - - @note Any pointer returned by a method of wxFSFile is valid only as long as - the wxFSFile object exists. For example a call to GetStream() - doesn't @e create the stream but only returns the pointer to it. - In other words after 10 calls to GetStream() you will have obtained - ten identical pointers. - - @library{wxbase} - @category{vfs} - - @see wxFileSystemHandler, wxFileSystem, @ref overview_fs -*/ -class wxFSFile : public wxObject -{ -public: - /** - Constructor. You probably won't use it. See the Note for details. - - It is seldom used by the application programmer but you will need it if - you are writing your own virtual FS. For example you may need something - similar to wxMemoryInputStream, but because wxMemoryInputStream doesn't - free the memory when destroyed and thus passing a memory stream pointer - into wxFSFile constructor would lead to memory leaks, you can write your - own class derived from wxFSFile: - - @code - class wxMyFSFile : public wxFSFile - { - private: - void *m_Mem; - public: - wxMyFSFile(.....) - ~wxMyFSFile() {free(m_Mem);} - // of course dtor is virtual ;-) - }; - @endcode - - If you are not sure of the meaning of these params, see the description - of the GetXXXX() functions. - - @param stream - The input stream that will be used to access data - @param location - The full location (aka filename) of the file - @param mimetype - MIME type of this file. It may be left empty, in which - case the type will be determined from file's extension (location must - not be empty in this case). - @param anchor - Anchor. See GetAnchor() for details. - */ - wxFSFile(wxInputStream stream, const wxString& loc, - const wxString& mimetype, - const wxString& anchor, wxDateTime modif); - - /** - Detaches the stream from the wxFSFile object. That is, the - stream obtained with GetStream() will continue its existance - after the wxFSFile object is deleted. - - You will have to delete the stream yourself. - */ - void DetachStream(); - - /** - Returns anchor (if present). The term of @b anchor can be easily - explained using few examples: - - @verbatim - index.htm#anchor // 'anchor' is anchor - index/wx001.htm // NO anchor here! - archive/main.zip#zip:index.htm#global // 'global' - archive/main.zip#zip:index.htm // NO anchor here! - @endverbatim - - Usually an anchor is presented only if the MIME type is 'text/html'. - But it may have some meaning with other files; for example myanim.avi#200 - may refer to position in animation or reality.wrl#MyView may refer - to a predefined view in VRML. - */ - const wxString& GetAnchor() const; - - /** - Returns full location of the file, including path and protocol. - - Examples: - @verbatim - http://www.wxwidgets.org - http://www.ms.mff.cuni.cz/~vsla8348/wxhtml/archive.zip#zip:info.txt - file:/home/vasek/index.htm - relative-file.htm - @endverbatim - */ - const wxString& GetLocation() const; - - /** - Returns the MIME type of the content of this file. - - It is either extension-based (see wxMimeTypesManager) or extracted from - HTTP protocol Content-Type header. - */ - const wxString& GetMimeType() const; - - /** - Returns time when this file was modified. - */ - wxDateTime GetModificationTime() const; - - /** - Returns pointer to the stream. - - You can use the returned stream to directly access data. - You may suppose that the stream provide Seek and GetSize functionality - (even in the case of the HTTP protocol which doesn't provide - this by default. wxHtml uses local cache to work around - this and to speed up the connection). - */ - wxInputStream* GetStream() const; -}; - - - -/** - @class wxFileSystemHandler - @wxheader{filesys.h} - - Classes derived from wxFileSystemHandler are used to access virtual file systems. - - Its public interface consists of two methods: wxFileSystemHandler::CanOpen - and wxFileSystemHandler::OpenFile. - - It provides additional protected methods to simplify the process - of opening the file: GetProtocol(), GetLeftLocation(), GetRightLocation(), - GetAnchor(), GetMimeTypeFromExt(). - - Please have a look at overview (see wxFileSystem) if you don't know how locations - are constructed. - - Also consult the @ref overview_fs_wxhtmlfs "list of available handlers". - - Note that the handlers are shared by all instances of wxFileSystem. - - @remarks - wxHTML library provides handlers for local files and HTTP or FTP protocol. - - @note - The location parameter passed to OpenFile() or CanOpen() methods is always an - absolute path. You don't need to check the FS's current path. - - @beginWxPerlOnly - In wxPerl, you need to derive your file system handler class - from Wx::PlFileSystemHandler. - @endWxPerlOnly - - @library{wxbase} - @category{vfs} - - @see wxFileSystem, wxFSFile, @ref overview_fs -*/ -class wxFileSystemHandler : public wxObject -{ -public: - /** - Constructor. - */ - wxFileSystemHandler(); - - /** - Returns @true if the handler is able to open this file. This function doesn't - check whether the file exists or not, it only checks if it knows the protocol. - Example: - - @code - bool MyHand::CanOpen(const wxString& location) - { - return (GetProtocol(location) == "http"); - } - @endcode - - Must be overridden in derived handlers. - */ - virtual bool CanOpen(const wxString& location); - - /** - Works like ::wxFindFirstFile(). - - Returns the name of the first filename (within filesystem's current path) - that matches @e wildcard. @a flags may be one of wxFILE (only files), - wxDIR (only directories) or 0 (both). - - This method is only called if CanOpen() returns @true. - */ - virtual wxString FindFirst(const wxString& wildcard, - int flags = 0); - - /** - Returns next filename that matches parameters passed to wxFileSystem::FindFirst. - - This method is only called if CanOpen() returns @true and FindFirst() - returned a non-empty string. - */ - virtual wxString FindNext(); - - /** - Returns the anchor if present in the location. - See wxFSFile::GetAnchor for details. - - Example: - @code - GetAnchor("index.htm#chapter2") == "chapter2" - @endcode - - @note the anchor is NOT part of the left location. - */ - wxString GetAnchor(const wxString& location) const; - - /** - Returns the left location string extracted from @e location. - - Example: - @code - GetLeftLocation("file:myzipfile.zip#zip:index.htm") == "file:myzipfile.zip" - @endcode - */ - wxString GetLeftLocation(const wxString& location) const; - - /** - Returns the MIME type based on @b extension of @a location. - (While wxFSFile::GetMimeType() returns real MIME type - either - extension-based or queried from HTTP.) - - Example: - @code - GetMimeTypeFromExt("index.htm") == "text/html" - @endcode - */ - wxString GetMimeTypeFromExt(const wxString& location); - - /** - Returns the protocol string extracted from @a location. - - Example: - @code - GetProtocol("file:myzipfile.zip#zip:index.htm") == "zip" - @endcode - */ - wxString GetProtocol(const wxString& location) const; - - /** - Returns the right location string extracted from @a location. - - Example: - @code - GetRightLocation("file:myzipfile.zip#zip:index.htm") == "index.htm" - @endcode - */ - wxString GetRightLocation(const wxString& location) const; - - /** - Opens the file and returns wxFSFile pointer or @NULL if failed. - Must be overridden in derived handlers. - - @param fs - Parent FS (the FS from that OpenFile was called). - See the ZIP handler for details of how to use it. - @param location - The absolute location of file. - */ - virtual wxFSFile* OpenFile(wxFileSystem& fs, - const wxString& location); -}; - diff --git a/interface/font.h b/interface/font.h deleted file mode 100644 index a3eeaba9fe..0000000000 --- a/interface/font.h +++ /dev/null @@ -1,748 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: font.h -// Purpose: interface of wxFont -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxFont - @wxheader{font.h} - - A font is an object which determines the appearance of text. Fonts are - used for drawing text to a device context, and setting the appearance of - a window's text. - - This class uses @ref overview_trefcount "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 counting, are not affected. - - You can retrieve the current system font settings with wxSystemSettings. - - wxSystemSettings - - @library{wxcore} - @category{gdi} - - @stdobjects - ::wxNullFont, ::wxNORMAL_FONT, ::wxSMALL_FONT, ::wxITALIC_FONT, ::wxSWISS_FONT - - @see @ref overview_wxfontoverview, wxDC::SetFont, wxDC::DrawText, - wxDC::GetTextExtent, wxFontDialog, wxSystemSettings -*/ -class wxFont : public wxGDIObject -{ -public: - //@{ - /** - Creates a font object with the specified attributes. - - @param pointSize - Size in points. - @param pixelSize - Size in pixels: this is directly supported only under MSW - currently where this constructor can be used directly, under other - platforms a - font with the closest size to the given one is found using binary search and - the static New method must be used. - @param family - Font family, a generic way of referring to fonts without specifying actual - facename. One of: - - - - - - - - wxFONTFAMILY_DEFAULT - - - - - Chooses a default font. - - - - - - wxFONTFAMILY_DECORATIVE - - - - - A decorative font. - - - - - - wxFONTFAMILY_ROMAN - - - - - A formal, serif font. - - - - - - wxFONTFAMILY_SCRIPT - - - - - A handwriting font. - - - - - - wxFONTFAMILY_SWISS - - - - - A sans-serif font. - - - - - - wxFONTFAMILY_MODERN - - - - - A fixed pitch font. - - - - - - wxFONTFAMILY_TELETYPE - - - - - A teletype font. - @param style - One of wxFONTSTYLE_NORMAL, wxFONTSTYLE_SLANT and wxFONTSTYLE_ITALIC. - @param weight - Font weight, sometimes also referred to as font boldness. One of: - - - - - - - - wxFONTWEIGHT_NORMAL - - - - - Normal font. - - - - - - wxFONTWEIGHT_LIGHT - - - - - Light font. - - - - - - wxFONTWEIGHT_BOLD - - - - - Bold font. - @param underline - The value can be @true or @false. At present this has an effect on Windows - and Motif 2.x only. - @param faceName - An optional string specifying the actual typeface to be used. If it is an - empty string, - a default typeface will be chosen based on the family. - @param encoding - An encoding which may be one of - - - - - - - - wxFONTENCODING_SYSTEM - - - - - Default system encoding. - - - - - - wxFONTENCODING_DEFAULT - - - - - Default application encoding: this - is the encoding set by calls to - SetDefaultEncoding and which may be set to, - say, KOI8 to create all fonts by default with KOI8 encoding. Initially, the - default application encoding is the same as default system encoding. - - - - - - wxFONTENCODING_ISO8859_1...15 - - - - - ISO8859 encodings. - - - - - - wxFONTENCODING_KOI8 - - - - - The standard Russian encoding for Internet. - - - - - - wxFONTENCODING_CP1250...1252 - - - - - Windows encodings similar to ISO8859 (but not identical). - - - - - - If the specified encoding isn't available, no font is created - (see also font encoding overview). - - @remarks If the desired font does not exist, the closest match will be - chosen. Under Windows, only scalable TrueType fonts are - used. - */ - wxFont(); - wxFont(const wxFont& font); - wxFont(int pointSize, wxFontFamily family, int style, - wxFontWeight weight, - const bool underline = false, - const wxString& faceName = "", - wxFontEncoding encoding = wxFONTENCODING_DEFAULT); - wxFont(const wxSize& pixelSize, wxFontFamily family, - int style, wxFontWeight weight, - const bool underline = false, - const wxString& faceName = "", - wxFontEncoding encoding = wxFONTENCODING_DEFAULT); - //@} - - /** - Destructor. - See @ref overview_refcountdestruct "reference-counted object destruction" for - more info. - - @remarks Although all remaining fonts are deleted when the application - exits, the application should try to clean up all fonts - itself. This is because wxWidgets cannot know if a - pointer to the font object is stored in an application - data structure, and there is a risk of double deletion. - */ - ~wxFont(); - - /** - Returns the current application's default encoding. - - @see @ref overview_wxfontencodingoverview, SetDefaultEncoding() - */ - static wxFontEncoding GetDefaultEncoding(); - - /** - Returns the typeface name associated with the font, or the empty string if - there is no - typeface information. - - @see SetFaceName() - */ - wxString GetFaceName() const; - - /** - Gets the font family. See SetFamily() for a list of valid - family identifiers. - - @see SetFamily() - */ - wxFontFamily GetFamily() const; - - /** - Returns the platform-dependent string completely describing this font. - Returned string is always non-empty. - Note that the returned string is not meant to be shown or edited by the user: a - typical - use of this function is for serializing in string-form a wxFont object. - - @see SetNativeFontInfo(),GetNativeFontInfoUserDesc() - */ - wxString GetNativeFontInfoDesc() const; - - /** - Returns a user-friendly string for this font object. Returned string is always - non-empty. - Some examples of the formats of returned strings (which are platform-dependent) - are in SetNativeFontInfoUserDesc(). - - @see GetNativeFontInfoDesc() - */ - wxString GetNativeFontInfoUserDesc(); - - /** - Gets the point size. - - @see SetPointSize() - */ - int GetPointSize() const; - - /** - Gets the font style. See wxFont() for a list of valid - styles. - - @see SetStyle() - */ - int GetStyle() const; - - /** - Returns @true if the font is underlined, @false otherwise. - - @see SetUnderlined() - */ - bool GetUnderlined() const; - - /** - Gets the font weight. See wxFont() for a list of valid - weight identifiers. - - @see SetWeight() - */ - wxFontWeight GetWeight() const; - - /** - Returns @true if the font is a fixed width (or monospaced) font, - @false if it is a proportional one or font is invalid. - */ - bool IsFixedWidth() const; - - /** - Returns @true if this object is a valid font, @false otherwise. - */ - bool IsOk() const; - - //@{ - /** - These functions take the same parameters as @ref ctor() wxFont - constructor 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. - */ - static wxFont* New(int pointSize, wxFontFamily family, int style, - wxFontWeight weight, - const bool underline = false, - const wxString& faceName = "", - wxFontEncoding encoding = wxFONTENCODING_DEFAULT); - static wxFont* New(int pointSize, wxFontFamily family, - int flags = wxFONTFLAG_DEFAULT, - const wxString& faceName = "", - wxFontEncoding encoding = wxFONTENCODING_DEFAULT); - static wxFont* New(const wxSize& pixelSize, - wxFontFamily family, - int style, - wxFontWeight weight, - const bool underline = false, - const wxString& faceName = "", - wxFontEncoding encoding = wxFONTENCODING_DEFAULT); - static wxFont* New(const wxSize& pixelSize, - wxFontFamily family, - int flags = wxFONTFLAG_DEFAULT, - const wxString& faceName = "", - wxFontEncoding encoding = wxFONTENCODING_DEFAULT); - //@} - - /** - Sets the default font encoding. - - @see @ref overview_wxfontencodingoverview, GetDefaultEncoding() - */ - static void SetDefaultEncoding(wxFontEncoding encoding); - - /** - Sets the facename for the font. - Returns @true if the given face name exists; @false otherwise. - - @param faceName - A valid facename, which should be on the end-user's system. - - @remarks To avoid portability problems, don't rely on a specific face, - but specify the font family instead or as well. A - suitable font will be found on the end-user's system. - If both the family and the facename are specified, - wxWidgets will first search for the specific face, and - then for a font belonging to the same family. - - @see GetFaceName(), SetFamily() - */ - bool SetFaceName(const wxString& faceName); - - /** - Sets the font family. - - @param family - One of: - - - - - - - - wxFONTFAMILY_DEFAULT - - - - - Chooses a default font. - - - - - - wxFONTFAMILY_DECORATIVE - - - - - A decorative font. - - - - - - wxFONTFAMILY_ROMAN - - - - - A formal, serif font. - - - - - - wxFONTFAMILY_SCRIPT - - - - - A handwriting font. - - - - - - wxFONTFAMILY_SWISS - - - - - A sans-serif font. - - - - - - wxFONTFAMILY_MODERN - - - - - A fixed pitch font. - - - - - - wxFONTFAMILY_TELETYPE - - - - - A teletype font. - - @see GetFamily(), SetFaceName() - */ - void SetFamily(wxFontFamily family); - - /** - Creates the font corresponding to the given native font description string and - returns @true if - the creation was successful. - which must have been previously returned by - GetNativeFontInfoDesc(). If the string is - invalid, font is unchanged. This function is typically used for de-serializing - a wxFont - object previously saved in a string-form. - - @see SetNativeFontInfoUserDesc() - */ - bool SetNativeFontInfo(const wxString& info); - - /** - Creates the font corresponding to the given native font description string and - returns @true if - the creation was successful. - Unlike SetNativeFontInfo(), this function accepts - strings which are user-friendly. - Examples of accepted string formats are: - - Generic syntax - - Example - - on @b wxGTK2: @c [FACE-NAME] [bold] [oblique|italic] [POINTSIZE] - - Monospace bold 10 - - on @b wxMSW: @c [light|bold] [italic] [FACE-NAME] [POINTSIZE] [ENCODING] - - Tahoma 10 WINDOWS-1252 - - on @b wxMac: FIXME - - FIXME - - For more detailed information about the allowed syntaxes you can look at the - documentation of the native API used for font-rendering (e.g. pango_font_description_from_string). - - @see SetNativeFontInfo() - */ - bool SetNativeFontInfoUserDesc(const wxString& info); - - /** - Sets the point size. - - @param pointSize - Size in points. - - @see GetPointSize() - */ - void SetPointSize(int pointSize); - - /** - Sets the font style. - - @param style - One of wxFONTSTYLE_NORMAL, wxFONTSTYLE_SLANT and wxFONTSTYLE_ITALIC. - - @see GetStyle() - */ - void SetStyle(int style); - - /** - Sets underlining. - - @param underlining - @true to underline, @false otherwise. - - @see GetUnderlined() - */ - void SetUnderlined(const bool underlined); - - /** - Sets the font weight. - - @param weight - One of: - - - - - - - - wxFONTWEIGHT_NORMAL - - - - - Normal font. - - - - - - wxFONTWEIGHT_LIGHT - - - - - Light font. - - - - - - wxFONTWEIGHT_BOLD - - - - - Bold font. - - @see GetWeight() - */ - void SetWeight(wxFontWeight weight); - - /** - Inequality operator. - See @ref overview_refcountequality "reference-counted object comparison" for - more info. - */ - bool operator !=(const wxFont& font); - - /** - Assignment operator, using @ref overview_trefcount "reference counting". - */ - wxFont operator =(const wxFont& font); - - /** - Equality operator. - See @ref overview_refcountequality "reference-counted object comparison" for - more info. - */ - bool operator ==(const wxFont& font); -}; - - -/** - An empty wxFont. -*/ -wxFont wxNullFont; - -/** - FIXME -*/ -wxFont wxNORMAL_FONT; - -/** - FIXME -*/ -wxFont wxSMALL_FONT; - -/** - FIXME -*/ -wxFont wxITALIC_FONT; - -/** - FIXME -*/ -wxFont wxSWISS_FONT; - - -/** - @class wxFontList - @wxheader{gdicmn.h} - - A font list is a list containing all fonts which have been created. There - is only one instance of this class: @b wxTheFontList. Use this object to search - for a previously created font of the desired type and create it if not already - found. - In some windowing systems, the font may be a scarce resource, so it is best to - reuse old resources if possible. When an application finishes, all fonts will - be - deleted and their resources freed, eliminating the possibility of 'memory - leaks'. - - @library{wxcore} - @category{gdi} - - @see wxFont -*/ -class wxFontList : public wxList -{ -public: - /** - Constructor. The application should not construct its own font list: - use the object pointer @b wxTheFontList. - */ - wxFontList(); - - /** - Finds a font of the given specification, or creates one and adds it to the - list. See the @ref wxFont::ctor "wxFont constructor" for - details of the arguments. - */ - wxFont* FindOrCreateFont(int point_size, int family, int style, - int weight, - bool underline = false, - const wxString& facename = NULL, - wxFontEncoding encoding = wxFONTENCODING_DEFAULT); -}; - - - -// ============================================================================ -// Global functions/macros -// ============================================================================ - -/** @ingroup group_funcmacro_misc */ -//@{ - -/** - Converts string to a wxFont best represented by the given string. Returns - @true on success. - - @see wxToString(const wxFont&) - - @header{wx/font.h} -*/ -bool wxFromString(const wxString& string, wxFont* font); - -/** - Converts the given wxFont into a string. - - @see wxFromString(const wxString&, wxFont*) - - @header{wx/font.h} -*/ -wxString wxToString(const wxFont& font); - -//@} - diff --git a/interface/fontdlg.h b/interface/fontdlg.h deleted file mode 100644 index 4a5ea24021..0000000000 --- a/interface/fontdlg.h +++ /dev/null @@ -1,93 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: fontdlg.h -// Purpose: interface of wxFontDialog -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxFontDialog - @wxheader{fontdlg.h} - - This class represents the font chooser dialog. - - @library{wxcore} - @category{cmndlg} - - @see Overview(), wxFontData, wxGetFontFromUser() -*/ -class wxFontDialog : public wxDialog -{ -public: - //@{ - /** - Constructor. Pass a parent window, and optionally the - @ref overview_wxfontdata "font data" object to be used to initialize the dialog - controls. If the default constructor is used, - Create() must be called before the dialog can be - shown. - */ - wxFontDialog(); - wxFontDialog(wxWindow* parent); - wxFontDialog(wxWindow* parent, const wxFontData& data); - //@} - - //@{ - /** - Creates the dialog if it the wxFontDialog object had been initialized using the - default constructor. Returns @true on success and @false if an error - occurred. - */ - bool Create(wxWindow* parent); - bool Create(wxWindow* parent, const wxFontData& data); - //@} - - //@{ - /** - Returns the @ref overview_wxfontdata "font data" associated with the font - dialog. - */ - const wxFontData GetFontData(); - const wxFontData& GetFontData(); - //@} - - /** - Shows the dialog, returning @c wxID_OK if the user pressed Ok, and - @c wxID_CANCEL otherwise. - If the user cancels the dialog (ShowModal returns @c wxID_CANCEL), no font - will be created. If the user presses OK, a new wxFont will be created and - stored in the font dialog's wxFontData structure. - */ - int ShowModal(); -}; - - - -// ============================================================================ -// Global functions/macros -// ============================================================================ - -/** @ingroup group_funcmacro_dialog */ -//@{ - -/** - Shows the font selection dialog and returns the font selected by user or - invalid font (use wxFont::IsOk() to test whether a font is valid) if the - dialog was cancelled. - - @param parent - The parent window for the font selection dialog. - @param fontInit - If given, this will be the font initially selected in the dialog. - @param caption - If given, this will be used for the dialog caption. - - @header{wx/fontdlg.h} -*/ -wxFont wxGetFontFromUser(wxWindow* parent, - const wxFont& fontInit, - const wxString& caption = wxEmptyString); - -//@} - diff --git a/interface/fontenum.h b/interface/fontenum.h deleted file mode 100644 index 8cf2da6104..0000000000 --- a/interface/fontenum.h +++ /dev/null @@ -1,85 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: fontenum.h -// Purpose: interface of wxFontEnumerator -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxFontEnumerator - @wxheader{fontenum.h} - - wxFontEnumerator enumerates either all available fonts on the system or only - the ones with given attributes - either only fixed-width (suited for use in - programs such as terminal emulators and the like) or the fonts available in - the given encoding(). - - To do this, you just have to call one of EnumerateXXX() functions - either - wxFontEnumerator::EnumerateFacenames or - wxFontEnumerator::EnumerateEncodings and the - corresponding callback (wxFontEnumerator::OnFacename or - wxFontEnumerator::OnFontEncoding) will be called - repeatedly until either all fonts satisfying the specified criteria are - exhausted or the callback returns @false. - - @library{wxcore} - @category{FIXME} - - @see @ref overview_wxfontencodingoverview, @ref overview_samplefont "Font - sample", wxFont, wxFontMapper -*/ -class wxFontEnumerator -{ -public: - /** - Call OnFontEncoding() for each - encoding supported by the given font - or for each encoding supported by at - least some font if @a font is not specified. - */ - virtual bool EnumerateEncodings(const wxString& font = ""); - - /** - Call OnFacename() for each font which - supports given encoding (only if it is not wxFONTENCODING_SYSTEM) and is of - fixed width (if @a fixedWidthOnly is @true). - Calling this function with default arguments will result in enumerating all - fonts available on the system. - */ - virtual bool EnumerateFacenames(wxFontEncoding encoding = wxFONTENCODING_SYSTEM, - bool fixedWidthOnly = false); - - /** - Return array of strings containing all encodings found by - EnumerateEncodings(). - */ - static wxArrayString GetEncodings(const wxString& facename = ""); - - /** - Return array of strings containing all facenames found by - EnumerateFacenames(). - */ - static wxArrayString GetFacenames(wxFontEncoding encoding = wxFONTENCODING_SYSTEM, - bool fixedWidthOnly = false); - - /** - Returns @true if the given string is valid face name, i.e. it's the face name - of an installed - font and it can safely be used with wxFont::SetFaceName. - */ - static bool IsValidFacename(const wxString& facename); - - /** - Called by EnumerateFacenames() for - each match. Return @true to continue enumeration or @false to stop it. - */ - virtual bool OnFacename(const wxString& font); - - /** - Called by EnumerateEncodings() for - each match. Return @true to continue enumeration or @false to stop it. - */ - virtual bool OnFontEncoding(const wxString& font, - const wxString& encoding); -}; - diff --git a/interface/fontmap.h b/interface/fontmap.h deleted file mode 100644 index 8adbc85135..0000000000 --- a/interface/fontmap.h +++ /dev/null @@ -1,176 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: fontmap.h -// Purpose: interface of wxFontMapper -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxFontMapper - @wxheader{fontmap.h} - - wxFontMapper manages user-definable correspondence between logical font - names and the fonts present on the machine. - - The default implementations of all functions will ask the user if they are - not capable of finding the answer themselves and store the answer in a - config file (configurable via SetConfigXXX functions). This behaviour may - be disabled by giving the value of @false to "interactive" parameter. - - However, the functions will always consult the config file to allow the - user-defined values override the default logic and there is no way to - disable this - which shouldn't be ever needed because if "interactive" was - never @true, the config file is never created anyhow. - - 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. - - @library{wxcore} - @category{misc} - - @see wxEncodingConverter, @ref overview_nonenglishoverview "Writing non-English - applications" -*/ -class wxFontMapper -{ -public: - /** - Default ctor. - */ - wxFontMapper(); - - /** - Virtual dtor for a base class. - */ - ~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 - time than a simple function call. For these reasons, it is almost always a bad - idea to call this function from the event handlers for repeatedly generated - events such as @c EVT_PAINT. - */ - wxFontEncoding CharsetToEncoding(const wxString& charset, - bool interactive = true); - - /** - 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 - GetEncodingName(). - */ - static const wxChar** GetAllEncodingNames(wxFontEncoding encoding); - - //@{ - /** - Find an alternative for the given encoding (which is supposed to not be - 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. - */ - bool GetAltForEncoding(wxFontEncoding encoding, - wxNativeEncodingInfo* info, - const wxString& facename = wxEmptyString, - bool interactive = true); - bool GetAltForEncoding(wxFontEncoding encoding, - wxFontEncoding* alt_encoding, - const wxString& facename = wxEmptyString, - bool interactive = true); - //@} - - /** - 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); - - /** - Return user-readable string describing the given encoding. - */ - 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(). - */ - static wxFontEncoding GetEncodingFromName(const wxString& encoding); - - /** - Return internal string identifier for the encoding (see also - 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 - all supported encodings. - */ - static size_t GetSupportedEncodingsCount(); - - /** - Check whether given encoding is available in given face or not. - If no facename is given, find @e any font in this encoding. - */ - bool IsEncodingAvailable(wxFontEncoding encoding, - const wxString& facename = wxEmptyString); - - /** - Set the current font mapper object and return previous one (may be @NULL). - This method is only useful if you want to plug-in an alternative font mapper - into wxWidgets. - - @see Get() - */ - static wxFontMapper* Set(wxFontMapper* mapper); - - /** - 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(). - */ - void SetConfig(wxConfigBase* config); - - /** - Set the root config path to use (should be an absolute path). - */ - void SetConfigPath(const wxString& prefix); - - /** - The parent window for modal dialogs. - */ - void SetDialogParent(wxWindow* parent); - - /** - The title for the dialogs (note that default is quite reasonable). - */ - void SetDialogTitle(const wxString& title); -}; - diff --git a/interface/fontpicker.h b/interface/fontpicker.h deleted file mode 100644 index 15c540785a..0000000000 --- a/interface/fontpicker.h +++ /dev/null @@ -1,153 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: fontpicker.h -// Purpose: interface of wxFontPickerCtrl -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxFontPickerCtrl - @wxheader{fontpicker.h} - - 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. - 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. - @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 - the user to specify a font (see SetSelectedFont). The text control - is automatically synchronized with button's value. Use functions - defined in wxPickerBase to modify the text control. - @style{wxFNTP_FONTDESC_AS_LABEL} - Keeps the label of the button updated with the fontface name and - the font size. E.g. choosing "Times New Roman bold, italic with - size 10" from the fontdialog, will update the label (overwriting - any previous label) with the "Times New Roman, 10" text. - @style{wxFNTP_USEFONT_FOR_LABEL} - Uses the currently selected font to draw the label of the button. - @endStyleTable - - @library{wxcore} - @category{pickers} - - - @see wxFontDialog, wxFontPickerEvent -*/ -class wxFontPickerCtrl : public wxPickerBase -{ -public: - /** - Initializes the object and calls Create() with - all the parameters. - */ - wxFontPickerCtrl(wxWindow* parent, wxWindowID id, - const wxFont& font = wxNullFont, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = wxFNTP_DEFAULT_STYLE, - const wxValidator& validator = wxDefaultValidator, - const wxString& name = "fontpickerctrl"); - - /** - @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. - @param pos - Initial position. - @param size - Initial size. - @param style - The window style, see wxFNTP_* flags. - @param validator - Validator which can be used for additional date checks. - @param name - Control name. - - @return @true if the control was successfully created or @false if - creation failed. - */ - bool Create(wxWindow* parent, wxWindowID id, - const wxFont& font = wxNullFont, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = wxFNTP_DEFAULT_STYLE, - const wxValidator& validator = wxDefaultValidator, - const wxString& name = "fontpickerctrl"); - - /** - Returns the maximum point size value allowed for the user-chosen font. - */ - unsigned int GetMaxPointSize() const; - - /** - Returns the currently selected font. - Note that this function is completely different from wxWindow::GetFont. - */ - wxFont GetSelectedFont() const; - - /** - 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. - */ - void GetMaxPointSize(unsigned int max); - - /** - Sets the currently selected font. - Note that this function is completely different from wxWindow::SetFont. - */ - void SetSelectedFont(const wxFont& font); -}; - - - -/** - @class wxFontPickerEvent - @wxheader{fontpicker.h} - - This event class is used for the events generated by - wxFontPickerCtrl. - - @library{wxcore} - @category{FIXME} - - @see wxFontPickerCtrl -*/ -class wxFontPickerEvent : public wxCommandEvent -{ -public: - /** - The constructor is not normally used by the user code. - */ - wxFontPickerEvent(wxObject* generator, int id, - const wxFont& font); - - /** - Retrieve the font the user has just selected. - */ - wxFont GetFont() const; - - /** - Set the font associated with the event. - */ - void SetFont(const wxFont& f); -}; - diff --git a/interface/frame.h b/interface/frame.h deleted file mode 100644 index 51af4a1666..0000000000 --- a/interface/frame.h +++ /dev/null @@ -1,410 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: frame.h -// Purpose: interface of wxFrame -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxFrame - @wxheader{frame.h} - - A frame is a window whose size and position can (usually) be changed by the user. - - It usually has thick borders and a title bar, and can optionally contain a - menu bar, toolbar and status bar. A frame can contain any window that is not - a frame or dialog. - - A frame that has a status bar and toolbar, created via the CreateStatusBar() and - CreateToolBar() functions, manages these windows and adjusts the value returned - by GetClientSize() to reflect the remaining size available to application windows. - - @remarks An application should normally define an wxCloseEvent handler for the - frame to respond to system close events, for example so that related - data and subwindows can be cleaned up. - - - @section wxframe_defaultevent Default event processing - - wxFrame processes the following events: - - @li @c wxEVT_SIZE: if the frame has exactly one child window, not counting the - status and toolbar, this child is resized to take the entire frame client area. - If two or more windows are present, they should be laid out explicitly either - by manually handling wxEVT_SIZE or using sizers; - @li @c wxEVT_MENU_HIGHLIGHT: the default implementation displays the help string - associated with the selected item in the first pane of the status bar, if there is one. - - - @beginStyleTable - @style{wxDEFAULT_FRAME_STYLE} - Defined as wxMINIMIZE_BOX | wxMAXIMIZE_BOX | wxRESIZE_BORDER | - wxSYSTEM_MENU | wxCAPTION | wxCLOSE_BOX | wxCLIP_CHILDREN. - @style{wxICONIZE} - Display the frame iconized (minimized). Windows only. - @style{wxCAPTION} - Puts a caption on the frame. - @style{wxMINIMIZE} - Identical to wxICONIZE. Windows only. - @style{wxMINIMIZE_BOX} - Displays a minimize box on the frame. - @style{wxMAXIMIZE} - Displays the frame maximized. Windows only. - @style{wxMAXIMIZE_BOX} - Displays a maximize box on the frame. - @style{wxCLOSE_BOX} - Displays a close box on the frame. - @style{wxSTAY_ON_TOP} - Stay on top of all other windows, see also wxFRAME_FLOAT_ON_PARENT. - @style{wxSYSTEM_MENU} - Displays a system menu. - @style{wxRESIZE_BORDER} - Displays a resizeable border around the window. - @style{wxFRAME_TOOL_WINDOW} - Causes a frame with a small titlebar to be created; the frame does - not appear in the taskbar under Windows or GTK+. - @style{wxFRAME_NO_TASKBAR} - Creates an otherwise normal frame but it does not appear in the - taskbar under Windows or GTK+ (note that it will minimize to the - desktop window under Windows which may seem strange to the users - and thus it might be better to use this style only without - wxMINIMIZE_BOX style). In wxGTK, the flag is respected only if GTK+ - is at least version 2.2 and the window manager supports - _NET_WM_STATE_SKIP_TASKBAR hint. Has no effect under other platforms. - @style{wxFRAME_FLOAT_ON_PARENT} - The frame will always be on top of its parent (unlike wxSTAY_ON_TOP). - A frame created with this style must have a non-@NULL parent. - @style{wxFRAME_SHAPED} - Windows with this style are allowed to have their shape changed - with the SetShape() method. - @endStyleTable - - The default frame style is for normal, resizeable frames. - To create a frame which can not be resized by user, you may use the following - combination of styles: - - @code - wxDEFAULT_FRAME_STYLE & ~(wxRESIZE_BORDER | wxRESIZE_BOX | wxMAXIMIZE_BOX) - @endcode - - See also the @ref overview_windowstyles. - - @beginExtraStyleTable - @style{wxFRAME_EX_CONTEXTHELP} - Under Windows, puts a query button on the caption. When pressed, - Windows will go into a context-sensitive help mode and wxWidgets - will send a wxEVT_HELP event if the user clicked on an application - window. Note that this is an extended style and must be set by - calling SetExtraStyle before Create is called (two-step - construction). You cannot use this style together with - wxMAXIMIZE_BOX or wxMINIMIZE_BOX, so you should use - wxDEFAULT_FRAME_STYLE ~ (wxMINIMIZE_BOX | wxMAXIMIZE_BOX) for the - frames having this style (the dialogs don't have a minimize or a - maximize box by default) - @style{wxFRAME_EX_METAL} - On Mac OS X, frames with this style will be shown with a metallic - look. This is an extra style. - @endExtraStyleTable - - @library{wxcore} - @category{managedwnd} - - @see wxMDIParentFrame, wxMDIChildFrame, wxMiniFrame, wxDialog -*/ -class wxFrame : public wxTopLevelWindow -{ -public: - //@{ - /** - Constructor, creating the window. - - @param parent - 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. - @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. - @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. - @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 - individual windows. - - @remarks For Motif, MWM (the Motif Window Manager) should be running for - 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. - */ - ~wxFrame(); - - /** - Centres the frame on the display. - - @param direction - The parameter may be wxHORIZONTAL, wxVERTICAL or wxBOTH. - */ - void Centre(int direction = wxBOTH); - - /** - Used in two-step frame construction. See wxFrame() - for further details. - */ - bool Create(wxWindow* parent, wxWindowID id, - const wxString& title, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = wxDEFAULT_FRAME_STYLE, - const wxString& name = "frame"); - - /** - Creates a status bar at the bottom of the frame. - - @param number - 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. - @param id - 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. - - @remarks The width of the status bar is the whole width of the frame - (adjusted automatically when resizing), and the height - and text size are chosen by the host windowing system. - - @see SetStatusText(), OnCreateStatusBar(), GetStatusBar() - */ - virtual wxStatusBar* CreateStatusBar(int number = 1, - long style = 0, - wxWindowID id = -1, - const wxString& name = "statusBar"); - - /** - Creates a toolbar at the top or left of the frame. - - @param style - 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. - @param name - The toolbar window name. - - @return A pointer to the toolbar if it was created successfully, @NULL - 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(). - - @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. - */ - wxPoint GetClientAreaOrigin() const; - - /** - Returns a pointer to the menubar currently associated with the frame (if any). - - @see SetMenuBar(), wxMenuBar, wxMenu - */ - wxMenuBar* GetMenuBar() const; - - /** - Returns a pointer to the status bar currently associated with the frame (if - any). - - @see CreateStatusBar(), wxStatusBar - */ - wxStatusBar* GetStatusBar() const; - - /** - Returns the status bar pane used to display menu and toolbar help. - - @see SetStatusBarPane() - */ - int GetStatusBarPane(); - - /** - Returns a pointer to the toolbar currently associated with the frame (if any). - - @see CreateToolBar(), wxToolBar, SetToolBar() - */ - wxToolBar* GetToolBar() const; - - /** - Virtual function called when a status bar is requested by CreateStatusBar(). - - @param number - The number of fields to create. - @param style - The window style. See wxStatusBar for a list - of valid styles. - @param id - The window identifier. If -1, an identifier will be chosen by - wxWidgets. - @param name - The window name. - - @return A status bar object. - - @remarks An application can override this function to return a different - kind of status bar. The default implementation returns - an instance of wxStatusBar. - - @see CreateStatusBar(), wxStatusBar. - */ - virtual wxStatusBar* OnCreateStatusBar(int number, long style, - wxWindowID id, - const wxString& name); - - /** - Virtual function called when a toolbar is requested by CreateToolBar(). - - @param style - 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. - @param name - The toolbar window name. - - @return A toolbar object. - - @remarks An application can override this function to return a different - kind of toolbar. The default implementation returns an - instance of wxToolBar. - - @see CreateToolBar(), wxToolBar. - */ - virtual wxToolBar* OnCreateToolBar(long style, wxWindowID id, - const wxString& name); - - /** - Simulate a menu command. - - @param id - The identifier for a menu item. - */ - void ProcessCommand(int id); - - /** - This function sends a dummy @ref overview_wxsizeevent "size event" to the frame - forcing it to reevaluate its children positions. It is sometimes useful to call - this function after adding or deleting a children after the frame creation or - if a child size changes. - Note that if the frame is using either sizers or constraints for the children - layout, it is enough to call wxWindow::Layout directly and - this function should not be used in this case. - */ - void SendSizeEvent(); - - /** - Tells the frame to show the given menu bar. - - @param menuBar - The menu bar to associate with the frame. - - @remarks If the frame is destroyed, the menu bar and its menus will be - destroyed also, so do not delete the menu bar - explicitly (except by resetting the frame's menu bar to - another frame or @NULL). - - @see GetMenuBar(), wxMenuBar, wxMenu. - */ - void SetMenuBar(wxMenuBar* menuBar); - - /** - Associates a status bar with the frame. - - @see CreateStatusBar(), wxStatusBar, GetStatusBar() - */ - void SetStatusBar(wxStatusBar* statusBar); - - /** - Set the status bar pane used to display menu and toolbar help. - Using -1 disables help display. - */ - void SetStatusBarPane(int n); - - /** - Sets the status bar text and redraws the status bar. - - @param text - The text for the status field. - @param number - The status field (starting from zero). - - @remarks Use an empty string to clear the status bar. - - @see CreateStatusBar(), wxStatusBar - */ - virtual void SetStatusText(const wxString& text, int number = 0); - - /** - Sets the widths of the fields in the status bar. - - @param n - The number of fields in the status bar. It must be the - same used in CreateStatusBar. - @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. - - @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. - */ - virtual void SetStatusWidths(int n, int* widths); - - /** - Associates a toolbar with the frame. - */ - void SetToolBar(wxToolBar* toolBar); -}; - diff --git a/interface/fs_mem.h b/interface/fs_mem.h deleted file mode 100644 index bef7f52f8d..0000000000 --- a/interface/fs_mem.h +++ /dev/null @@ -1,116 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: fs_mem.h -// Purpose: interface of wxMemoryFSHandler -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxMemoryFSHandler - @wxheader{fs_mem.h} - - This wxFileSystem handler can store arbitrary data in memory stream and make - them accessible via an URL. - - It is particularly suitable for storing bitmaps from resources or included XPM - files so that they can be used with wxHTML. - - Filenames are prefixed with @c "memory:", e.g. @c "memory:myfile.html". - - Example: - - @code - #ifndef __WXMSW__ - #include "logo.xpm" - #endif - - void MyFrame::OnAbout(wxCommandEvent&) - { - wxBusyCursor bcur; - wxFileSystem::AddHandler(new wxMemoryFSHandler); - wxMemoryFSHandler::AddFile("logo.pcx", wxBITMAP(logo), wxBITMAP_TYPE_PCX); - wxMemoryFSHandler::AddFile("about.htm", - "About: " - ""); - - wxDialog dlg(this, -1, wxString(_("About"))); - wxBoxSizer *topsizer; - wxHtmlWindow *html; - topsizer = new wxBoxSizer(wxVERTICAL); - html = new wxHtmlWindow(&dlg, -1, wxDefaultPosition, - wxSize(380, 160), wxHW_SCROLLBAR_NEVER); - html->SetBorders(0); - html->LoadPage("memory:about.htm"); - html->SetSize(html->GetInternalRepresentation()->GetWidth(), - html->GetInternalRepresentation()->GetHeight()); - topsizer->Add(html, 1, wxALL, 10); - topsizer->Add(new wxStaticLine(&dlg, -1), 0, wxEXPAND | wxLEFT | wxRIGHT, 10); - topsizer->Add(new wxButton(&dlg, wxID_OK, "Ok"), - 0, wxALL | wxALIGN_RIGHT, 15); - dlg.SetAutoLayout(true); - dlg.SetSizer(topsizer); - topsizer->Fit(&dlg); - dlg.Centre(); - dlg.ShowModal(); - - wxMemoryFSHandler::RemoveFile("logo.pcx"); - wxMemoryFSHandler::RemoveFile("about.htm"); - } - @endcode - - @library{wxbase} - @category{vfs} - - @see wxMemoryFSHandler::AddFileWithMimeType -*/ -class wxMemoryFSHandler : public wxFileSystemHandler -{ -public: - /** - Constructor. - */ - wxMemoryFSHandler(); - - //@{ - /** - Adds a file to the list of the files stored in memory. - - Stored data (bitmap, text or raw data) will be copied into private memory - stream and available under name @c "memory:" + @e filename. - - @note you must use a @a type value (aka image format) that wxWidgets - can save (e.g. JPG, PNG, see wxImage documentation)! - - @see AddFileWithMimeType() - */ - static void AddFile(const wxString& filename, wxImage& image, wxBitmapType type); - static void AddFile(const wxString& filename, const wxBitmap& bitmap, wxBitmapType type); - //@} - - //@{ - /** - Like AddFile(), but lets you explicitly specify added file's MIME type. - - This version should be used whenever you know the MIME type, because it - makes accessing the files faster. - - @since 2.8.5 - - @see AddFile() - */ - static void AddFileWithMimeType(const wxString& filename, - const wxString& textdata, - const wxString& mimetype); - static void AddFileWithMimeType(const wxString& filename, - const void* binarydata, - size_t size, - const wxString& mimetype); - //@} - - /** - Removes a file from memory FS and frees the occupied memory. - */ - static void RemoveFile(const wxString& filename); -}; - diff --git a/interface/gauge.h b/interface/gauge.h deleted file mode 100644 index d617d7489b..0000000000 --- a/interface/gauge.h +++ /dev/null @@ -1,184 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: gauge.h -// Purpose: interface of wxGauge -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxGauge - @wxheader{gauge.h} - - A gauge is a horizontal or vertical bar which shows a quantity (often - time). - - wxGauge supports two working modes: determinate and indeterminate progress. - - The first is the usual working mode (see SetValue() and SetRange()) while - the second can be used when the program is doing some processing but you - don't know how much progress is being done. In this case, you can - periodically call the Pulse() function to make the progress bar switch to - indeterminate mode (graphically it's usually a set of blocks which move or - bounce in the bar control). - - wxGauge supports dynamic switch between these two work modes. - - There are no user commands for the gauge. - - @beginStyleTable - @style{wxGA_HORIZONTAL} - Creates a horizontal gauge. - @style{wxGA_VERTICAL} - Creates a vertical gauge. - @style{wxGA_SMOOTH} - Creates smooth progress bar with one pixel wide update step (not - supported by all platforms). - @endStyleTable - - @library{wxcore} - @category{ctrl} - - - @see wxSlider, wxScrollBar -*/ -class wxGauge : public wxControl -{ -public: - /** - Default constructor. - */ - wxGauge(); - /** - Constructor, creating and showing a gauge. - - @param parent - Window parent. - @param id - Window identifier. - @param range - Integer range (maximum value) of the gauge. It is ignored when the - gauge is used in indeterminate mode. - @param pos - Window position. - @param size - Window size. - @param style - Gauge style. - @param name - Window name. - - @see Create() - */ - wxGauge(wxWindow* parent, wxWindowID id, int range, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = wxGA_HORIZONTAL, - const wxValidator& validator = wxDefaultValidator, - const wxString& name = "gauge"); - - /** - Destructor, destroying the gauge. - */ - ~wxGauge(); - - /** - Creates the gauge for two-step construction. See wxGauge() for further - details. - */ - bool Create(wxWindow* parent, wxWindowID id, int range, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = wxGA_HORIZONTAL, - const wxValidator& validator = wxDefaultValidator, - const wxString& name = "gauge"); - - /** - Returns the width of the 3D bezel face. - - @remarks This method is not implemented (returns 0) for most platforms. - - @see SetBezelFace() - */ - int GetBezelFace() const; - - /** - Returns the maximum position of the gauge. - - @see SetRange() - */ - int GetRange() const; - - /** - Returns the 3D shadow margin width. - - @remarks This method is not implemented (returns 0) for most platforms. - - @see SetShadowWidth() - */ - int GetShadowWidth() const; - - /** - Returns the current position of the gauge. - - @see SetValue() - */ - int GetValue() const; - - /** - Returns @true if the gauge is vertical (has @c wxGA_VERTICAL style) and - @false otherwise. - */ - bool IsVertical() const; - - /** - Switch the gauge to indeterminate mode (if required) and makes the - gauge move a bit to indicate the user that some progress has been made. - - @note After calling this function the value returned by GetValue() is - undefined and thus you need to explicitely call SetValue() if you - want to restore the determinate mode. - */ - void Pulse(); - - /** - Sets the 3D bezel face width. - - @remarks This method is not implemented (doesn't do anything) for most - platforms. - - @see GetBezelFace() - */ - void SetBezelFace(int width); - - /** - Sets the range (maximum value) of the gauge. This function makes the - gauge switch to determinate mode, if it's not already. - - @see GetRange() - */ - void SetRange(int range); - - /** - Sets the 3D shadow width. - - @remarks This method is not implemented (doesn't do anything) for most - platforms. - */ - void SetShadowWidth(int width); - - /** - Sets the position of the gauge. The @a pos must be between 0 and the - gauge range as returned by GetRange(), inclusive. - - This function makes the gauge switch to determinate mode, if it was in - indeterminate mode before. - - @param pos - Position for the gauge level. - - @see GetValue() - */ - void SetValue(int pos); -}; - diff --git a/interface/gbsizer.h b/interface/gbsizer.h deleted file mode 100644 index 30ffb83eab..0000000000 --- a/interface/gbsizer.h +++ /dev/null @@ -1,354 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: gbsizer.h -// Purpose: interface of wxGBPosition -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxGBPosition - @wxheader{gbsizer.h} - - This class represents the position of an item in a virtual grid of rows and - columns managed by a wxGridBagSizer. - - @library{wxcore} - @category{winlayout} -*/ -class wxGBPosition -{ -public: - /** - Default constructor, setting the row and column to (0,0). - */ - wxGBPosition(); - /** - Construct a new wxGBPosition, setting the row and column. - */ - wxGBPosition(int row, int col); - - /** - Get the current column value. - */ - int GetCol() const; - - /** - Get the current row value. - */ - int GetRow() const; - - /** - Set a new column value. - */ - void SetCol(int col); - - /** - Set a new row value. - */ - void SetRow(int row); - - /** - Checks if the position is valid. An invalid position is (-1,-1). - */ - bool operator!(const wxGBPosition& p) const; - - /** - Compare equality of two wxGBPositions. - */ - bool operator==(const wxGBPosition& p) const; -}; - - - -/** - @class wxGridBagSizer - @wxheader{gbsizer.h} - - A wxSizer that can lay out items in a virtual grid like a wxFlexGridSizer - but in this case explicit positioning of the items is allowed using - wxGBPosition, and items can optionally span more than one row and/or column - using wxGBSpan. - - @library{wxcore} - @category{winlayout} -*/ -class wxGridBagSizer : public wxFlexGridSizer -{ -public: - /** - Constructor, with optional parameters to specify the gap between the - rows and columns. - */ - wxGridBagSizer(int vgap = 0, int hgap = 0); - - //@{ - /** - Adds the given item to the given position. - - @return A valid pointer if the item was successfully placed at the - given position, or @NULL if something was already there. - */ - wxSizerItem* Add(wxWindow* window, const wxGBPosition& pos, - const wxGBSpan& span = wxDefaultSpan, - int flag = 0, int border = 0, wxObject* userData = NULL); - wxSizerItem* Add(wxSizer* sizer, const wxGBPosition& pos, - const wxGBSpan& span = wxDefaultSpan, - int flag = 0, int border = 0, wxObject* userData = NULL); - wxSizerItem* Add(int width, int height, const wxGBPosition& pos, - const wxGBSpan& span = wxDefaultSpan, - int flag = 0, int border = 0, wxObject* userData = NULL); - wxSizerItem* Add(wxGBSizerItem* item); - //@} - - /** - Called when the managed size of the sizer is needed or when layout - needs done. - */ - wxSize CalcMin(); - - //@{ - /** - Look at all items and see if any intersect (or would overlap) the given - item. Returns @true if so, @false if there would be no overlap. If an - @a excludeItem is given then it will not be checked for intersection, - for example it may be the item we are checking the position of. - */ - bool CheckForIntersection(wxGBSizerItem* item, - wxGBSizerItem* excludeItem = NULL); - bool CheckForIntersection(const wxGBPosition& pos, const wxGBSpan& span, - wxGBSizerItem* excludeItem = NULL); - //@} - - //@{ - /** - Find the sizer item for the given window or subsizer, returns @NULL if - not found. (non-recursive) - */ - wxGBSizerItem* FindItem(wxWindow* window); - wxGBSizerItem* FindItem(wxSizer* sizer); - //@} - - /** - Return the sizer item located at the point given in pt, or @NULL if - there is no item at that point. The (x,y) coordinates in @a pt - correspond to the client coordinates of the window using the sizer for - layout. (non-recursive) - */ - wxGBSizerItem* FindItemAtPoint(const wxPoint& pt); - - /** - Return the sizer item for the given grid cell, or @NULL if there is no - item at that position. (non-recursive) - */ - wxGBSizerItem* FindItemAtPosition(const wxGBPosition& pos); - - /** - Return the sizer item that has a matching user data (it only compares - pointer values) or @NULL if not found. (non-recursive) - */ - wxGBSizerItem* FindItemWithData(const wxObject* userData); - - /** - Get the size of the specified cell, including hgap and vgap. Only valid - after window layout has been performed. - */ - wxSize GetCellSize(int row, int col) const; - - /** - Get the size used for cells in the grid with no item. - */ - wxSize GetEmptyCellSize() const; - - //@{ - /** - Get the grid position of the specified item. - */ - wxGBPosition GetItemPosition(wxWindow* window); - wxGBPosition GetItemPosition(wxSizer* sizer); - wxGBPosition GetItemPosition(size_t index); - //@} - - //@{ - /** - Get the row/col spanning of the specified item. - */ - wxGBSpan GetItemSpan(wxWindow* window); - wxGBSpan GetItemSpan(wxSizer* sizer); - wxGBSpan GetItemSpan(size_t index); - //@} - - /** - Called when the managed size of the sizer is needed or when layout - needs done. - */ - void RecalcSizes(); - - /** - Set the size used for cells in the grid with no item. - */ - void SetEmptyCellSize(const wxSize& sz); - - //@{ - /** - Set the grid position of the specified item. Returns @true on success. - If the move is not allowed (because an item is already there) then - @false is returned. - */ - bool SetItemPosition(wxWindow* window, const wxGBPosition& pos); - bool SetItemPosition(wxSizer* sizer, const wxGBPosition& pos); - bool SetItemPosition(size_t index, const wxGBPosition& pos); - //@} - - //@{ - /** - Set the row/col spanning of the specified item. Returns @true on - success. If the move is not allowed (because an item is already there) - then @false is returned. - */ - bool SetItemSpan(wxWindow* window, const wxGBSpan& span); - bool SetItemSpan(wxSizer* sizer, const wxGBSpan& span); - bool SetItemSpan(size_t index, const wxGBSpan& span); - //@} -}; - - - -/** - @class wxGBSizerItem - @wxheader{gbsizer.h} - - The wxGBSizerItem class is used by the wxGridBagSizer for tracking the - items in the sizer. It adds grid position and spanning information to the - normal wxSizerItem by adding wxGBPosition and wxGBSpan attrbibutes. Most of - the time you will not need to use a wxGBSizerItem directly in your code, - but there are a couple of cases where it is handy. - - @library{wxcore} - @category{winlayout} -*/ -class wxGBSizerItem : public wxSizerItem -{ -public: - /** - Construct a sizer item for tracking a spacer. - */ - wxGBSizerItem(int width, int height, const wxGBPosition& pos, - const wxGBSpan& span, int flag, int border, - wxObject* userData); - /** - Construct a sizer item for tracking a window. - */ - wxGBSizerItem(wxWindow* window, const wxGBPosition& pos, - const wxGBSpan& span, int flag, int border, - wxObject* userData); - /** - Construct a sizer item for tracking a subsizer. - */ - wxGBSizerItem(wxSizer* sizer, const wxGBPosition& pos, - const wxGBSpan& span, int flag, int border, - wxObject* userData); - - /** - Get the row and column of the endpoint of this item. - */ - void GetEndPos(int& row, int& col); - - //@{ - /** - Get the grid position of the item. - */ - wxGBPosition GetPos() const; - void GetPos(int& row, int& col) const; - //@} - - //@{ - /** - Get the row and column spanning of the item. - */ - wxGBSpan GetSpan() const; - void GetSpan(int& rowspan, int& colspan) const; - //@} - - /** - Returns @true if this item and the @a other item instersect. - */ - bool Intersects(const wxGBSizerItem& other); - /** - Returns @true if the given pos/span would intersect with this item. - */ - bool Intersects(const wxGBPosition& pos, const wxGBSpan& span); - - /** - If the item is already a member of a sizer then first ensure that there - is no other item that would intersect with this one at the new - position, then set the new position. Returns @true if the change is - successful and after the next Layout the item will be moved. - */ - bool SetPos(const wxGBPosition& pos); - - /** - If the item is already a member of a sizer then first ensure that there - is no other item that would intersect with this one with its new - spanning size, then set the new spanning. Returns @true if the change - is successful and after the next Layout the item will be resized. - */ - bool SetSpan(const wxGBSpan& span); -}; - - - -/** - @class wxGBSpan - @wxheader{gbsizer.h} - - This class is used to hold the row and column spanning attributes of items - in a wxGridBagSizer. - - @library{wxcore} - @category{winlayout} -*/ -class wxGBSpan -{ -public: - /** - Default constructor, setting the rowspan and colspan to (1,1) meaning - that the item occupies one cell in each direction. - */ - wxGBSpan(); - /** - Construct a new wxGBSpan, setting the @a rowspan and @a colspan. - */ - wxGBSpan(int rowspan, int colspan); - - /** - Get the current colspan value. - */ - int GetColspan() const; - - /** - Get the current rowspan value. - */ - int GetRowspan() const; - - /** - Set a new colspan value. - */ - void SetColspan(int colspan); - - /** - Set a new rowspan value. - */ - void SetRowspan(int rowspan); - - /** - Checks if the span is valid. An invalid span is (-1,-1). - */ - bool operator!(const wxGBSpan& o) const; - - /** - Compare equality of two wxGBSpans. - */ - bool operator==(const wxGBSpan& o) const; -}; - diff --git a/interface/gdicmn.h b/interface/gdicmn.h deleted file mode 100644 index f415ecf9d8..0000000000 --- a/interface/gdicmn.h +++ /dev/null @@ -1,881 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: gdicmn.h -// Purpose: interface of wxRealPoint -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - - -/** - Bitmap type flags. See wxBitmap and wxImage classes. -*/ -enum wxBitmapType -{ - wxBITMAP_TYPE_INVALID, - wxBITMAP_TYPE_BMP, - wxBITMAP_TYPE_BMP_RESOURCE, - wxBITMAP_TYPE_RESOURCE = wxBITMAP_TYPE_BMP_RESOURCE, - wxBITMAP_TYPE_ICO, - wxBITMAP_TYPE_ICO_RESOURCE, - wxBITMAP_TYPE_CUR, - wxBITMAP_TYPE_CUR_RESOURCE, - wxBITMAP_TYPE_XBM, - wxBITMAP_TYPE_XBM_DATA, - wxBITMAP_TYPE_XPM, - wxBITMAP_TYPE_XPM_DATA, - wxBITMAP_TYPE_TIF, - wxBITMAP_TYPE_TIF_RESOURCE, - wxBITMAP_TYPE_GIF, - wxBITMAP_TYPE_GIF_RESOURCE, - wxBITMAP_TYPE_PNG, - wxBITMAP_TYPE_PNG_RESOURCE, - wxBITMAP_TYPE_JPEG, - wxBITMAP_TYPE_JPEG_RESOURCE, - wxBITMAP_TYPE_PNM, - wxBITMAP_TYPE_PNM_RESOURCE, - wxBITMAP_TYPE_PCX, - wxBITMAP_TYPE_PCX_RESOURCE, - wxBITMAP_TYPE_PICT, - wxBITMAP_TYPE_PICT_RESOURCE, - wxBITMAP_TYPE_ICON, - wxBITMAP_TYPE_ICON_RESOURCE, - wxBITMAP_TYPE_ANI, - wxBITMAP_TYPE_IFF, - wxBITMAP_TYPE_TGA, - wxBITMAP_TYPE_MACCURSOR, - wxBITMAP_TYPE_MACCURSOR_RESOURCE, - wxBITMAP_TYPE_ANY = 50 -}; - -/** - Standard cursors. See wxCursor. -*/ -enum wxStockCursor -{ - wxCURSOR_NONE, - wxCURSOR_ARROW, ///< A standard arrow cursor. - wxCURSOR_RIGHT_ARROW, ///< A standard arrow cursor pointing to the right. - wxCURSOR_BULLSEYE, ///< Bullseye cursor. - wxCURSOR_CHAR, ///< Rectangular character cursor. - wxCURSOR_CROSS, ///< A cross cursor. - wxCURSOR_HAND, ///< A hand cursor. - wxCURSOR_IBEAM, ///< An I-beam cursor (vertical line). - wxCURSOR_LEFT_BUTTON, ///< Represents a mouse with the left button depressed. - wxCURSOR_MAGNIFIER, ///< A magnifier icon. - wxCURSOR_MIDDLE_BUTTON, ///< Represents a mouse with the middle button depressed. - wxCURSOR_NO_ENTRY, ///< A no-entry sign cursor. - wxCURSOR_PAINT_BRUSH, ///< A paintbrush cursor. - wxCURSOR_PENCIL, ///< A pencil cursor. - wxCURSOR_POINT_LEFT, ///< A cursor that points left. - wxCURSOR_POINT_RIGHT, ///< A cursor that points right. - wxCURSOR_QUESTION_ARROW, ///< An arrow and question mark. - wxCURSOR_RIGHT_BUTTON, ///< Represents a mouse with the right button depressed. - wxCURSOR_SIZENESW, ///< A sizing cursor pointing NE-SW. - wxCURSOR_SIZENS, ///< A sizing cursor pointing N-S. - wxCURSOR_SIZENWSE, ///< A sizing cursor pointing NW-SE. - wxCURSOR_SIZEWE, ///< A sizing cursor pointing W-E. - wxCURSOR_SIZING, ///< A general sizing cursor. - wxCURSOR_SPRAYCAN, ///< A spraycan cursor. - wxCURSOR_WAIT, ///< A wait cursor. - wxCURSOR_WATCH, ///< A watch cursor. - wxCURSOR_BLANK, ///< Transparent cursor. - wxCURSOR_DEFAULT, ///< Standard X11 cursor (only in wxGTK). - wxCURSOR_COPY_ARROW , ///< MacOS Theme Plus arrow (only in wxMac). - wxCURSOR_CROSS_REVERSE, ///< Only available on wxX11. - wxCURSOR_DOUBLE_ARROW, ///< Only available on wxX11. - wxCURSOR_BASED_ARROW_UP, ///< Only available on wxX11. - wxCURSOR_BASED_ARROW_DOWN, ///< Only available on wxX11. - wxCURSOR_ARROWWAIT, ///< A wait cursor with a standard arrow. - wxCURSOR_MAX -}; - - - -/** - @class wxRealPoint - @wxheader{gdicmn.h} - - A wxRealPoint is a useful data structure for graphics operations. - - It contains floating point @e x and @e y members. See wxPoint for an - integer version. - - @library{wxcore} - @category{data} - - @see wxPoint -*/ -class wxRealPoint -{ -public: - wxRealPoint(); - - /** - Initializes the point with the given coordinates. - */ - wxRealPoint(double x, double y); - - /** - X coordinate of this point. - */ - double x; - - /** - Y coordinate of this point. - */ - double y; -}; - - - -/** - @class wxRect - @wxheader{gdicmn.h} - - A class for manipulating rectangles. - - @library{wxcore} - @category{data} - - @see wxPoint, wxSize -*/ -class wxRect -{ -public: - /** - Default constructor. - */ - wxRect(); - /** - Creates a wxRect object from @a x, @a y, @a width and @a height values. - */ - wxRect(int x, int y, int width, int height); - /** - Creates a wxRect object from top-left and bottom-right points. - */ - wxRect(const wxPoint& topLeft, const wxPoint& bottomRight); - /** - Creates a wxRect object from position and @a size values. - */ - wxRect(const wxPoint& pos, const wxSize& size); - /** - Creates a wxRect object from @a size values at the origin. - */ - wxRect(const wxSize& size); - - //@{ - /** - Returns the rectangle having the same size as this one but centered - relatively to the given rectangle @a r. By default, rectangle is - centred in both directions but if @a dir includes only @c wxVERTICAL or - only @c wxHORIZONTAL, then it is only centered in this direction while - the other component of its position remains unchanged. - */ - wxRect CentreIn(const wxRect& r, int dir = wxBOTH) const; - wxRect CenterIn(const wxRect& r, int dir = wxBOTH) const; - //@} - - /** - Returns @true if the given point is inside the rectangle (or on its - boundary) and @false otherwise. - */ - bool Contains(int x, int y) const; - /** - Returns @true if the given point is inside the rectangle (or on its - boundary) and @false otherwise. - */ - bool Contains(const wxPoint& pt) const; - /** - Returns @true if the given rectangle is completely inside this - rectangle (or touches its boundary) and @false otherwise. - */ - bool Contains(const wxRect& rect) const; - - //@{ - /** - Decrease the rectangle size. - - This method is the opposite from Inflate(): Deflate(a, b) is equivalent - to Inflate(-a, -b). Please refer to Inflate() for full description. - */ - void Deflate(wxCoord dx, wxCoord dy); - void Deflate(const wxSize& diff); - void Deflate(wxCoord diff); - wxRect Deflate(wxCoord dx, wxCoord dy) const; - //@} - - /** - Gets the bottom point of the rectangle. - */ - int GetBottom() const; - - /** - Gets the position of the bottom left corner. - */ - wxPoint GetBottomLeft() const; - - /** - Gets the position of the bottom right corner. - */ - wxPoint GetBottomRight() const; - - /** - Gets the height member. - */ - int GetHeight() const; - - /** - Gets the left point of the rectangle (the same as GetX()). - */ - int GetLeft() const; - - /** - Gets the position. - */ - wxPoint GetPosition() const; - - /** - Gets the right point of the rectangle. - */ - int GetRight() const; - - /** - Gets the size. - - @see SetSize() - */ - wxSize GetSize() const; - - /** - Gets the top point of the rectangle (the same as GetY()). - */ - int GetTop() const; - - /** - Gets the position of the top left corner of the rectangle, same as - GetPosition(). - */ - wxPoint GetTopLeft() const; - - /** - Gets the position of the top right corner. - */ - wxPoint GetTopRight() const; - - /** - Gets the width member. - */ - int GetWidth() const; - - /** - Gets the x member. - */ - int GetX() const; - - /** - Gets the y member. - */ - int GetY() const; - - //@{ - /** - Increases the size of the rectangle. - - The left border is moved farther left and the right border is moved - farther right by @a dx. The upper border is moved farther up and the - bottom border is moved farther down by @a dy. (Note the the width and - height of the rectangle thus change by 2*dx and 2*dy, respectively.) If - one or both of @a dx and @a dy are negative, the opposite happens: the - rectangle size decreases in the respective direction. - - Inflating and deflating behaves "naturally". Defined more precisely, - that means: - -# "Real" inflates (that is, @a dx and/or @a dy = 0) are not - constrained. Thus inflating a rectangle can cause its upper left - corner to move into the negative numbers. (2.5.4 and older forced - the top left coordinate to not fall below (0, 0), which implied a - forced move of the rectangle.) - -# Deflates are clamped to not reduce the width or height of the - rectangle below zero. In such cases, the top-left corner is - nonetheless handled properly. For example, a rectangle at (10, 10) - with size (20, 40) that is inflated by (-15, -15) will become - located at (20, 25) at size (0, 10). Finally, observe that the width - and height are treated independently. In the above example, the - width is reduced by 20, whereas the height is reduced by the full 30 - (rather than also stopping at 20, when the width reached zero). - - @see Deflate() - */ - void Inflate(wxCoord dx, wxCoord dy); - void Inflate(const wxSize& diff); - void Inflate(wxCoord diff); - wxRect Inflate(wxCoord dx, wxCoord dy) const; - //@} - - //@{ - /** - Modifies the rectangle to contain the overlapping box of this rectangle - and the one passed in as parameter. - */ - wxRect Intersect(const wxRect& rect) const; - wxRect& Intersect(const wxRect& rect); - //@} - - /** - Returns @true if this rectangle has a non-empty intersection with the - rectangle @a rect and @false otherwise. - */ - bool Intersects(const wxRect& rect) const; - - /** - Returns @true if this rectangle has a width or height less than or - equal to 0 and @false otherwise. - */ - bool IsEmpty() const; - - //@{ - /** - Moves the rectangle by the specified offset. If @a dx is positive, the - rectangle is moved to the right, if @a dy is positive, it is moved to the - bottom, otherwise it is moved to the left or top respectively. - */ - void Offset(wxCoord dx, wxCoord dy); - void Offset(const wxPoint& pt); - //@} - - /** - Sets the height. - */ - void SetHeight(int height); - - /** - Sets the size. - - @see GetSize() - */ - void SetSize(const wxSize& s); - - /** - Sets the width. - */ - void SetWidth(int width); - - /** - Sets the x position. - */ - void SetX(int x); - - /** - Sets the y position. - */ - void SetY(int y); - - //@{ - /** - Modifies the rectangle to contain the bounding box of this rectangle - and the one passed in as parameter. - */ - wxRect Union(const wxRect& rect) const; - wxRect& Union(const wxRect& rect); - //@} - - /** - Inequality operator. - */ - bool operator !=(const wxRect& r1, const wxRect& r2); - - //@{ - /** - Like Union(), but doesn't treat empty rectangles specially. - */ - wxRect operator +(const wxRect& r1, const wxRect& r2); - wxRect& operator +=(const wxRect& r); - //@} - - //@{ - /** - Returns the intersection of two rectangles (which may be empty). - */ - wxRect operator *(const wxRect& r1, const wxRect& r2); - wxRect& operator *=(const wxRect& r); - //@} - - /** - Assignment operator. - */ - void operator =(const wxRect& rect); - - /** - Equality operator. - */ - bool operator ==(const wxRect& r1, const wxRect& r2); - - /** - Height member. - */ - int height; - - /** - Width member. - */ - int width; - - /** - x coordinate of the top-level corner of the rectangle. - */ - int x; - - /** - y coordinate of the top-level corner of the rectangle. - */ - int y; -}; - - - -/** - @class wxPoint - @wxheader{gdicmn.h} - - A wxPoint is a useful data structure for graphics operations. - - It contains integer @e x and @e y members. See wxRealPoint for a floating - point version. - - @library{wxcore} - @category{data} - - @stdobjects - ::wxDefaultPosition - - @see wxRealPoint -*/ -class wxPoint -{ -public: - //@{ - /** - Constructs a point. - */ - wxPoint(); - wxPoint(int x, int y); - //@} - - /** - Assignment operator. - */ - void operator =(const wxPoint& pt); - - bool operator ==(const wxPoint& p1, const wxPoint& p2); - bool operator !=(const wxPoint& p1, const wxPoint& p2); - - wxPoint operator +(const wxPoint& p1, const wxPoint& p2); - wxPoint operator -(const wxPoint& p1, const wxPoint& p2); - - wxPoint& operator +=(const wxPoint& pt); - wxPoint& operator -=(const wxPoint& pt); - - wxPoint operator +(const wxPoint& pt, const wxSize& sz); - wxPoint operator -(const wxPoint& pt, const wxSize& sz); - wxPoint operator +(const wxSize& sz, const wxPoint& pt); - wxPoint operator -(const wxSize& sz, const wxPoint& pt); - - wxPoint& operator +=(const wxSize& sz); - wxPoint& operator -=(const wxSize& sz); - - /** - x member. - */ - int x; - - /** - y member. - */ - int y; -}; - -/** - Global istance of a wxPoint initialized with values (-1,-1). -*/ -wxPoint wxDefaultPosition; - - -/** - @class wxColourDatabase - @wxheader{gdicmn.h} - - wxWidgets maintains a database of standard RGB colours for a predefined - set of named colours. The application may add to this set if desired by - using AddColour() and may use it to look up colours by names using Find() - or find the names for the standard colour using FindName(). - - There is one predefined, global instance of this class called - ::wxTheColourDatabase. - - The standard database contains at least the following colours: - - @beginTable - - AQUAMARINE - @n BLACK - @n BLUE - @n BLUE VIOLET - @n BROWN - @n CADET BLUE - @n CORAL - @n CORNFLOWER BLUE - @n CYAN - @n DARK GREY - @n DARK GREEN - @n DARK OLIVE GREEN - @n DARK ORCHID - @n DARK SLATE BLUE - @n DARK SLATE GREY - @n DARK TURQUOISE - @n DIM GREY - - FIREBRICK - @n FOREST GREEN - @n GOLD - @n GOLDENROD - @n GREY - @n GREEN - @n GREEN YELLOW - @n INDIAN RED - @n KHAKI - @n LIGHT BLUE - @n LIGHT GREY - @n LIGHT STEEL BLUE - @n LIME GREEN - @n MAGENTA - @n MAROON - @n MEDIUM AQUAMARINE - @n MEDIUM BLUE - - MEDIUM FOREST GREEN - @n MEDIUM GOLDENROD - @n MEDIUM ORCHID - @n MEDIUM SEA GREEN - @n MEDIUM SLATE BLUE - @n MEDIUM SPRING GREEN - @n MEDIUM TURQUOISE - @n MEDIUM VIOLET RED - @n MIDNIGHT BLUE - @n NAVY - @n ORANGE - @n ORANGE RED - @n ORCHID - @n PALE GREEN - @n PINK - @n PLUM - @n PURPLE - - RED - @n SALMON - @n SEA GREEN - @n SIENNA - @n SKY BLUE - @n SLATE BLUE - @n SPRING GREEN - @n STEEL BLUE - @n TAN - @n THISTLE - @n TURQUOISE - @n VIOLET - @n VIOLET RED - @n WHEAT - @n WHITE - @n YELLOW - @n YELLOW GREEN - - @endTable - - @library{wxcore} - @category{gdi} - - @see wxColour -*/ -class wxColourDatabase -{ -public: - /** - Constructs the colour database. It will be initialized at the first - use. - */ - wxColourDatabase(); - - /** - Adds a colour to the database. If a colour with the same name already - exists, it is replaced. - */ - void AddColour(const wxString& colourName, const wxColour& colour); - - /** - Finds a colour given the name. Returns an invalid colour object (that - is, wxColour::IsOk() will return @false) if the colour wasn't found in - the database. - */ - wxColour Find(const wxString& colourName); - - /** - Finds a colour name given the colour. Returns an empty string if the - colour is not found in the database. - */ - wxString FindName(const wxColour& colour) const; -}; - - -/** - @class wxSize - @wxheader{gdicmn.h} - - A wxSize is a useful data structure for graphics operations. It simply - contains integer @e width and @e height members. - - wxSize is used throughout wxWidgets as well as wxPoint which, although - almost equivalent to wxSize, has a different meaning: wxPoint represents a - position while wxSize represents the size. - - @beginWxPythonOnly - wxPython defines aliases for the @e x and @e y members named @e width and - @e height since it makes much more sense for sizes. - @endWxPythonOnly - - @library{wxcore} - @category{data} - - @stdobjects - ::wxDefaultSize - - @see wxPoint, wxRealPoint -*/ -class wxSize -{ -public: - //@{ - /** - Creates a size object. - */ - wxSize(); - wxSize(int width, int height); - //@} - - //@{ - /** - Decreases the size in both x and y directions. - - @see IncBy() - */ - void DecBy(const wxSize& size); - void DecBy(int dx, int dy); - void DecBy(int d); - //@} - - /** - Decrements this object so that both of its dimensions are not greater - than the corresponding dimensions of the @a size. - - @see IncTo() - */ - void DecTo(const wxSize& size); - - /** - Gets the height member. - */ - int GetHeight() const; - - /** - Gets the width member. - */ - int GetWidth() const; - - //@{ - /** - Increases the size in both x and y directions. - - @see DecBy() - */ - void IncBy(const wxSize& size); - void IncBy(int dx, int dy); - void IncBy(int d); - //@} - - /** - Increments this object so that both of its dimensions are not less than - the corresponding dimensions of the @a size. - - @see DecTo() - */ - void IncTo(const wxSize& size); - - /** - Returns @true if neither of the size object components is equal to -1, - which is used as default for the size values in wxWidgets (hence the - predefined ::wxDefaultSize has both of its components equal to -1). - - This method is typically used before calling SetDefaults(). - */ - bool IsFullySpecified() const; - - /** - Scales the dimensions of this object by the given factors. If you want - to scale both dimensions by the same factor you can also use - operator*=(). - - @return A reference to this object (so that you can concatenate other - operations in the same line). - */ - wxSize& Scale(float xscale, float yscale); - - /** - Sets the width and height members. - */ - void Set(int width, int height); - - /** - Combine this size object with another one replacing the default (i.e. - equal to -1) components of this object with those of the other. It is - typically used like this: - - @code - if ( !size.IsFullySpecified() ) - { - size.SetDefaults(GetDefaultSize()); - } - @endcode - - @see IsFullySpecified() - */ - void SetDefaults(const wxSize& sizeDefault); - - /** - Sets the height. - */ - void SetHeight(int height); - - /** - Sets the width. - */ - void SetWidth(int width); - - /** - Assignment operator. - */ - void operator =(const wxSize& sz); - - bool operator ==(const wxSize& s1, const wxSize& s2); - bool operator !=(const wxSize& s1, const wxSize& s2); - - wxSize operator +(const wxSize& s1, const wxSize& s2); - wxSize operator -(const wxSize& s1, const wxSize& s2); - wxSize& operator +=(const wxSize& sz); - wxSize& operator -=(const wxSize& sz); - - wxSize operator /(const wxSize& sz, int factor); - wxSize operator *(const wxSize& sz, int factor); - wxSize operator *(int factor, const wxSize& sz); - wxSize& operator /=(int factor); - wxSize& operator *=(int factor); -}; - -/** - Global instance of a wxSize object initialized to (-1,-1). -*/ -wxSize wxDefaultSize; - - - - -// ============================================================================ -// Global functions/macros -// ============================================================================ - -/** @ingroup group_funcmacro_gdi */ -//@{ - -/** - This macro loads a bitmap from either application resources (on the - platforms for which they exist, i.e. Windows and OS2) or from an XPM file. - This can help to avoid using @ifdef_ when creating bitmaps. - - @see @ref overview_bitmap, wxICON() - - @header{wx/gdicmn.h} -*/ -#define wxBITMAP(bitmapName) - -/** - This macro loads an icon from either application resources (on the - platforms for which they exist, i.e. Windows and OS2) or from an XPM file. - This can help to avoid using @ifdef_ when creating icons. - - @see @ref overview_bitmap, wxBITMAP() - - @header{wx/gdicmn.h} -*/ -wxICON(); - -/** - Returns @true if the display is colour, @false otherwise. - - @header{wx/gdicmn.h} -*/ -bool wxColourDisplay(); - -/** - Returns the depth of the display (a value of 1 denotes a monochrome - display). - - @header{wx/gdicmn.h} -*/ -int wxDisplayDepth(); - -/** - Globally sets the cursor; only has an effect on Windows, Mac and GTK+. You - should call this function with wxNullCursor to restore the system cursor. - - @see wxCursor, wxWindow::SetCursor() - - @header{wx/gdicmn.h} -*/ -void wxSetCursor(const wxCursor& cursor); - -//@} - -/** @ingroup group_funcmacro_gdi */ -//@{ -/** - Returns the dimensions of the work area on the display. On Windows this - means the area not covered by the taskbar, etc. Other platforms are - currently defaulting to the whole display until a way is found to provide - this info for all window managers, etc. - - @header{wx/gdicmn.h} -*/ -void wxClientDisplayRect(int* x, int* y, int* width, int* height); -wxRect wxGetClientDisplayRect(); -//@} - -/** @ingroup group_funcmacro_gdi */ -//@{ -/** - Returns the display size in pixels. - - @header{wx/gdicmn.h} -*/ -void wxDisplaySize(int* width, int* height); -wxSize wxGetDisplaySize(); -//@} - -/** @ingroup group_funcmacro_gdi */ -//@{ -/** - Returns the display size in millimeters. - - @header{wx/gdicmn.h} -*/ -void wxDisplaySizeMM(int* width, int* height); -wxSize wxGetDisplaySizeMM(); -//@} - diff --git a/interface/gdiobj.h b/interface/gdiobj.h deleted file mode 100644 index 52464ff191..0000000000 --- a/interface/gdiobj.h +++ /dev/null @@ -1,36 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: gdiobj.h -// Purpose: interface of wxGDIObject -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxGDIObject - @wxheader{gdiobj.h} - - This class allows platforms to implement functionality to optimise GDI objects, - such - as wxPen, wxBrush and wxFont. On Windows, the underling GDI objects are a - scarce resource - and are cleaned up when a usage count goes to zero. On some platforms this - class may not have any special functionality. - - Since the functionality of this class is platform-specific, it is not - documented here in detail. - - @library{wxcore} - @category{FIXME} - - @see wxPen, wxBrush, wxFont -*/ -class wxGDIObject : public wxObject -{ -public: - /** - Default constructor. - */ - wxGDIObject(); -}; - diff --git a/interface/generic/helpext.h b/interface/generic/helpext.h deleted file mode 100644 index 57c84afce9..0000000000 --- a/interface/generic/helpext.h +++ /dev/null @@ -1,168 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: helpext.h -// Purpose: interface of wxExtHelpController -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - - -/** - @class wxExtHelpController - @wxheader{help.h} - - This class implements help via an external browser. - It requires the name of a directory containing the documentation - and a file mapping numerical Section numbers to relative URLS. - - The map file contains two or three fields per line: - numeric_id relative_URL [; comment/documentation] - - The numeric_id is the id used to look up the entry in - DisplaySection()/DisplayBlock(). The relative_URL is a filename of - an html file, relative to the help directory. The optional - comment/documentation field (after a ';') is used for keyword - searches, so some meaningful text here does not hurt. - If the documentation itself contains a ';', only the part before - that will be displayed in the listbox, but all of it used for search. - - Lines starting with ';' will be ignored. - - @library{wxadv} - @category{help} - - @see wxHelpController -*/ -class wxExtHelpController : public wxHelpController -{ -public: - wxExtHelpController(wxWindow* parentWindow = NULL); - virtual ~wxExtHelpController(); - - /** - Tell it which browser to use. - The Netscape support will check whether Netscape is already - running (by looking at the .netscape/lock file in the user's - home directory) and tell it to load the page into the existing window. - - @param viewer - The command to call a browser/html viewer. - @param flags - Set this to wxHELP_NETSCAPE if the browser is some variant of Netscape. - */ - virtual void SetViewer(const wxString& viewer = wxEmptyString, - long flags = wxHELP_NETSCAPE); - - /** - This must be called to tell the controller where to find the - documentation. - If a locale is set, look in file/localename, i.e. - If passed "/usr/local/myapp/help" and the current wxLocale is - set to be "de", then look in "/usr/local/myapp/help/de/" - first and fall back to "/usr/local/myapp/help" if that - doesn't exist. - - @param file - NOT a filename, but a directory name. - - @return @true on success - */ - virtual bool Initialize(const wxString& dir, int server); - - /** - This must be called to tell the controller where to find the - documentation. - If a locale is set, look in file/localename, i.e. - If passed "/usr/local/myapp/help" and the current wxLocale is - set to be "de", then look in "/usr/local/myapp/help/de/" - first and fall back to "/usr/local/myapp/help" if that - doesn't exist. - - @param dir - directory name where to fine the help files - - @return @true on success - */ - virtual bool Initialize(const wxString& dir); - - /** - If file is "", reloads file given in Initialize. - - @param file - Name of help directory. - - @return @true on success - */ - virtual bool LoadFile(const wxString& file = wxEmptyString); - - /** - Display list of all help entries. - - @return @true on success - */ - virtual bool DisplayContents(void); - - /** - Display help for id sectionNo. - - @return @true on success - */ - virtual bool DisplaySection(int sectionNo); - - /** - Display help for id sectionNo -- identical with DisplaySection(). - - @return @true on success - */ - virtual bool DisplaySection(const wxString& section); - - /** - Display help for URL (using DisplayHelp) or keyword (using KeywordSearch) - - @return @true on success - */ - virtual bool DisplayBlock(long blockNo); - - /** - Search comment/documentation fields in map file and present a - list to chose from. - - @param k - string to search for, empty string will list all entries - - @return @true on success - */ - virtual bool KeywordSearch(const wxString& k, - wxHelpSearchMode mode = wxHELP_SEARCH_ALL); - - /** - Does nothing. - */ - virtual bool Quit(); - - /** - Does nothing. - */ - virtual void OnQuit(); - - /** - Call the browser using a relative URL. - */ - virtual bool DisplayHelp(const wxString &) ; - - /** - Allows one to override the default settings for the help frame. - */ - virtual void SetFrameParameters(const wxString& title, - const wxSize& size, - const wxPoint& pos = wxDefaultPosition, - bool newFrameEachTime = false); - - /** - Obtains the latest settings used by the help frame and the help frame. - */ - virtual wxFrame *GetFrameParameters(wxSize *size = NULL, - wxPoint *pos = NULL, - bool *newFrameEachTime = NULL); -}; - diff --git a/interface/glcanvas.h b/interface/glcanvas.h deleted file mode 100644 index c3694c591d..0000000000 --- a/interface/glcanvas.h +++ /dev/null @@ -1,271 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: glcanvas.h -// Purpose: interface of wxGLContext -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxGLContext - @wxheader{glcanvas.h} - - An instance of a wxGLContext represents the state of an OpenGL state machine - and the connection between OpenGL and the system. - - The OpenGL state includes everything that can be set with the OpenGL API: - colors, rendering variables, display lists, texture objects, etc. - Although it is possible to have multiple rendering contexts share display lists - in order to save resources, - this method is hardly used today any more, because display lists are only a - tiny fraction of the overall state. - - Therefore, one rendering context is usually used with or bound to multiple - output windows in turn, - so that the application has access to the complete and identical state while - rendering into each window. - - Binding (making current) a rendering context with another instance of a - wxGLCanvas however works only - if the other wxGLCanvas was created with the same attributes as the wxGLCanvas - from which the wxGLContext - was initialized. (This applies to sharing display lists among contexts - analogously.) - - Note that some wxGLContext features are extremely platform-specific - its best - to check your native platform's glcanvas header (on windows include/wx/msw/glcanvas.h) to see what features your native platform provides. - - @library{wxgl} - @category{gl} - - @see wxGLCanvas -*/ -class wxGLContext : public wxObject -{ -public: - /** - Constructor. - - @param win - The canvas that is used to initialize this context. This parameter is - needed only temporarily, - and the caller may do anything with it (e.g. destroy the window) after the - constructor returned. - It will be possible to bind (make current) this context to any other - wxGLCanvas that has been created - with equivalent attributes as win. - @param other - Context to share display lists with or @NULL (the default) for no sharing. - */ - wxGLContext(wxGLCanvas* win, const wxGLContext* other = NULL); - - /** - Makes the OpenGL state that is represented by this rendering context current - with the wxGLCanvas @e win. - Note that @a win can be a different wxGLCanvas window than the one that was - passed to the constructor of this rendering context. - If @e RC is an object of type wxGLContext, the statements @e - RC.SetCurrent(win); and @e win.SetCurrent(RC); are equivalent, - see wxGLCanvas::SetCurrent. - */ - void SetCurrent(const wxGLCanvas& win); -}; - -/** - Constants for use with wxGLCanvas. - - Notice that not all implementation support options such as stereo, - auxiliary buffers, alpha channel, and accumulator buffer, use - wxGLCanvas::IsDisplaySupported() to check for individual attributes support. - */ -enum -{ - /// Use true color palette (on if no attributes at all specified). - WX_GL_RGBA = 1, - - /// Specifies the number of bits for buffer if not WX_GL_RGBA. - WX_GL_BUFFER_SIZE, - - /// Must be followed by 0 for main buffer, >0 for overlay, <0 for underlay. - WX_GL_LEVEL, - - /// Use double buffering if present (on if no attributes specified). - WX_GL_DOUBLEBUFFER, - - /// Use stereoscopic display. - WX_GL_STEREO, - - /// Specifies number of auxiliary buffers. - WX_GL_AUX_BUFFERS, - - /// Use red buffer with most bits (> MIN_RED bits) - WX_GL_MIN_RED, - - /// Use green buffer with most bits (> MIN_GREEN bits) - WX_GL_MIN_GREEN, - - /// Use blue buffer with most bits (> MIN_BLUE bits) - WX_GL_MIN_BLUE, - - /// Use alpha buffer with most bits (> MIN_ALPHA bits) - WX_GL_MIN_ALPHA, - - /// Specifies number of bits for Z-buffer (typically 0, 16 or 32). - WX_GL_DEPTH_SIZE, - - /// Specifies number of bits for stencil buffer. - WX_GL_STENCIL_SIZE, - - /// Specifies minimal number of red accumulator bits. - WX_GL_MIN_ACCUM_RED, - - /// Specifies minimal number of green accumulator bits. - WX_GL_MIN_ACCUM_GREEN, - - /// Specifies minimal number of blue accumulator bits. - WX_GL_MIN_ACCUM_BLUE, - - /// Specifies minimal number of alpha accumulator bits. - WX_GL_MIN_ACCUM_ALPHA, - - /// 1 for multisampling support (antialiasing) - WX_GL_SAMPLE_BUFFERS, - - /// 4 for 2x2 antialising supersampling on most graphics cards - WX_GL_SAMPLES - -}; - -/** - @class wxGLCanvas - @wxheader{glcanvas.h} - - wxGLCanvas is a class for displaying OpenGL graphics. It is always used in - conjunction with wxGLContext as the context can only be - be made current (i.e. active for the OpenGL commands) when it is associated to - a wxGLCanvas. - - More precisely, you first need to create a wxGLCanvas window and then create an - instance of a wxGLContext that is initialized with this - wxGLCanvas and then later use either wxGLCanvas::SetCurrent - with the instance of the wxGLContext or - wxGLContext::SetCurrent with the instance of - the wxGLCanvas (which might be not the same as was used - for the creation of the context) to bind the OpenGL state that is represented - by the rendering context to the canvas, and then finally call - wxGLCanvas::SwapBuffers to swap the buffers of - the OpenGL canvas and thus show your current output. - - Notice that previous versions of wxWidgets used to implicitly create a - wxGLContext inside wxGLCanvas itself. This is still supported in the current - version but is deprecated now and will be removed in the future, please update - your code to create the rendering contexts explicitly. - - To set up the attributes for the canvas (number of bits for the depth buffer, - number of bits for the stencil buffer and so on) you should set up the correct - values of - the @e attribList parameter. The values that should be set up and their - meanings will be described below. - - Notice that OpenGL is not enabled by default. To switch it on, you need to edit - setup.h under Windows and set @c wxUSE_GLCANVAS to 1 (you may also need - to have to add @c opengl32.lib and @c glu32.lib to the list of libraries - your program is linked with). On Unix, pass @c --with-opengl to configure. - - @library{wxgl} - @category{gl} - - @see wxGLContext -*/ -class wxGLCanvas : public wxWindow -{ -public: - /** - Creates a window with the given parameters. Notice that you need to create and - use a wxGLContext to output to this window. - If - - @param attribList is not specified, double buffered RGBA mode is used. - - parent - Pointer to a parent window. - @param id - Window identifier. If -1, will automatically create an identifier. - @param pos - Window position. wxDefaultPosition is (-1, -1) which indicates that - wxWidgets - should generate a default position for the window. - @param size - Window size. wxDefaultSize is (-1, -1) which indicates that wxWidgets should - generate a default size for the window. If no suitable size can be found, - the window will be sized to 20x20 pixels so that the window is visible but obviously not correctly sized. - @param style - Window style. - @param name - Window name. - @param attribList - Array of integers. With this parameter you can set the device - context attributes associated to this window. This array is - zero-terminated: it should be set up with constants described in - the table above. If a constant should be followed by a value, put - it in the next array position. For example, the WX_GL_DEPTH_SIZE - should be followed by the value that indicates the number of bits - for the depth buffer, e.g: - @code - attribList[n++] = WX_GL_DEPTH_SIZE; - attribList[n++] = 32; - attribList[n] = 0; // terminate the list - @endcode - If the attribute list is not specified at all, i.e. if this - parameter is @NULL, the default attributes including @c WX_GL_RGBA - and @c WX_GL_DOUBLEBUFFER are used. But notice that if you do - specify some attributes you also need to explicitly include these - two default attributes in the list if you need them. - @param palette - Palette for indexed colour (i.e. non WX_GL_RGBA) mode. - Ignored under most platforms. - */ - wxGLCanvas(wxWindow* parent, wxWindowID id = wxID_ANY, - const int* attribList = NULL, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = 0, - const wxString& name = "GLCanvas", - const wxPalette& palette = wxNullPalette); - - /** - Determines if a canvas having the specified attributes is available. - Returns @true if attributes are supported. - - @param attribList - See attribList for wxGLCanvas(). - */ - static bool IsDisplaySupported(const int* attribList = NULL); - - /** - Sets the current colour for this window (using @c glcolor3f()), using the - wxWidgets colour database to find a named colour. - */ - void SetColour(const wxString& colour); - - /** - Makes the OpenGL state that is represented by the OpenGL rendering context - @a context current, i.e. it will be used by all subsequent OpenGL calls. - This is equivalent to wxGLContext::SetCurrent - called with this window as parameter. - Note that this function may only be called when the window is shown on screen, - in particular it can't usually be called from the constructor as the window - isn't yet shown at this moment. - Returns @false if an error occurred. - */ - bool SetCurrent(const wxGLContext context); - - /** - Swaps the double-buffer of this window, making the back-buffer the front-buffer - and vice versa, - so that the output of the previous OpenGL commands is displayed on the window. - Returns @false if an error occurred. - */ - bool SwapBuffers(); -}; - diff --git a/interface/graphics.h b/interface/graphics.h deleted file mode 100644 index 45360115b7..0000000000 --- a/interface/graphics.h +++ /dev/null @@ -1,766 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: graphics.h -// Purpose: interface of wxGraphicsPath -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxGraphicsPath - @wxheader{graphics.h} - - A wxGraphicsPath is a native representation of an geometric path. The contents - are specific an private to the respective renderer. Instances are ref counted and can - therefore be assigned as usual. The only way to get a valid instance is via a - CreatePath call on the graphics context or the renderer instance. - - @library{wxcore} - @category{FIXME} -*/ -class wxGraphicsPath : public wxGraphicsObject -{ -public: - //@{ - /** - - */ - void AddArc(wxDouble x, wxDouble y, wxDouble r, - wxDouble startAngle, - wxDouble endAngle, bool clockwise); - void AddArc(const wxPoint2DDouble& c, wxDouble r, - wxDouble startAngle, - wxDouble endAngle, - bool clockwise); - //@} - - /** - Appends a an arc to two tangents connecting (current) to (x1,y1) and (x1,y1) to - (x2,y2), also a straight line from (current) to (x1,y1). - */ - void AddArcToPoint(wxDouble x1, wxDouble y1, wxDouble x2, - wxDouble y2, - wxDouble r); - - /** - Appends a circle around (x,y) with radius r as a new closed subpath. - */ - void AddCircle(wxDouble x, wxDouble y, wxDouble r); - - //@{ - /** - - */ - void AddCurveToPoint(wxDouble cx1, wxDouble cy1, wxDouble cx2, - wxDouble cy2, - wxDouble x, - wxDouble y); - void AddCurveToPoint(const wxPoint2DDouble& c1, - const wxPoint2DDouble& c2, - const wxPoint2DDouble& e); - //@} - - /** - Appends an ellipse fitting into the passed in rectangle. - */ - void AddEllipse(wxDouble x, wxDouble y, wxDouble w, wxDouble h); - - //@{ - /** - - */ - void AddLineToPoint(wxDouble x, wxDouble y); - void AddLineToPoint(const wxPoint2DDouble& p); - //@} - - /** - Adds another path. - */ - void AddPath(const wxGraphicsPath& path); - - /** - Adds a quadratic Bezier curve from the current point, using a control point and - an end point. - */ - void AddQuadCurveToPoint(wxDouble cx, wxDouble cy, wxDouble x, - wxDouble y); - - /** - Appends a rectangle as a new closed subpath. - */ - void AddRectangle(wxDouble x, wxDouble y, wxDouble w, wxDouble h); - - /** - Appends a rounded rectangle as a new closed subpath. - */ - void AddRoundedRectangle(wxDouble x, wxDouble y, wxDouble w, - wxDouble h, - wxDouble radius); - - /** - Closes the current sub-path. - */ - void CloseSubpath(); - - //@{ - /** - Returns @true if the point is within the path. - */ - bool Contains(const wxPoint2DDouble& c, - int fillStyle = wxODDEVEN_RULE) const; - const bool Contains(wxDouble x, wxDouble y, - int fillStyle = wxODDEVEN_RULE) const; - //@} - - //@{ - /** - Gets the bounding box enclosing all points (possibly including control points). - */ - wxRect2DDouble GetBox() const; - const void GetBox(wxDouble* x, wxDouble* y, wxDouble* w, - wxDouble* h) const; - //@} - - //@{ - /** - Gets the last point of the current path, (0,0) if not yet set. - */ - void GetCurrentPoint(wxDouble* x, wxDouble* y) const; - const wxPoint2DDouble GetCurrentPoint() const; - //@} - - /** - Returns the native path (CGPathRef for Core Graphics, Path pointer for GDIPlus - and a cairo_path_t pointer for cairo). - */ - void* GetNativePath() const; - - //@{ - /** - Begins a new subpath at (x,y) - */ - void MoveToPoint(wxDouble x, wxDouble y); - void MoveToPoint(const wxPoint2DDouble& p); - //@} - - /** - Transforms each point of this path by the matrix. - */ - void Transform(const wxGraphicsMatrix& matrix); - - /** - Gives back the native path returned by GetNativePath() because there might be - some deallocations necessary (eg on cairo the native path returned by - GetNativePath is newly allocated each time). - */ - void UnGetNativePath(void* p) const; -}; - - - -/** - @class wxGraphicsObject - @wxheader{graphics.h} - - This class is the superclass of native graphics objects like pens etc. It - allows reference counting. Not instantiated by user code. - - @library{wxcore} - @category{FIXME} - - @see wxGraphicsBrush, wxGraphicsPen, wxGraphicsMatrix, wxGraphicsPath -*/ -class wxGraphicsObject : public wxObject -{ -public: - /** - Returns the renderer that was used to create this instance, or @NULL if it has - not been initialized yet - */ - wxGraphicsRenderer* GetRenderer() const; - - /** - Is this object valid (@false) or still empty (@true)? - */ - bool IsNull() const; -}; - - - -/** - @class wxGraphicsContext - @wxheader{graphics.h} - - A wxGraphicsContext instance is the object that is drawn upon. It is created by - a renderer using wxGraphicsRenderer::CreateContext(). This can be either directly - using a renderer instance, or indirectly using the static convenience Create() - functions of wxGraphicsContext that always delegate the task to the default renderer. - - @code - void MyCanvas::OnPaint(wxPaintEvent &event) - { - // Create paint DC - wxPaintDC dc(this); - - // Create graphics context from it - wxGraphicsContext *gc = wxGraphicsContext::Create( dc ); - - if (gc) - { - // make a path that contains a circle and some lines - gc->SetPen( *wxRED_PEN ); - wxGraphicsPath path = gc->CreatePath(); - path.AddCircle( 50.0, 50.0, 50.0 ); - path.MoveToPoint(0.0, 50.0); - path.AddLineToPoint(100.0, 50.0); - path.MoveToPoint(50.0, 0.0); - path.AddLineToPoint(50.0, 100.0 ); - path.CloseSubpath(); - path.AddRectangle(25.0, 25.0, 50.0, 50.0); - - gc->StrokePath(path); - - delete gc; - } - } - @endcode - - - @library{wxcore} - @category{FIXME} - - @see wxGraphicsRenderer::CreateContext(), wxGCDC, wxDC -*/ -class wxGraphicsContext : public wxGraphicsObject -{ -public: - /** - Creates a wxGraphicsContext from a wxWindow. - - @see wxGraphicsRenderer::CreateContext() - */ - static wxGraphicsContext* Create( wxWindow* window ) ; - - /** - Creates a wxGraphicsContext from a wxWindowDC - - @see wxGraphicsRenderer::CreateContext() - */ - static wxGraphicsContext* Create( const wxWindowDC& dc) ; - - /** - Creates a wxGraphicsContext from a wxMemoryDC - - @see wxGraphicsRenderer::CreateContext() - */ - static wxGraphicsContext * Create( const wxMemoryDC& dc) ; - - /** - Creates a wxGraphicsContext from a wxPrinterDC. Under - GTK+, this will only work when using the GtkPrint - printing backend which is available since GTK+ 2.10. - - @see wxGraphicsRenderer::CreateContext(), @ref overview_unixprinting "Printing under Unix" - */ - static wxGraphicsContext * Create( const wxPrinterDC& dc) ; - - /** - Clips drawings to the region - */ - void Clip(const wxRegion& region); - - /** - Clips drawings to the rectangle. - */ - void Clip(wxDouble x, wxDouble y, wxDouble w, wxDouble h); - - /** - Concatenates the passed in transform with the current transform of this context - */ - void ConcatTransform(const wxGraphicsMatrix& matrix); - - - /** - Creates a native brush from a wxBrush. - */ - wxGraphicsBrush CreateBrush(const wxBrush& brush) const; - - /** - Creates a native graphics font from a wxFont and a text colour. - */ - wxGraphicsFont CreateFont(const wxFont& font, - const wxColour& col = wxBLACK) const; - - /** - Creates a wxGraphicsContext from a native context. This native context must be - eg a CGContextRef for Core Graphics, a Graphics pointer for GDIPlus or a - cairo_t pointer for cairo. - - @see wxGraphicsRenderer:: CreateContextFromNativeContext - */ - wxGraphicsContext* CreateFromNative(void* context); - - /** - Creates a wxGraphicsContext from a native window. - - @see wxGraphicsRenderer:: CreateContextFromNativeWindow - */ - wxGraphicsContext* CreateFromNativeWindow(void* window); - - /** - Creates a native brush, having a linear gradient, starting at (x1,y1) with - color c1 to (x2,y2) with color c2 - */ - wxGraphicsBrush CreateLinearGradientBrush(wxDouble x1, - wxDouble y1, - wxDouble x2, - wxDouble y2, - const wxColouramp;c1, - const wxColouramp;c2) const; - - /** - Creates a native affine transformation matrix from the passed in values. The - defaults result in an identity matrix. - */ - wxGraphicsMatrix CreateMatrix(wxDouble a = 1.0, wxDouble b = 0.0, - wxDouble c = 0.0, - wxDouble d = 1.0, - wxDouble tx = 0.0, - wxDouble ty = 0.0) const; - - /** - Creates a native graphics path which is initially empty. - */ - wxGraphicsPath CreatePath() const; - - /** - Creates a native pen from a wxPen. - */ - wxGraphicsPen CreatePen(const wxPen& pen) const; - - /** - Creates a native brush, having a radial gradient originating at (xo,yc) with - color oColour and ends on a circle around (xc,yc) with radius r and color cColour - */ - wxGraphicsBrush CreateRadialGradientBrush(wxDouble xo, - wxDouble yo, - wxDouble xc, - wxDouble yc, - wxDouble radius, - const wxColour& oColor, - const wxColour& cColor) const; - - /** - Draws the bitmap. In case of a mono bitmap, this is treated as a mask and the - current brushed is used for filling. - */ - void DrawBitmap(const wxBitmap& bmp, wxDouble x, wxDouble y, - wxDouble w, wxDouble h); - - /** - Draws an ellipse. - */ - void DrawEllipse(wxDouble x, wxDouble y, wxDouble w, wxDouble h); - - /** - Draws the icon. - */ - void DrawIcon(const wxIcon& icon, wxDouble x, wxDouble y, - wxDouble w, wxDouble h); - - /** - Draws a polygon. - */ - void DrawLines(size_t n, const wxPoint2DDouble* points, - int fillStyle = wxODDEVEN_RULE); - - /** - Draws the path by first filling and then stroking. - */ - void DrawPath(const wxGraphicsPath& path, - int fillStyle = wxODDEVEN_RULE); - - /** - Draws a rectangle. - */ - void DrawRectangle(wxDouble x, wxDouble y, wxDouble w, - wxDouble h); - - /** - Draws a rounded rectangle. - */ - void DrawRoundedRectangle(wxDouble x, wxDouble y, wxDouble w, - wxDouble h, - wxDouble radius); - - //@{ - /** - Draws a text at the defined position, at the given angle. - */ - void DrawText(const wxString& str, wxDouble x, wxDouble y, - wxDouble angle); - void DrawText(const wxString& str, wxDouble x, wxDouble y); - //@} - - /** - Fills the path with the current brush. - */ - void FillPath(const wxGraphicsPath& path, - int fillStyle = wxODDEVEN_RULE); - - /** - Returns the native context (CGContextRef for Core Graphics, Graphics pointer - for GDIPlus and cairo_t pointer for cairo). - */ - void* GetNativeContext(); - - /** - Fills the @a widths array with the widths from the beginning of - @a text to the corresponding character of @e text. - */ - void GetPartialTextExtents(const wxString& text, - wxArrayDouble& widths) const; - - /** - Gets the dimensions of the string using the currently selected font. - @e string is the text string to measure, @e w and @e h are - the total width and height respectively, @a descent is the - dimension from the baseline of the font to the bottom of the - descender, and @a externalLeading is any extra vertical space added - to the font by the font designer (usually is zero). - */ - void GetTextExtent(const wxString& text, wxDouble* width, - wxDouble* height, - wxDouble* descent, - wxDouble* externalLeading) const; - - /** - Gets the current transformation matrix of this context. - */ - wxGraphicsMatrix GetTransform() const; - - /** - Resets the clipping to original shape. - */ - void ResetClip(); - - /** - Rotates the current transformation matrix (radians), - */ - void Rotate(wxDouble angle); - - /** - Scales the current transformation matrix. - */ - void Scale(wxDouble xScale, wxDouble yScale); - - //@{ - /** - Sets the brush for filling paths. - */ - void SetBrush(const wxBrush& brush); - void SetBrush(const wxGraphicsBrush& brush); - //@} - - //@{ - /** - Sets the font for drawing text. - */ - void SetFont(const wxFont& font, const wxColour& colour); - void SetFont(const wxGraphicsFont& font); - //@} - - //@{ - /** - Sets the pen used for stroking. - */ - void SetPen(const wxGraphicsPen& pen); - void SetPen(const wxPen& pen); - //@} - - /** - Sets the current transformation matrix of this context - */ - void SetTransform(const wxGraphicsMatrix& matrix); - - /** - Strokes a single line. - */ - void StrokeLine(wxDouble x1, wxDouble y1, wxDouble x2, - wxDouble y2); - - //@{ - /** - Stroke disconnected lines from begin to end points, fastest method available - for this purpose. - */ - void StrokeLines(size_t n, const wxPoint2DDouble* beginPoints, - const wxPoint2DDouble* endPoints); - void StrokeLines(size_t n, const wxPoint2DDouble* points); - //@} - - /** - Strokes along a path with the current pen. - */ - void StrokePath(const wxGraphicsPath& path); - - /** - Translates the current transformation matrix. - */ - void Translate(wxDouble dx, wxDouble dy); -}; - - - -/** - @class wxGraphicsRenderer - @wxheader{graphics.h} - - A wxGraphicsRenderer is the instance corresponding to the rendering engine - used. There may be multiple instances on a system, if there are different - rendering engines present, but there is always only one instance per engine. - This instance is pointed back to by all objects created by it (wxGraphicsContext, - wxGraphicsPath etc) and can be retrieved through their wxGraphicsObject::GetRenderer() - method. Therefore you can create an additional instance of a path etc. by calling - wxGraphicsObject::GetRenderer() and then using the appropriate CreateXXX function - of that renderer. - - @code - wxGraphicsPath *path = // from somewhere - wxGraphicsBrush *brush = path->GetRenderer()->CreateBrush( *wxBLACK_BRUSH ); - @endcode - - @library{wxcore} - @category{FIXME} -*/ -class wxGraphicsRenderer : public wxObject -{ -public: - /** - Creates a wxGraphicsContext from a wxWindow. - */ - virtual wxGraphicsContext* CreateContext(wxWindow* window) = 0; - - /** - Creates a wxGraphicsContext from a wxWindowDC - */ - virtual wxGraphicsContext * CreateContext( const wxWindowDC& dc) = 0 ; - - /** - Creates a wxGraphicsContext from a wxMemoryDC - */ - virtual wxGraphicsContext * CreateContext( const wxMemoryDC& dc) = 0 ; - - /** - Creates a wxGraphicsContext from a wxPrinterDC - */ - virtual wxGraphicsContext * CreateContext( const wxPrinterDC& dc) = 0 ; - - /** - Creates a native brush from a wxBrush. - */ - wxGraphicsBrush CreateBrush(const wxBrush& brush); - - - /** - Creates a wxGraphicsContext from a native context. This native context must be - eg a CGContextRef for Core Graphics, a Graphics pointer for GDIPlus or a cairo_t - pointer for cairo. - */ - wxGraphicsContext* CreateContextFromNativeContext(void* context); - - /** - Creates a wxGraphicsContext from a native window. - */ - wxGraphicsContext* CreateContextFromNativeWindow(void* window); - - /** - Creates a native graphics font from a wxFont and a text colour. - */ - wxGraphicsFont CreateFont(const wxFont& font, - const wxColour& col = wxBLACK); - - /** - Creates a native brush, having a linear gradient, starting at (x1,y1) with - color c1 to (x2,y2) with color c2 - */ - wxGraphicsBrush CreateLinearGradientBrush(wxDouble x1, - wxDouble y1, - wxDouble x2, - wxDouble y2, - const wxColouramp;c1, - const wxColouramp;c2); - - /** - Creates a native affine transformation matrix from the passed in values. The - defaults result in an identity matrix. - */ - wxGraphicsMatrix CreateMatrix(wxDouble a = 1.0, wxDouble b = 0.0, - wxDouble c = 0.0, - wxDouble d = 1.0, - wxDouble tx = 0.0, - wxDouble ty = 0.0); - - /** - Creates a native graphics path which is initially empty. - */ - wxGraphicsPath CreatePath(); - - /** - Creates a native pen from a wxPen. - */ - wxGraphicsPen CreatePen(const wxPen& pen); - - /** - Creates a native brush, having a radial gradient originating at (xo,yc) with - color oColour and ends on a circle around (xc,yc) with radius r and color cColour - */ - wxGraphicsBrush CreateRadialGradientBrush(wxDouble xo, - wxDouble yo, - wxDouble xc, - wxDouble yc, - wxDouble radius, - const wxColour& oColour, - const wxColour& cColour); - - /** - Returns the default renderer on this platform. On OS X this is the Core - Graphics (a.k.a. Quartz 2D) renderer, on MSW the GDIPlus renderer, and on GTK we currently default to the cairo renderer. - */ - static wxGraphicsRenderer* GetDefaultRenderer(); -}; - - - -/** - @class wxGraphicsBrush - @wxheader{graphics.h} - - - @library{wxcore} - @category{FIXME} -*/ -class wxGraphicsBrush : public wxGraphicsObject -{ -public: - -}; - - - -/** - @class wxGraphicsFont - @wxheader{graphics.h} - - - @library{wxcore} - @category{FIXME} -*/ -class wxGraphicsFont : public wxGraphicsObject -{ -public: - -}; - - - -/** - @class wxGraphicsPen - @wxheader{graphics.h} - - - @library{wxcore} - @category{FIXME} -*/ -class wxGraphicsPen : public wxGraphicsObject -{ -public: - -}; - - - -/** - @class wxGraphicsMatrix - @wxheader{graphics.h} - - A wxGraphicsMatrix is a native representation of an affine matrix. The contents - are specific and private to the respective renderer. Instances are ref counted and can therefore be assigned as usual. The only way to get a valid instance is via a CreateMatrix call on the graphics context or the renderer instance. - - @library{wxcore} - @category{FIXME} -*/ -class wxGraphicsMatrix : public wxGraphicsObject -{ -public: - //@{ - /** - - */ - void Concat(const wxGraphicsMatrix* t); - void Concat(const wxGraphicsMatrix& t); - //@} - - /** - Returns the component values of the matrix via the argument pointers. - */ - void Get(wxDouble* a = NULL, wxDouble* b = NULL, wxDouble* c = NULL, - wxDouble* d = NULL, wxDouble* tx = NULL, - wxDouble* ty = NULL) const; - - /** - Returns the native representation of the matrix. For CoreGraphics this is a - CFAffineMatrix pointer. For GDIPlus a Matrix Pointer and for Cairo a cairo_matrix_t pointer. - */ - void* GetNativeMatrix() const; - - /** - Inverts the matrix. - */ - void Invert(); - - /** - Returns @true if the elements of the transformation matrix are equal. - */ - bool IsEqual(const wxGraphicsMatrix& t) const; - - /** - Return @true if this is the identity matrix. - */ - bool IsIdentity() const; - - /** - Rotates this matrix (radians). - */ - void Rotate(wxDouble angle); - - /** - Scales this matrix. - */ - void Scale(wxDouble xScale, wxDouble yScale); - - /** - Sets the matrix to the respective values (default values are the identity - matrix) - */ - void Set(wxDouble a = 1.0, wxDouble b = 0.0, wxDouble c = 0.0, - wxDouble d = 1.0, wxDouble tx = 0.0, - wxDouble ty = 0.0); - - /** - Applies this matrix to a distance (ie. performs all transforms except - translations) - */ - void TransformDistance(wxDouble* dx, wxDouble* dy) const; - - /** - Applies this matrix to a point. - */ - void TransformPoint(wxDouble* x, wxDouble* y) const; - - /** - Translates this matrix. - */ - void Translate(wxDouble dx, wxDouble dy); -}; - diff --git a/interface/grid.h b/interface/grid.h deleted file mode 100644 index 9d1eeb0ebc..0000000000 --- a/interface/grid.h +++ /dev/null @@ -1,2812 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: grid.h -// Purpose: interface of wxGridCellFloatRenderer -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxGridCellFloatRenderer - @wxheader{grid.h} - - This class may be used to format floating point data in a cell. - - @library{wxadv} - @category{FIXME} - - @see wxGridCellRenderer, wxGridCellNumberRenderer, wxGridCellStringRenderer, - wxGridCellBoolRenderer -*/ -class wxGridCellFloatRenderer : public wxGridCellStringRenderer -{ -public: - /** - @param width - Minimum number of characters to be shown. - @param precision - Number of digits after the decimal dot. - */ - wxGridCellFloatRenderer(int width = -1, int precision = -1); - - /** - Returns the precision ( see @ref constr() wxGridCellFloatRenderer ). - */ - int GetPrecision() const; - - /** - Returns the width ( see @ref constr() wxGridCellFloatRenderer ). - */ - int GetWidth() const; - - /** - Parameters string format is "width[,precision]". - */ - void SetParameters(const wxString& params); - - /** - Sets the precision ( see @ref constr() wxGridCellFloatRenderer ). - */ - void SetPrecision(int precision); - - /** - Sets the width ( see @ref constr() wxGridCellFloatRenderer ) - */ - void SetWidth(int width); -}; - - - -/** - @class wxGridTableBase - @wxheader{grid.h} - - Grid table classes. - - @library{wxadv} - @category{FIXME} -*/ -class wxGridTableBase : public wxObject -{ -public: - /** - - */ - wxGridTableBase(); - - /** - - */ - ~wxGridTableBase(); - - /** - - */ - bool AppendCols(size_t numCols = 1); - - /** - - */ - bool AppendRows(size_t numRows = 1); - - /** - - */ - bool CanGetValueAs(int row, int col, const wxString& typeName); - - /** - Does this table allow attributes? Default implementation creates - a wxGridCellAttrProvider if necessary. - */ - bool CanHaveAttributes(); - - /** - - */ - bool CanSetValueAs(int row, int col, const wxString& typeName); - - /** - - */ - void Clear(); - - /** - - */ - bool DeleteCols(size_t pos = 0, size_t numCols = 1); - - /** - - */ - bool DeleteRows(size_t pos = 0, size_t numRows = 1); - - /** - by default forwarded to wxGridCellAttrProvider if any. May be - overridden to handle attributes directly in the table. - */ - wxGridCellAttr* GetAttr(int row, int col); - - /** - get the currently used attr provider (may be @NULL) - */ - wxGridCellAttrProvider* GetAttrProvider() const; - - /** - - */ - wxString GetColLabelValue(int col); - - /** - - */ - int GetNumberCols(); - - /** - You must override these functions in a derived table class. - */ - int GetNumberRows(); - - /** - - */ - wxString GetRowLabelValue(int row); - - /** - Data type determination and value access. - */ - wxString GetTypeName(int row, int col); - - /** - - */ - wxString GetValue(int row, int col); - - /** - - */ - bool GetValueAsBool(int row, int col); - - /** - For user defined types - */ - void* GetValueAsCustom(int row, int col, - const wxString& typeName); - - /** - - */ - double GetValueAsDouble(int row, int col); - - /** - - */ - long GetValueAsLong(int row, int col); - - /** - - */ - wxGrid* GetView() const; - - /** - - */ - bool InsertCols(size_t pos = 0, size_t numCols = 1); - - /** - - */ - bool InsertRows(size_t pos = 0, size_t numRows = 1); - - /** - - */ - bool IsEmptyCell(int row, int col); - - /** - these functions take ownership of the pointer - */ - void SetAttr(wxGridCellAttr* attr, int row, int col); - - /** - Attribute handling - give us the attr provider to use - we take ownership of the pointer - */ - void SetAttrProvider(wxGridCellAttrProvider* attrProvider); - - /** - - */ - void SetColAttr(wxGridCellAttr* attr, int col); - - /** - , @e wxString) - */ - void SetColLabelValue() const; - - /** - - */ - void SetRowAttr(wxGridCellAttr* attr, int row); - - /** - , @e wxString) - */ - void SetRowLabelValue() const; - - /** - - */ - void SetValue(int row, int col, const wxString& value); - - /** - - */ - void SetValueAsBool(int row, int col, bool value); - - /** - - */ - void SetValueAsCustom(int row, int col, const wxString& typeName, - void* value); - - /** - - */ - void SetValueAsDouble(int row, int col, double value); - - /** - - */ - void SetValueAsLong(int row, int col, long value); - - /** - Overriding these is optional - */ - void SetView(wxGrid* grid); - - /** - - */ - void UpdateAttrCols(size_t pos, int numCols); - - /** - change row/col number in attribute if needed - */ - void UpdateAttrRows(size_t pos, int numRows); -}; - - - -/** - @class wxGridCellEditor - @wxheader{grid.h} - - This class is responsible for providing and manipulating - the in-place edit controls for the grid. Instances of wxGridCellEditor - (actually, instances of derived classes since it is an abstract class) can be - associated with the cell attributes for individual cells, rows, columns, or - even for the entire grid. - - @library{wxadv} - @category{FIXME} - - @see wxGridCellTextEditor, wxGridCellFloatEditor, wxGridCellBoolEditor, - wxGridCellNumberEditor, wxGridCellChoiceEditor -*/ -class wxGridCellEditor -{ -public: - /** - - */ - wxGridCellEditor(); - - /** - The dtor is private because only DecRef() can delete us. - */ - ~wxGridCellEditor(); - - /** - Fetch the value from the table and prepare the edit control - to begin editing. Set the focus to the edit control. - */ - void BeginEdit(int row, int col, wxGrid* grid); - - /** - Create a new object which is the copy of this one. - */ - wxGridCellEditor* Clone() const; - - /** - Creates the actual edit control. - */ - void Create(wxWindow* parent, wxWindowID id, - wxEvtHandler* evtHandler); - - /** - Final cleanup. - */ - void Destroy(); - - /** - Complete the editing of the current cell. Returns @true if the value has - changed. If necessary, the control may be destroyed. - */ - bool EndEdit(int row, int col, wxGrid* grid); - - /** - Some types of controls on some platforms may need some help - with the Return key. - */ - void HandleReturn(wxKeyEvent& event); - - /** - - */ - bool IsCreated(); - - /** - Draws the part of the cell not occupied by the control: the base class - version just fills it with background colour from the attribute. - */ - void PaintBackground(const wxRect& rectCell, - wxGridCellAttr* attr); - - /** - Reset the value in the control back to its starting value. - */ - void Reset(); - - /** - Size and position the edit control. - */ - void SetSize(const wxRect& rect); - - /** - Show or hide the edit control, use the specified attributes to set - colours/fonts for it. - */ - void Show(bool show, wxGridCellAttr* attr = NULL); - - /** - If the editor is enabled by clicking on the cell, this method will be - called. - */ - void StartingClick(); - - /** - If the editor is enabled by pressing keys on the grid, - this will be called to let the editor do something about - that first key if desired. - */ - void StartingKey(wxKeyEvent& event); -}; - - - -/** - @class wxGridCellTextEditor - @wxheader{grid.h} - - The editor for string/text data. - - @library{wxadv} - @category{FIXME} - - @see wxGridCellEditor, wxGridCellFloatEditor, wxGridCellBoolEditor, - wxGridCellNumberEditor, wxGridCellChoiceEditor -*/ -class wxGridCellTextEditor : public wxGridCellEditor -{ -public: - /** - Default constructor. - */ - wxGridCellTextEditor(); - - /** - The parameters string format is "n" where n is a number representing the - maximum width. - */ - void SetParameters(const wxString& params); -}; - - - -/** - @class wxGridCellStringRenderer - @wxheader{grid.h} - - This class may be used to format string data in a cell; it is the default - for string cells. - - @library{wxadv} - @category{FIXME} - - @see wxGridCellRenderer, wxGridCellNumberRenderer, wxGridCellFloatRenderer, - wxGridCellBoolRenderer -*/ -class wxGridCellStringRenderer : public wxGridCellRenderer -{ -public: - /** - Default constructor - */ - wxGridCellStringRenderer(); -}; - - - -/** - @class wxGridCellChoiceEditor - @wxheader{grid.h} - - The editor for string data allowing to choose from a list of strings. - - @library{wxadv} - @category{FIXME} - - @see wxGridCellEditor, wxGridCellFloatEditor, wxGridCellBoolEditor, - wxGridCellTextEditor, wxGridCellNumberEditor -*/ -class wxGridCellChoiceEditor : public wxGridCellEditor -{ -public: - //@{ - /** - @param count - Number of strings from which the user can choose. - @param choices - An array of strings from which the user can choose. - @param allowOthers - If allowOthers is @true, the user can type a string not in choices array. - */ - wxGridCellChoiceEditor(size_t count = 0, - const wxString choices[] = NULL, - bool allowOthers = false); - wxGridCellChoiceEditor(const wxArrayString& choices, - bool allowOthers = false); - //@} - - /** - Parameters string format is "item1[,item2[...,itemN]]" - */ - void SetParameters(const wxString& params); -}; - - - -/** - @class wxGridEditorCreatedEvent - @wxheader{grid.h} - - - @library{wxadv} - @category{FIXME} -*/ -class wxGridEditorCreatedEvent : public wxCommandEvent -{ -public: - //@{ - /** - - */ - wxGridEditorCreatedEvent(); - wxGridEditorCreatedEvent(int id, wxEventType type, - wxObject* obj, - int row, - int col, - wxControl* ctrl); - //@} - - /** - Returns the column at which the event occurred. - */ - int GetCol(); - - /** - Returns the edit control. - */ - wxControl* GetControl(); - - /** - Returns the row at which the event occurred. - */ - int GetRow(); - - /** - Sets the column at which the event occurred. - */ - void SetCol(int col); - - /** - Sets the edit control. - */ - void SetControl(wxControl* ctrl); - - /** - Sets the row at which the event occurred. - */ - void SetRow(int row); -}; - - - -/** - @class wxGridRangeSelectEvent - @wxheader{grid.h} - - - @library{wxadv} - @category{FIXME} -*/ -class wxGridRangeSelectEvent : public wxNotifyEvent -{ -public: - //@{ - /** - - */ - wxGridRangeSelectEvent(); - wxGridRangeSelectEvent(int id, wxEventType type, - wxObject* obj, - const wxGridCellCoords& topLeft, - const wxGridCellCoords& bottomRight, - bool sel = true, - bool control = false, - bool shift = false, - bool alt = false, - bool meta = false); - //@} - - /** - Returns @true if the Alt key was down at the time of the event. - */ - bool AltDown(); - - /** - Returns @true if the Control key was down at the time of the event. - */ - bool ControlDown(); - - /** - Top left corner of the rectangular area that was (de)selected. - */ - wxGridCellCoords GetBottomRightCoords(); - - /** - Bottom row of the rectangular area that was (de)selected. - */ - int GetBottomRow(); - - /** - Left column of the rectangular area that was (de)selected. - */ - int GetLeftCol(); - - /** - Right column of the rectangular area that was (de)selected. - */ - int GetRightCol(); - - /** - Top left corner of the rectangular area that was (de)selected. - */ - wxGridCellCoords GetTopLeftCoords(); - - /** - Top row of the rectangular area that was (de)selected. - */ - int GetTopRow(); - - /** - Returns @true if the Meta key was down at the time of the event. - */ - bool MetaDown(); - - /** - Returns @true if the area was selected, @false otherwise. - */ - bool Selecting(); - - /** - Returns @true if the Shift key was down at the time of the event. - */ - bool ShiftDown(); -}; - - - -/** - @class wxGridCellRenderer - @wxheader{grid.h} - - This class is responsible for actually drawing the cell - in the grid. You may pass it to the wxGridCellAttr (below) to change the - format of one given cell or to wxGrid::SetDefaultRenderer() to change the - view of all cells. This is an abstract class, and you will normally use one of - the - predefined derived classes or derive your own class from it. - - @library{wxadv} - @category{FIXME} - - @see wxGridCellStringRenderer, wxGridCellNumberRenderer, - wxGridCellFloatRenderer, wxGridCellBoolRenderer -*/ -class wxGridCellRenderer -{ -public: - /** - - */ - wxGridCellRenderer* Clone() const; - - /** - Draw the given cell on the provided DC inside the given rectangle - using the style specified by the attribute and the default or selected - state corresponding to the isSelected value. - This pure virtual function has a default implementation which will - prepare the DC using the given attribute: it will draw the rectangle - with the background colour from attr and set the text colour and font. - */ - void Draw(wxGrid& grid, wxGridCellAttr& attr, wxDC& dc, - const wxRect& rect, int row, int col, - bool isSelected); - - /** - Get the preferred size of the cell for its contents. - */ - wxSize GetBestSize(wxGrid& grid, wxGridCellAttr& attr, wxDC& dc, - int row, int col); -}; - - - -/** - @class wxGridCellNumberEditor - @wxheader{grid.h} - - The editor for numeric integer data. - - @library{wxadv} - @category{FIXME} - - @see wxGridCellEditor, wxGridCellFloatEditor, wxGridCellBoolEditor, - wxGridCellTextEditor, wxGridCellChoiceEditor -*/ -class wxGridCellNumberEditor : public wxGridCellTextEditor -{ -public: - /** - Allows to specify the range for acceptable data; - if min == max == -1, no range checking is done - */ - wxGridCellNumberEditor(int min = -1, int max = -1); - - /** - String representation of the value. - */ - wxString GetString() const; - - /** - If the return value is @true, the editor uses a wxSpinCtrl to get user input, - otherwise it uses a wxTextCtrl. - */ - bool HasRange() const; - - /** - Parameters string format is "min,max". - */ - void SetParameters(const wxString& params); -}; - - - -/** - @class wxGridSizeEvent - @wxheader{grid.h} - - This event class contains information about a row/column resize event. - - @library{wxadv} - @category{FIXME} -*/ -class wxGridSizeEvent : public wxNotifyEvent -{ -public: - //@{ - /** - - */ - wxGridSizeEvent(); - wxGridSizeEvent(int id, wxEventType type, wxObject* obj, - int rowOrCol = -1, - int x = -1, - int y = -1, - bool control = false, - bool shift = false, - bool alt = false, - bool meta = false); - //@} - - /** - Returns @true if the Alt key was down at the time of the event. - */ - bool AltDown(); - - /** - Returns @true if the Control key was down at the time of the event. - */ - bool ControlDown(); - - /** - Position in pixels at which the event occurred. - */ - wxPoint GetPosition(); - - /** - Row or column at that was resized. - */ - int GetRowOrCol(); - - /** - Returns @true if the Meta key was down at the time of the event. - */ - bool MetaDown(); - - /** - Returns @true if the Shift key was down at the time of the event. - */ - bool ShiftDown(); -}; - - - -/** - @class wxGridCellNumberRenderer - @wxheader{grid.h} - - This class may be used to format integer data in a cell. - - @library{wxadv} - @category{FIXME} - - @see wxGridCellRenderer, wxGridCellStringRenderer, wxGridCellFloatRenderer, - wxGridCellBoolRenderer -*/ -class wxGridCellNumberRenderer : public wxGridCellStringRenderer -{ -public: - /** - Default constructor - */ - wxGridCellNumberRenderer(); -}; - - - -/** - @class wxGridCellAttr - @wxheader{grid.h} - - This class can be used to alter the cells' appearance in - the grid by changing their colour/font/... from default. An object of this - class may be returned by wxGridTableBase::GetAttr. - - @library{wxadv} - @category{FIXME} -*/ -class wxGridCellAttr -{ -public: - //@{ - /** - Constructor specifying some of the often used attributes. - */ - wxGridCellAttr(); - wxGridCellAttr(const wxColour& colText, - const wxColour& colBack, - const wxFont& font, - int hAlign, int vAlign); - //@} - - /** - Creates a new copy of this object. - */ - wxGridCellAttr* Clone() const; - - /** - - */ - void DecRef(); - - /** - See SetAlignment() for the returned values. - */ - void GetAlignment(int* hAlign, int* vAlign) const; - - /** - - */ - const wxColour GetBackgroundColour() const; - - /** - - */ - wxGridCellEditor* GetEditor(wxGrid* grid, int row, int col) const; - - /** - - */ - const wxFont GetFont() const; - - /** - - */ - wxGridCellRenderer* GetRenderer(wxGrid* grid, int row, int col) const; - - /** - - */ - const wxColour GetTextColour() const; - - /** - - */ - bool HasAlignment() const; - - /** - - */ - bool HasBackgroundColour() const; - - /** - - */ - bool HasEditor() const; - - /** - - */ - bool HasFont() const; - - /** - - */ - bool HasRenderer() const; - - /** - accessors - */ - bool HasTextColour() const; - - /** - This class is ref counted: it is created with ref count of 1, so - calling DecRef() once will delete it. Calling IncRef() allows to lock - it until the matching DecRef() is called - */ - void IncRef(); - - /** - - */ - bool IsReadOnly() const; - - /** - Sets the alignment. @a hAlign can be one of @c wxALIGN_LEFT, - @c wxALIGN_CENTRE or @c wxALIGN_RIGHT and @a vAlign can be one - of @c wxALIGN_TOP, @c wxALIGN_CENTRE or @c wxALIGN_BOTTOM. - */ - void SetAlignment(int hAlign, int vAlign); - - /** - Sets the background colour. - */ - void SetBackgroundColour(const wxColour& colBack); - - /** - - */ - void SetDefAttr(wxGridCellAttr* defAttr); - - /** - - */ - void SetEditor(wxGridCellEditor* editor); - - /** - Sets the font. - */ - void SetFont(const wxFont& font); - - /** - - */ - void SetReadOnly(bool isReadOnly = true); - - /** - takes ownership of the pointer - */ - void SetRenderer(wxGridCellRenderer* renderer); - - /** - Sets the text colour. - */ - void SetTextColour(const wxColour& colText); -}; - - - -/** - @class wxGridCellBoolRenderer - @wxheader{grid.h} - - This class may be used to format boolean data in a cell. - for string cells. - - @library{wxadv} - @category{FIXME} - - @see wxGridCellRenderer, wxGridCellStringRenderer, wxGridCellFloatRenderer, - wxGridCellNumberRenderer -*/ -class wxGridCellBoolRenderer : public wxGridCellRenderer -{ -public: - /** - Default constructor - */ - wxGridCellBoolRenderer(); -}; - - - -/** - @class wxGridEvent - @wxheader{grid.h} - - This event class contains information about various grid events. - - @library{wxadv} - @category{FIXME} -*/ -class wxGridEvent : public wxNotifyEvent -{ -public: - //@{ - /** - - */ - wxGridEvent(); - wxGridEvent(int id, wxEventType type, wxObject* obj, - int row = -1, int col = -1, - int x = -1, int y = -1, - bool sel = true, - bool control = false, - bool shift = false, - bool alt = false, - bool meta = false); - //@} - - /** - Returns @true if the Alt key was down at the time of the event. - */ - bool AltDown(); - - /** - Returns @true if the Control key was down at the time of the event. - */ - bool ControlDown(); - - /** - Column at which the event occurred. - */ - int GetCol(); - - /** - Position in pixels at which the event occurred. - */ - wxPoint GetPosition(); - - /** - Row at which the event occurred. - */ - int GetRow(); - - /** - Returns @true if the Meta key was down at the time of the event. - */ - bool MetaDown(); - - /** - Returns @true if the user is selecting grid cells, @false -- if - deselecting. - */ - bool Selecting(); - - /** - Returns @true if the Shift key was down at the time of the event. - */ - bool ShiftDown(); -}; - - - -/** - @class wxGridCellFloatEditor - @wxheader{grid.h} - - The editor for floating point numbers data. - - @library{wxadv} - @category{FIXME} - - @see wxGridCellEditor, wxGridCellNumberEditor, wxGridCellBoolEditor, - wxGridCellTextEditor, wxGridCellChoiceEditor -*/ -class wxGridCellFloatEditor : public wxGridCellTextEditor -{ -public: - /** - @param width - Minimum number of characters to be shown. - @param precision - Number of digits after the decimal dot. - */ - wxGridCellFloatEditor(int width = -1, int precision = -1); - - /** - Parameters string format is "width,precision" - */ - void SetParameters(const wxString& params); -}; - - - -/** - @class wxGrid - @wxheader{grid.h} - - wxGrid and its related classes are used for displaying and editing tabular - data. They provide a rich set of features for display, editing, and - interacting with a variety of data sources. For simple applications, and to - help you get started, wxGrid is the only class you need to refer to - directly. It will set up default instances of the other classes and manage - them for you. For more complex applications you can derive your own - classes for custom grid views, grid data tables, cell editors and - renderers. The @ref overview_gridoverview has - examples of simple and more complex applications, explains the - relationship between the various grid classes and has a summary of the - keyboard shortcuts and mouse functions provided by wxGrid. - - wxGrid has been greatly expanded and redesigned for wxWidgets 2.2 - onwards. The new grid classes are reasonably backward-compatible - but there are some exceptions. There are also easier ways of doing many things - compared to - the previous implementation. - - A wxGridTableBase class holds the actual - data to be displayed by a wxGrid class. One or more wxGrid classes - may act as a view for one table class. - The default table class is called wxGridStringTable and - holds an array of strings. An instance of such a class is created - by wxGrid::CreateGrid. - - wxGridCellRenderer is the abstract base - class for rendereing contents in a cell. The following renderers are - predefined: - wxGridCellStringRenderer, - wxGridCellBoolRenderer, - wxGridCellFloatRenderer, - wxGridCellNumberRenderer. The - look of a cell can be further defined using wxGridCellAttr. - An object of this type may be returned by wxGridTableBase::GetAttr. - - wxGridCellEditor is the abstract base - class for editing the value of a cell. The following editors are - predefined: - wxGridCellTextEditor - wxGridCellBoolEditor - wxGridCellChoiceEditor - wxGridCellNumberEditor. - - @library{wxadv} - @category{miscwnd} - - @see @ref overview_gridoverview "wxGrid overview" -*/ -class wxGrid : public wxScrolledWindow -{ -public: - //@{ - /** - Constructor to create a grid object. Call either CreateGrid() or - SetTable() directly after this to initialize the grid before using - it. - */ - wxGrid(); - wxGrid(wxWindow* parent, wxWindowID id, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = wxWANTS_CHARS, - const wxString& name = wxPanelNameStr); - //@} - - /** - Destructor. This will also destroy the associated grid table unless you passed - a table - object to the grid and specified that the grid should not take ownership of the - table (see wxGrid::SetTable). - */ - ~wxGrid(); - - /** - Appends one or more new columns to the right of the grid and returns @true if - successful. The updateLabels argument is not used at present. - If you are using a derived grid table class you will need to override - wxGridTableBase::AppendCols. See - InsertCols() for further information. - */ - bool AppendCols(int numCols = 1, bool updateLabels = true); - - /** - Appends one or more new rows to the bottom of the grid and returns @true if - successful. The updateLabels argument is not used at present. - If you are using a derived grid table class you will need to override - wxGridTableBase::AppendRows. See - InsertRows() for further information. - */ - bool AppendRows(int numRows = 1, bool updateLabels = true); - - /** - Automatically sets the height and width of all rows and columns to fit their - contents. - */ - void AutoSize(); - - /** - Automatically adjusts width of the column to fit its label. - */ - void AutoSizeColLabelSize(int col); - - /** - Automatically sizes the column to fit its contents. If setAsMin is @true the - calculated width will - also be set as the minimal width for the column. - */ - void AutoSizeColumn(int col, bool setAsMin = true); - - /** - Automatically sizes all columns to fit their contents. If setAsMin is @true the - calculated widths will - also be set as the minimal widths for the columns. - */ - void AutoSizeColumns(bool setAsMin = true); - - /** - Automatically sizes the row to fit its contents. If setAsMin is @true the - calculated height will - also be set as the minimal height for the row. - */ - void AutoSizeRow(int row, bool setAsMin = true); - - /** - Automatically adjusts height of the row to fit its label. - */ - void AutoSizeRowLabelSize(int col); - - /** - Automatically sizes all rows to fit their contents. If setAsMin is @true the - calculated heights will - also be set as the minimal heights for the rows. - */ - void AutoSizeRows(bool setAsMin = true); - - /** - AutoSizeColumn() - - AutoSizeRow() - - AutoSizeColumns() - - AutoSizeRows() - - AutoSize() - - SetColMinimalWidth() - - SetRowMinimalHeight() - - SetColMinimalAcceptableWidth() - - SetRowMinimalAcceptableHeight() - - GetColMinimalAcceptableWidth() - - GetRowMinimalAcceptableHeight() - */ - - - /** - Increments the grid's batch count. When the count is greater than zero - repainting of - the grid is suppressed. Each call to BeginBatch must be matched by a later call - to - EndBatch(). Code that does a lot of grid - modification can be enclosed between BeginBatch and EndBatch calls to avoid - screen flicker. The final EndBatch will cause the grid to be repainted. - - @see wxGridUpdateLocker - */ - void BeginBatch(); - - /** - This function returns the rectangle that encloses the block of cells - limited by TopLeft and BottomRight cell in device coords and clipped - to the client size of the grid window. - */ - wxRect BlockToDeviceRect(const wxGridCellCoords& topLeft, - const wxGridCellCoords& bottomRight) const; - - /** - Returns @true if columns can be moved by dragging with the mouse. Columns can be - moved - by dragging on their labels. - */ - bool CanDragColMove() const; - - /** - Returns @true if columns can be resized by dragging with the mouse. Columns can - be resized - by dragging the edges of their labels. If grid line dragging is enabled they - can also be - resized by dragging the right edge of the column in the grid cell area - (see wxGrid::EnableDragGridSize). - */ - bool CanDragColSize() const; - - /** - Return @true if the dragging of grid lines to resize rows and columns is enabled - or @false otherwise. - */ - bool CanDragGridSize() const; - - /** - Returns @true if rows can be resized by dragging with the mouse. Rows can be - resized - by dragging the edges of their labels. If grid line dragging is enabled they - can also be - resized by dragging the lower edge of the row in the grid cell area - (see wxGrid::EnableDragGridSize). - */ - bool CanDragRowSize() const; - - /** - Returns @true if the in-place edit control for the current grid cell can be used - and - @false otherwise (e.g. if the current cell is read-only). - */ - bool CanEnableCellControl() const; - - /** - Do we have some place to store attributes in? - */ - bool CanHaveAttributes() const; - - /** - EnableDragRowSize() - - EnableDragColSize() - - CanDragRowSize() - - CanDragColSize() - - EnableDragColMove() - - CanDragColMove() - - EnableDragGridSize() - - CanDragGridSize() - - GetColAt() - - SetColPos() - - GetColPos() - - EnableDragCell() - - CanDragCell() - */ - - - //@{ - /** - Return the rectangle corresponding to the grid cell's size and position in - logical - coordinates. - */ - wxRect CellToRect(int row, int col) const; - const wxRect CellToRect(const wxGridCellCoords& coords) const; - //@} - - /** - Clears all data in the underlying grid table and repaints the grid. The table - is not deleted by - this function. If you are using a derived table class then you need to override - wxGridTableBase::Clear for this function to have any effect. - */ - void ClearGrid(); - - /** - Deselects all cells that are currently selected. - */ - void ClearSelection(); - - /** - @ref ctor() wxGrid - - @ref dtor() ~wxGrid - - CreateGrid() - - SetTable() - */ - - - /** - Creates a grid with the specified initial number of rows and columns. - Call this directly after the grid constructor. When you use this - function wxGrid will create and manage a simple table of string values - for you. All of the grid data will be stored in memory. - For applications with more complex data types or relationships, or for - dealing with very large datasets, you should derive your own grid table - class and pass a table object to the grid with SetTable(). - */ - bool CreateGrid(int numRows, int numCols, - wxGrid::wxGridSelectionModes selmode = wxGrid::wxGridSelectCells); - - /** - MoveCursorUp() - - MoveCursorDown() - - MoveCursorLeft() - - MoveCursorRight() - - MoveCursorPageUp() - - MoveCursorPageDown() - - MoveCursorUpBlock() - - MoveCursorDownBlock() - - MoveCursorLeftBlock() - - MoveCursorRightBlock() - */ - - - /** - Deletes one or more columns from a grid starting at the specified position and - returns - @true if successful. The updateLabels argument is not used at present. - If you are using a derived grid table class you will need to override - wxGridTableBase::DeleteCols. See - InsertCols() for further information. - */ - bool DeleteCols(int pos = 0, int numCols = 1, - bool updateLabels = true); - - /** - Deletes one or more rows from a grid starting at the specified position and - returns - @true if successful. The updateLabels argument is not used at present. - If you are using a derived grid table class you will need to override - wxGridTableBase::DeleteRows. See - InsertRows() for further information. - */ - bool DeleteRows(int pos = 0, int numRows = 1, - bool updateLabels = true); - - /** - Disables in-place editing of grid cells. - Equivalent to calling EnableCellEditControl(@false). - */ - void DisableCellEditControl(); - - /** - Disables column moving by dragging with the mouse. Equivalent to passing @false - to - EnableDragColMove(). - */ - void DisableDragColMove(); - - /** - Disables column sizing by dragging with the mouse. Equivalent to passing @false - to - EnableDragColSize(). - */ - void DisableDragColSize(); - - /** - Disable mouse dragging of grid lines to resize rows and columns. Equivalent to - passing - @false to EnableDragGridSize() - */ - void DisableDragGridSize(); - - /** - Disables row sizing by dragging with the mouse. Equivalent to passing @false to - EnableDragRowSize(). - */ - void DisableDragRowSize(); - - /** - Enables or disables in-place editing of grid cell data. The grid will issue - either a - wxEVT_GRID_EDITOR_SHOWN or wxEVT_GRID_EDITOR_HIDDEN event. - */ - void EnableCellEditControl(bool enable = true); - - /** - Enables or disables column moving by dragging with the mouse. - */ - void EnableDragColMove(bool enable = true); - - /** - Enables or disables column sizing by dragging with the mouse. - */ - void EnableDragColSize(bool enable = true); - - /** - Enables or disables row and column resizing by dragging gridlines with the - mouse. - */ - void EnableDragGridSize(bool enable = true); - - /** - Enables or disables row sizing by dragging with the mouse. - */ - void EnableDragRowSize(bool enable = true); - - /** - If the edit argument is @false this function sets the whole grid as read-only. - If the - argument is @true the grid is set to the default state where cells may be - editable. In the - default state you can set single grid cells and whole rows and columns to be - editable or - read-only via - wxGridCellAttribute::SetReadOnly. For single - cells you can also use the shortcut function - SetReadOnly(). - For more information about controlling grid cell attributes see the - wxGridCellAttr cell attribute class and the - @ref overview_gridoverview. - */ - void EnableEditing(bool edit); - - /** - Turns the drawing of grid lines on or off. - */ - void EnableGridLines(bool enable = true); - - /** - Decrements the grid's batch count. When the count is greater than zero - repainting of - the grid is suppressed. Each previous call to - BeginBatch() must be matched by a later call to - EndBatch. Code that does a lot of grid modification can be enclosed between - BeginBatch and EndBatch calls to avoid screen flicker. The final EndBatch will - cause the grid to be repainted. - - @see wxGridUpdateLocker - */ - void EndBatch(); - - /** - Overridden wxWindow method. - */ - void Fit(); - - /** - Causes immediate repainting of the grid. Use this instead of the usual - wxWindow::Refresh. - */ - void ForceRefresh(); - - /** - Returns the number of times that BeginBatch() has been called - without (yet) matching calls to EndBatch(). While - the grid's batch count is greater than zero the display will not be updated. - */ - int GetBatchCount() const; - - /** - Sets the arguments to the horizontal and vertical text alignment values for the - grid cell at the specified location. - Horizontal alignment will be one of wxALIGN_LEFT, wxALIGN_CENTRE or - wxALIGN_RIGHT. - - Vertical alignment will be one of wxALIGN_TOP, wxALIGN_CENTRE or wxALIGN_BOTTOM. - */ - void GetCellAlignment(int row, int col, int* horiz, int* vert) const; - - /** - Returns the background colour of the cell at the specified location. - */ - wxColour GetCellBackgroundColour(int row, int col) const; - - /** - Returns a pointer to the editor for the cell at the specified location. - See wxGridCellEditor and - the @ref overview_gridoverview "wxGrid overview" for more information about - cell editors and renderers. - */ - wxGridCellEditor* GetCellEditor(int row, int col) const; - - /** - Returns the font for text in the grid cell at the specified location. - */ - wxFont GetCellFont(int row, int col) const; - - /** - Returns a pointer to the renderer for the grid cell at the specified location. - See wxGridCellRenderer and - the @ref overview_gridoverview "wxGrid overview" for more information about - cell editors and renderers. - */ - wxGridCellRenderer* GetCellRenderer(int row, int col) const; - - /** - Returns the text colour for the grid cell at the specified location. - */ - wxColour GetCellTextColour(int row, int col) const; - - //@{ - /** - Returns the string contained in the cell at the specified location. For simple - applications where a - grid object automatically uses a default grid table of string values you use - this function together - with SetCellValue() to access cell values. - For more complex applications where you have derived your own grid table class - that contains - various data types (e.g. numeric, boolean or user-defined custom types) then - you only use this - function for those cells that contain string values. - See wxGridTableBase::CanGetValueAs - and the @ref overview_gridoverview "wxGrid overview" for more information. - */ - wxString GetCellValue(int row, int col) const; - const wxString GetCellValue(const wxGridCellCoords& coords) const; - //@} - - /** - Returns the column ID of the specified column position. - */ - int GetColAt(int colPos) const; - - /** - Returns the pen used for vertical grid lines. This virtual function may be - overridden in derived classes in order to change the appearance of individual - grid lines for the given column @e col. - See GetRowGridLinePen() for an example. - */ - wxPen GetColGridLinePen(int col); - - /** - Sets the arguments to the current column label alignment values. - Horizontal alignment will be one of wxALIGN_LEFT, wxALIGN_CENTRE or - wxALIGN_RIGHT. - - Vertical alignment will be one of wxALIGN_TOP, wxALIGN_CENTRE or wxALIGN_BOTTOM. - */ - void GetColLabelAlignment(int* horiz, int* vert) const; - - /** - Returns the current height of the column labels. - */ - int GetColLabelSize() const; - - /** - Returns the specified column label. The default grid table class provides - column labels of - the form A,B...Z,AA,AB...ZZ,AAA... If you are using a custom grid table you can - override - wxGridTableBase::GetColLabelValue to provide - your own labels. - */ - wxString GetColLabelValue(int col) const; - - /** - - */ - int GetColLeft(int col) const; - - /** - This returns the value of the lowest column width that can be handled - correctly. See - member SetColMinimalAcceptableWidth() for details. - */ - int GetColMinimalAcceptableWidth() const; - - /** - Get the minimal width of the given column/row. - */ - int GetColMinimalWidth(int col) const; - - /** - Returns the position of the specified column. - */ - int GetColPos(int colID) const; - - /** - - */ - int GetColRight(int col) const; - - /** - Returns the width of the specified column. - */ - int GetColSize(int col) const; - - /** - Sets the arguments to the current default horizontal and vertical text alignment - values. - Horizontal alignment will be one of wxALIGN_LEFT, wxALIGN_CENTRE or - wxALIGN_RIGHT. - - Vertical alignment will be one of wxALIGN_TOP, wxALIGN_CENTRE or wxALIGN_BOTTOM. - */ - void GetDefaultCellAlignment(int* horiz, int* vert) const; - - /** - Returns the current default background colour for grid cells. - */ - wxColour GetDefaultCellBackgroundColour() const; - - /** - Returns the current default font for grid cell text. - */ - wxFont GetDefaultCellFont() const; - - /** - Returns the current default colour for grid cell text. - */ - wxColour GetDefaultCellTextColour() const; - - /** - Returns the default height for column labels. - */ - int GetDefaultColLabelSize() const; - - /** - Returns the current default width for grid columns. - */ - int GetDefaultColSize() const; - - /** - Returns a pointer to the current default grid cell editor. - See wxGridCellEditor and - the @ref overview_gridoverview "wxGrid overview" for more information about - cell editors and renderers. - */ - wxGridCellEditor* GetDefaultEditor() const; - - //@{ - /** - - */ - wxGridCellEditor* GetDefaultEditorForCell(int row, int col) const; - const wxGridCellEditor* GetDefaultEditorForCell(const wxGridCellCoords& c) const; - //@} - - /** - - */ - wxGridCellEditor* GetDefaultEditorForType(const wxString& typeName) const; - - /** - Returns the pen used for grid lines. This virtual function may be overridden in - derived classes in order to change the appearance of grid lines. Note that - currently the pen width must be 1. - - @see GetColGridLinePen(), GetRowGridLinePen() - */ - wxPen GetDefaultGridLinePen(); - - /** - Returns a pointer to the current default grid cell renderer. - See wxGridCellRenderer and - the @ref overview_gridoverview "wxGrid overview" for more information about - cell editors and renderers. - */ - wxGridCellRenderer* GetDefaultRenderer() const; - - /** - - */ - wxGridCellRenderer* GetDefaultRendererForCell(int row, int col) const; - - /** - - */ - wxGridCellRenderer* GetDefaultRendererForType(const wxString& typeName) const; - - /** - Returns the default width for the row labels. - */ - int GetDefaultRowLabelSize() const; - - /** - Returns the current default height for grid rows. - */ - int GetDefaultRowSize() const; - - /** - Returns the current grid cell column position. - */ - int GetGridCursorCol() const; - - /** - Returns the current grid cell row position. - */ - int GetGridCursorRow() const; - - /** - Returns the colour used for grid lines. - - @see GetDefaultGridLinePen() - */ - wxColour GetGridLineColour() const; - - /** - Returns the colour used for the background of row and column labels. - */ - wxColour GetLabelBackgroundColour() const; - - /** - Returns the font used for row and column labels. - */ - wxFont GetLabelFont() const; - - /** - Returns the colour used for row and column label text. - */ - wxColour GetLabelTextColour() const; - - /** - Returns the total number of grid columns (actually the number of columns in the - underlying grid - table). - */ - int GetNumberCols() const; - - /** - Returns the total number of grid rows (actually the number of rows in the - underlying grid table). - */ - int GetNumberRows() const; - - /** - - */ - wxGridCellAttr* GetOrCreateCellAttr(int row, int col) const; - - /** - Returns the pen used for horizontal grid lines. This virtual function may be - overridden in derived classes in order to change the appearance of individual - grid line for the given row @e row. - Example: - */ - wxPen GetRowGridLinePen(int row); - - /** - Sets the arguments to the current row label alignment values. - Horizontal alignment will be one of wxLEFT, wxCENTRE or wxRIGHT. - - Vertical alignment will be one of wxTOP, wxCENTRE or wxBOTTOM. - */ - void GetRowLabelAlignment(int* horiz, int* vert) const; - - /** - Returns the current width of the row labels. - */ - int GetRowLabelSize() const; - - /** - Returns the specified row label. The default grid table class provides numeric - row labels. - If you are using a custom grid table you can override - wxGridTableBase::GetRowLabelValue to provide - your own labels. - */ - wxString GetRowLabelValue(int row) const; - - /** - This returns the value of the lowest row width that can be handled correctly. - See - member SetRowMinimalAcceptableHeight() for details. - */ - int GetRowMinimalAcceptableHeight() const; - - /** - - */ - int GetRowMinimalHeight(int col) const; - - /** - Returns the height of the specified row. - */ - int GetRowSize(int row) const; - - /** - Returns the number of pixels per horizontal scroll increment. The default is 15. - - @see GetScrollLineY(), SetScrollLineX(), SetScrollLineY() - */ - int GetScrollLineX() const; - - /** - Returns the number of pixels per vertical scroll increment. The default is 15. - - @see GetScrollLineX(), SetScrollLineX(), SetScrollLineY() - */ - int GetScrollLineY() const; - - /** - Returns an array of singly selected cells. - */ - wxGridCellCoordsArray GetSelectedCells() const; - - /** - Returns an array of selected cols. - */ - wxArrayInt GetSelectedCols() const; - - /** - Returns an array of selected rows. - */ - wxArrayInt GetSelectedRows() const; - - /** - Access or update the selection fore/back colours - */ - wxColour GetSelectionBackground() const; - - /** - Returns an array of the bottom right corners of blocks of selected cells, - see GetSelectionBlockTopLeft(). - */ - wxGridCellCoordsArray GetSelectionBlockBottomRight() const; - - /** - Returns an array of the top left corners of blocks of selected cells, - see GetSelectionBlockBottomRight(). - */ - wxGridCellCoordsArray GetSelectionBlockTopLeft() const; - - /** - - */ - wxColour GetSelectionForeground() const; - - /** - Returns the current selection mode, see SetSelectionMode(). - */ - wxGrid::wxGridSelectionModes GetSelectionMode() const; - - /** - Returns a base pointer to the current table object. - */ - wxGridTableBase* GetTable() const; - - /** - Returned number of whole cols visible. - */ - int GetViewWidth() const; - - /** - EnableGridLines() - - GridLinesEnabled() - - SetGridLineColour() - - GetGridLineColour() - - GetDefaultGridLinePen() - - GetRowGridLinePen() - - GetColGridLinePen() - */ - - - /** - Returns @true if drawing of grid lines is turned on, @false otherwise. - */ - bool GridLinesEnabled() const; - - /** - Hides the in-place cell edit control. - */ - void HideCellEditControl(); - - /** - Hides the column labels by calling SetColLabelSize() - with a size of 0. Show labels again by calling that method with - a width greater than 0. - */ - void HideColLabels(); - - /** - Hides the row labels by calling SetRowLabelSize() - with a size of 0. Show labels again by calling that method with - a width greater than 0. - */ - void HideRowLabels(); - - /** - Init the m_colWidths/Rights arrays - */ - void InitColWidths(); - - /** - @note @e never access m_row/col arrays directly because they are created - on demand, @e always use accessor functions instead! - Init the m_rowHeights/Bottoms arrays with default values. - */ - void InitRowHeights(); - - /** - Inserts one or more new columns into a grid with the first new column at the - specified position and returns @true if successful. The updateLabels argument is - not - used at present. - The sequence of actions begins with the grid object requesting the underlying - grid - table to insert new columns. If this is successful the table notifies the grid - and the - grid updates the display. For a default grid (one where you have called - wxGrid::CreateGrid) this process is automatic. If you are - using a custom grid table (specified with wxGrid::SetTable) - then you must override - wxGridTableBase::InsertCols in your derived - table class. - */ - bool InsertCols(int pos = 0, int numCols = 1, - bool updateLabels = true); - - /** - Inserts one or more new rows into a grid with the first new row at the specified - position and returns @true if successful. The updateLabels argument is not used - at - present. - The sequence of actions begins with the grid object requesting the underlying - grid - table to insert new rows. If this is successful the table notifies the grid and - the - grid updates the display. For a default grid (one where you have called - wxGrid::CreateGrid) this process is automatic. If you are - using a custom grid table (specified with wxGrid::SetTable) - then you must override - wxGridTableBase::InsertRows in your derived - table class. - */ - bool InsertRows(int pos = 0, int numRows = 1, - bool updateLabels = true); - - /** - Returns @true if the in-place edit control is currently enabled. - */ - bool IsCellEditControlEnabled() const; - - /** - Returns @true if the current cell has been set to read-only - (see wxGrid::SetReadOnly). - */ - bool IsCurrentCellReadOnly() const; - - /** - Returns @false if the whole grid has been set as read-only or @true otherwise. - See EnableEditing() for more information about - controlling the editing status of grid cells. - */ - bool IsEditable() const; - - //@{ - /** - Is this cell currently selected. - */ - bool IsInSelection(int row, int col) const; - const bool IsInSelection(const wxGridCellCoords& coords) const; - //@} - - /** - Returns @true if the cell at the specified location can't be edited. - See also IsReadOnly(). - */ - bool IsReadOnly(int row, int col) const; - - /** - Returns @true if there are currently rows, columns or blocks of cells selected. - */ - bool IsSelection() const; - - //@{ - /** - Returns @true if a cell is either wholly visible (the default) or at least - partially - visible in the grid window. - */ - bool IsVisible(int row, int col, bool wholeCellVisible = true) const; - const bool IsVisible(const wxGridCellCoords& coords, - bool wholeCellVisible = true) const; - //@} - - //@{ - /** - Brings the specified cell into the visible grid cell area with minimal - scrolling. Does - nothing if the cell is already visible. - */ - void MakeCellVisible(int row, int col); - void MakeCellVisible(const wxGridCellCoords& coords); - //@} - - /** - Moves the grid cursor down by one row. If a block of cells was previously - selected it - will expand if the argument is @true or be cleared if the argument is @false. - */ - bool MoveCursorDown(bool expandSelection); - - /** - Moves the grid cursor down in the current column such that it skips to the - beginning or - end of a block of non-empty cells. If a block of cells was previously selected - it - will expand if the argument is @true or be cleared if the argument is @false. - */ - bool MoveCursorDownBlock(bool expandSelection); - - /** - Moves the grid cursor left by one column. If a block of cells was previously - selected it - will expand if the argument is @true or be cleared if the argument is @false. - */ - bool MoveCursorLeft(bool expandSelection); - - /** - Moves the grid cursor left in the current row such that it skips to the - beginning or - end of a block of non-empty cells. If a block of cells was previously selected - it - will expand if the argument is @true or be cleared if the argument is @false. - */ - bool MoveCursorLeftBlock(bool expandSelection); - - /** - Moves the grid cursor right by one column. If a block of cells was previously - selected it - will expand if the argument is @true or be cleared if the argument is @false. - */ - bool MoveCursorRight(bool expandSelection); - - /** - Moves the grid cursor right in the current row such that it skips to the - beginning or - end of a block of non-empty cells. If a block of cells was previously selected - it - will expand if the argument is @true or be cleared if the argument is @false. - */ - bool MoveCursorRightBlock(bool expandSelection); - - /** - Moves the grid cursor up by one row. If a block of cells was previously - selected it - will expand if the argument is @true or be cleared if the argument is @false. - */ - bool MoveCursorUp(bool expandSelection); - - /** - Moves the grid cursor up in the current column such that it skips to the - beginning or - end of a block of non-empty cells. If a block of cells was previously selected - it - will expand if the argument is @true or be cleared if the argument is @false. - */ - bool MoveCursorUpBlock(bool expandSelection); - - /** - Moves the grid cursor down by some number of rows so that the previous bottom - visible row - becomes the top visible row. - */ - bool MovePageDown(); - - /** - Moves the grid cursor up by some number of rows so that the previous top - visible row - becomes the bottom visible row. - */ - bool MovePageUp(); - - /** - Methods for a registry for mapping data types to Renderers/Editors - */ - void RegisterDataType(const wxString& typeName, - wxGridCellRenderer* renderer, - wxGridCellEditor* editor); - - /** - SetRowLabelValue() - - SetColLabelValue() - - GetRowLabelValue() - - GetColLabelValue() - - SetUseNativeColLabels() - - HideColLabels() - - HideRowLabels() - - SetRowLabelSize() - - SetColLabelSize() - - GetRowLabelSize() - - GetColLabelSize() - - AutoSizeRowLabelSize() - - AutoSizeColLabelSize() - - GetDefaultRowLabelSize() - - GetDefaultColLabelSize() - - SetRowLabelAlignment() - - SetColLabelAlignment() - - GetRowLabelAlignment() - - GetColLabelAlignment() - - SetLabelFont() - - SetLabelTextColour() - - SetLabelBackgroundColour() - - GetLabelFont() - - GetLabelBackgroundColour() - - GetLabelTextColour() - - SetColLabelTextOrientation() - - GetColLabelTextOrientation() - */ - - - /** - Sets the value of the current grid cell to the current in-place edit control - value. - This is called automatically when the grid cursor moves from the current cell - to a - new cell. It is also a good idea to call this function when closing a grid since - any edits to the final cell location will not be saved otherwise. - */ - void SaveEditControlValue(); - - /** - Selects all cells in the grid. - */ - void SelectAll(); - - //@{ - /** - Selects a rectangular block of cells. If addToSelected is @false then any - existing selection will be - deselected; if @true the column will be added to the existing selection. - */ - void SelectBlock(int topRow, int leftCol, int bottomRow, - int rightCol, - bool addToSelected = false); - void SelectBlock(const wxGridCellCoords& topLeft, - const wxGridCellCoords& bottomRight, - bool addToSelected = false); - //@} - - /** - Selects the specified column. If addToSelected is @false then any existing - selection will be - deselected; if @true the column will be added to the existing selection. - */ - void SelectCol(int col, bool addToSelected = false); - - /** - Selects the specified row. If addToSelected is @false then any existing - selection will be - deselected; if @true the row will be added to the existing selection. - */ - void SelectRow(int row, bool addToSelected = false); - - /** - ClearSelection() - - IsSelection() - - SelectAll() - - SelectBlock() - - SelectCol() - - SelectRow() - */ - - - /** - This function returns the rectangle that encloses the selected cells - in device coords and clipped to the client size of the grid window. - */ - wxRect SelectionToDeviceRect() const; - - //@{ - /** - Sets the horizontal and vertical alignment for grid cell text at the specified - location. - Horizontal alignment should be one of wxALIGN_LEFT, wxALIGN_CENTRE or - wxALIGN_RIGHT. - - Vertical alignment should be one of wxALIGN_TOP, wxALIGN_CENTRE or - wxALIGN_BOTTOM. - */ - void SetCellAlignment(int row, int col, int horiz, int vert); - void SetCellAlignment(int align, int row, int col); - //@} - - /** - - */ - void SetCellBackgroundColour(int row, int col, - const wxColour& colour); - - /** - Sets the editor for the grid cell at the specified location. - The grid will take ownership of the pointer. - See wxGridCellEditor and - the @ref overview_gridoverview "wxGrid overview" for more information about - cell editors and renderers. - */ - void SetCellEditor(int row, int col, wxGridCellEditor* editor); - - /** - Sets the font for text in the grid cell at the specified location. - */ - void SetCellFont(int row, int col, const wxFont& font); - - /** - Sets the renderer for the grid cell at the specified location. - The grid will take ownership of the pointer. - See wxGridCellRenderer and - the @ref overview_gridoverview "wxGrid overview" for more information about - cell editors and renderers. - */ - void SetCellRenderer(int row, int col, - wxGridCellRenderer* renderer); - - //@{ - /** - Sets the text colour for the grid cell at the specified location. - */ - void SetCellTextColour(int row, int col, const wxColour& colour); - void SetCellTextColour(const wxColour& val, int row, int col); - void SetCellTextColour(const wxColour& colour); - //@} - - //@{ - /** - Sets the string value for the cell at the specified location. For simple - applications where a - grid object automatically uses a default grid table of string values you use - this function together - with GetCellValue() to access cell values. - For more complex applications where you have derived your own grid table class - that contains - various data types (e.g. numeric, boolean or user-defined custom types) then - you only use this - function for those cells that contain string values. - The last form is for backward compatibility only. - See wxGridTableBase::CanSetValueAs - and the @ref overview_gridoverview "wxGrid overview" for more information. - */ - void SetCellValue(int row, int col, const wxString& s); - void SetCellValue(const wxGridCellCoords& coords, - const wxString& s); - void SetCellValue(const wxString& val, int row, int col); - //@} - - /** - Sets the cell attributes for all cells in the specified column. - For more information about controlling grid cell attributes see the - wxGridCellAttr cell attribute class and the - @ref overview_gridoverview. - */ - void SetColAttr(int col, wxGridCellAttr* attr); - - /** - Sets the specified column to display boolean values. wxGrid displays boolean - values with a checkbox. - */ - void SetColFormatBool(int col); - - /** - Sets the specified column to display data in a custom format. - See the @ref overview_gridoverview "wxGrid overview" for more information on - working - with custom data types. - */ - void SetColFormatCustom(int col, const wxString& typeName); - - /** - Sets the specified column to display floating point values with the given width - and precision. - */ - void SetColFormatFloat(int col, int width = -1, - int precision = -1); - - /** - Sets the specified column to display integer values. - */ - void SetColFormatNumber(int col); - - /** - Sets the horizontal and vertical alignment of column label text. - Horizontal alignment should be one of wxALIGN_LEFT, wxALIGN_CENTRE or - wxALIGN_RIGHT. - Vertical alignment should be one of wxALIGN_TOP, wxALIGN_CENTRE or - wxALIGN_BOTTOM. - */ - void SetColLabelAlignment(int horiz, int vert); - - /** - Sets the height of the column labels. - If @a height equals to @c wxGRID_AUTOSIZE then height is calculated - automatically - so that no label is truncated. Note that this could be slow for a large table. - */ - void SetColLabelSize(int height); - - /** - Set the value for the given column label. If you are using a derived grid table - you must - override wxGridTableBase::SetColLabelValue - for this to have any effect. - */ - void SetColLabelValue(int col, const wxString& value); - - /** - This modifies the minimum column width that can be handled correctly. - Specifying a low value here - allows smaller grid cells to be dealt with correctly. Specifying a value here - which is much smaller - than the actual minimum size will incur a performance penalty in the functions - which perform - grid cell index lookup on the basis of screen coordinates. - This should normally be called when creating the grid because it will not - resize existing columns - with sizes smaller than the value specified here. - */ - void SetColMinimalAcceptableWidth(int width); - - /** - Sets the minimal width for the specified column. This should normally be called - when creating the grid - because it will not resize a column that is already narrower than the minimal - width. - The width argument must be higher than the minimimal acceptable column width, - see - GetColMinimalAcceptableWidth(). - */ - void SetColMinimalWidth(int col, int width); - - /** - Sets the position of the specified column. - */ - void SetColPos(int colID, int newPos); - - /** - Sets the width of the specified column. - This function does not refresh the grid. If you are calling it outside of a - BeginBatch / EndBatch - block you can use ForceRefresh() to see the changes. - Automatically sizes the column to fit its contents. If setAsMin is @true the - calculated width will - also be set as the minimal width for the column. - */ - void SetColSize(int col, int width); - - /** - Sets the default horizontal and vertical alignment for grid cell text. - Horizontal alignment should be one of wxALIGN_LEFT, wxALIGN_CENTRE or - wxALIGN_RIGHT. - Vertical alignment should be one of wxALIGN_TOP, wxALIGN_CENTRE or - wxALIGN_BOTTOM. - */ - void SetDefaultCellAlignment(int horiz, int vert); - - /** - Sets the default background colour for grid cells. - */ - void SetDefaultCellBackgroundColour(const wxColour& colour); - - /** - Sets the default font to be used for grid cell text. - */ - void SetDefaultCellFont(const wxFont& font); - - /** - Sets the current default colour for grid cell text. - */ - void SetDefaultCellTextColour(const wxColour& colour); - - /** - Sets the default width for columns in the grid. This will only affect columns - subsequently added to - the grid unless resizeExistingCols is @true. - */ - void SetDefaultColSize(int width, - bool resizeExistingCols = false); - - /** - Sets the default editor for grid cells. The grid will take ownership of the - pointer. - See wxGridCellEditor and - the @ref overview_gridoverview "wxGrid overview" for more information about - cell editors and renderers. - */ - void SetDefaultEditor(wxGridCellEditor* editor); - - /** - Sets the default renderer for grid cells. The grid will take ownership of the - pointer. - See wxGridCellRenderer and - the @ref overview_gridoverview "wxGrid overview" for more information about - cell editors and renderers. - */ - void SetDefaultRenderer(wxGridCellRenderer* renderer); - - /** - Sets the default height for rows in the grid. This will only affect rows - subsequently added - to the grid unless resizeExistingRows is @true. - */ - void SetDefaultRowSize(int height, - bool resizeExistingRows = false); - - /** - Set the grid cursor to the specified cell. - This function calls MakeCellVisible(). - */ - void SetGridCursor(int row, int col); - - /** - Sets the colour used to draw grid lines. - */ - void SetGridLineColour(const wxColour& colour); - - /** - Sets the background colour for row and column labels. - */ - void SetLabelBackgroundColour(const wxColour& colour); - - /** - Sets the font for row and column labels. - */ - void SetLabelFont(const wxFont& font); - - /** - Sets the colour for row and column label text. - */ - void SetLabelTextColour(const wxColour& colour); - - /** - A grid may occupy more space than needed for its rows/columns. This - function allows to set how big this extra space is - */ - void SetMargins(int extraWidth, int extraHeight); - - /** - Common part of AutoSizeColumn/Row() and GetBestSize() - */ - int SetOrCalcColumnSizes(bool calcOnly, bool setAsMin = true); - - /** - - */ - int SetOrCalcRowSizes(bool calcOnly, bool setAsMin = true); - - /** - Makes the cell at the specified location read-only or editable. - See also IsReadOnly(). - */ - void SetReadOnly(int row, int col, bool isReadOnly = true); - - /** - Sets the cell attributes for all cells in the specified row. - See the wxGridCellAttr class for more information - about controlling cell attributes. - */ - void SetRowAttr(int row, wxGridCellAttr* attr); - - /** - Sets the horizontal and vertical alignment of row label text. - Horizontal alignment should be one of wxALIGN_LEFT, wxALIGN_CENTRE or - wxALIGN_RIGHT. - Vertical alignment should be one of wxALIGN_TOP, wxALIGN_CENTRE or - wxALIGN_BOTTOM. - */ - void SetRowLabelAlignment(int horiz, int vert); - - /** - Sets the width of the row labels. - If @a width equals @c wxGRID_AUTOSIZE then width is calculated automatically - so that no label is truncated. Note that this could be slow for a large table. - */ - void SetRowLabelSize(int width); - - /** - Set the value for the given row label. If you are using a derived grid table - you must - override wxGridTableBase::SetRowLabelValue - for this to have any effect. - */ - void SetRowLabelValue(int row, const wxString& value); - - /** - This modifies the minimum row width that can be handled correctly. Specifying a - low value here - allows smaller grid cells to be dealt with correctly. Specifying a value here - which is much smaller - than the actual minimum size will incur a performance penalty in the functions - which perform - grid cell index lookup on the basis of screen coordinates. - This should normally be called when creating the grid because it will not - resize existing rows - with sizes smaller than the value specified here. - */ - void SetRowMinimalAcceptableHeight(int height); - - /** - Sets the minimal height for the specified row. This should normally be called - when creating the grid - because it will not resize a row that is already shorter than the minimal - height. - The height argument must be higher than the minimimal acceptable row height, see - GetRowMinimalAcceptableHeight(). - */ - void SetRowMinimalHeight(int row, int height); - - /** - Sets the height of the specified row. - This function does not refresh the grid. If you are calling it outside of a - BeginBatch / EndBatch - block you can use ForceRefresh() to see the changes. - Automatically sizes the column to fit its contents. If setAsMin is @true the - calculated width will - also be set as the minimal width for the column. - */ - void SetRowSize(int row, int height); - - /** - Sets the number of pixels per horizontal scroll increment. The default is 15. - Sometimes wxGrid has trouble setting the scrollbars correctly due to rounding - errors: setting this to 1 can help. - - @see GetScrollLineX(), GetScrollLineY(), SetScrollLineY() - */ - void SetScrollLineX(int x); - - /** - Sets the number of pixels per vertical scroll increment. The default is 15. - Sometimes wxGrid has trouble setting the scrollbars correctly due to rounding - errors: setting this to 1 can help. - - @see GetScrollLineX(), GetScrollLineY(), SetScrollLineX() - */ - void SetScrollLineY(int y); - - /** - - */ - void SetSelectionBackground(const wxColour& c); - - /** - - */ - void SetSelectionForeground(const wxColour& c); - - /** - Set the selection behaviour of the grid. - - @param wxGridSelectCells() - The default mode where individual cells are selected. - @param wxGridSelectRows() - Selections will consist of whole rows. - @param wxGridSelectColumns() - Selections will consist of whole columns. - */ - void SetSelectionMode(wxGrid::wxGridSelectionModes selmode); - - /** - Passes a pointer to a custom grid table to be used by the grid. This should be - called - after the grid constructor and before using the grid object. If takeOwnership - is set to - @true then the table will be deleted by the wxGrid destructor. - Use this function instead of CreateGrid() when your - application involves complex or non-string data or data sets that are too large - to fit - wholly in memory. - */ - bool SetTable(wxGridTableBase* table, bool takeOwnership = false, - wxGrid::wxGridSelectionModes selmode = wxGrid::wxGridSelectCells); - - /** - Call this in order to make the column labels use a native look by using - wxRenderer::DrawHeaderButton - internally. There is no equivalent method for drawing row columns as - there is not native look for that. This option is useful when using - wxGrid for displaying tables and not as a spread-sheet. - */ - void SetUseNativeColLabels(bool native = true); - - /** - Displays the in-place cell edit control for the current cell. - */ - void ShowCellEditControl(); - - /** - @param x - The x position to evaluate. - @param clipToMinMax - If @true, rather than returning wxNOT_FOUND, it returns either the first or - last column depending on whether x is too far to the left or right respectively. - */ - int XToCol(int x, bool clipToMinMax = false) const; - - /** - Returns the column whose right hand edge is close to the given logical x - position. - If no column edge is near to this position @c wxNOT_FOUND is returned. - */ - int XToEdgeOfCol(int x) const; - - /** - Returns the row whose bottom edge is close to the given logical y position. - If no row edge is near to this position @c wxNOT_FOUND is returned. - */ - int YToEdgeOfRow(int y) const; - - /** - Returns the grid row that corresponds to the logical y coordinate. Returns - @c wxNOT_FOUND if there is no row at the y position. - */ - int YToRow(int y) const; -}; - - - -/** - @class wxGridCellBoolEditor - @wxheader{grid.h} - - The editor for boolean data. - - @library{wxadv} - @category{FIXME} - - @see wxGridCellEditor, wxGridCellFloatEditor, wxGridCellNumberEditor, - wxGridCellTextEditor, wxGridCellChoiceEditor -*/ -class wxGridCellBoolEditor : public wxGridCellEditor -{ -public: - /** - Default constructor. - */ - wxGridCellBoolEditor(); - - /** - Returns @true if the given @a value is equal to the string representation of - the truth value we currently use (see - wxGridCellBoolEditor::UseStringValues). - */ - static bool IsTrueValue(const wxString& value); - - /** - , wxString&@e valueFalse = _T("")) - This method allows to customize the values returned by GetValue() method for - the cell using this editor. By default, the default values of the arguments are - used, i.e. @c "1" is returned if the cell is checked and an empty string - otherwise, using this method allows to change this. - */ - static void UseStringValues() const; -}; - - - -/** - @class wxGridUpdateLocker - @wxheader{grid.h} - - This small class can be used to prevent wxGrid from redrawing - during its lifetime by calling wxGrid::BeginBatch - in its constructor and wxGrid::EndBatch in its - destructor. It is typically used in a function performing several operations - with a grid which would otherwise result in flicker. For example: - - @code - void MyFrame::Foo() - { - m_grid = new wxGrid(this, ...); - - wxGridUpdateLocker noUpdates(m_grid); - m_grid-AppendColumn(); - ... many other operations with m_grid... - m_grid-AppendRow(); - - // destructor called, grid refreshed - } - @endcode - - Using this class is easier and safer than calling - wxGrid::BeginBatch and wxGrid::EndBatch - because you don't risk not to call the latter (due to an exception for example). - - @library{wxadv} - @category{FIXME} -*/ -class wxGridUpdateLocker -{ -public: - /** - Creates an object preventing the updates of the specified @e grid. The - parameter could be @NULL in which case nothing is done. If @a grid is - non-@NULL then the grid must exist for longer than wxGridUpdateLocker object - itself. - The default constructor could be followed by a call to - Create() to set the - grid object later. - */ - wxGridUpdateLocker(wxGrid* grid = NULL); - - /** - Destructor reenables updates for the grid this object is associated with. - */ - ~wxGridUpdateLocker(); - - /** - This method can be called if the object had been constructed using the default - constructor. It must not be called more than once. - */ - void Create(wxGrid* grid); -}; - diff --git a/interface/hash.h b/interface/hash.h deleted file mode 100644 index b7bfc1091a..0000000000 --- a/interface/hash.h +++ /dev/null @@ -1,107 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: hash.h -// Purpose: interface of wxHashTable -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxHashTable - @wxheader{hash.h} - - @b Please note that this class is retained for backward compatibility - reasons; you should use wxHashMap. - - This class provides hash table functionality for wxWidgets, and for an - application if it wishes. Data can be hashed on an integer or string - key. - - @library{wxbase} - @category{containers} - - @see wxList -*/ -class wxHashTable : public wxObject -{ -public: - /** - Constructor. @a key_type is one of wxKEY_INTEGER, or wxKEY_STRING, - and indicates what sort of keying is required. @a size is optional. - */ - wxHashTable(unsigned int key_type, int size = 1000); - - /** - Destroys the hash table. - */ - ~wxHashTable(); - - /** - The counterpart of @e Next. If the application wishes to iterate - through all the data in the hash table, it can call @e BeginFind and - then loop on @e Next. - */ - void BeginFind(); - - /** - Clears the hash table of all nodes (but as usual, doesn't delete user data). - */ - void Clear(); - - //@{ - /** - Deletes entry in hash table and returns the user's data (if found). - */ - wxObject* Delete(long key); - wxObject* Delete(const wxString& key); - //@} - - /** - If set to @true data stored in hash table will be deleted when hash table object - is destroyed. - */ - void DeleteContents(bool flag); - - //@{ - /** - Gets data from the hash table, using an integer or string key (depending on - which - has table constructor was used). - */ - wxObject* Get(long key); - wxObject* Get(const char* key); - //@} - - /** - Returns the number of elements in the hash table. - */ - size_t GetCount() const; - - /** - Makes an integer key out of a string. An application may wish to make a key - explicitly (for instance when combining two data values to form a key). - */ - long MakeKey(const wxString& string); - - /** - If the application wishes to iterate through all the data in the hash - table, it can call @e BeginFind and then loop on @e Next. This function - returns a @b Node() pointer (or @NULL if there are no more nodes). - The return value is functionally equivalent to @b wxNode but might not be - implemented as a @b wxNode. The user will probably only wish to use the - @b GetData method to retrieve the data; the node may also be deleted. - */ - wxHashTable::Node* Next(); - - //@{ - /** - Inserts data into the hash table, using an integer or string key (depending on - which - has table constructor was used). The key string is copied and stored by the hash - table implementation. - */ - void Put(long key, wxObject* object); - void Put(const char* key, wxObject* object); - //@} -}; - diff --git a/interface/hashmap.h b/interface/hashmap.h deleted file mode 100644 index bfba745898..0000000000 --- a/interface/hashmap.h +++ /dev/null @@ -1,106 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: hashmap.h -// Purpose: interface of wxHashMap -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxHashMap - @wxheader{hashmap.h} - - This is a simple, type-safe, and reasonably efficient hash map class, - whose interface is a subset of the interface of STL containers. In - particular, the interface is modeled after std::map, and the various, - non-standard, std::hash_map. - - @library{wxbase} - @category{FIXME} -*/ -class wxHashMap -{ -public: - //@{ - /** - Copy constructor. - */ - wxHashMap(size_type size = 10); - wxHashMap(const wxHashMap& map); - //@} - - //@{ - /** - Returns an iterator pointing at the first element of the hash map. - Please remember that hash maps do not guarantee ordering. - */ - const_iterator begin(); - const iterator begin(); - //@} - - /** - Removes all elements from the hash map. - */ - void clear(); - - /** - Counts the number of elements with the given key present in the map. - This function returns only 0 or 1. - */ - size_type count(const key_type& key) const; - - /** - Returns @true if the hash map does not contain any elements, @false otherwise. - */ - bool empty() const; - - //@{ - /** - Returns an iterator pointing at the one-after-the-last element of the hash map. - Please remember that hash maps do not guarantee ordering. - */ - const_iterator end(); - const iterator end(); - //@} - - //@{ - /** - Erases the element pointed to by the iterator. After the deletion - the iterator is no longer valid and must not be used. - */ - size_type erase(const key_type& key); - void erase(iterator it); - void erase(const_iterator it); - //@} - - //@{ - /** - If an element with the given key is present, the functions returns - an iterator pointing at that element, otherwise an invalid iterator - is returned (i.e. hashmap.find( non_existent_key ) == hashmap.end()). - */ - iterator find(const key_type& key) const; - const_iterator find(const key_type& key) const; - //@} - - /** - Inserts the given value in the hash map. The return value is - equivalent to a @c std::pairiterator(), bool; - the iterator points to the inserted element, the boolean value - is @true if @c v was actually inserted. - */ - Insert_Result insert(const value_type& v); - - /** - Use the key as an array subscript. The only difference is that if the - given key is not present in the hash map, an element with the - default @c value_type() is inserted in the table. - */ - mapped_type operator[](const key_type& key); - - /** - Returns the number of elements in the map. - */ - size_type size() const; -}; - diff --git a/interface/hashset.h b/interface/hashset.h deleted file mode 100644 index 1470b29ef0..0000000000 --- a/interface/hashset.h +++ /dev/null @@ -1,99 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: hashset.h -// Purpose: interface of wxHashSet -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxHashSet - @wxheader{hashset.h} - - This is a simple, type-safe, and reasonably efficient hash set class, - whose interface is a subset of the interface of STL containers. In - particular, the interface is modeled after std::set, and the various, - non-standard, std::hash_map. - - @library{wxbase} - @category{FIXME} -*/ -class wxHashSet -{ -public: - //@{ - /** - Copy constructor. - */ - wxHashSet(size_type size = 10); - wxHashSet(const wxHashSet& set); - //@} - - //@{ - /** - Returns an iterator pointing at the first element of the hash set. - Please remember that hash sets do not guarantee ordering. - */ - const_iterator begin(); - const iterator begin(); - //@} - - /** - Removes all elements from the hash set. - */ - void clear(); - - /** - Counts the number of elements with the given key present in the set. - This function returns only 0 or 1. - */ - size_type count(const key_type& key) const; - - /** - Returns @true if the hash set does not contain any elements, @false otherwise. - */ - bool empty() const; - - //@{ - /** - Returns an iterator pointing at the one-after-the-last element of the hash set. - Please remember that hash sets do not guarantee ordering. - */ - const_iterator end(); - const iterator end(); - //@} - - //@{ - /** - Erases the element pointed to by the iterator. After the deletion - the iterator is no longer valid and must not be used. - */ - size_type erase(const key_type& key); - void erase(iterator it); - void erase(const_iterator it); - //@} - - //@{ - /** - If an element with the given key is present, the functions returns - an iterator pointing at that element, otherwise an invalid iterator - is returned (i.e. hashset.find( non_existent_key ) == hashset.end()). - */ - iterator find(const key_type& key) const; - const_iterator find(const key_type& key) const; - //@} - - /** - Inserts the given value in the hash set. The return value is - equivalent to a @c std::pairwxHashMap::iterator, bool; - the iterator points to the inserted element, the boolean value - is @true if @c v was actually inserted. - */ - Insert_Result insert(const value_type& v); - - /** - Returns the number of elements in the set. - */ - size_type size() const; -}; - diff --git a/interface/help.h b/interface/help.h deleted file mode 100644 index 832d8f48a1..0000000000 --- a/interface/help.h +++ /dev/null @@ -1,246 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: help.h -// Purpose: interface of wxHelpController -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxHelpController - @wxheader{help.h} - - This is a family of classes by which - applications may invoke a help viewer to provide on-line help. - - A help controller allows an application to display help, at the contents - or at a particular topic, and shut the help program down on termination. - This avoids proliferation of many instances of the help viewer whenever the - user requests a different topic via the application's menus or buttons. - - Typically, an application will create a help controller instance - when it starts, and immediately call @b Initialize - to associate a filename with it. The help viewer will only get run, however, - just before the first call to display something. - - Most help controller classes actually derive from wxHelpControllerBase and have - names of the form wxXXXHelpController or wxHelpControllerXXX. An - appropriate class is aliased to the name wxHelpController for each platform, as - follows: - - On desktop Windows, wxCHMHelpController is used (MS HTML Help). - On Windows CE, wxWinceHelpController is used. - On all other platforms, wxHtmlHelpController is used if wxHTML is - compiled into wxWidgets; otherwise wxExtHelpController is used (for invoking an - external - browser). - - The remaining help controller classes need to be named - explicitly by an application that wishes to make use of them. - - There are currently the following help controller classes defined: - - wxWinHelpController, for controlling Windows Help. - wxCHMHelpController, for controlling MS HTML Help. To use this, you need to - set wxUSE_MS_HTML_HELP - to 1 in setup.h and have htmlhelp.h header from Microsoft's HTML Help kit (you - don't need - VC++ specific htmlhelp.lib because wxWidgets loads necessary DLL at runtime and - so it - works with all compilers). - wxBestHelpController, for controlling MS HTML Help or, if Microsoft's runtime - is - not available, wxHtmlHelpController. You need to provide - @b both CHM and HTB versions of the help file. For 32bit Windows only. - wxExtHelpController, for controlling external browsers under Unix. - The default browser is Netscape Navigator. The 'help' sample shows its use. - wxWinceHelpController, for controlling a simple @c .htm help controller for - Windows CE applications. - wxHtmlHelpController, a sophisticated help controller using wxHTML(), in - a similar style to the Microsoft HTML Help viewer and using some of the same - files. - Although it has an API compatible with other help controllers, it has more - advanced features, so it is - recommended that you use the specific API for this class instead. Note that if - you - use .zip or .htb formats for your books, you - must add this line to your application initialization: @c - wxFileSystem::AddHandler(new wxArchiveFSHandler); - or nothing will be shown in your help window. - - - @library{wxbase} - @category{help} - - @see wxHtmlHelpController, wxHTML() -*/ -class wxHelpController : public wxObject -{ -public: - /** - Constructs a help instance object, but does not invoke the help viewer. - If you provide a window, it will be used by some help controller classes, such - as - wxCHMHelpController, wxWinHelpController and wxHtmlHelpController, as the - parent for the help window instead of the value of wxApp::GetTopWindow. You can - also change the parent window later with - SetParentWindow(). - */ - wxHelpController(wxWindow* parentWindow = NULL); - - /** - Destroys the help instance, closing down the viewer if it is running. - */ - ~wxHelpController(); - - /** - If the help viewer is not running, runs it and displays the file at the given - block number. - @e WinHelp: Refers to the context number. - @e MS HTML Help: Refers to the context number. - @e External HTML help: the same as for DisplaySection(). - @e wxHtmlHelpController: @e sectionNo is an identifier as specified in the @c - .hhc file. See @ref overview_helpformat "Help files format". - This function is for backward compatibility only, and applications should use - @ref displaysection() wxHelpController instead. - */ - virtual bool DisplayBlock(long blockNo); - - /** - If the help viewer is not running, runs it and displays the - contents. - */ - virtual bool DisplayContents(); - - /** - Displays the section as a popup window using a context id. - Returns @false if unsuccessful or not implemented. - */ - virtual bool DisplayContextPopup(int contextId); - - //@{ - /** - If the help viewer is not running, runs it and displays the given section. - @e WinHelp, MS HTML Help @a sectionNo is a context id. - @e External HTML help: wxExtHelpController implements @a sectionNo as an id in - a map file, which is of the form: - - @e wxHtmlHelpController: @a sectionNo is an identifier as specified in the @c - .hhc file. See @ref overview_helpformat "Help files format". - See also the help sample for notes on how to specify section numbers for - various help file formats. - */ - virtual bool DisplaySection(const wxString& section); - virtual bool DisplaySection(int sectionNo); - //@} - - /** - Displays the text in a popup window, if possible. - Returns @false if unsuccessful or not implemented. - */ - virtual bool DisplayTextPopup(const wxString& text, - const wxPoint& pos); - - /** - wxHtmlHelpController returns the frame, size and position. - For all other help controllers, this function does nothing - and just returns @NULL. - - @param viewer - This defaults to "netscape" for wxExtHelpController. - @param flags - This defaults to wxHELP_NETSCAPE for wxExtHelpController, indicating - that the viewer is a variant of Netscape Navigator. - */ - virtual wxFrame* GetFrameParameters(const wxSize* size = NULL, - const wxPoint* pos = NULL, - bool* newFrameEachTime = NULL); - - /** - Returns the window to be used as the parent for the help window. This window is - used - by wxCHMHelpController, wxWinHelpController and wxHtmlHelpController. - */ - virtual wxWindow* GetParentWindow() const; - - //@{ - /** - Initializes the help instance with a help filename, and optionally a server - socket - number if using wxHelp (now obsolete). Does not invoke the help viewer. - This must be called directly after the help instance object is created and - before - any attempts to communicate with the viewer. - You may omit the file extension and a suitable one will be chosen. For - wxHtmlHelpController, the extensions zip, htb and hhp will be appended while - searching for - a suitable file. For WinHelp, the hlp extension is appended. - */ - virtual bool Initialize(const wxString& file); - virtual bool Initialize(const wxString& file, int server); - //@} - - /** - If the help viewer is not running, runs it, and searches for sections matching - the given keyword. If one match is found, the file is displayed at this - section. The optional parameter allows the search the index - (wxHELP_SEARCH_INDEX) but this currently only supported by the - wxHtmlHelpController. - @e WinHelp, MS HTML Help: If more than one match is found, - the first topic is displayed. - @e External HTML help, simple wxHTML help: If more than one match is found, - a choice of topics is displayed. - @e wxHtmlHelpController: see wxHtmlHelpController::KeywordSearch. - */ - virtual bool KeywordSearch(const wxString& keyWord, - wxHelpSearchMode mode = wxHELP_SEARCH_ALL); - - /** - If the help viewer is not running, runs it and loads the given file. - If the filename is not supplied or is - empty, the file specified in @b Initialize is used. If the viewer is - already displaying the specified file, it will not be reloaded. This - member function may be used before each display call in case the user - has opened another file. - wxHtmlHelpController ignores this call. - */ - virtual bool LoadFile(const wxString& file = ""); - - /** - Overridable member called when this application's viewer is quit by the user. - This does not work for all help controllers. - */ - virtual bool OnQuit(); - - /** - If the viewer is running, quits it by disconnecting. - For Windows Help, the viewer will only close if no other application is using - it. - */ - virtual bool Quit(); - - /** - For wxHtmlHelpController, the title is set (again with %s indicating the - page title) and also the size and position of the frame if the frame is already - open. @a newFrameEachTime is ignored. - For all other help controllers this function has no effect. - */ - virtual void SetFrameParameters(const wxString& title, - const wxSize& size, - const wxPoint& pos = wxDefaultPosition, - bool newFrameEachTime = false); - - /** - Sets the window to be used as the parent for the help window. This is used - by wxCHMHelpController, wxWinHelpController and wxHtmlHelpController. - */ - virtual void SetParentWindow(wxWindow* parentWindow); - - /** - Sets detailed viewer information. So far this is only relevant to - wxExtHelpController. - Some examples of usage: - */ - virtual void SetViewer(const wxString& viewer, long flags); -}; - diff --git a/interface/html/helpctrl.h b/interface/html/helpctrl.h deleted file mode 100644 index ee3869a63b..0000000000 --- a/interface/html/helpctrl.h +++ /dev/null @@ -1,202 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: html/helpctrl.h -// Purpose: interface of wxHtmlHelpController -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxHtmlHelpController - @headerfile helpctrl.h wx/html/helpctrl.h - - This help controller provides an easy way of displaying HTML help in your - application (see @e test sample). The help system is based on @b books - (see wxHtmlHelpController::AddBook). A book is a logical - section of documentation (for example "User's Guide" or "Programmer's Guide" or - "C++ Reference" or "wxWidgets Reference"). The help controller can handle as - many books as you want. - - Although this class has an API compatible with other wxWidgets - help controllers as documented by wxHelpController, it - is recommended that you use the enhanced capabilities of wxHtmlHelpController's - API. - - wxHTML uses Microsoft's HTML Help Workshop project files (.hhp, .hhk, .hhc) as - its - native format. The file format is described here(). - Have a look at docs/html/ directory where sample project files are stored. - - You can use Tex2RTF to produce these files when generating HTML, if you set @b - htmlWorkshopFiles to @b @true in - your tex2rtf.ini file. The commercial tool HelpBlocks (www.helpblocks.com) can - also create these files. - - @library{wxhtml} - @category{help} - - @see @ref overview_wxhelpcontroller "Information about wxBestHelpController", - wxHtmlHelpFrame, wxHtmlHelpDialog, wxHtmlHelpWindow, wxHtmlModalHelp -*/ -class wxHtmlHelpController -{ -public: - /** - Constructor. - */ - wxHtmlHelpController(int style = wxHF_DEFAULT_STYLE, - wxWindow* parentWindow = NULL); - - //@{ - /** - Adds book (@ref overview_helpformat ".hhp file" - HTML Help Workshop project - file) into the list of loaded books. - This must be called at least once before displaying any help. - @a bookFile or @a bookUrl may be either .hhp file or ZIP archive - that contains arbitrary number of .hhp files in - top-level directory. This ZIP archive must have .zip or .htb extension - (the latter stands for "HTML book"). In other words, @c - AddBook(wxFileName("help.zip")) - is possible and is the recommended way. - - @param showWaitMsg - If @true then a decoration-less window with progress message is displayed. - @param bookFile - Help book filename. It is recommended to use this prototype - instead of the one taking URL, because it is less error-prone. - @param bookUrl - Help book URL (note that syntax of filename and URL is - different on most platforms) - */ - bool AddBook(const wxFileName& bookFile, bool showWaitMsg); - bool AddBook(const wxString& bookUrl, bool showWaitMsg); - //@} - - /** - This protected virtual method may be overridden so that when specifying the - wxHF_DIALOG style, the controller - uses a different dialog. - */ - virtual wxHtmlHelpDialog* CreateHelpDialog(wxHtmlHelpData* data); - - /** - This protected virtual method may be overridden so that the controller - uses a different frame. - */ - virtual wxHtmlHelpFrame* CreateHelpFrame(wxHtmlHelpData* data); - - //@{ - /** - This alternative form is used to search help contents by numeric IDs. - */ - void Display(const wxString& x); - void Display(const int id); - //@} - - /** - Displays help window and focuses contents panel. - */ - void DisplayContents(); - - /** - Displays help window and focuses index panel. - */ - void DisplayIndex(); - - /** - Displays help window, focuses search panel and starts searching. Returns @true - if the keyword was found. Optionally it searches through the index (mode = - wxHELP_SEARCH_INDEX), default the content (mode = wxHELP_SEARCH_ALL). - @b Important: KeywordSearch searches only pages listed in .hhc file(s). - You should list all pages in the contents file. - */ - bool KeywordSearch(const wxString& keyword, - wxHelpSearchMode mode = wxHELP_SEARCH_ALL); - - /** - Reads the controller's setting (position of window, etc.) - */ - void ReadCustomization(wxConfigBase* cfg, - wxString path = wxEmptyString); - - /** - Sets the path for storing temporary files - cached binary versions of index and - contents files. These binary - forms are much faster to read. Default value is empty string (empty string means - that no cached data are stored). Note that these files are @e not - deleted when program exits. - Once created these cached files will be used in all subsequent executions - of your application. If cached files become older than corresponding .hhp - file (e.g. if you regenerate documentation) it will be refreshed. - */ - void SetTempDir(const wxString& path); - - /** - Sets format of title of the frame. Must contain exactly one "%s" - (for title of displayed HTML page). - */ - void SetTitleFormat(const wxString& format); - - /** - Associates @a config object with the controller. - If there is associated config object, wxHtmlHelpController automatically - reads and writes settings (including wxHtmlWindow's settings) when needed. - The only thing you must do is create wxConfig object and call UseConfig. - If you do not use @e UseConfig, wxHtmlHelpController will use - default wxConfig object if available (for details see - wxConfigBase::Get and - wxConfigBase::Set). - */ - void UseConfig(wxConfigBase* config, - const wxString& rootpath = wxEmptyString); - - /** - Stores controllers setting (position of window etc.) - */ - void WriteCustomization(wxConfigBase* cfg, - wxString path = wxEmptyString); -}; - - - -/** - @class wxHtmlModalHelp - @headerfile helpctrl.h wx/html/helpctrl.h - - This class uses wxHtmlHelpController - to display help in a modal dialog. This is useful on platforms such as wxMac - where if you display help from a modal dialog, the help window must itself be a - modal - dialog. - - Create objects of this class on the stack, for example: - - @code - // The help can be browsed during the lifetime of this object; when the user - quits - // the help, program execution will continue. - wxHtmlModalHelp help(parent, wxT("help"), wxT("My topic")); - @endcode - - @library{wxhtml} - @category{FIXME} -*/ -class wxHtmlModalHelp -{ -public: - /** - @param parent - is the parent of the dialog. - @param helpFile - is the HTML help file to show. - @param topic - is an optional topic. If this is empty, the help contents will be shown. - @param style - is a combination of the flags described in the wxHtmlHelpController - documentation. - */ - wxHtmlModalHelp(wxWindow* parent, const wxString& helpFile, - const wxString& topic = wxEmptyString, - int style = wxHF_DEFAULT_STYLE | wxHF_DIALOG | wxHF_MODAL); -}; - diff --git a/interface/html/helpdata.h b/interface/html/helpdata.h deleted file mode 100644 index f124c123a1..0000000000 --- a/interface/html/helpdata.h +++ /dev/null @@ -1,69 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: html/helpdata.h -// Purpose: interface of wxHtmlHelpData -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxHtmlHelpData - @headerfile helpdata.h wx/html/helpdata.h - - This class is used by wxHtmlHelpController - and wxHtmlHelpFrame to access HTML help items. - It is internal class and should not be used directly - except for the case - you're writing your own HTML help controller. - - @library{wxhtml} - @category{FIXME} -*/ -class wxHtmlHelpData : public wxObject -{ -public: - /** - Constructor. - */ - wxHtmlHelpData(); - - /** - Adds new book. @e book is URL (not filename!) of HTML help project (hhp) - or ZIP file that contains arbitrary number of .hhp projects (this zip - file can have either .zip or .htb extension, htb stands for "html book"). - Returns success. - */ - bool AddBook(const wxString& book_url); - - /** - Returns page's URL based on integer ID stored in project. - */ - wxString FindPageById(int id); - - /** - Returns page's URL based on its (file)name. - */ - wxString FindPageByName(const wxString& page); - - /** - Returns array with help books info. - */ - const wxHtmlBookRecArray GetBookRecArray(); - - /** - Returns reference to array with contents entries. - */ - const wxHtmlHelpDataItems GetContentsArray(); - - /** - Returns reference to array with index entries. - */ - const wxHtmlHelpDataItems GetIndexArray(); - - /** - Sets temporary directory where binary cached versions of MS HTML Workshop - files will be stored. (This is turned off by default and you can enable - this feature by setting non-empty temp dir.) - */ - void SetTempDir(const wxString& path); -}; - diff --git a/interface/html/helpdlg.h b/interface/html/helpdlg.h deleted file mode 100644 index 3b689e837d..0000000000 --- a/interface/html/helpdlg.h +++ /dev/null @@ -1,82 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: html/helpdlg.h -// Purpose: interface of wxHtmlHelpDialog -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxHtmlHelpDialog - @headerfile helpdlg.h wx/html/helpdlg.h - - This class is used by wxHtmlHelpController - to display help. - It is an internal class and should not be used directly - except for the case - when you're writing your own HTML help controller. - - @library{wxhtml} - @category{FIXME} -*/ -class wxHtmlHelpDialog : public wxFrame -{ -public: - //@{ - /** - Constructor. For the values of @e style, please see the documentation for - wxHtmlHelpController. - */ - wxHtmlHelpDialog(wxHtmlHelpData* data = NULL); - wxHtmlHelpDialog(wxWindow* parent, int wxWindowID, - const wxString& title = wxEmptyString, - int style = wxHF_DEFAULT_STYLE, - wxHtmlHelpData* data = NULL); - //@} - - /** - You may override this virtual method to add more buttons to the help window's - toolbar. @a toolBar is a pointer to the toolbar and @a style is the style - flag as passed to the Create method. - wxToolBar::Realize is called immediately after returning from this function. - */ - virtual void AddToolbarButtons(wxToolBar* toolBar, int style); - - /** - Creates the dialog. See @ref wxhtmlhelpdialog() "the constructor" - for a description of the parameters. - */ - bool Create(wxWindow* parent, wxWindowID id, - const wxString& title = wxEmptyString, - int style = wxHF_DEFAULT_STYLE); - - /** - Returns the help controller associated with the dialog. - */ - wxHtmlHelpController* GetController() const; - - /** - Reads the user's settings for this dialog see - wxHtmlHelpController::ReadCustomization) - */ - void ReadCustomization(wxConfigBase* cfg, - const wxString& path = wxEmptyString); - - /** - Sets the help controller associated with the dialog. - */ - void SetController(wxHtmlHelpController* contoller); - - /** - Sets the dialog's title format. @a format must contain exactly one "%s" - (it will be replaced by the page title). - */ - void SetTitleFormat(const wxString& format); - - /** - Saves the user's settings for this dialog (see - wxHtmlHelpController::WriteCustomization). - */ - void WriteCustomization(wxConfigBase* cfg, - const wxString& path = wxEmptyString); -}; - diff --git a/interface/html/helpfrm.h b/interface/html/helpfrm.h deleted file mode 100644 index 90d084eb5b..0000000000 --- a/interface/html/helpfrm.h +++ /dev/null @@ -1,82 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: html/helpfrm.h -// Purpose: interface of wxHtmlHelpFrame -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxHtmlHelpFrame - @headerfile helpfrm.h wx/html/helpfrm.h - - This class is used by wxHtmlHelpController - to display help. - It is an internal class and should not be used directly - except for the case - when you're writing your own HTML help controller. - - @library{wxhtml} - @category{FIXME} -*/ -class wxHtmlHelpFrame : public wxFrame -{ -public: - //@{ - /** - Constructor. For the values of @e style, please see the documentation for - wxHtmlHelpController. - */ - wxHtmlHelpFrame(wxHtmlHelpData* data = NULL); - wxHtmlHelpFrame(wxWindow* parent, int wxWindowID, - const wxString& title = wxEmptyString, - int style = wxHF_DEFAULT_STYLE, - wxHtmlHelpData* data = NULL); - //@} - - /** - You may override this virtual method to add more buttons to the help window's - toolbar. @a toolBar is a pointer to the toolbar and @a style is the style - flag as passed to the Create method. - wxToolBar::Realize is called immediately after returning from this function. - */ - virtual void AddToolbarButtons(wxToolBar* toolBar, int style); - - /** - Creates the frame. See @ref wxhtmlhelpframe() "the constructor" - for a description of the parameters. - */ - bool Create(wxWindow* parent, wxWindowID id, - const wxString& title = wxEmptyString, - int style = wxHF_DEFAULT_STYLE); - - /** - Returns the help controller associated with the frame. - */ - wxHtmlHelpController* GetController() const; - - /** - Reads the user's settings for this frame see - wxHtmlHelpController::ReadCustomization) - */ - void ReadCustomization(wxConfigBase* cfg, - const wxString& path = wxEmptyString); - - /** - Sets the help controller associated with the frame. - */ - void SetController(wxHtmlHelpController* contoller); - - /** - Sets the frame's title format. @a format must contain exactly one "%s" - (it will be replaced by the page title). - */ - void SetTitleFormat(const wxString& format); - - /** - Saves the user's settings for this frame (see - wxHtmlHelpController::WriteCustomization). - */ - void WriteCustomization(wxConfigBase* cfg, - const wxString& path = wxEmptyString); -}; - diff --git a/interface/html/helpwnd.h b/interface/html/helpwnd.h deleted file mode 100644 index 192661a073..0000000000 --- a/interface/html/helpwnd.h +++ /dev/null @@ -1,168 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: html/helpwnd.h -// Purpose: interface of wxHtmlHelpWindow -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxHtmlHelpWindow - @headerfile helpwnd.h wx/html/helpwnd.h - - This class is used by wxHtmlHelpController - to display help within a frame or dialog, but you can use it yourself to create - an embedded HTML help window. - - For example: - - @code - // m_embeddedHelpWindow is a wxHtmlHelpWindow - // m_embeddedHtmlHelp is a wxHtmlHelpController - - // Create embedded HTML Help window - m_embeddedHelpWindow = new wxHtmlHelpWindow; - m_embeddedHtmlHelp.UseConfig(config, rootPath); // Set your own config - object here - m_embeddedHtmlHelp.SetHelpWindow(m_embeddedHelpWindow); - m_embeddedHelpWindow-Create(this, - wxID_ANY, wxDefaultPosition, GetClientSize(), - wxTAB_TRAVERSAL|wxBORDER_NONE, wxHF_DEFAULT_STYLE); - m_embeddedHtmlHelp.AddBook(wxFileName(_T("doc.zip"))); - @endcode - - You should pass the style wxHF_EMBEDDED to the style parameter of - wxHtmlHelpController to allow - the embedded window to be destroyed independently of the help controller. - - @library{wxhtml} - @category{FIXME} -*/ -class wxHtmlHelpWindow : public wxWindow -{ -public: - //@{ - /** - Constructor. - Constructor. For the values of @e helpStyle, please see the documentation for - wxHtmlHelpController. - */ - wxHtmlHelpWindow(wxHtmlHelpData* data = NULL); - wxHtmlHelpWindow(wxWindow* parent, int wxWindowID, - const wxPoint& pos = wxDefaultPosition, - const wxSize& pos = wxDefaultSize, - int style = wxTAB_TRAVERSAL|wxBORDER_NONE, - int helpStyle = wxHF_DEFAULT_STYLE, - wxHtmlHelpData* data = NULL); - //@} - - /** - You may override this virtual method to add more buttons to the help window's - toolbar. @a toolBar is a pointer to the toolbar and @a style is the style - flag as passed to the Create method. - wxToolBar::Realize is called immediately after returning from this function. - See @e samples/html/helpview for an example. - */ - virtual void AddToolbarButtons(wxToolBar* toolBar, int style); - - /** - Creates the help window. See @ref wxhtmlhelpwindow() "the constructor" - for a description of the parameters. - */ - bool Create(wxWindow* parent, wxWindowID id, - const wxPoint& pos = wxDefaultPosition, - const wxSize& pos = wxDefaultSize, - int style = wxTAB_TRAVERSAL|wxBORDER_NONE, - int helpStyle = wxHF_DEFAULT_STYLE, - wxHtmlHelpData* data = NULL); - - /** - Creates contents panel. (May take some time.) - Protected. - */ - void CreateContents(); - - /** - Creates index panel. (May take some time.) - Protected. - */ - void CreateIndex(); - - /** - Creates search panel. - */ - void CreateSearch(); - - //@{ - /** - Displays page x. If not found it will give the user the choice of - searching books. - Looking for the page runs in these steps: - try to locate file named x (if x is for example "doc/howto.htm") - try to open starting page of book x - try to find x in contents (if x is for example "How To ...") - try to find x in index (if x is for example "How To ...") - The second form takes numeric ID as the parameter. - (uses extension to MS format, param name="ID" value=id) - */ - bool Display(const wxString& x); - bool Display(const int id); - //@} - - /** - Displays contents panel. - */ - bool DisplayContents(); - - /** - Displays index panel. - */ - bool DisplayIndex(); - - /** - Returns the wxHtmlHelpData object, which is usually a pointer to the - controller's data. - */ - wxHtmlHelpData* GetData(); - - /** - Search for given keyword. Optionally it searches through the index (mode = - wxHELP_SEARCH_INDEX), default the content (mode = wxHELP_SEARCH_ALL). - */ - bool KeywordSearch(const wxString& keyword, - wxHelpSearchMode mode = wxHELP_SEARCH_ALL); - - /** - Reads the user's settings for this window (see - wxHtmlHelpController::ReadCustomization) - */ - void ReadCustomization(wxConfigBase* cfg, - const wxString& path = wxEmptyString); - - /** - Refresh all panels. This is necessary if a new book was added. - Protected. - */ - void RefreshLists(); - - /** - Sets the frame's title format. @a format must contain exactly one "%s" - (it will be replaced by the page title). - */ - void SetTitleFormat(const wxString& format); - - /** - Associates a wxConfig object with the help window. It is recommended that you - use wxHtmlHelpController::UseConfig instead. - */ - void UseConfig(wxConfigBase* config, - const wxString& rootpath = wxEmptyString); - - /** - Saves the user's settings for this window(see - wxHtmlHelpController::WriteCustomization). - */ - void WriteCustomization(wxConfigBase* cfg, - const wxString& path = wxEmptyString); -}; - diff --git a/interface/html/htmlcell.h b/interface/html/htmlcell.h deleted file mode 100644 index 79c441f684..0000000000 --- a/interface/html/htmlcell.h +++ /dev/null @@ -1,732 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: html/htmlcell.h -// Purpose: interface of wxHtmlColourCell -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxHtmlColourCell - @headerfile htmlcell.h wx/html/htmlcell.h - - This cell changes the colour of either the background or the foreground. - - @library{wxhtml} - @category{FIXME} -*/ -class wxHtmlColourCell : public wxHtmlCell -{ -public: - /** - Constructor. - - @param clr - The color - @param flags - Can be one of following: - - - - - - - wxHTML_CLR_FOREGROUND - - - - - change color of text - - - - - - wxHTML_CLR_BACKGROUND - - - - - change background color - */ - wxHtmlColourCell(wxColour clr, int flags = wxHTML_CLR_FOREGROUND); -}; - - - -/** - @class wxHtmlWidgetCell - @headerfile htmlcell.h wx/html/htmlcell.h - - wxHtmlWidgetCell is a class that provides a connection between HTML cells and - widgets (an object derived - from wxWindow). You can use it to display things like forms, input boxes etc. - in an HTML window. - - wxHtmlWidgetCell takes care of resizing and moving window. - - @library{wxhtml} - @category{FIXME} -*/ -class wxHtmlWidgetCell : public wxHtmlCell -{ -public: - /** - Constructor. - - @param wnd - Connected window. It is parent window must be the wxHtmlWindow object within - which it is displayed! - @param w - Floating width. If non-zero width of wnd window is adjusted so that it is - always w percents of parent container's width. (For example w = 100 means - that the window - will always have same width as parent container) - */ - wxHtmlWidgetCell(wxWindow* wnd, int w = 0); -}; - - - -/** - @class wxHtmlCell - @headerfile htmlcell.h wx/html/htmlcell.h - - Internal data structure. It represents fragments of parsed HTML - page, the so-called @b cell - a word, picture, table, horizontal line and so on. - It is used by wxHtmlWindow and - wxHtmlWinParser to represent HTML page in memory. - - You can divide cells into two groups : @e visible cells with non-zero width and - height and @e helper cells (usually with zero width and height) that - perform special actions such as color or font change. - - @library{wxhtml} - @category{FIXME} - - @see @ref overview_cells "Cells Overview", wxHtmlContainerCell -*/ -class wxHtmlCell : public wxObject -{ -public: - /** - Constructor. - */ - wxHtmlCell(); - - /** - This method is used to adjust pagebreak position. The parameter is - variable that contains y-coordinate of page break (= horizontal line that - should not be crossed by words, images etc.). If this cell cannot be divided - into two pieces (each one on another page) then it moves the pagebreak - few pixels up. - Returns @true if pagebreak was modified, @false otherwise - Usage: - */ - virtual bool AdjustPagebreak(int* pagebreak); - - /** - Renders the cell. - - @param dc - Device context to which the cell is to be drawn - @param x,y - Coordinates of parent's upper left corner (origin). You must - add this to m_PosX,m_PosY when passing coordinates to dc's methods - Example : dc - DrawText("hello", x + m_PosX, y + m_PosY) - @param view_y1 - y-coord of the first line visible in window. This is - used to optimize rendering speed - @param view_y2 - y-coord of the last line visible in window. This is - used to optimize rendering speed - */ - virtual void Draw(wxDC& dc, int x, int y, int view_y1, - int view_y2); - - /** - This method is called instead of Draw() when the - cell is certainly out of the screen (and thus invisible). This is not - nonsense - some tags (like wxHtmlColourCell - or font setter) must be drawn even if they are invisible! - - @param dc - Device context to which the cell is to be drawn - @param x,y - Coordinates of parent's upper left corner. You must - add this to m_PosX,m_PosY when passing coordinates to dc's methods - Example : dc - DrawText("hello", x + m_PosX, y + m_PosY) - */ - virtual void DrawInvisible(wxDC& dc, int x, int y); - - /** - Returns pointer to itself if this cell matches condition (or if any of the cells - following in the list matches), @NULL otherwise. - (In other words if you call top-level container's Find it will - return pointer to the first cell that matches the condition) - It is recommended way how to obtain pointer to particular cell or - to cell of some type (e.g. wxHtmlAnchorCell reacts on - wxHTML_COND_ISANCHOR condition) - - @param condition - Unique integer identifier of condition - @param param - Optional parameters - */ - virtual const wxHtmlCell* Find(int condition, const void* param); - - /** - Returns descent value of the cell (m_Descent member). - See explanation: - */ - int GetDescent() const; - - /** - Returns pointer to the first cell in the list. - You can then use child's GetNext() - method to obtain pointer to the next cell in list. - @note This shouldn't be used by the end user. If you need some way of - finding particular cell in the list, try Find() method - instead. - */ - wxHtmlCell* GetFirstChild(); - - /** - Returns height of the cell (m_Height member). - */ - int GetHeight() const; - - /** - Returns unique cell identifier if there is any, empty string otherwise. - */ - virtual wxString GetId() const; - - /** - Returns hypertext link if associated with this cell or @NULL otherwise. - See wxHtmlLinkInfo. - (Note: this makes sense only for visible tags). - - @param x,y - Coordinates of position where the user pressed mouse button. - These coordinates are used e.g. by COLORMAP. Values are relative to the - upper left corner of THIS cell (i.e. from 0 to m_Width or m_Height) - */ - virtual wxHtmlLinkInfo* GetLink(int x = 0, int y = 0) const; - - /** - Returns cursor to show when mouse pointer is over the cell. - - @param window - interface to the parent HTML window - */ - virtual wxCursor GetMouseCursor(wxHtmlWindowInterface* window); - - /** - Returns pointer to the next cell in list (see htmlcell.h if you're - interested in details). - */ - wxHtmlCell* GetNext() const; - - /** - Returns pointer to parent container. - */ - wxHtmlContainerCell* GetParent() const; - - /** - Returns X position within parent (the value is relative to parent's - upper left corner). The returned value is meaningful only if - parent's Layout() was called before! - */ - int GetPosX() const; - - /** - Returns Y position within parent (the value is relative to parent's - upper left corner). The returned value is meaningful only if - parent's Layout() was called before! - */ - int GetPosY() const; - - /** - Returns width of the cell (m_Width member). - */ - int GetWidth() const; - - /** - This method performs two actions: - adjusts the cell's width according to the fact that maximal possible width is - @e w. - (this has sense when working with horizontal lines, tables etc.) - prepares layout (=fill-in m_PosX, m_PosY (and sometimes m_Height) members) - based on actual width @e w - It must be called before displaying cells structure because - m_PosX and m_PosY are undefined (or invalid) - before calling Layout. - */ - virtual void Layout(int w); - - /** - This function is simple event handler. Each time the user clicks mouse button - over a cell within wxHtmlWindow this method of that - cell is called. Default behavior is to call - wxHtmlWindow::LoadPage. - - @param window - interface to the parent HTML window - @param pos - coordinates of mouse click (this is relative to cell's origin - @param event - mouse event that triggered the call - - @return @true if a link was clicked, @false otherwise. - */ - virtual bool ProcessMouseClick(wxHtmlWindowInterface* window, - const wxPoint& pos, - const wxMouseEvent& event); - - /** - Sets unique cell identifier. Default value is no identifier, i.e. empty string. - */ - void SetId(const wxString& id); - - /** - Sets the hypertext link associated with this cell. (Default value - is wxHtmlLinkInfo("", "") (no link)) - */ - void SetLink(const wxHtmlLinkInfo& link); - - /** - Sets the next cell in the list. This shouldn't be called by user - it is - to be used only by wxHtmlContainerCell::InsertCell. - */ - void SetNext(wxHtmlCell cell); - - /** - Sets parent container of this cell. This is called from - wxHtmlContainerCell::InsertCell. - */ - void SetParent(wxHtmlContainerCell p); - - /** - Sets the cell's position within parent container. - */ - void SetPos(int x, int y); -}; - - - -/** - @class wxHtmlContainerCell - @headerfile htmlcell.h wx/html/htmlcell.h - - The wxHtmlContainerCell class is an implementation of a cell that may - contain more cells in it. It is heavily used in the wxHTML layout algorithm. - - @library{wxhtml} - @category{FIXME} - - @see @ref overview_cells "Cells Overview" -*/ -class wxHtmlContainerCell : public wxHtmlCell -{ -public: - /** - Constructor. @a parent is pointer to parent container or @NULL. - */ - wxHtmlContainerCell(wxHtmlContainerCell parent); - - /** - Returns container's horizontal alignment. - */ - int GetAlignHor() const; - - /** - Returns container's vertical alignment. - */ - int GetAlignVer() const; - - /** - Returns the background colour of the container or @c wxNullColour if no - background - colour is set. - */ - wxColour GetBackgroundColour(); - - /** - Returns the indentation. @a ind is one of the @b wxHTML_INDENT_* constants. - @note You must call GetIndentUnits() - with same @a ind parameter in order to correctly interpret the returned integer - value. - It is NOT always in pixels! - */ - int GetIndent(int ind) const; - - /** - Returns the units of indentation for @a ind where @a ind is one - of the @b wxHTML_INDENT_* constants. - */ - int GetIndentUnits(int ind) const; - - /** - Inserts new cell into the container. - */ - void InsertCell(wxHtmlCell cell); - - /** - Sets the container's alignment (both horizontal and vertical) according to - the values stored in @e tag. (Tags @c ALIGN parameter is extracted.) In fact - it is only a front-end to SetAlignHor() - and SetAlignVer(). - */ - void SetAlign(const wxHtmlTag& tag); - - /** - Sets the container's @e horizontal alignment. During wxHtmlCell::Layout - each line is aligned according to @a al value. - - @param al - new horizontal alignment. May be one of these values: - - - - - - - wxHTML_ALIGN_LEFT - - - - - lines are left-aligned (default) - - - - - - wxHTML_ALIGN_JUSTIFY - - - - - lines are justified - - - - - - wxHTML_ALIGN_CENTER - - - - - lines are centered - - - - - - wxHTML_ALIGN_RIGHT - - - - - lines are right-aligned - */ - void SetAlignHor(int al); - - /** - Sets the container's @e vertical alignment. This is per-line alignment! - - @param al - new vertical alignment. May be one of these values: - - - - - - - wxHTML_ALIGN_BOTTOM - - - - - cells are over the line (default) - - - - - - wxHTML_ALIGN_CENTER - - - - - cells are centered on line - - - - - - wxHTML_ALIGN_TOP - - - - - cells are under the line - */ - void SetAlignVer(int al); - - /** - Sets the background colour for this container. - */ - void SetBackgroundColour(const wxColour& clr); - - /** - Sets the border (frame) colours. A border is a rectangle around the container. - - @param clr1 - Colour of top and left lines - @param clr2 - Colour of bottom and right lines - */ - void SetBorder(const wxColour& clr1, const wxColour& clr2); - - /** - Sets the indentation (free space between borders of container and subcells). - - @param i - Indentation value. - @param what - Determines which of the four borders we're setting. It is OR - combination of following constants: - - - - - - - wxHTML_INDENT_TOP - - - - - top border - - - - - - wxHTML_INDENT_BOTTOM - - - - - bottom - - - - - - wxHTML_INDENT_LEFT - - - - - left - - - - - - wxHTML_INDENT_RIGHT - - - - - right - - - - - - wxHTML_INDENT_HORIZONTAL - - - - - left and right - - - - - - wxHTML_INDENT_VERTICAL - - - - - top and bottom - - - - - - wxHTML_INDENT_ALL - - - - - all 4 borders - @param units - Units of i. This parameter affects interpretation of value. - - - - - - - wxHTML_UNITS_PIXELS - - - - - i is number of pixels - - - - - - wxHTML_UNITS_PERCENT - - - - - i is interpreted as percents of width - of parent container - */ - void SetIndent(int i, int what, int units = wxHTML_UNITS_PIXELS); - - /** - Sets minimal height of the container. - When container's wxHtmlCell::Layout is called, m_Height - is set depending on layout of subcells to the height of area covered - by layed-out subcells. Calling this method guarantees you that the height - of container is never smaller than @a h - even if the subcells cover - much smaller area. - - @param h - The minimal height. - @param align - If height of the container is lower than the minimum height, empty space - must be inserted - somewhere in order to ensure minimal height. This parameter is one of - wxHTML_ALIGN_TOP, - wxHTML_ALIGN_BOTTOM, wxHTML_ALIGN_CENTER. It refers to the contents, not to - the - empty place. - */ - void SetMinHeight(int h, int align = wxHTML_ALIGN_TOP); - - //@{ - /** - Sets floating width adjustment. - The normal behaviour of container is that its width is the same as the width of - parent container (and thus you can have only one sub-container per line). - You can change this by setting FWA. - @a pixel_scale is number of real pixels that equals to 1 HTML pixel. - - @param w - Width of the container. If the value is negative it means - complement to full width of parent container (e.g. - SetWidthFloat(-50, wxHTML_UNITS_PIXELS) sets the width - of container to parent's width minus 50 pixels. This is useful when - creating tables - you can call SetWidthFloat(50) and SetWidthFloat(-50)) - @param units - Units of w This parameter affects the interpretation of value. - - - - - - - wxHTML_UNITS_PIXELS - - - - - w is number of pixels - - - - - - wxHTML_UNITS_PERCENT - - - - - w is interpreted as percents of width - of parent container - @param tag - In the second version of method, w and units - info is extracted from tag's WIDTH parameter. - */ - void SetWidthFloat(int w, int units); - void SetWidthFloat(const wxHtmlTag& tag, - double pixel_scale = 1.0); - //@} -}; - - - -/** - @class wxHtmlLinkInfo - @headerfile htmlcell.h wx/html/htmlcell.h - - This class stores all necessary information about hypertext - links (as represented by @c A tag in HTML documents). In - current implementation it stores URL and target frame name. - @e Note that frames are not currently supported by wxHTML! - - @library{wxhtml} - @category{FIXME} -*/ -class wxHtmlLinkInfo : public wxObject -{ -public: - //@{ - /** - Construct hypertext link from HREF (aka URL) and TARGET (name of target - frame). - */ - wxHtmlLinkInfo(); - wxHtmlLinkInfo(const wxString& href, - const wxString& target = wxEmptyString); - //@} - - /** - Return pointer to event that generated OnLinkClicked event. Valid - only within wxHtmlWindow::OnLinkClicked, - @NULL otherwise. - */ - const wxMouseEvent* GetEvent(); - - /** - Return @e HREF value of the @c A tag. - */ - wxString GetHref(); - - /** - Return pointer to the cell that was clicked. Valid - only within wxHtmlWindow::OnLinkClicked, - @NULL otherwise. - */ - const wxHtmlCell* GetHtmlCell(); - - /** - Return @e TARGET value of the @c A tag (this value - is used to specify in which frame should be the page pointed - by @ref gethref() Href opened). - */ - wxString GetTarget(); -}; - diff --git a/interface/html/htmlfilt.h b/interface/html/htmlfilt.h deleted file mode 100644 index 9a40dbcff1..0000000000 --- a/interface/html/htmlfilt.h +++ /dev/null @@ -1,41 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: html/htmlfilt.h -// Purpose: interface of wxHtmlFilter -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxHtmlFilter - @headerfile htmlfilt.h wx/html/htmlfilt.h - - This class is the parent class of input filters for wxHtmlWindow. - It allows you to read and display files of different file formats. - - @library{wxhtml} - @category{FIXME} - - @see Overview() -*/ -class wxHtmlFilter : public wxObject -{ -public: - /** - Constructor. - */ - wxHtmlFilter(); - - /** - Returns @true if this filter is capable of reading file @e file. - Example: - */ - bool CanRead(const wxFSFile& file); - - /** - Reads the file and returns string with HTML document. - Example: - */ - wxString ReadFile(const wxFSFile& file); -}; - diff --git a/interface/html/htmlpars.h b/interface/html/htmlpars.h deleted file mode 100644 index 1131d385b3..0000000000 --- a/interface/html/htmlpars.h +++ /dev/null @@ -1,270 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: html/htmlpars.h -// Purpose: interface of wxHtmlTagHandler -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxHtmlTagHandler - @headerfile htmlpars.h wx/html/htmlpars.h - - - @library{wxhtml} - @category{html} - - @see Overview(), wxHtmlTag -*/ -class wxHtmlTagHandler : public wxObject -{ -public: - /** - Constructor. - */ - wxHtmlTagHandler(); - - /** - Returns list of supported tags. The list is in uppercase and tags - are delimited by ','. Example : @c "I,B,FONT,P" - */ - virtual wxString GetSupportedTags(); - - /** - This is the core method of each handler. It is called each time - one of supported tags is detected. @a tag contains all necessary - info (see wxHtmlTag for details). - - @return @true if ParseInner was called, @false otherwise. - */ - virtual bool HandleTag(const wxHtmlTag& tag); - - /** - This method calls parser's wxHtmlParser::DoParsing method - for the string between this tag and the paired ending tag: - - In this example, a call to ParseInner (with @a tag pointing to A tag) - will parse 'Hello, world!'. - */ - void ParseInner(const wxHtmlTag& tag); - - /** - Assigns @a parser to this handler. Each @b instance of handler - is guaranteed to be called only from the parser. - */ - virtual void SetParser(wxHtmlParser parser); - - /** - @b wxHtmlParser* m_Parser - This attribute is used to access parent parser. It is protected so that - it can't be accessed by user but can be accessed from derived classes. - */ -}; - - - -/** - @class wxHtmlParser - @headerfile htmlpars.h wx/html/htmlpars.h - - Classes derived from this handle the @b generic parsing of HTML documents: it - scans - the document and divide it into blocks of tags (where one block - consists of beginning and ending tag and of text between these - two tags). - - It is independent from wxHtmlWindow and can be used as stand-alone parser - (Julian Smart's idea of speech-only HTML viewer or wget-like utility - - see InetGet sample for example). - - It uses system of tag handlers to parse the HTML document. Tag handlers - are not statically shared by all instances but are created for each - wxHtmlParser instance. The reason is that the handler may contain - document-specific temporary data used during parsing (e.g. complicated - structures like tables). - - Typically the user calls only the wxHtmlParser::Parse method. - - @library{wxhtml} - @category{html} - - @see @ref overview_cells "Cells Overview", @ref overview_handlers "Tag Handlers - Overview", wxHtmlTag -*/ -class wxHtmlParser -{ -public: - /** - Constructor. - */ - wxHtmlParser(); - - /** - This may (and may not) be overwritten in derived class. - This method is called each time new tag is about to be added. - @a tag contains information about the tag. (See wxHtmlTag - for details.) - Default (wxHtmlParser) behaviour is this: - First it finds a handler capable of handling this tag and then it calls - handler's HandleTag method. - */ - void AddTag(const wxHtmlTag& tag); - - /** - Adds handler to the internal list ( hash table) of handlers. This - method should not be called directly by user but rather by derived class' - constructor. - This adds the handler to this @b instance of wxHtmlParser, not to - all objects of this class! (Static front-end to AddTagHandler is provided - by wxHtmlWinParser). - All handlers are deleted on object deletion. - */ - virtual void AddTagHandler(wxHtmlTagHandler handler); - - /** - Must be overwritten in derived class. - This method is called by DoParsing() - each time a part of text is parsed. @a txt is NOT only one word, it is - substring of input. It is not formatted or preprocessed (so white spaces are - unmodified). - */ - virtual void AddWord(const wxString& txt); - - //@{ - /** - Parses the m_Source from begin_pos to end_pos-1. - (in noparams version it parses whole m_Source) - */ - void DoParsing(int begin_pos, int end_pos); - void DoParsing(); - //@} - - /** - This must be called after DoParsing(). - */ - virtual void DoneParser(); - - /** - Returns pointer to the file system. Because each tag handler has - reference to it is parent parser it can easily request the file by - calling - */ - wxFileSystem* GetFS() const; - - /** - Returns product of parsing. Returned value is result of parsing - of the document. The type of this result depends on internal - representation in derived parser (but it must be derived from wxObject!). - See wxHtmlWinParser for details. - */ - virtual wxObject* GetProduct(); - - /** - Returns pointer to the source being parsed. - */ - wxString* GetSource(); - - /** - Setups the parser for parsing the @a source string. (Should be overridden - in derived class) - */ - virtual void InitParser(const wxString& source); - - /** - Opens given URL and returns @c wxFSFile object that can be used to read data - from it. This method may return @NULL in one of two cases: either the URL doesn't - point to any valid resource or the URL is blocked by overridden implementation - of @e OpenURL in derived class. - - @param type - Indicates type of the resource. Is one of: - - - - - - - wxHTML_URL_PAGE - - - - - Opening a HTML page. - - - - - - wxHTML_URL_IMAGE - - - - - Opening an image. - - - - - - wxHTML_URL_OTHER - - - - - Opening a resource that doesn't fall into - any other category. - @param url - URL being opened. - */ - virtual wxFSFile* OpenURL(wxHtmlURLType type, - const wxString& url); - - /** - Proceeds parsing of the document. This is end-user method. You can simply - call it when you need to obtain parsed output (which is parser-specific) - The method does these things: - calls @ref initparser() InitParser(source) - calls DoParsing() - calls GetProduct() - calls DoneParser() - returns value returned by GetProduct - You shouldn't use InitParser, DoParsing, GetProduct or DoneParser directly. - */ - wxObject* Parse(const wxString& source); - - /** - Restores parser's state before last call to - PushTagHandler(). - */ - void PopTagHandler(); - - /** - Forces the handler to handle additional tags - (not returned by wxHtmlTagHandler::GetSupportedTags). - The handler should already be added to this parser. - - @param handler - the handler - @param tags - List of tags (in same format as GetSupportedTags's return value). The parser - will redirect these tags to handler (until call to PopTagHandler). - */ - void PushTagHandler(wxHtmlTagHandler* handler, - const wxString& tags); - - /** - Sets the virtual file system that will be used to request additional - files. (For example @c IMG tag handler requests wxFSFile with the - image data.) - */ - void SetFS(wxFileSystem fs); - - /** - Call this function to interrupt parsing from a tag handler. No more tags - will be parsed afterward. This function may only be called from - Parse() or any function called - by it (i.e. from tag handlers). - */ - void StopParsing(); -}; - diff --git a/interface/html/htmltag.h b/interface/html/htmltag.h deleted file mode 100644 index 974106a761..0000000000 --- a/interface/html/htmltag.h +++ /dev/null @@ -1,130 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: html/htmltag.h -// Purpose: interface of wxHtmlTag -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxHtmlTag - @headerfile htmltag.h wx/html/htmltag.h - - This class represents a single HTML tag. - It is used by @ref overview_handlers "tag handlers". - - @library{wxhtml} - @category{FIXME} -*/ -class wxHtmlTag -{ -public: - /** - Constructor. You will probably never have to construct a wxHtmlTag object - yourself. Feel free to ignore the constructor parameters. - Have a look at src/html/htmlpars.cpp if you're interested in creating it. - */ - wxHtmlTag(wxHtmlTag* parent, const wxString& source, int pos, - int end_pos, wxHtmlTagsCache* cache, - wxHtmlEntitiesParser* entParser); - - /** - Returns a string containing all parameters. - Example : tag contains @c FONT SIZE=+2 COLOR="#000000". Call to - tag.GetAllParams() would return @c SIZE=+2 COLOR="#000000". - */ - const wxString GetAllParams() const; - - /** - Returns beginning position of the text @e between this tag and paired - ending tag. - See explanation (returned position is marked with '|'): - */ - int GetBeginPos() const; - - /** - Returns ending position of the text @e between this tag and paired - ending tag. - See explanation (returned position is marked with '|'): - */ - int GetEndPos1() const; - - /** - Returns ending position 2 of the text @e between this tag and paired - ending tag. - See explanation (returned position is marked with '|'): - */ - int GetEndPos2() const; - - /** - Returns tag's name. The name is always in uppercase and it doesn't contain - " or '/' characters. (So the name of @c FONT SIZE=+2 tag is "FONT" - and name of @c /table is "TABLE") - */ - wxString GetName() const; - - /** - Returns the value of the parameter. You should check whether the - parameter exists or not (use wxHtmlTag::HasParam) first. - - @param par - The parameter's name. - @param with_quotes - @true if you want to get quotes as well. See example. - */ - wxString GetParam(const wxString& par, bool with_quotes = false) const; - - /** - Interprets tag parameter @a par as colour specification and saves its value - into wxColour variable pointed by @e clr. - Returns @true on success and @false if @a par is not colour specification or - if the tag has no such parameter. - */ - bool GetParamAsColour(const wxString& par, wxColour* clr) const; - - /** - Interprets tag parameter @a par as an integer and saves its value - into int variable pointed by @e value. - Returns @true on success and @false if @a par is not an integer or - if the tag has no such parameter. - */ - bool GetParamAsInt(const wxString& par, int* value) const; - - /** - Returns @true if this tag is paired with ending tag, @false otherwise. - See the example of HTML document: - - In this example tags HTML and BODY have ending tags, first P and BR - doesn't have ending tag while the second P has. The third P tag (which - is ending itself) of course doesn't have ending tag. - */ - bool HasEnding() const; - - /** - Returns @true if the tag has a parameter of the given name. - Example : @c FONT SIZE=+2 COLOR="#FF00FF" has two parameters named - "SIZE" and "COLOR". - - @param par - the parameter you're looking for. - */ - bool HasParam(const wxString& par) const; - - /** - This method scans the given parameter. Usage is exactly the same as sscanf's - usage except that you don't pass a string but a parameter name as the first - argument - and you can only retrieve one value (i.e. you can use only one "%" element - in @e format). - - @param par - The name of the tag you want to query - @param format - scanf()-like format string. - @param value - pointer to a variable to store the value in - */ - wxString ScanParam(const wxString& par, const wxChar* format, - void* value) const; -}; - diff --git a/interface/html/htmlwin.h b/interface/html/htmlwin.h deleted file mode 100644 index 3b6ccc2912..0000000000 --- a/interface/html/htmlwin.h +++ /dev/null @@ -1,483 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: html/htmlwin.h -// Purpose: interface of wxHtmlWindow -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxHtmlWindow - @headerfile htmlwin.h wx/html/htmlwin.h - - wxHtmlWindow is probably the only class you will directly use - unless you want to do something special (like adding new tag - handlers or MIME filters). - - The purpose of this class is to display HTML pages (either local - file or downloaded via HTTP protocol) in a window. The width - of the window is constant - given in the constructor - and virtual height - is changed dynamically depending on page size. - Once the window is created you can set its content by calling - @ref wxHtmlWindow::setpage SetPage(text), - @ref wxHtmlWindow::loadpage LoadPage(filename) or - wxHtmlWindow::LoadFile. - - @beginStyleTable - @style{wxHW_SCROLLBAR_NEVER} - Never display scrollbars, not even when the page is larger than the - window. - @style{wxHW_SCROLLBAR_AUTO} - Display scrollbars only if page's size exceeds window's size. - @style{wxHW_NO_SELECTION} - Don't allow the user to select text. - @endStyleTable - - @library{wxhtml} - @category{html} - - @see wxHtmlLinkEvent, wxHtmlCellEvent -*/ -class wxHtmlWindow : public wxScrolledWindow -{ -public: - //@{ - /** - Constructor. The parameters are the same as wxScrolled::wxScrolled() - constructor. - - @param style - Window style. See wxHtmlWindow. - */ - wxHtmlWindow(); - wxHtmlWindow(wxWindow parent, wxWindowID id = -1, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = wxHW_DEFAULT_STYLE, - const wxString& name = "htmlWindow"); - //@} - - /** - Adds @ref overview_filters "input filter" to the static list of available - filters. These filters are present by default: - @c text/html MIME type - @c image/* MIME types - Plain Text filter (this filter is used if no other filter matches) - */ - static void AddFilter(wxHtmlFilter filter); - - /** - Appends HTML fragment to currently displayed text and refreshes the window. - - @param source - HTML code fragment - - @return @false if an error occurred, @true otherwise. - */ - bool AppendToPage(const wxString& source); - - /** - Returns pointer to the top-level container. - See also: @ref overview_cells "Cells Overview", - @ref overview_printing - */ - wxHtmlContainerCell* GetInternalRepresentation() const; - - /** - Returns anchor within currently opened page - (see wxHtmlWindow::GetOpenedPage). - If no page is opened or if the displayed page wasn't - produced by call to LoadPage, empty string is returned. - */ - wxString GetOpenedAnchor(); - - /** - Returns full location of the opened page. If no page is opened or if the - displayed page wasn't - produced by call to LoadPage, empty string is returned. - */ - wxString GetOpenedPage(); - - /** - Returns title of the opened page or wxEmptyString if current page does not - contain @c TITLE tag. - */ - wxString GetOpenedPageTitle(); - - /** - Returns the related frame. - */ - wxFrame* GetRelatedFrame() const; - - /** - Moves back to the previous page. (each page displayed using - LoadPage() is stored in history list.) - */ - bool HistoryBack(); - - /** - Returns @true if it is possible to go back in the history (i.e. HistoryBack() - won't fail). - */ - bool HistoryCanBack(); - - /** - Returns @true if it is possible to go forward in the history (i.e. HistoryBack() - won't fail). - */ - bool HistoryCanForward(); - - /** - Clears history. - */ - void HistoryClear(); - - /** - Moves to next page in history. - */ - bool HistoryForward(); - - /** - Loads HTML page from file and displays it. - - @return @false if an error occurred, @true otherwise - - @see LoadPage() - */ - virtual bool LoadFile(const wxFileName& filename); - - /** - Unlike SetPage this function first loads HTML page from @a location - and then displays it. See example: - - @param location - The address of document. See wxFileSystem for details on address format and - behaviour of "opener". - - @return @false if an error occurred, @true otherwise - - @see LoadFile() - */ - virtual bool LoadPage(const wxString& location); - - /** - This method is called when a mouse button is clicked inside wxHtmlWindow. - The default behaviour is to emit a wxHtmlCellEvent - and, if the event was not processed or skipped, call - OnLinkClicked() if the cell contains an - hypertext link. - Overloading this method is deprecated; intercept the event instead. - - @param cell - The cell inside which the mouse was clicked, always a simple - (i.e. non-container) cell - @param x, y - The logical coordinates of the click point - @param event - The mouse event containing other information about the click - - @return @true if a link was clicked, @false otherwise. - */ - virtual bool OnCellClicked(wxHtmlCell cell, wxCoord x, wxCoord y, - const wxMouseEvent& event); - - /** - This method is called when a mouse moves over an HTML cell. - Default behaviour is to emit a wxHtmlCellEvent. - Overloading this method is deprecated; intercept the event instead. - - @param cell - The cell inside which the mouse is currently, always a simple - (i.e. non-container) cell - @param x, y - The logical coordinates of the click point - */ - virtual void OnCellMouseHover(wxHtmlCell cell, wxCoord x, - wxCoord y); - - /** - Called when user clicks on hypertext link. Default behaviour is to emit a - wxHtmlLinkEvent and, if the event was not processed - or skipped, call LoadPage() and do nothing else. - Overloading this method is deprecated; intercept the event instead. - Also see wxHtmlLinkInfo. - */ - virtual void OnLinkClicked(const wxHtmlLinkInfo& link); - - /** - Called when an URL is being opened (either when the user clicks on a link or - an image is loaded). The URL will be opened only if OnOpeningURL returns - @c wxHTML_OPEN. This method is called by - wxHtmlParser::OpenURL. - You can override OnOpeningURL to selectively block some - URLs (e.g. for security reasons) or to redirect them elsewhere. Default - behaviour is to always return @c wxHTML_OPEN. - - @param type - Indicates type of the resource. Is one of - - - - - - - wxHTML_URL_PAGE - - - - - Opening a HTML page. - - - - - - wxHTML_URL_IMAGE - - - - - Opening an image. - - - - - - wxHTML_URL_OTHER - - - - - Opening a resource that doesn't fall into - any other category. - @param url - URL being opened. - @param redirect - Pointer to wxString variable that must be filled with an - URL if OnOpeningURL returns wxHTML_REDIRECT. - */ - virtual wxHtmlOpeningStatus OnOpeningURL(wxHtmlURLType type, - const wxString& url, - wxString* redirect); - - /** - Called on parsing @c TITLE tag. - */ - virtual void OnSetTitle(const wxString& title); - - /** - This reads custom settings from wxConfig. It uses the path 'path' - if given, otherwise it saves info into currently selected path. - The values are stored in sub-path @c wxHtmlWindow - Read values: all things set by SetFonts, SetBorders. - - @param cfg - wxConfig from which you want to read the configuration. - @param path - Optional path in config tree. If not given current path is used. - */ - virtual void ReadCustomization(wxConfigBase cfg, - wxString path = wxEmptyString); - - /** - Selects all text in the window. - - @see SelectLine(), SelectWord() - */ - void SelectAll(); - - /** - Selects the line of text that @a pos points at. Note that @e pos - is relative to the top of displayed page, not to window's origin, use - wxScrolled::CalcUnscrolledPosition() - to convert physical coordinate. - - @see SelectAll(), SelectWord() - */ - void SelectLine(const wxPoint& pos); - - /** - Selects the word at position @e pos. Note that @e pos - is relative to the top of displayed page, not to window's origin, use - wxScrolled::CalcUnscrolledPosition() - to convert physical coordinate. - - @see SelectAll(), SelectLine() - */ - void SelectWord(const wxPoint& pos); - - /** - Returns current selection as plain text. Returns empty string if no text - is currently selected. - */ - wxString SelectionToText(); - - /** - This function sets the space between border of window and HTML contents. See - image: - - @param b - indentation from borders in pixels - */ - void SetBorders(int b); - - /** - This function sets font sizes and faces. - - @param normal_face - This is face name for normal (i.e. non-fixed) font. - It can be either empty string (then the default face is chosen) or - platform-specific face name. Examples are "helvetica" under Unix or - "Times New Roman" under Windows. - @param fixed_face - The same thing for fixed face ( TT../TT ) - @param sizes - This is an array of 7 items of int type. - The values represent size of font with HTML size from -2 to +4 - ( FONT SIZE=-2 to FONT SIZE=+4 ). Default sizes are used if sizes - is @NULL. - */ - void SetFonts(const wxString& normal_face, - const wxString& fixed_face, - const int sizes = NULL); - - /** - Sets HTML page and display it. This won't @b load the page!! - It will display the @e source. See example: - - If you want to load a document from some location use - LoadPage() instead. - - @param source - The HTML document source to be displayed. - - @return @false if an error occurred, @true otherwise. - */ - bool SetPage(const wxString& source); - - /** - Sets the frame in which page title will be displayed. @a format is format of - frame title, e.g. "HtmlHelp : %s". It must contain exactly one %s. This - %s is substituted with HTML page title. - */ - void SetRelatedFrame(wxFrame* frame, const wxString& format); - - /** - @b After calling SetRelatedFrame(), - this sets statusbar slot where messages will be displayed. - (Default is -1 = no messages.) - - @param index - Statusbar slot number (0..n) - */ - void SetRelatedStatusBar(int index); - - /** - @b Sets the associated statusbar where messages will be displayed. - Call this instead of SetRelatedFrame() if you want statusbar updates only, - no changing of the frame title. - - @param statusbar - Statusbar pointer - @param index - Statusbar slot number (0..n) - - @since 2.9.0 - */ - void SetRelatedStatusBar(wxStatusBar* statusbar, int index = 0); - - /** - Returns content of currently displayed page as plain text. - */ - wxString ToText(); - - /** - Saves custom settings into wxConfig. It uses the path 'path' - if given, otherwise it saves info into currently selected path. - Regardless of whether the path is given or not, the function creates sub-path - @c wxHtmlWindow. - Saved values: all things set by SetFonts, SetBorders. - - @param cfg - wxConfig to which you want to save the configuration. - @param path - Optional path in config tree. If not given, the current path is used. - */ - virtual void WriteCustomization(wxConfigBase cfg, - wxString path = wxEmptyString); -}; - - - -/** - @class wxHtmlLinkEvent - @headerfile htmlwin.h wx/html/htmlwin.h - - This event class is used for the events generated by wxHtmlWindow. - - @library{wxhtml} - @category{FIXME} -*/ -class wxHtmlLinkEvent : public wxCommandEvent -{ -public: - /** - The constructor is not normally used by the user code. - */ - wxHyperlinkEvent(int id, const wxHtmlLinkInfo& linkinfo); - - /** - Returns the wxHtmlLinkInfo which contains info about the cell clicked and the - hyperlink it contains. - */ - const wxHtmlLinkInfo GetLinkInfo() const; -}; - - - -/** - @class wxHtmlCellEvent - @headerfile htmlwin.h wx/html/htmlwin.h - - This event class is used for the events generated by wxHtmlWindow. - - @library{wxhtml} - @category{FIXME} -*/ -class wxHtmlCellEvent : public wxCommandEvent -{ -public: - /** - The constructor is not normally used by the user code. - */ - wxHtmlCellEvent(wxEventType commandType, int id, - wxHtmlCell* cell, - const wxPoint& point); - - /** - Returns the wxHtmlCellEvent associated with the event. - */ - wxHtmlCell* GetCell() const; - - /** - Returns @true if @ref setlinkclicked() SetLinkClicked(@true) has previously - been called; - @false otherwise. - */ - bool GetLinkClicked() const; - - /** - Returns the wxPoint associated with the event. - */ - wxPoint GetPoint() const; - - /** - Call this function with @c linkclicked set to @true if the cell which has - been clicked contained a link or - @false otherwise (which is the default). With this function the event handler - can return info to the - wxHtmlWindow which sent the event. - */ - bool SetLinkClicked(bool linkclicked); -}; - diff --git a/interface/html/htmprint.h b/interface/html/htmprint.h deleted file mode 100644 index 7e5cb99a06..0000000000 --- a/interface/html/htmprint.h +++ /dev/null @@ -1,330 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: html/htmprint.h -// Purpose: interface of wxHtmlDCRenderer -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxHtmlDCRenderer - @headerfile htmprint.h wx/html/htmprint.h - - This class can render HTML document into a specified area of a DC. You can use - it - in your own printing code, although use of wxHtmlEasyPrinting - or wxHtmlPrintout is strongly recommended. - - @library{wxhtml} - @category{FIXME} -*/ -class wxHtmlDCRenderer : public wxObject -{ -public: - /** - Constructor. - */ - wxHtmlDCRenderer(); - - /** - Returns the height of the HTML text. This is important if area height (see - wxHtmlDCRenderer::SetSize) - is smaller that total height and thus the page cannot fit into it. In that case - you're supposed to - call Render() as long as its return value is smaller than GetTotalHeight's. - */ - int GetTotalHeight(); - - /** - Renders HTML text to the DC. - - @param x,y - position of upper-left corner of printing rectangle (see SetSize) - @param from - y-coordinate of the very first visible cell - @param dont_render - if @true then this method only returns y coordinate of the next page - and does not output anything - */ - int Render(int x, int y, int from = 0, int dont_render = false); - - /** - Assign DC instance to the renderer. - @a pixel_scale can be used when rendering to high-resolution DCs (e.g. printer) - to adjust size of pixel metrics. - (Many dimensions in HTML are given in pixels -- e.g. image sizes. 300x300 image - would be only one - inch wide on typical printer. With pixel_scale = 3.0 it would be 3 inches.) - */ - void SetDC(wxDC* dc, double pixel_scale = 1.0); - - /** - Sets fonts. See wxHtmlWindow::SetFonts for - detailed description. - See also SetSize(). - */ - void SetFonts(const wxString& normal_face, - const wxString& fixed_face, - const int sizes = NULL); - - /** - Assign text to the renderer. Render() then draws - the text onto DC. - - @param html - HTML text. This is not a filename. - @param basepath - base directory (html string would be stored there if it was in - file). It is used to determine path for loading images, for example. - @param isdir - @false if basepath is filename, @true if it is directory name - (see wxFileSystem for detailed explanation) - */ - void SetHtmlText(const wxString& html, - const wxString& basepath = wxEmptyString, - bool isdir = true); - - /** - Set size of output rectangle, in pixels. Note that you @b can't change - width of the rectangle between calls to wxHtmlDCRenderer::Render! - (You can freely change height.) - */ - void SetSize(int width, int height); -}; - - - -/** - @class wxHtmlEasyPrinting - @headerfile htmprint.h wx/html/htmprint.h - - This class provides very simple interface to printing - architecture. It allows you to print HTML documents using - only a few commands. - - @library{wxhtml} - @category{html} -*/ -class wxHtmlEasyPrinting : public wxObject -{ -public: - /** - Constructor. - - @param name - Name of the printing object. Used by preview frames and setup dialogs. - @param parentWindow - pointer to the window that will own the preview frame and setup dialogs. - May be @NULL. - */ - wxHtmlEasyPrinting(const wxString& name = "Printing", - wxWindow* parentWindow = NULL); - - /** - Returns a pointer to wxPageSetupDialogData instance used by - this class. You can set its parameters (via SetXXXX methods). - */ - wxPageSetupDialogData* GetPageSetupData(); - - /** - Gets the parent window for dialogs. - */ - wxWindow* GetParentWindow() const; - - /** - Returns pointer to wxPrintData instance used by this class. You can - set its parameters (via SetXXXX methods). - */ - wxPrintData* GetPrintData(); - - /** - Display page setup dialog and allows the user to modify settings. - */ - void PageSetup(); - - /** - Preview HTML file. - Returns @false in case of error -- call - wxPrinter::GetLastError to get detailed - information about the kind of the error. - */ - bool PreviewFile(const wxString& htmlfile); - - /** - Preview HTML text (not file!). - Returns @false in case of error -- call - wxPrinter::GetLastError to get detailed - information about the kind of the error. - - @param htmltext - HTML text. - @param basepath - base directory (html string would be stored there if it was in - file). It is used to determine path for loading images, for example. - */ - bool PreviewText(const wxString& htmltext, - const wxString& basepath = wxEmptyString); - - /** - Print HTML file. - Returns @false in case of error -- call - wxPrinter::GetLastError to get detailed - information about the kind of the error. - */ - bool PrintFile(const wxString& htmlfile); - - /** - Print HTML text (not file!). - Returns @false in case of error -- call - wxPrinter::GetLastError to get detailed - information about the kind of the error. - - @param htmltext - HTML text. - @param basepath - base directory (html string would be stored there if it was in - file). It is used to determine path for loading images, for example. - */ - bool PrintText(const wxString& htmltext, - const wxString& basepath = wxEmptyString); - - /** - Sets fonts. See wxHtmlWindow::SetFonts for - detailed description. - */ - void SetFonts(const wxString& normal_face, - const wxString& fixed_face, - const int sizes = NULL); - - /** - Set page footer. The following macros can be used inside it: - @DATE@ is replaced by the current date in default format - @PAGENUM@ is replaced by page number - @PAGESCNT@ is replaced by total number of pages - @TIME@ is replaced by the current time in default format - @TITLE@ is replaced with the title of the document - - @param footer - HTML text to be used as footer. - @param pg - one of wxPAGE_ODD, wxPAGE_EVEN and wxPAGE_ALL constants. - */ - void SetFooter(const wxString& footer, int pg = wxPAGE_ALL); - - /** - Set page header. The following macros can be used inside it: - @DATE@ is replaced by the current date in default format - @PAGENUM@ is replaced by page number - @PAGESCNT@ is replaced by total number of pages - @TIME@ is replaced by the current time in default format - @TITLE@ is replaced with the title of the document - - @param header - HTML text to be used as header. - @param pg - one of wxPAGE_ODD, wxPAGE_EVEN and wxPAGE_ALL constants. - */ - void SetHeader(const wxString& header, int pg = wxPAGE_ALL); - - /** - Sets the parent window for dialogs. - */ - void SetParentWindow(wxWindow* window); -}; - - - -/** - @class wxHtmlPrintout - @headerfile htmprint.h wx/html/htmprint.h - - This class serves as printout class for HTML documents. - - @library{wxhtml} - @category{html} -*/ -class wxHtmlPrintout : public wxPrintout -{ -public: - /** - Constructor. - */ - wxHtmlPrintout(const wxString& title = "Printout"); - - /** - Adds a filter to the static list of filters for wxHtmlPrintout. See - wxHtmlFilter for - further information. - */ - static void AddFilter(wxHtmlFilter* filter); - - /** - Sets fonts. See wxHtmlWindow::SetFonts for - detailed description. - */ - void SetFonts(const wxString& normal_face, - const wxString& fixed_face, - const int sizes = NULL); - - /** - Set page footer. The following macros can be used inside it: - @DATE@ is replaced by the current date in default format - @PAGENUM@ is replaced by page number - @PAGESCNT@ is replaced by total number of pages - @TIME@ is replaced by the current time in default format - @TITLE@ is replaced with the title of the document - - @param footer - HTML text to be used as footer. - @param pg - one of wxPAGE_ODD, wxPAGE_EVEN and wxPAGE_ALL constants. - */ - void SetFooter(const wxString& footer, int pg = wxPAGE_ALL); - - /** - Set page header. The following macros can be used inside it: - @DATE@ is replaced by the current date in default format - @PAGENUM@ is replaced by page number - @PAGESCNT@ is replaced by total number of pages - @TIME@ is replaced by the current time in default format - @TITLE@ is replaced with the title of the document - - @param header - HTML text to be used as header. - @param pg - one of wxPAGE_ODD, wxPAGE_EVEN and wxPAGE_ALL constants. - */ - void SetHeader(const wxString& header, int pg = wxPAGE_ALL); - - /** - Prepare the class for printing this HTML @b file. The file may be located on - any virtual file system or it may be normal file. - */ - void SetHtmlFile(const wxString& htmlfile); - - /** - Prepare the class for printing this HTML text. - - @param html - HTML text. (NOT file!) - @param basepath - base directory (html string would be stored there if it was in - file). It is used to determine path for loading images, for example. - @param isdir - @false if basepath is filename, @true if it is directory name - (see wxFileSystem for detailed explanation) - */ - void SetHtmlText(const wxString& html, - const wxString& basepath = wxEmptyString, - bool isdir = true); - - /** - Sets margins in millimeters. Defaults to 1 inch for margins and 0.5cm for space - between text and header and/or footer - */ - void SetMargins(float top = 25.2, float bottom = 25.2, - float left = 25.2, - float right = 25.2, - float spaces = 5); -}; - diff --git a/interface/html/winpars.h b/interface/html/winpars.h deleted file mode 100644 index ed5d5348b1..0000000000 --- a/interface/html/winpars.h +++ /dev/null @@ -1,314 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: html/winpars.h -// Purpose: interface of wxHtmlTagsModule -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxHtmlTagsModule - @headerfile winpars.h wx/html/winpars.h - - This class provides easy way of filling wxHtmlWinParser's table of - tag handlers. It is used almost exclusively together with the set of - @ref overview_handlers "TAGS_MODULE_* macros" - - @library{wxhtml} - @category{FIXME} - - @see @ref overview_handlers "Tag Handlers", wxHtmlTagHandler, - wxHtmlWinTagHandler, -*/ -class wxHtmlTagsModule : public wxModule -{ -public: - /** - You must override this method. In most common case its body consists - only of lines of the following type: - - I recommend using the @b TAGS_MODULE_* macros. - - @param parser - Pointer to the parser that requested tables filling. - */ - virtual void FillHandlersTable(wxHtmlWinParser parser); -}; - - - -/** - @class wxHtmlWinTagHandler - @headerfile winpars.h wx/html/winpars.h - - This is basically wxHtmlTagHandler except that - it is extended with protected member m_WParser pointing to - the wxHtmlWinParser object (value of this member is identical - to wxHtmlParser's m_Parser). - - @library{wxhtml} - @category{html} -*/ -class wxHtmlWinTagHandler : public wxHtmlTagHandler -{ -public: - /** - @b wxHtmlWinParser* m_WParser - Value of this attribute is identical to value of m_Parser. The only different - is that m_WParser points to wxHtmlWinParser object while m_Parser - points to wxHtmlParser object. (The same object, but overcast.) - */ -}; - - - -/** - @class wxHtmlWinParser - @headerfile winpars.h wx/html/winpars.h - - This class is derived from wxHtmlParser and - its main goal is to parse HTML input so that it can be displayed in - wxHtmlWindow. It uses a special - wxHtmlWinTagHandler. - - @library{wxhtml} - @category{html} - - @see @ref overview_handlers "Handlers overview" -*/ -class wxHtmlWinParser : public wxHtmlParser -{ -public: - //@{ - /** - Constructor. Don't use the default one, use constructor with - @a wndIface parameter (@a wndIface is a pointer to interface object for - the associated wxHtmlWindow or other HTML rendering - window such as wxHtmlListBox). - */ - wxHtmlWinParser(); - wxHtmlWinParser(wxHtmlWindowInterface wndIface); - //@} - - /** - Adds module() to the list of wxHtmlWinParser tag handler. - */ - static void AddModule(wxHtmlTagsModule module); - - /** - Closes the container, sets actual container to the parent one - and returns pointer to it (see Overview()). - */ - wxHtmlContainerCell* CloseContainer(); - - /** - Creates font based on current setting (see - SetFontSize(), - SetFontBold(), - SetFontItalic(), - SetFontFixed(), - wxHtmlWinParser::SetFontUnderlined) - and returns pointer to it. - If the font was already created only a pointer is returned. - */ - virtual wxFont* CreateCurrentFont(); - - /** - Returns actual text colour. - */ - const wxColour GetActualColor() const; - - /** - Returns default horizontal alignment. - */ - int GetAlign() const; - - /** - Returns (average) char height in standard font. It is used as DC-independent - metrics. - @note This function doesn't return the @e actual height. If you want to - know the height of the current font, call @c GetDC - GetCharHeight(). - */ - int GetCharHeight() const; - - /** - Returns average char width in standard font. It is used as DC-independent - metrics. - @note This function doesn't return the @e actual width. If you want to - know the height of the current font, call @c GetDC - GetCharWidth() - */ - int GetCharWidth() const; - - /** - Returns pointer to the currently opened container (see Overview()). - Common use: - */ - wxHtmlContainerCell* GetContainer() const; - - /** - Returns pointer to the DC used during parsing. - */ - wxDC* GetDC(); - - /** - Returns wxEncodingConverter class used - to do conversion between @ref getinputencoding() "input encoding" - and @ref getoutputencoding() "output encoding". - */ - wxEncodingConverter* GetEncodingConverter() const; - - /** - Returns @true if actual font is bold, @false otherwise. - */ - int GetFontBold() const; - - /** - Returns actual font face name. - */ - wxString GetFontFace() const; - - /** - Returns @true if actual font is fixed face, @false otherwise. - */ - int GetFontFixed() const; - - /** - Returns @true if actual font is italic, @false otherwise. - */ - int GetFontItalic() const; - - /** - Returns actual font size (HTML size varies from -2 to +4) - */ - int GetFontSize() const; - - /** - Returns @true if actual font is underlined, @false otherwise. - */ - int GetFontUnderlined() const; - - /** - Returns input encoding. - */ - wxFontEncoding GetInputEncoding() const; - - /** - Returns actual hypertext link. (This value has a non-empty - @ref wxHtmlLinkInfo::gethref Href string - if the parser is between @c A and @c /A tags, - wxEmptyString otherwise.) - */ - const wxHtmlLinkInfo GetLink() const; - - /** - Returns the colour of hypertext link text. - */ - const wxColour GetLinkColor() const; - - /** - Returns output encoding, i.e. closest match to document's input encoding - that is supported by operating system. - */ - wxFontEncoding GetOutputEncoding() const; - - /** - Returns associated window (wxHtmlWindow). This may be @NULL! (You should always - test if it is non-@NULL. For example @c TITLE handler sets window - title only if some window is associated, otherwise it does nothing) - */ - wxHtmlWindow* GetWindow(); - - /** - Opens new container and returns pointer to it (see Overview()). - */ - wxHtmlContainerCell* OpenContainer(); - - /** - Sets actual text colour. Note: this DOESN'T change the colour! - You must create wxHtmlColourCell yourself. - */ - void SetActualColor(const wxColour& clr); - - /** - Sets default horizontal alignment (see - wxHtmlContainerCell::SetAlignHor.) - Alignment of newly opened container is set to this value. - */ - void SetAlign(int a); - - /** - Allows you to directly set opened container. This is not recommended - you - should use OpenContainer - wherever possible. - */ - wxHtmlContainerCell* SetContainer(wxHtmlContainerCell* c); - - /** - Sets the DC. This must be called before wxHtmlParser::Parse! - @a pixel_scale can be used when rendering to high-resolution - DCs (e.g. printer) to adjust size of pixel metrics. (Many dimensions in - HTML are given in pixels -- e.g. image sizes. 300x300 image would be only one - inch wide on typical printer. With pixel_scale = 3.0 it would be 3 inches.) - */ - virtual void SetDC(wxDC dc, double pixel_scale = 1.0); - - /** - Sets bold flag of actualfont. @a x is either @true of @false. - */ - void SetFontBold(int x); - - /** - Sets current font face to @e face. This affects either fixed size - font or proportional, depending on context (whether the parser is - inside @c TT tag or not). - */ - void SetFontFace(const wxString& face); - - /** - Sets fixed face flag of actualfont. @a x is either @true of @false. - */ - void SetFontFixed(int x); - - /** - Sets italic flag of actualfont. @a x is either @true of @false. - */ - void SetFontItalic(int x); - - /** - Sets actual font size (HTML size varies from 1 to 7) - */ - void SetFontSize(int s); - - /** - Sets underlined flag of actualfont. @a x is either @true of @false. - */ - void SetFontUnderlined(int x); - - /** - Sets fonts. See wxHtmlWindow::SetFonts for - detailed description. - */ - void SetFonts(const wxString& normal_face, - const wxString& fixed_face, - const int sizes = NULL); - - /** - Sets input encoding. The parser uses this information to build conversion - tables from document's encoding to some encoding supported by operating - system. - */ - void SetInputEncoding(wxFontEncoding enc); - - /** - Sets actual hypertext link. Empty link is represented - by wxHtmlLinkInfo with @e Href equal - to wxEmptyString. - */ - void SetLink(const wxHtmlLinkInfo& link); - - /** - Sets colour of hypertext link. - */ - void SetLinkColor(const wxColour& clr); -}; - diff --git a/interface/htmllbox.h b/interface/htmllbox.h deleted file mode 100644 index 150398f04b..0000000000 --- a/interface/htmllbox.h +++ /dev/null @@ -1,240 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: htmllbox.h -// Purpose: interface of wxHtmlListBox -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxHtmlListBox - @wxheader{htmllbox.h} - - wxHtmlListBox is an implementation of wxVListBox which - shows HTML content in the listbox rows. This is still an abstract base class - and you will need to derive your own class from it (see htlbox sample for the - example) but you will only need to override a single - wxHtmlListBox::OnGetItem function. - - @library{wxhtml} - @category{ctrl} - - - @see wxSimpleHtmlListBox -*/ -class wxHtmlListBox : public wxVListBox -{ -public: - //@{ - /** - Default constructor, you must call Create() - later. - */ - wxHtmlListBox(wxWindow* parent, wxWindowID id = wxID_ANY, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = 0, - const wxString& name = wxHtmlListBoxNameStr); - wxHtmlListBox(); - //@} - - /** - Destructor cleans up whatever resources we use. - */ - ~wxHtmlListBox(); - - /** - Creates the control and optionally sets the initial number of items in it - (it may also be set or changed later with - wxVListBox::SetItemCount). - There are no special styles defined for wxHtmlListBox, in particular the - wxListBox styles (with the exception of @c wxLB_MULTIPLE) can not be used here. - Returns @true on success or @false if the control couldn't be created - */ - bool Create(wxWindow* parent, wxWindowID id = wxID_ANY, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = 0, - const wxString& name = wxHtmlListBoxNameStr); - - //@{ - /** - Returns the wxFileSystem used by the HTML parser of - this object. The file system object is used to resolve the paths in HTML - fragments displayed in the control and you should use - wxFileSystem::ChangePathTo if you use - relative paths for the images or other resources embedded in your HTML. - */ - wxFileSystem GetFileSystem() const; - const wxFileSystem GetFileSystem() const; - //@} - - /** - This virtual function may be overridden to change the appearance of the - background of the selected cells in the same way as - GetSelectedTextColour(). - It should be rarely, if ever, used because - wxVListBox::SetSelectionBackground allows to - change the selection background for all cells at once and doing anything more - fancy is probably going to look strangely. - - @see GetSelectedTextColour() - */ - wxColour GetSelectedTextBgColour(const wxColour& colBg) const; - - /** - This virtual function may be overridden to customize the appearance of the - selected cells. It is used to determine how the colour @a colFg is going to - look inside selection. By default all original colours are completely ignored - and the standard, system-dependent, selection colour is used but the program - may wish to override this to achieve some custom appearance. - - @see GetSelectedTextBgColour(), - wxVListBox::SetSelectionBackground, wxSystemSettings::GetColour - */ - wxColour GetSelectedTextColour(const wxColour& colFg) const; - - /** - This method must be implemented in the derived class and should return - the body (i.e. without @c html nor @c body tags) of the HTML fragment - for the given item. - Note that this function should always return a text fragment for the @a n item - which renders with the same height both when it is selected and when it's not: - i.e. if you call, inside your OnGetItem() implementation, @c IsSelected(n) to - make the items appear differently when they are selected, then you should make - sure - that the returned HTML fragment will render with the same height or else you'll - see some artifacts when the user selects an item. - */ - wxString OnGetItem(size_t n) const; - - /** - This function may be overridden to decorate HTML returned by - OnGetItem(). - */ - wxString OnGetItemMarkup(size_t n) const; - - /** - Called when the user clicks on hypertext link. Does nothing by default. - Overloading this method is deprecated; intercept the event instead. - - @param n - Index of the item containing the link. - @param link - Description of the link. - - @see See also wxHtmlLinkInfo. - */ - virtual void OnLinkClicked(size_t n, const wxHtmlLinkInfo& link); -}; - - - -/** - @class wxSimpleHtmlListBox - @wxheader{htmllbox.h} - - wxSimpleHtmlListBox is an implementation of wxHtmlListBox which - shows HTML content in the listbox rows. - - Unlike wxHtmlListBox, this is not an abstract class and thus it - has the advantage that you can use it without deriving your own class from it. - However, it also has the disadvantage that this is not a virtual control and - thus it's not - well-suited for those cases where you need to show a huge number of items: - every time you - add/insert a string, it will be stored internally and thus will take memory. - - The interface exposed by wxSimpleHtmlListBox fully implements the - wxControlWithItems interface, thus you should refer to - wxControlWithItems's documentation for the API reference - for adding/removing/retrieving items in the listbox. - Also note that the wxVListBox::SetItemCount function is - @c protected in wxSimpleHtmlListBox's context so that you cannot call it - directly, - wxSimpleHtmlListBox will do it for you. - - Note: in case you need to append a lot of items to the control at once, make - sure to use the - @ref wxControlWithItems::append "Append(const wxArrayString )" function. - - Thus the only difference between a wxListBox and a wxSimpleHtmlListBox - is that the latter stores strings which can contain HTML fragments (see the - list of - @ref overview_htmltagssupported "tags supported by wxHTML"). - - Note that the HTML strings you fetch to wxSimpleHtmlListBox should not contain - the @c html - or @c body tags. - - @beginStyleTable - @style{wxHLB_DEFAULT_STYLE} - The default style: wxBORDER_SUNKEN - @style{wxHLB_MULTIPLE} - Multiple-selection list: the user can toggle multiple items on and - off. - @endStyleTable - - @library{wxhtml} - @category{ctrl} - - - @see wxSimpleHtmlListBox::Create -*/ -class wxSimpleHtmlListBox : public wxHtmlListBox -{ -public: - //@{ - /** - Default constructor, you must call Create() - later. - */ - wxHtmlListBox(wxWindow* parent, wxWindowID id, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - int n = 0, - const wxString choices[] = NULL, - long style = wxHLB_DEFAULT_STYLE, - const wxValidator& validator = wxDefaultValidator, - const wxString& name = "simpleHtmlListBox"); - wxHtmlListBox(wxWindow* parent, wxWindowID id, - const wxPoint& pos, - const wxSize& size, - const wxArrayString& choices, - long style = wxHLB_DEFAULT_STYLE, - const wxValidator& validator = wxDefaultValidator, - const wxString& name = "simpleHtmlListBox"); - See also - wxSimpleHtmlListBox::Create - - wxSimpleHtmlListBox(); - //@} - - /** - Frees the array of stored items and relative client data. - */ - ~wxSimpleHtmlListBox(); - - //@{ - /** - Creates the HTML listbox for two-step construction. - See wxSimpleHtmlListBox() for further details. - */ - bool Create(wxWindow* parent, wxWindowID id, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - int n, - const wxString choices[] = NULL, - long style = wxHLB_DEFAULT_STYLE, - const wxValidator& validator = wxDefaultValidator, - const wxString& name = "simpleHtmlListBox"); - bool Create(wxWindow* parent, wxWindowID id, - const wxPoint& pos, - const wxSize& size, - const wxArrayString& choices, - long style = wxHLB_DEFAULT_STYLE, - const wxValidator& validator = wxDefaultValidator, - const wxString& name = "simpleHtmlListBox"); - //@} -}; - diff --git a/interface/hyperlink.h b/interface/hyperlink.h deleted file mode 100644 index 5982f6d1ca..0000000000 --- a/interface/hyperlink.h +++ /dev/null @@ -1,186 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: hyperlink.h -// Purpose: interface of wxHyperlinkEvent -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxHyperlinkEvent - @wxheader{hyperlink.h} - - This event class is used for the events generated by - wxHyperlinkCtrl. - - @library{wxadv} - @category{FIXME} -*/ -class wxHyperlinkEvent : public wxCommandEvent -{ -public: - /** - The constructor is not normally used by the user code. - */ - wxHyperlinkEvent(wxObject* generator, int id, - const wxString& url); - - /** - Returns the URL of the hyperlink where the user has just clicked. - */ - wxString GetURL() const; - - /** - Sets the URL associated with the event. - */ - void SetURL(const wxString& url); -}; - - - -/** - @class wxHyperlinkCtrl - @wxheader{hyperlink.h} - - This class shows a static text element which links to an URL. - Appearance and behaviour is completely customizable. In fact, when the user - clicks on the hyperlink, a wxHyperlinkEvent is - sent but if that event is not handled (or it's skipped; see - wxEvent::Skip), then a call to - wxLaunchDefaultBrowser() is done with the - hyperlink's URL. - - Note that standard wxWindow functions like wxWindow::SetBackgroundColour, - wxWindow::SetFont, wxWindow::SetCursor, wxWindow::SetLabel can be used to customize appearance of the hyperlink. - - @beginStyleTable - @style{wxHL_ALIGN_LEFT} - Align the text to the left. - @style{wxHL_ALIGN_RIGHT} - Align the text to the right. - @style{wxHL_ALIGN_CENTRE} - Center the text (horizontally). - @style{wxHL_CONTEXTMENU} - Pop up a context menu when the hyperlink is right-clicked. The - context menu contains a "Copy URL" menu item which is automatically - handled by the hyperlink and which just copies in the clipboard the - URL (not the label) of the control. - @style{wxHL_DEFAULT_STYLE} - The default style for wxHyperlinkCtrl: - wxBORDER_NONE|wxHL_CONTEXTMENU|wxHL_ALIGN_CENTRE. - @endStyleTable - - @library{wxadv} - @category{ctrl} - - - @see wxURL, wxHyperlinkEvent -*/ -class wxHyperlinkCtrl : public wxControl -{ -public: - /** - Constructor. See Create() for more info. - */ - wxHyperLink(wxWindow* parent, wxWindowID id, - const wxString& label, - const wxString& url, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = wxHL_DEFAULT_STYLE, - const wxString& name = "hyperlink"); - - /** - Creates the hyperlink control. - - @param parent - Parent window. Must not be @NULL. - @param id - Window identifier. A value of wxID_ANY indicates a default value. - @param label - The label of the hyperlink. - @param url - The URL associated with the given label. - @param pos - Window position. - @param size - Window size. If the wxDefaultSize is specified then the window is sized - appropriately. - @param style - Window style. See wxHyperlinkCtrl. - @param validator - Window validator. - @param name - Window name. - */ - bool Create(wxWindow* parent, wxWindowID id, - const wxString& label, - const wxString& url, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = wxHL_DEFAULT_STYLE, - const wxString& name = "hyperlink"); - - /** - Returns the colour used to print the label of the hyperlink when the mouse is - over the control. - */ - wxColour GetHoverColour() const; - - /** - Returns the colour used to print the label when the link has never been clicked - before - (i.e. the link has not been @e visited) and the mouse is not over the control. - */ - wxColour GetNormalColour() const; - - /** - Returns the URL associated with the hyperlink. - */ - wxString GetURL() const; - - /** - Returns @true if the hyperlink has already been clicked by the user at least - one time. - */ - virtual bool GetVisited() const = 0; - - /** - Returns the colour used to print the label when the mouse is not over the - control - and the link has already been clicked before (i.e. the link has been @e - visited). - */ - wxColour GetVisitedColour() const; - - /** - Sets the colour used to print the label of the hyperlink when the mouse is over - the control. - */ - void SetHoverColour(const wxColour& colour); - - /** - Sets the colour used to print the label when the link has never been clicked - before - (i.e. the link has not been @e visited) and the mouse is not over the control. - */ - void SetNormalColour(const wxColour& colour); - - /** - Sets the URL associated with the hyperlink. - */ - void SetURL(const wxString& url); - - /** - Marks the hyperlink as visited (see wxHyperlinkCtrl::SetVisitedColour). - */ - virtual void SetVisited(bool visited = true) = 0; - - /** - Sets the colour used to print the label when the mouse is not over the control - and the link has already been clicked before (i.e. the link has been @e - visited). - */ - void SetVisitedColour(const wxColour& colour); -}; - diff --git a/interface/icon.h b/interface/icon.h deleted file mode 100644 index acfca50218..0000000000 --- a/interface/icon.h +++ /dev/null @@ -1,321 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: icon.h -// Purpose: interface of wxIcon -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxIcon - @wxheader{icon.h} - - An icon is a small rectangular bitmap usually used for denoting a - minimized application. It differs from a wxBitmap in always - having a mask associated with it for transparent drawing. On some platforms, - icons and bitmaps are implemented identically, since there is no real - distinction between - a wxBitmap with a mask and an icon; and there is no specific icon format on - some platforms (X-based applications usually standardize on XPMs for small - bitmaps - and icons). However, some platforms (such as Windows) make the distinction, so - a separate class is provided. - - @library{wxcore} - @category{gdi} - - @stdobjects - ::wxNullIcon - - @see @ref overview_wxbitmapoverview "Bitmap and icon overview", @ref - overview_supportedbitmapformats "supported bitmap file formats", wxDC::DrawIcon, wxCursor -*/ -class wxIcon : public wxBitmap -{ -public: - //@{ - /** - Loads an icon from the specified location(). - - @param bits - Specifies an array of pixel values. - @param width - Specifies the width of the icon. - @param height - Specifies the height of the icon. - @param desiredWidth - Specifies the desired width of the icon. This - parameter only has an effect in Windows (32-bit) where icon resources can - contain - several icons of different sizes. - @param desiredWidth - Specifies the desired height of the icon. This - parameter only has an effect in Windows (32-bit) where icon resources can - contain - several icons of different sizes. - @param depth - Specifies the depth of the icon. If this is omitted, the display depth of - the - screen is used. - @param name - This can refer to a resource name under MS Windows, or a filename under MS - Windows and X. - Its meaning is determined by the flags parameter. - @param loc - The object describing the location of the native icon, see - wxIconLocation. - @param type - May be one of the following: - - - - - - - - wxBITMAP_TYPE_ICO - - - - - Load a Windows icon file. - - - - - - wxBITMAP_TYPE_ICO_RESOURCE - - - - - Load a Windows icon from the resource database. - - - - - - wxBITMAP_TYPE_GIF - - - - - Load a GIF bitmap file. - - - - - - wxBITMAP_TYPE_XBM - - - - - Load an X bitmap file. - - - - - - wxBITMAP_TYPE_XPM - - - - - Load an XPM bitmap file. - - - - - - The validity of these flags depends on the platform and wxWidgets - configuration. - If all possible wxWidgets settings are used, the Windows platform supports - ICO file, ICO resource, - XPM data, and XPM file. Under wxGTK, the available formats are BMP file, - XPM data, XPM file, and PNG file. - Under wxMotif, the available formats are XBM data, XBM file, XPM data, XPM - file. - - @remarks The first form constructs an icon object with no data; an - assignment or another member function such as Create or - LoadFile must be called subsequently. - */ - wxIcon(); - wxIcon(const wxIcon& icon); - wxIcon(void* data, int type, int width, int height, - int depth = -1); - wxIcon(const char bits[], int width, int height, - int depth = 1); - wxIcon(int width, int height, int depth = -1); - wxIcon(const char* const* bits); - wxIcon(const wxString& name, wxBitmapType type, - int desiredWidth = -1, - int desiredHeight = -1); - wxIcon(const wxIconLocation& loc); - //@} - - /** - Destructor. - See @ref overview_refcountdestruct "reference-counted object destruction" for - more info. - If the application omits to delete the icon explicitly, the icon will be - destroyed automatically by wxWidgets when the application exits. - Do not delete an icon that is selected into a memory device context. - */ - ~wxIcon(); - - /** - Copies @a bmp bitmap to this icon. Under MS Windows the bitmap - must have mask colour set. - - LoadFile() - - Wx::Icon-new( width, height, depth = -1 ) - Wx::Icon-new( name, type, desiredWidth = -1, desiredHeight = -1 ) - Wx::Icon-newFromBits( bits, width, height, depth = 1 ) - Wx::Icon-newFromXPM( data ) - */ - void CopyFromBitmap(const wxBitmap& bmp); - - /** - Gets the colour depth of the icon. A value of 1 indicates a - monochrome icon. - */ - int GetDepth() const; - - /** - Gets the height of the icon in pixels. - */ - int GetHeight() const; - - /** - Gets the width of the icon in pixels. - - @see GetHeight() - */ - int GetWidth() const; - - /** - Returns @true if icon data is present. - */ - bool IsOk() const; - - /** - Loads an icon from a file or resource. - - @param name - Either a filename or a Windows resource name. - The meaning of name is determined by the type parameter. - @param type - One of the following values: - - - - - - - - wxBITMAP_TYPE_ICO - - - - - Load a Windows icon file. - - - - - - wxBITMAP_TYPE_ICO_RESOURCE - - - - - Load a Windows icon from the resource database. - - - - - - wxBITMAP_TYPE_GIF - - - - - Load a GIF bitmap file. - - - - - - wxBITMAP_TYPE_XBM - - - - - Load an X bitmap file. - - - - - - wxBITMAP_TYPE_XPM - - - - - Load an XPM bitmap file. - - - - - - The validity of these flags depends on the platform and wxWidgets - configuration. - - @return @true if the operation succeeded, @false otherwise. - - @see wxIcon() - */ - bool LoadFile(const wxString& name, wxBitmapType type); - - /** - Sets the depth member (does not affect the icon data). - - @param depth - Icon depth. - */ - void SetDepth(int depth); - - /** - Sets the height member (does not affect the icon data). - - @param height - Icon height in pixels. - */ - void SetHeight(int height); - - /** - Sets the width member (does not affect the icon data). - - @param width - Icon width in pixels. - */ - void SetWidth(int width); - - /** - Assignment operator, using @ref overview_trefcount "reference counting". - - @param icon - Icon to assign. - */ - wxIcon operator =(const wxIcon& icon); -}; - -/** - An empty wxIcon. -*/ -wxIcon wxNullIcon; - - diff --git a/interface/iconbndl.h b/interface/iconbndl.h deleted file mode 100644 index 8532db9145..0000000000 --- a/interface/iconbndl.h +++ /dev/null @@ -1,89 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: iconbndl.h -// Purpose: interface of wxIconBundle -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxIconBundle - @wxheader{iconbndl.h} - - This class contains multiple copies of an icon in different sizes, - see also wxDialog::SetIcons and - wxTopLevelWindow::SetIcons. - - @library{wxcore} - @category{FIXME} - - @stdobjects - ::wxNullIconBundle -*/ -class wxIconBundle : public wxGDIObject -{ -public: - //@{ - /** - Copy constructor. - */ - wxIconBundle(); - wxIconBundle(const wxString& file, wxBitmapType type); - wxIconBundle(const wxIcon& icon); - wxIconBundle(const wxIconBundle& ic); - //@} - - /** - Destructor. - */ - ~wxIconBundle(); - - //@{ - /** - Adds the icon to the collection; if the collection already - contains an icon with the same width and height, it is - replaced by the new one. - */ - void AddIcon(const wxString& file, wxBitmapType type); - void AddIcon(const wxIcon& icon); - //@} - - //@{ - /** - Same as GetIcon( wxSize( size, size ) ). - */ - wxIcon GetIcon(const wxSize& size) const; - const wxIcon GetIcon(wxCoord size = -1) const; - //@} - - /** - Returns the icon with exactly the given size or @c wxNullIcon if this - size is not available. - */ - wxIcon GetIconOfExactSize(const wxSize& size) const; - - /** - Returns @true if the bundle doesn't contain any icons, @false otherwise (in - which case a call to GetIcon() with default - parameter should return a valid icon). - */ - bool IsEmpty() const; - - /** - Assignment operator, using @ref overview_trefcount "reference counting". - */ - wxIconBundle operator =(const wxIconBundle& ic); - - /** - Equality operator. This returns @true if two icon bundles are equal. - */ - bool operator ==(const wxIconBundle& ic); -}; - - -/** - An empty wxIconBundle. -*/ -wxIconBundle wxNullIconBundle; - - diff --git a/interface/iconloc.h b/interface/iconloc.h deleted file mode 100644 index 4ed130a56c..0000000000 --- a/interface/iconloc.h +++ /dev/null @@ -1,39 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: iconloc.h -// Purpose: interface of wxIconLocation -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxIconLocation - @wxheader{iconloc.h} - - wxIconLocation is a tiny class describing the location of an (external, i.e. - not embedded into the application resources) icon. For most platforms it simply - contains the file name but under some others (notably Windows) the same file - may contain multiple icons and so this class also stores the index of the icon - inside the file. - - In any case, its details should be of no interest to the application code and - most of them are not even documented here (on purpose) as it is only meant to - be used as an opaque class: the application may get the object of this class - from somewhere and the only reasonable thing to do with it later is to create - a wxIcon from it. - - @library{wxbase} - @category{FIXME} - - @see wxIcon, wxFileType::GetIcon -*/ -class wxIconLocation -{ -public: - /** - Returns @true if the object is valid, i.e. was properly initialized, and - @false otherwise. - */ - bool IsOk() const; -}; - diff --git a/interface/image.h b/interface/image.h deleted file mode 100644 index ef66408ff0..0000000000 --- a/interface/image.h +++ /dev/null @@ -1,1073 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: image.h -// Purpose: interface of wxImageHandler -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxImageHandler - @wxheader{image.h} - - This is the base class for implementing image file loading/saving, and - image creation from data. - It is used within wxImage and is not normally seen by the application. - - If you wish to extend the capabilities of wxImage, derive a class from - wxImageHandler and add the handler using wxImage::AddHandler in your - application initialisation. - - @stdobjects - ::wxNullImage - - @library{wxcore} - @category{FIXME} - - @see wxImage, wxInitAllImageHandlers() - - @todo Document all image handler types, indicating their library. -*/ -class wxImageHandler : public wxObject -{ -public: - /** - Default constructor. In your own default constructor, initialise the members - m_name, m_extension and m_type. - */ - wxImageHandler(); - - /** - Destroys the wxImageHandler object. - */ - ~wxImageHandler(); - - /** - Gets the file extension associated with this handler. - */ - const wxString GetExtension() const; - - /** - If the image file contains more than one image and the image handler is capable - of retrieving these individually, this function will return the number of - available images. - - @param stream - Opened input stream for reading image data. Currently, the stream must - support seeking. - - @return Number of available images. For most image handlers, this is 1 - (exceptions are TIFF and ICO formats). - */ - int GetImageCount(wxInputStream& stream); - - /** - Gets the MIME type associated with this handler. - */ - const wxString GetMimeType() const; - - /** - Gets the name of this handler. - */ - const wxString GetName() const; - - /** - Gets the image type associated with this handler. - */ - wxBitmapType GetType() const; - - /** - Loads a image from a stream, putting the resulting data into @e image. If the - image file contains - more than one image and the image handler is capable of retrieving these - individually, @e index - indicates which image to read from the stream. - - @param image - The image object which is to be affected by this operation. - @param stream - Opened input stream for reading image data. - @param verbose - If set to @true, errors reported by the image handler will produce - wxLogMessages. - @param index - The index of the image in the file (starting from zero). - - @return @true if the operation succeeded, @false otherwise. - - @see wxImage::LoadFile, wxImage::SaveFile, SaveFile() - */ - bool LoadFile(wxImage* image, wxInputStream& stream, - bool verbose = true, int index = 0); - - /** - Saves a image in the output stream. - - @param image - The image object which is to be affected by this operation. - @param stream - Opened output stream for writing the data. - - @return @true if the operation succeeded, @false otherwise. - - @see wxImage::LoadFile, wxImage::SaveFile, LoadFile() - */ - bool SaveFile(wxImage* image, wxOutputStream& stream); - - /** - Sets the handler extension. - - @param extension - Handler extension. - */ - void SetExtension(const wxString& extension); - - /** - Sets the handler MIME type. - - @param mimename - Handler MIME type. - */ - void SetMimeType(const wxString& mimetype); - - /** - Sets the handler name. - - @param name - Handler name. - */ - void SetName(const wxString& name); -}; - - - -/** - @class wxImage - @wxheader{image.h} - - This class encapsulates a platform-independent image. An image can be - created from data, or using wxBitmap::ConvertToImage. An image can be - loaded from a file in a variety of formats, and is extensible to new - formats via image format handlers. Functions are available to set and - get image bits, so it can be used for basic image manipulation. - - A wxImage cannot (currently) be drawn directly to a wxDC. Instead, - a platform-specific wxBitmap object must be created from it using - the wxBitmap::wxBitmap(wxImage,int depth) constructor. - This bitmap can then be drawn in a device context, using wxDC::DrawBitmap. - - One colour value of the image may be used as a mask colour which will lead to - the automatic creation of a wxMask object associated to the bitmap object. - - @library{wxcore} - @category{gdi} - - @stdobjects - ::wxNullImage - - @see wxBitmap, wxInitAllImageHandlers(), wxPixelData -*/ -class wxImage : public wxObject -{ -public: - - /** - Creates an empty wxImage object without an alpha channel. - */ - wxImage(); - - /** - Creates an image with the given size and clears it if requested. - Does not create an alpha channel. - - @param width - Specifies the width of the image. - @param height - Specifies the height of the image. - @clear - Clear the image with zeros. - */ - wxImage(int width, int height, bool clear = true); - - /** - Creates an image from data in memory. If static_data is false - then the wxImage will take ownership of the data and free it - afterwards. For this, it has to be allocated with @e malloc. - - @param width - Specifies the width of the image. - @param height - Specifies the height of the image. - @param data - A pointer to RGB data - @param static_data - Indicates if the data should be free'd after use - - */ - wxImage(int width, int height, unsigned char* data, bool static_data = false); - - /** - Creates an image from data in memory. If static_data is false - then the wxImage will take ownership of the data and free it - afterwards. For this, it has to be allocated with @e malloc. - - @param width - Specifies the width of the image. - @param height - Specifies the height of the image. - @param data - A pointer to RGB data - @param alpha - A pointer to alpha-channel data - @param static_data - Indicates if the data should be free'd after use - - */ - wxImage(int width, int height, unsigned char* data, unsigned char* alpha, bool static_data = false ); - - /** - Creates an image from XPM data. - - @param xpmData - A pointer to XPM image data. - */ - wxImage(const char* const* xpmData); - - /** - Creates an image from a file. - - @param name - Name of the file from which to load the image. - @param type - May be one of the following: - @li wxBITMAP_TYPE_BMP: Load a Windows bitmap file. - @li wxBITMAP_TYPE_GIF: Load a GIF bitmap file. - @li wxBITMAP_TYPE_JPEG: Load a JPEG bitmap file. - @li wxBITMAP_TYPE_PNG: Load a PNG bitmap file. - @li wxBITMAP_TYPE_PCX: Load a PCX bitmap file. - @li wxBITMAP_TYPE_PNM: Load a PNM bitmap file. - @li wxBITMAP_TYPE_TIF: Load a TIFF bitmap file. - @li wxBITMAP_TYPE_TGA: Load a TGA bitmap file. - @li wxBITMAP_TYPE_XPM: Load a XPM bitmap file. - @li wxBITMAP_TYPE_ICO: Load a Windows icon file (ICO). - @li wxBITMAP_TYPE_CUR: Load a Windows cursor file (CUR). - @li wxBITMAP_TYPE_ANI: Load a Windows animated cursor file (ANI). - @li wxBITMAP_TYPE_ANY: Will try to autodetect the format. - @param index - Index of the image to load in the case that the image file contains - multiple images. This is only used by GIF, ICO and TIFF handlers. - The default value (-1) means "choose the default image" and is - interpreted as the first image (index=0) by the GIF and TIFF handler - and as the largest and most colourful one by the ICO handler. - - @remarks Depending on how wxWidgets has been configured, not all formats - may be available. - - @see LoadFile() - */ - wxImage(const wxString& name, wxBitmapType type = wxBITMAP_TYPE_ANY, int index = -1); - - /** - Creates an image from a file using MIME-types to specify the type. - - @param name - Name of the file from which to load the image. - @param type - See above - @param mimetype - MIME type string (for example 'image/jpeg') - @param index - See above - */ - wxImage(const wxString& name, const wxString& mimetype, int index = -1); - - /** - Creates an image from a stream. - - @param stream - Opened input stream from which to load the image. Currently, - the stream must support seeking. - @param type - See above - @param index - See above. - */ - wxImage(wxInputStream& stream, wxBitmapType type = wxBITMAP_TYPE_ANY, int index = -1); - - /** - Creates an image from a stream using MIME-types to specify the type. - - @param stream - Opened input stream from which to load the image. Currently, - the stream must support seeking. - @param mimetype - MIME type string (for example 'image/jpeg') - @param index - See above. - */ - wxImage(wxInputStream& stream, const wxString& mimetype, int index = -1); - - - /** - Destructor. - See @ref overview_refcountdestruct "reference-counted object destruction" for - more info. - */ - ~wxImage(); - - /** - Register an image handler. - */ - static void AddHandler(wxImageHandler* handler); - - /** - Blurs the image in both horizontal and vertical directions by the - specified pixel @e blurRadius. This should not be used when using - a single mask colour for transparency. - - @see BlurHorizontal(), BlurVertical() - */ - wxImage Blur(int blurRadius); - - /** - Blurs the image in the horizontal direction only. This should not be used - when using a single mask colour for transparency. - - @see Blur(), BlurVertical() - */ - wxImage BlurHorizontal(int blurRadius); - - /** - Blurs the image in the vertical direction only. This should not be used - when using a single mask colour for transparency. - - @see Blur(), BlurHorizontal() - */ - wxImage BlurVertical(int blurRadius); - - /** - Returns @true if the current image handlers can read this file - */ - bool CanRead(const wxString& filename); - - /** - Deletes all image handlers. - This function is called by wxWidgets on exit. - */ - static void CleanUpHandlers(); - - /** - Computes the histogram of the image. @a histogram is a reference to - wxImageHistogram object. wxImageHistogram is a specialization of - wxHashMap "template" and is defined as follows: - - @return Returns number of colours in the histogram. - */ - unsigned long ComputeHistogram(wxImageHistogram& histogram) const; - - /** - If the image has alpha channel, this method converts it to mask. All pixels - with alpha value less than @a threshold are replaced with mask colour - and the alpha channel is removed. Mask colour is chosen automatically using - FindFirstUnusedColour(). - If the image image doesn't have alpha channel, - ConvertAlphaToMask does nothing. - - @return @false if FindFirstUnusedColour returns @false, @true otherwise. - */ - bool ConvertAlphaToMask(unsigned char threshold = 128); - - /** - Deprecated, use equivalent @ref wxBitmap::ctor "wxBitmap constructor" - (which takes wxImage and depth as its arguments) instead. - */ - wxBitmap ConvertToBitmap() const; - - /** - Returns a greyscale version of the image. The returned image uses the luminance - component of the original to calculate the greyscale. Defaults to using - ITU-T BT.601 when converting to YUV, where every pixel equals - (R * @e lr) + (G * @e lg) + (B * @e lb). - */ - wxImage ConvertToGreyscale(double lr = 0.299, double lg = 0.587, - double lb = 0.114) const; - - /** - Returns monochromatic version of the image. The returned image has white - colour where the original has @e (r,g,b) colour and black colour - everywhere else. - */ - wxImage ConvertToMono(unsigned char r, unsigned char g, - unsigned char b) const; - - /** - Returns an identical copy of the image. - */ - wxImage Copy() const; - - /** - Creates a fresh image. If @a clear is @true, the new image will be initialized - to black. - Otherwise, the image data will be uninitialized. - - @param width - The width of the image in pixels. - @param height - The height of the image in pixels. - - @return @true if the call succeeded, @false otherwise. - */ - bool Create(int width, int height, bool clear = true); - - /** - Destroys the image data. - */ - void Destroy(); - - /** - @param r,g,b - Pointers to variables to save the colour. - @param startR,startG,startB - Initial values of the colour. Returned colour - will have RGB values equal to or greater than these. - - @return Returns @false if there is no unused colour left, @true on success. - */ - bool FindFirstUnusedColour(unsigned char* r, unsigned char* g, - unsigned char* b, - unsigned char startR = 1, - unsigned char startG = 0, - unsigned char startB = 0); - - //@{ - /** - Finds the handler associated with the given MIME type. - - @param name - The handler name. - @param extension - The file extension, such as "bmp". - @param imageType - The image type, such as wxBITMAP_TYPE_BMP. - @param mimetype - MIME type. - - @return A pointer to the handler if found, @NULL otherwise. - - @see wxImageHandler - */ - static wxImageHandler* FindHandler(const wxString& name); - static wxImageHandler* FindHandler(const wxString& extension, - wxBitmapType imageType); - static wxImageHandler* FindHandler(wxBitmapType imageType); - static wxImageHandler* FindHandlerMime(const wxString& mimetype); - //@} - - /** - Return alpha value at given pixel location. - */ - unsigned char GetAlpha(int x, int y) const; - - /** - Returns pointer to the array storing the alpha values for this image. This - pointer is @NULL for the images without the alpha channel. If the image - does have it, this pointer may be used to directly manipulate the alpha values - which are stored as the RGB ones. - */ - const unsigned char * GetAlpha() const; - - /** - Returns the blue intensity at the given coordinate. - */ - unsigned char GetBlue(int x, int y) const; - - /** - Returns the image data as an array. This is most often used when doing - direct image manipulation. The return value points to an array of - characters in RGBRGBRGB... format in the top-to-bottom, left-to-right - order, that is the first RGB triplet corresponds to the pixel first pixel of - the first row, the second one --- to the second pixel of the first row and so - on until the end of the first row, with second row following after it and so - on. - You should not delete the returned pointer nor pass it to - SetData(). - */ - unsigned char* GetData() const; - - /** - Returns the green intensity at the given coordinate. - */ - unsigned char GetGreen(int x, int y) const; - - /** - Returns the static list of image format handlers. - - @see wxImageHandler - */ - static wxList GetHandlers(); - - /** - Gets the height of the image in pixels. - */ - int GetHeight() const; - - //@{ - /** - If the image file contains more than one image and the image handler is capable - of retrieving these individually, this function will return the number of - available images. - - @param name - Name of the file to query. - @param stream - Opened input stream with image data. Currently, the stream must - support seeking. - @param type - May be one of the following: - @li wxBITMAP_TYPE_BMP: Load a Windows bitmap file. - @li wxBITMAP_TYPE_GIF: Load a GIF bitmap file. - @li wxBITMAP_TYPE_JPEG: Load a JPEG bitmap file. - @li wxBITMAP_TYPE_PNG: Load a PNG bitmap file. - @li wxBITMAP_TYPE_PCX: Load a PCX bitmap file. - @li wxBITMAP_TYPE_PNM: Load a PNM bitmap file. - @li wxBITMAP_TYPE_TIF: Load a TIFF bitmap file. - @li wxBITMAP_TYPE_TGA: Load a TGA bitmap file. - @li wxBITMAP_TYPE_XPM: Load a XPM bitmap file. - @li wxBITMAP_TYPE_ICO: Load a Windows icon file (ICO). - @li wxBITMAP_TYPE_CUR: Load a Windows cursor file (CUR). - @li wxBITMAP_TYPE_ANI: Load a Windows animated cursor file (ANI). - @li wxBITMAP_TYPE_ANY: Will try to autodetect the format. - - @return Number of available images. For most image handlers, this is 1 - (exceptions are TIFF and ICO formats). - */ - static int GetImageCount(const wxString& filename, - wxBitmapType type = wxBITMAP_TYPE_ANY); - static int GetImageCount(wxInputStream& stream, - wxBitmapType type = wxBITMAP_TYPE_ANY); - //@} - - /** - Iterates all registered wxImageHandler objects, and returns a string containing - file extension masks - suitable for passing to file open/save dialog boxes. - - @return The format of the returned string is - "(*.ext1;*.ext2)|*.ext1;*.ext2". - - @see wxImageHandler - */ - static wxString GetImageExtWildcard(); - - /** - Gets the blue value of the mask colour. - */ - unsigned char GetMaskBlue() const; - - /** - Gets the green value of the mask colour. - */ - unsigned char GetMaskGreen() const; - - /** - Gets the red value of the mask colour. - */ - unsigned char GetMaskRed() const; - - /** - Gets a user-defined option. The function is case-insensitive to @e name. - For example, when saving as a JPEG file, the option @b quality is - used, which is a number between 0 and 100 (0 is terrible, 100 is very good). - - @see SetOption(), GetOptionInt(), HasOption() - */ - wxString GetOption(const wxString& name) const; - - /** - Gets a user-defined option as an integer. The function is case-insensitive - to @e name. If the given option is not present, the function returns 0. - Use HasOption() is 0 is a possibly valid value for the option. - Options for wxPNGHandler - @li wxIMAGE_OPTION_PNG_FORMAT: Format for saving a PNG file. - @li wxIMAGE_OPTION_PNG_BITDEPTH: Bit depth for every channel (R/G/B/A). - - Supported values for wxIMAGE_OPTION_PNG_FORMAT: - @li wxPNG_TYPE_COLOUR: Stores RGB image. - @li wxPNG_TYPE_GREY: Stores grey image, converts from RGB. - @li wxPNG_TYPE_GREY_RED: Stores grey image, uses red value as grey. - - @see SetOption(), GetOption() - */ - int GetOptionInt(const wxString& name) const; - - /** - Get the current mask colour or find a suitable unused colour that could be - used as a mask colour. Returns @true if the image currently has a mask. - */ - bool GetOrFindMaskColour(unsigned char r, unsigned char g, - unsigned char b) const; - - /** - Returns the palette associated with the image. Currently the palette is only - used when converting to wxBitmap under Windows. Some of the wxImage handlers - have been modified to set the palette if one exists in the image file (usually - 256 or less colour images in GIF or PNG format). - */ - const wxPalette GetPalette() const; - - /** - Returns the red intensity at the given coordinate. - */ - unsigned char GetRed(int x, int y) const; - - /** - Returns a sub image of the current one as long as the rect belongs entirely to - the image. - */ - wxImage GetSubImage(const wxRect& rect) const; - - /** - Gets the type of image found by LoadFile or specified with SaveFile - @since 2.9.0 - */ - wxBitmapType GetType() const; - - /** - Gets the width of the image in pixels. - - @see GetHeight() - */ - int GetWidth() const; - - /** - Constructor for HSVValue, an object that contains values for hue, saturation - and value which - represent the value of a color. It is used by HSVtoRGB() - and RGBtoHSV(), which - converts between HSV color space and RGB color space. - */ - HSVValue(double h = 0.0, double s = 0.0, double v = 0.0); - - /** - Converts a color in HSV color space to RGB color space. - */ -#define wxImage::RGBValue HSVtoRGB(const HSVValue& hsv) /* implementation is private */ - - /** - Returns @true if this image has alpha channel, @false otherwise. - - @see GetAlpha(), SetAlpha() - */ - bool HasAlpha() const; - - /** - Returns @true if there is a mask active, @false otherwise. - */ - bool HasMask() const; - - /** - Returns @true if the given option is present. The function is case-insensitive - to @e name. - - @see SetOption(), GetOption(), GetOptionInt() - */ - bool HasOption(const wxString& name) const; - - /** - Initializes the image alpha channel data. It is an error to call it - if the image already has alpha data. If it doesn't, alpha data will be - by default initialized to all pixels being fully opaque. But if the image has a - a mask colour, all mask pixels will be completely transparent. - */ - void InitAlpha(); - - /** - Internal use only. Adds standard image format handlers. It only install BMP - for the time being, which is used by wxBitmap. - This function is called by wxWidgets on startup, and shouldn't be called by - the user. - - @see wxImageHandler, wxInitAllImageHandlers(), wxQuantize - */ - static void InitStandardHandlers(); - - /** - Adds a handler at the start of the static list of format handlers. - - @param handler - A new image format handler object. There is usually only one instance - of a given handler class in an application session. - - @see wxImageHandler - */ - static void InsertHandler(wxImageHandler* handler); - - /** - Returns @true if image data is present. - */ - bool IsOk() const; - - /** - Returns @true if the given pixel is transparent, i.e. either has the mask - colour if this image has a mask or if this image has alpha channel and alpha - value of this pixel is strictly less than @e threshold. - */ - bool IsTransparent(int x, int y, unsigned char threshold = 128) const; - - //@{ - /** - Loads an image from an input stream. - - @param name - Name of the file from which to load the image. - @param stream - Opened input stream from which to load the image. Currently, the - stream must support seeking. - @param type - May be one of the following: - @li wxBITMAP_TYPE_BMP: Load a Windows bitmap file. - @li wxBITMAP_TYPE_GIF: Load a GIF bitmap file. - @li wxBITMAP_TYPE_JPEG: Load a JPEG bitmap file. - @li wxBITMAP_TYPE_PNG: Load a PNG bitmap file. - @li wxBITMAP_TYPE_PCX: Load a PCX bitmap file. - @li wxBITMAP_TYPE_PNM: Load a PNM bitmap file. - @li wxBITMAP_TYPE_TIF: Load a TIFF bitmap file. - @li wxBITMAP_TYPE_TGA: Load a TGA bitmap file. - @li wxBITMAP_TYPE_XPM: Load a XPM bitmap file. - @li wxBITMAP_TYPE_ICO: Load a Windows icon file (ICO). - @li wxBITMAP_TYPE_CUR: Load a Windows cursor file (CUR). - @li wxBITMAP_TYPE_ANI: Load a Windows animated cursor file (ANI). - @li wxBITMAP_TYPE_ANY: Will try to autodetect the format. - @param mimetype - MIME type string (for example 'image/jpeg') - @param index - Index of the image to load in the case that the image file contains - multiple images. This is only used by GIF, ICO and TIFF handlers. - The default value (-1) means "choose the default image" and is - interpreted as the first image (index=0) by the GIF and TIFF handler - and as the largest and most colourful one by the ICO handler. - - @return @true if the operation succeeded, @false otherwise. If the - optional index parameter is out of range, @false is - returned and a call to wxLogError() takes place. - - @remarks Depending on how wxWidgets has been configured, not all formats - may be available. - - @see SaveFile() - */ - bool LoadFile(const wxString& name, - wxBitmapType type = wxBITMAP_TYPE_ANY, - int index = -1); - bool LoadFile(const wxString& name, const wxString& mimetype, - int index = -1); - bool LoadFile(wxInputStream& stream, wxBitmapType type, - int index = -1); - bool LoadFile(wxInputStream& stream, - const wxString& mimetype, - int index = -1); - //@} - - /** - Returns a mirrored copy of the image. The parameter @e horizontally - indicates the orientation. - */ - wxImage Mirror(bool horizontally = true) const; - - /** - Copy the data of the given @a image to the specified position in this image. - */ - void Paste(const wxImage& image, int x, int y); - - /** - Constructor for RGBValue, an object that contains values for red, green and - blue which - represent the value of a color. It is used by HSVtoRGB() - and RGBtoHSV(), which - converts between HSV color space and RGB color space. - */ - RGBValue(unsigned char r = 0, unsigned char g = 0, - unsigned char b = 0); - - /** - Converts a color in RGB color space to HSV color space. - */ -#define wxImage::HSVValue RGBtoHSV(const RGBValue& rgb) /* implementation is private */ - - /** - Finds the handler with the given name, and removes it. The handler - is not deleted. - - @param name - The handler name. - - @return @true if the handler was found and removed, @false otherwise. - - @see wxImageHandler - */ - static bool RemoveHandler(const wxString& name); - - /** - Replaces the colour specified by @e r1,g1,b1 by the colour @e r2,g2,b2. - */ - void Replace(unsigned char r1, unsigned char g1, - unsigned char b1, unsigned char r2, - unsigned char g2, unsigned char b2); - - /** - Changes the size of the image in-place by scaling it: after a call to this - function, - the image will have the given width and height. - For a description of the @a quality parameter, see the Scale() function. - Returns the (modified) image itself. - - @see Scale() - */ - wxImage Rescale(int width, int height, - int quality = wxIMAGE_QUALITY_NORMAL); - - /** - Changes the size of the image in-place without scaling it by adding either a - border - with the given colour or cropping as necessary. The image is pasted into a new - image with the given @a size and background colour at the position @e pos - relative to the upper left of the new image. If @a red = green = blue = -1 - then use either the current mask colour if set or find, use, and set a - suitable mask colour for any newly exposed areas. - Returns the (modified) image itself. - - @see Size() - */ - wxImage Resize(const wxSize& size, const wxPoint pos, - int red = -1, int green = -1, - int blue = -1); - - /** - Rotates the image about the given point, by @a angle radians. Passing @true - to @a interpolating results in better image quality, but is slower. If the - image has a mask, then the mask colour is used for the uncovered pixels in the - rotated image background. Else, black (rgb 0, 0, 0) will be used. - Returns the rotated image, leaving this image intact. - */ - wxImage Rotate(double angle, const wxPoint& rotationCentre, - bool interpolating = true, - wxPoint* offsetAfterRotation = NULL); - - /** - Returns a copy of the image rotated 90 degrees in the direction - indicated by @e clockwise. - */ - wxImage Rotate90(bool clockwise = true) const; - - /** - Rotates the hue of each pixel in the image by @e angle, which is a double in - the range of -1.0 to +1.0, where -1.0 corresponds to -360 degrees and +1.0 - corresponds - to +360 degrees. - */ - void RotateHue(double angle); - - //@{ - /** - Saves an image in the given stream. - - @param name - Name of the file to save the image to. - @param stream - Opened output stream to save the image to. - @param type - Currently these types can be used: - @li wxBITMAP_TYPE_BMP: Save a BMP image file. - @li wxBITMAP_TYPE_JPEG: Save a JPEG image file. - @li wxBITMAP_TYPE_PNG: Save a PNG image file. - @li wxBITMAP_TYPE_PCX: Save a PCX image file (tries to save as 8-bit if possible, - falls back to 24-bit otherwise). - @li wxBITMAP_TYPE_PNM: Save a PNM image file (as raw RGB always). - @li wxBITMAP_TYPE_TIFF: Save a TIFF image file. - @li wxBITMAP_TYPE_XPM: Save a XPM image file. - @li wxBITMAP_TYPE_ICO: Save a Windows icon file (ICO) (the size may - be up to 255 wide by 127 high. A single image is saved in 8 colors - at the size supplied). - @li wxBITMAP_TYPE_CUR: Save a Windows cursor file (CUR). - @param mimetype - MIME type. - - @return @true if the operation succeeded, @false otherwise. - - @remarks Depending on how wxWidgets has been configured, not all formats - may be available. - - @see LoadFile() - */ - bool SaveFile(const wxString& name, int type) const; - const bool SaveFile(const wxString& name, - const wxString& mimetype) const; - const bool SaveFile(const wxString& name) const; - const bool SaveFile(wxOutputStream& stream, int type) const; - const bool SaveFile(wxOutputStream& stream, - const wxString& mimetype) const; - //@} - - /** - Returns a scaled version of the image. This is also useful for - scaling bitmaps in general as the only other way to scale bitmaps - is to blit a wxMemoryDC into another wxMemoryDC. - It should be noted that although using wxIMAGE_QUALITY_HIGH produces much nicer - looking results it is a slower method. Downsampling will use the box averaging - method - which seems to operate very fast. If you are upsampling larger images using - this method you will most likely notice that it is a bit slower and in extreme - cases - it will be quite substantially slower as the bicubic algorithm has to process a - lot of - data. - It should also be noted that the high quality scaling may not work as expected - when using a single mask colour for transparency, as the scaling will blur the - image and will therefore remove the mask partially. Using the alpha channel - will work. - Example: - - @param quality - Determines what method to use for resampling the image. - - Can be one of the following: - @li wxIMAGE_QUALITY_NORMAL: Uses the normal default scaling method of - pixel replication - @li wxIMAGE_QUALITY_HIGH: Uses bicubic and box averaging resampling - methods for upsampling and downsampling respectively - - @see Rescale() - */ - wxImage Scale(int width, int height, - int quality = wxIMAGE_QUALITY_NORMAL) const; - - /** - Assigns new data as alpha channel to the image. - If @e static_data is false the data will be - free()'d after use. - */ - void SetAlpha(unsigned char* alpha = NULL, - bool static_data = false); - - /** - Sets the alpha value for the given pixel. This function should only be - called if the image has alpha channel data, use HasAlpha() to - check for this. - */ - void SetAlpha(int x, int y, unsigned char alpha); - - /** - Sets the image data without performing checks. The data given must have - the size (width*height*3) or results will be unexpected. Don't use this - method if you aren't sure you know what you are doing. - The data must have been allocated with @c malloc(), @b NOT with - @c operator new. - After this call the pointer to the data is owned by the wxImage object, - that will be responsible for deleting it. - Do not pass to this function a pointer obtained through - GetData(). - */ - void SetData(unsigned char* data); - - /** - Specifies whether there is a mask or not. The area of the mask is determined by - the current mask colour. - */ - void SetMask(bool hasMask = true); - - /** - Sets the mask colour for this image (and tells the image to use the mask). - */ - void SetMaskColour(unsigned char red, unsigned char green, - unsigned char blue); - - /** - @param mask - The mask image to extract mask shape from. Must have same dimensions as the - image. - @param mr,mg,mb - RGB value of pixels in mask that will be used to create the mask. - - @return Returns @false if mask does not have same dimensions as the image - or if there is no unused colour left. Returns @true if - the mask was successfully applied. - */ - bool SetMaskFromImage(const wxImage& mask, unsigned char mr, - unsigned char mg, - unsigned char mb); - - //@{ - /** - Sets a user-defined option. The function is case-insensitive to @e name. - For example, when saving as a JPEG file, the option @b quality is - used, which is a number between 0 and 100 (0 is terrible, 100 is very good). - - @see GetOption(), GetOptionInt(), HasOption() - */ - void SetOption(const wxString& name, const wxString& value); - void SetOption(const wxString& name, int value); - //@} - - /** - Associates a palette with the image. The palette may be used when converting - wxImage to wxBitmap (MSW only at present) or in file save operations (none as - yet). - */ - void SetPalette(const wxPalette& palette); - - /** - Sets the colour of the pixels within the given rectangle. This routine performs - bounds-checks for the coordinate so it can be considered a safe way to - manipulate the - data. - */ - void SetRGB(wxRect& rect, unsigned char red, - unsigned char green, - unsigned char blue); - - /** - Returns a resized version of this image without scaling it by adding either a - border - with the given colour or cropping as necessary. The image is pasted into a new - image with the given @a size and background colour at the position @e pos - relative to the upper left of the new image. If @a red = green = blue = -1 - then the areas of the larger image not covered by this image are made - transparent by filling them with the image mask colour (which will be allocated - automatically if it isn't currently set). Otherwise, the areas will be filled - with the colour with the specified RGB components. - - @see Resize() - */ - wxImage Size(const wxSize& size, const wxPoint pos, int red = -1, - int green = -1, int blue = -1) const; - - /** - Assignment operator, using @ref overview_trefcount "reference counting". - - @param image - Image to assign. - - @return Returns 'this' object. - */ - wxImage operator =(const wxImage& image); -}; - -// ============================================================================ -// Global functions/macros -// ============================================================================ - -/** @ingroup group_funcmacro_appinitterm */ -//@{ - -/** - Initializes all available image handlers. For a list of available handlers, - see wxImage. - - @see wxImage, wxImageHandler - - @header{wx/image.h} -*/ -void wxInitAllImageHandlers(); - -//@} - diff --git a/interface/imaglist.h b/interface/imaglist.h deleted file mode 100644 index ca3711c418..0000000000 --- a/interface/imaglist.h +++ /dev/null @@ -1,208 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: imaglist.h -// Purpose: interface of wxImageList -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxImageList - @wxheader{imaglist.h} - - A wxImageList contains a list of images, which are stored in - an unspecified form. Images can have masks for transparent - drawing, and can be made from a variety of sources including bitmaps - and icons. - - wxImageList is used principally in conjunction with wxTreeCtrl and - wxListCtrl classes. - - @library{wxcore} - @category{gdi} - - @see wxTreeCtrl, wxListCtrl -*/ -class wxImageList : public wxObject -{ -public: - //@{ - /** - Constructor specifying the image size, whether image masks should be created, - and the initial size of the list. - - @param width - Width of the images in the list. - @param height - Height of the images in the list. - @param mask - @true if masks should be created for all images. - @param initialCount - The initial size of the list. - - @see Create() - */ - wxImageList(); - wxImageList(int width, int height, bool mask = true, - int initialCount = 1); - //@} - - //@{ - /** - Adds a new image using an icon. - - @param bitmap - Bitmap representing the opaque areas of the image. - @param mask - Monochrome mask bitmap, representing the transparent areas of the image. - @param maskColour - Colour indicating which parts of the image are transparent. - @param icon - Icon to use as the image. - - @return The new zero-based image index. - - @remarks The original bitmap or icon is not affected by the Add - operation, and can be deleted afterwards. - */ - int Add(const wxBitmap& bitmap, - const wxBitmap& mask = wxNullBitmap); - int Add(const wxBitmap& bitmap, const wxColour& maskColour); - int Add(const wxIcon& icon); - //@} - - /** - Initializes the list. See wxImageList() for details. - */ - bool Create(int width, int height, bool mask = true, - int initialCount = 1); - - /** - Draws a specified image onto a device context. - - @param index - Image index, starting from zero. - @param dc - Device context to draw on. - @param x - X position on the device context. - @param y - Y position on the device context. - @param flags - How to draw the image. A bitlist of a selection of the following: - - - - - - - wxIMAGELIST_DRAW_NORMAL - - - - - Draw the image normally. - - - - - - wxIMAGELIST_DRAW_TRANSPARENT - - - - - Draw the image with transparency. - - - - - - wxIMAGELIST_DRAW_SELECTED - - - - - Draw the image in selected state. - - - - - - wxIMAGELIST_DRAW_FOCUSED - - - - - Draw the image in a focused state. - @param solidBackground - For optimisation - drawing can be faster if the function is told - that the background is solid. - */ - bool Draw(int index, wxDC& dc, int x, int y, - int flags = wxIMAGELIST_DRAW_NORMAL, - bool solidBackground = false); - - /** - Returns the bitmap corresponding to the given index. - */ - wxBitmap GetBitmap(int index) const; - - /** - Returns the icon corresponding to the given index. - */ - wxIcon GetIcon(int index) const; - - /** - Returns the number of images in the list. - */ - int GetImageCount() const; - - /** - Retrieves the size of the images in the list. Currently, the @a index - parameter is ignored as all images in the list have the same size. - - @param index - currently unused, should be 0 - @param width - receives the width of the images in the list - @param height - receives the height of the images in the list - - @return @true if the function succeeded, @false if it failed (for example, - if the image list was not yet initialized). - */ - bool GetSize(int index, int& width, int& height) const; - - /** - Removes the image at the given position. - */ - bool Remove(int index); - - /** - Removes all the images in the list. - */ - bool RemoveAll(); - - //@{ - /** - Replaces the existing image with the new image. - - @param bitmap - Bitmap representing the opaque areas of the image. - @param mask - Monochrome mask bitmap, representing the transparent areas of the image. - @param icon - Icon to use as the image. - - @return @true if the replacement was successful, @false otherwise. - - @remarks The original bitmap or icon is not affected by the Replace - operation, and can be deleted afterwards. - */ - bool Replace(int index, const wxBitmap& bitmap, - const wxBitmap& mask = wxNullBitmap); - bool Replace(int index, const wxIcon& icon); - //@} -}; - diff --git a/interface/init.h b/interface/init.h deleted file mode 100644 index 499dbe1eed..0000000000 --- a/interface/init.h +++ /dev/null @@ -1,53 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: init.h -// Purpose: interface of global functions -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** @ingroup group_funcmacro_appinitterm */ -//@{ - -/** - This function can be used to perform the initialization of wxWidgets if you - can't use the default initialization code for any reason. - - If the function returns true, the initialization was successful and the - global wxApp object ::wxTheApp has been created. Moreover, wxEntryCleanup() - must be called afterwards. If the function returns false, a catastrophic - initialization error occured and (at least the GUI part of) the library - can't be used at all. - - Notice that parameters @c argc and @c argv may be modified by this - function. - - @header{wx/init.h} -*/ -bool wxEntryStart(int& argc, wxChar** argv); - -/** - See wxEntryStart(int&,wxChar**) for more info about this function. - - This is an additional overload of wxEntryStart() provided under MSW only. - It is meant to be called with the parameters passed to WinMain(). - - @note Under Windows CE platform, and only there, the type of @a pCmdLine is - @c wchar_t *, otherwise it is @c char *, even in Unicode build. - - @header{wx/init.h} -*/ -bool wxEntryStart(HINSTANCE hInstance, - HINSTANCE hPrevInstance = NULL, - char* pCmdLine = NULL, - int nCmdShow = SW_SHOWNORMAL); - -/** - Free resources allocated by a successful call to wxEntryStart(). - - @header{wx/init.h} -*/ -void wxEntryCleanup(); - -//@} - diff --git a/interface/intl.h b/interface/intl.h deleted file mode 100644 index e71e3ef00f..0000000000 --- a/interface/intl.h +++ /dev/null @@ -1,661 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: intl.h -// Purpose: interface of wxLocale -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxLocale - @wxheader{intl.h} - - wxLocale class encapsulates all language-dependent settings and is a - generalization of the C locale concept. - - In wxWidgets this class manages message catalogs which contain the translations - of the strings used to the current language. - - @b wxPerl note: In wxPerl you can't use the '_' function name, so - the @c Wx::Locale module can export the @c gettext and - @c gettext_noop under any given name. - - @code - # this imports gettext ( equivalent to Wx::GetTranslation - # and gettext_noop ( a noop ) - # into your module - use Wx::Locale qw(:default); - - # .... - - # use the functions - print gettext( "Panic!" ); - - button = Wx::Button-new( window, -1, gettext( "Label" ) ); - @endcode - - If you need to translate a lot of strings, then adding gettext( ) around - each one is a long task ( that is why _( ) was introduced ), so just choose - a shorter name for gettext: - - @code - # - use Wx::Locale 'gettext' = 't', - 'gettext_noop' = 'gettext_noop'; - - # ... - - # use the functions - print t( "Panic!!" ); - - # ... - @endcode - - @library{wxbase} - @category{FIXME} - - @see @ref overview_internationalization, @ref overview_sampleinternat "Internat - sample", wxXLocale -*/ -class wxLocale -{ -public: - //@{ - /** - See Init() for parameters description. - The call of this function has several global side effects which you should - understand: first of all, the application locale is changed - note that this - will affect many of standard C library functions such as printf() or strftime(). - Second, this wxLocale object becomes the new current global locale for the - application and so all subsequent calls to wxGetTranslation() will try to - translate the messages using the message catalogs for this locale. - */ - wxLocale(); - wxLocale(int language, - int flags = - wxLOCALE_LOAD_DEFAULT | wxLOCALE_CONV_ENCODING); - wxLocale(const wxString& name, - const wxString& short = wxEmptyString, - const wxString& locale = wxEmptyString, - bool bLoadDefault = true, - bool bConvertEncoding = false); - //@} - - /** - The destructor, like the constructor, also has global side effects: the - previously - set locale is restored and so the changes described in - Init() documentation are rolled back. - */ - ~wxLocale(); - - //@{ - /** - Add a catalog for use with the current locale: it is searched for in standard - places (current directory first, then the system one), but you may also prepend - additional directories to the search path with - AddCatalogLookupPathPrefix(). - All loaded catalogs will be used for message lookup by - GetString() for the current locale. - Returns @true if catalog was successfully loaded, @false otherwise (which might - mean that the catalog is not found or that it isn't in the correct format). - The second form of this method takes two additional arguments, - @a msgIdLanguage and @e msgIdCharset. - @a msgIdLanguage specifies the language of "msgid" strings in source code - (i.e. arguments to GetString(), - wxGetTranslation() and the - _() macro). It is used if AddCatalog cannot find any - catalog for current language: if the language is same as source code language, - then strings from source code are used instead. - @a msgIdCharset lets you specify the charset used for msgids in sources - in case they use 8-bit characters (e.g. German or French strings). This - argument has no effect in Unicode build, because literals in sources are - Unicode strings; you have to use compiler-specific method of setting the right - charset when compiling with Unicode. - By default (i.e. when you use the first form), msgid strings are assumed - to be in English and written only using 7-bit ASCII characters. - If you have to deal with non-English strings or 8-bit characters in the source - code, see the instructions in - @ref overview_nonenglishoverview "Writing non-English applications". - */ - bool AddCatalog(const wxString& domain); - bool AddCatalog(const wxString& domain, - wxLanguage msgIdLanguage, - const wxString& msgIdCharset); - //@} - - /** - Add a prefix to the catalog lookup path: the message catalog files will be - looked up under prefix/lang/LC_MESSAGES, prefix/lang and prefix - (in this order). - This only applies to subsequent invocations of AddCatalog(). - */ - void AddCatalogLookupPathPrefix(const wxString& prefix); - - /** - Adds custom, user-defined language to the database of known languages. This - database is used in conjunction with the first form of - Init(). - wxLanguageInfo is defined as follows: - @e Language should be greater than wxLANGUAGE_USER_DEFINED. - Wx::LanguageInfo-new( language, canonicalName, WinLang, WinSubLang, Description - ) - */ - static void AddLanguage(const wxLanguageInfo& info); - - /** - This function may be used to find the language description structure for the - given locale, specified either as a two letter ISO language code (for example, - "pt"), a language code followed by the country code ("pt_BR") or a full, human - readable, language description ("Portuguese-Brazil"). - Returns the information for the given language or @NULL if this language - is unknown. Note that even if the returned pointer is valid, the caller should - @e not delete it. - - @see GetLanguageInfo() - */ - static wxLanguageInfo* FindLanguageInfo(const wxString& locale); - - /** - Returns the canonical form of current locale name. Canonical form is the - one that is used on UNIX systems: it is a two- or five-letter string in xx or - xx_YY format, where xx is ISO 639 code of language and YY is ISO 3166 code of - the country. Examples are "en", "en_GB", "en_US" or "fr_FR". - This form is internally used when looking up message catalogs. - Compare GetSysName(). - */ - wxString GetCanonicalName() const; - - /** - Returns the header value for header @e header. The search for @a header is case - sensitive. If an @e domain - is passed, this domain is searched. Else all domains will be searched until a - header has been found. - The return value is the value of the header if found. Else this will be empty. - */ - wxString GetHeaderValue(const wxString& header, - const wxString& domain = wxEmptyString) const; - - /** - Returns wxLanguage() constant of current language. - Note that you can call this function only if you used the form of - Init() that takes wxLanguage argument. - */ - int GetLanguage() const; - - /** - Returns a pointer to wxLanguageInfo structure containing information about the - given language or @NULL if this language is unknown. Note that even if the - returned pointer is valid, the caller should @e not delete it. - See AddLanguage() for the wxLanguageInfo - description. - As with Init(), @c wxLANGUAGE_DEFAULT has the - special meaning if passed as an argument to this function and in this case the - result of GetSystemLanguage() is used. - */ - static wxLanguageInfo* GetLanguageInfo(int lang) const; - - /** - Returns English name of the given language or empty string if this - language is unknown. - See GetLanguageInfo() for a remark about - special meaning of @c wxLANGUAGE_DEFAULT. - */ - static wxString GetLanguageName(int lang) const; - - /** - Returns the locale name as passed to the constructor or - Init(). This is full, human-readable name, - e.g. "English" or "French". - */ - const wxString GetLocale() const; - - /** - Returns the current short name for the locale (as given to the constructor or - the Init() function). - */ - const wxString GetName() const; - - //@{ - /** - Retrieves the translation for a string in all loaded domains unless the szDomain - parameter is specified (and then only this catalog/domain is searched). - Returns original string if translation is not available - (in this case an error message is generated the first time - a string is not found; use wxLogNull to suppress it). - The second form is used when retrieving translation of string that has - different singular and plural form in English or different plural forms in some - other language. It takes two extra arguments: @e origString - parameter must contain the singular form of the string to be converted. - It is also used as the key for the search in the catalog. - The @a origString2 parameter is the plural form (in English). - The parameter @a n is used to determine the plural form. If no - message catalog is found @a origString is returned if 'n == 1', - otherwise @e origString2. - See GNU gettext manual for additional information on plural forms handling. - This method is called by the wxGetTranslation() - function and _() macro. - - @remarks Domains are searched in the last to first order, i.e. catalogs - added later override those added before. - */ - const wxString GetString(const wxString& origString, - const wxString& domain = wxEmptyString) const; - const const wxString& GetString(const wxString& origString, - const wxString& origString2, - size_t n, - const wxString& domain = NULL) const; - //@} - - /** - Returns current platform-specific locale name as passed to setlocale(). - Compare GetCanonicalName(). - */ - wxString GetSysName() const; - - /** - Tries to detect the user's default font encoding. - Returns wxFontEncoding() value or - @b wxFONTENCODING_SYSTEM if it couldn't be determined. - */ - static wxFontEncoding GetSystemEncoding() const; - - /** - Tries to detect the name of the user's default font encoding. This string isn't - particularly useful for the application as its form is platform-dependent and - so you should probably use - GetSystemEncoding() instead. - Returns a user-readable string value or an empty string if it couldn't be - determined. - */ - static wxString GetSystemEncodingName() const; - - /** - Tries to detect the user's default language setting. - Returns wxLanguage() value or - @b wxLANGUAGE_UNKNOWN if the language-guessing algorithm failed. - */ - static int GetSystemLanguage() const; - - //@{ - /** - The second form is deprecated, use the first one unless you know what you are - doing. - - @param language - wxLanguage identifier of the locale. - wxLANGUAGE_DEFAULT has special meaning -- wxLocale will use system's - default - language (see GetSystemLanguage). - @param flags - Combination of the following: - - - - - - - - wxLOCALE_LOAD_DEFAULT - - - - - Load the message catalog - for the given locale containing the translations of standard wxWidgets - messages - automatically. - - - - - - wxLOCALE_CONV_ENCODING - - - - - Automatically convert message - catalogs to platform's default encoding. Note that it will do only basic - conversion between well-known pair like iso8859-1 and windows-1252 or - iso8859-2 and windows-1250. See Writing non-English applications for - detailed - description of this behaviour. Note that this flag is meaningless in - Unicode build. - @param name - The name of the locale. Only used in diagnostic messages. - @param short - The standard 2 letter locale abbreviation; it is used as the - directory prefix when looking for the message catalog files. - @param locale - The parameter for the call to setlocale(). Note that it is - platform-specific. - @param bLoadDefault - May be set to @false to prevent loading of the message catalog - for the given locale containing the translations of standard wxWidgets - messages. - This parameter would be rarely used in normal circumstances. - @param bConvertEncoding - May be set to @true to do automatic conversion of message - catalogs to platform's native encoding. Note that it will do only basic - conversion between well-known pair like iso8859-1 and windows-1252 or - iso8859-2 and windows-1250. - See Writing non-English applications for detailed - description of this behaviour. - */ - bool Init(int language = wxLANGUAGE_DEFAULT, - int flags = - wxLOCALE_LOAD_DEFAULT | wxLOCALE_CONV_ENCODING); - bool Init(const wxString& name, - const wxString& short = wxEmptyString, - const wxString& locale = wxEmptyString, - bool bLoadDefault = true, - bool bConvertEncoding = false); - //@} - - /** - Check whether the operating system and/or C run time environment supports - this locale. For example in Windows 2000 and Windows XP, support for many - locales is not installed by default. Returns @true if the locale is - supported. - The argument @a lang is the wxLanguage identifier. To obtain this for a - given a two letter ISO language code, use - FindLanguageInfo() to obtain its - wxLanguageInfo structure. See AddLanguage() for - the wxLanguageInfo description. - - @since 2.7.1. - */ - static bool IsAvailable(int lang); - - /** - Check if the given catalog is loaded, and returns @true if it is. - According to GNU gettext tradition, each catalog - normally corresponds to 'domain' which is more or less the application name. - See also: AddCatalog() - */ - bool IsLoaded(const char* domain) const; - - /** - Returns @true if the locale could be set successfully. - */ - bool IsOk() const; - - /** - See @ref overview_languagecodes "list of recognized language constants". - These constants may be used to specify the language - in Init() and are returned by - GetSystemLanguage(): - */ -}; - - - -/** - @class wxXLocale - @wxheader{intl.h} - - - wxXLocale::wxXLocale - wxXLocale::GetCLocale - wxXLocale::IsOk - - - Introduction - - This class represents a locale object used by so-called xlocale API. Unlike - wxLocale it doesn't provide any non-trivial operations but - simply provides a portable wrapper for POSIX @c locale_t type. It exists - solely to be provided as an argument to various @c wxFoo_l() functions - which are the extensions of the standard locale-dependent functions (hence the - name xlocale). These functions do exactly the same thing as the corresponding - standard @c foo() except that instead of using the global program locale - they use the provided wxXLocale object. For example, if the user runs the - program in French locale, the standard @c printf() function will output - floating point numbers using decimal comma instead of decimal period. If the - program needs to format a floating-point number in a standard format it can - use @c wxPrintf_l(wxXLocale::GetCLocale(), "%g", number) to do it. - Conversely, if a program wanted to output the number in French locale, even if - the current locale is different, it could use wxXLocale(wxLANGUAGE_FRENCH). - - - Availability - - This class is fully implemented only under the platforms where xlocale POSIX - API or equivalent is available. Currently the xlocale API is available under - most of the recent Unix systems (including Linux, various BSD and Mac OS X) and - Microsoft Visual C++ standard library provides a similar API starting from - version 8 (Visual Studio 2005). - - If neither POSIX API nor Microsoft proprietary equivalent are available, this - class is still available but works in degraded mode: the only supported locale - is the C one and attempts to create wxXLocale object for any other locale will - fail. You can use the preprocessor macro @c wxHAS_XLOCALE_SUPPORT to - test if full xlocale API is available or only skeleton C locale support is - present. - - Notice that wxXLocale is new in wxWidgets 2.9.0 and is not compiled in if - @c wxUSE_XLOCALE was set to 0 during the library compilation. - - - Locale-dependent functions - - Currently the following @c _l-functions are available: - - Character classification functions: @c wxIsxxx_l(), e.g. - @c wxIsalpha_l(), @c wxIslower_l() and all the others. - Character transformation functions: @c wxTolower_l() and - @c wxToupper_l() - - We hope to provide many more functions (covering numbers, time and formatted - IO) in the near future. - - @library{wxbase} - @category{FIXME} - - @see wxLocale -*/ -class wxXLocale -{ -public: - //@{ - /** - Creates the locale object corresponding to the specified locale string. The - locale string is system-dependent, use constructor taking wxLanguage for better - portability. - */ - wxLocale(); - wxLocale(wxLanguage lang); - wxLocale(const char* loc); - //@} - - /** - This class is fully implemented only under the platforms where xlocale POSIX - API or equivalent is available. Currently the xlocale API is available under - most of the recent Unix systems (including Linux, various BSD and Mac OS X) and - Microsoft Visual C++ standard library provides a similar API starting from - version 8 (Visual Studio 2005). - If neither POSIX API nor Microsoft proprietary equivalent are available, this - class is still available but works in degraded mode: the only supported locale - is the C one and attempts to create wxXLocale object for any other locale will - fail. You can use the preprocessor macro @c wxHAS_XLOCALE_SUPPORT to - test if full xlocale API is available or only skeleton C locale support is - present. - Notice that wxXLocale is new in wxWidgets 2.9.0 and is not compiled in if - @c wxUSE_XLOCALE was set to 0 during the library compilation. - */ - - - /** - Returns the global object representing the "C" locale. For an even shorter - access to this object a global @c wxCLocale variable (implemented as a - macro) is provided and can be used instead of calling this method. - */ - static wxXLocale GetCLocale(); - - /** - This class represents a locale object used by so-called xlocale API. Unlike - wxLocale it doesn't provide any non-trivial operations but - simply provides a portable wrapper for POSIX @c locale_t type. It exists - solely to be provided as an argument to various @c wxFoo_l() functions - which are the extensions of the standard locale-dependent functions (hence the - name xlocale). These functions do exactly the same thing as the corresponding - standard @c foo() except that instead of using the global program locale - they use the provided wxXLocale object. For example, if the user runs the - program in French locale, the standard @c printf() function will output - floating point numbers using decimal comma instead of decimal period. If the - program needs to format a floating-point number in a standard format it can - use @c wxPrintf_l(wxXLocale::GetCLocale(), "%g", number) to do it. - Conversely, if a program wanted to output the number in French locale, even if - the current locale is different, it could use wxXLocale(wxLANGUAGE_FRENCH). - */ - - - /** - Returns @true if this object is initialized, i.e. represents a valid locale - or - @false otherwise. - */ - bool IsOk() const; - - /** - Currently the following @c _l-functions are available: - Character classification functions: @c wxIsxxx_l(), e.g. - @c wxIsalpha_l(), @c wxIslower_l() and all the others. - Character transformation functions: @c wxTolower_l() and - @c wxToupper_l() - We hope to provide many more functions (covering numbers, time and formatted - IO) in the near future. - - @see wxLocale - */ -}; - - - -// ============================================================================ -// Global functions/macros -// ============================================================================ - -/** @ingroup group_funcmacro_string */ -//@{ - -/** - This macro is identical to _() but for the plural variant of - wxGetTranslation(). - - @return A const wxString. - - @header{wx/intl.h} -*/ -#define wxPLURAL(string, plural, n) - -/** - This macro doesn't do anything in the program code -- it simply expands to - the value of its argument. - - However it does have a purpose which is to mark the literal strings for the - extraction into the message catalog created by @c xgettext program. Usually - this is achieved using _() but that macro not only marks the string for - extraction but also expands into a wxGetTranslation() call which means that - it cannot be used in some situations, notably for static array - initialization. - - Here is an example which should make it more clear: suppose that you have a - static array of strings containing the weekday names and which have to be - translated (note that it is a bad example, really, as wxDateTime already - can be used to get the localized week day names already). If you write: - - @code - static const char * const weekdays[] = { _("Mon"), ..., _("Sun") }; - ... - // use weekdays[n] as usual - @endcode - - The code wouldn't compile because the function calls are forbidden in the - array initializer. So instead you should do this: - - @code - static const char * const weekdays[] = { wxTRANSLATE("Mon"), ..., - wxTRANSLATE("Sun") }; - ... - // use wxGetTranslation(weekdays[n]) - @endcode - - Note that although the code @b would compile if you simply omit - wxTRANSLATE() in the above, it wouldn't work as expected because there - would be no translations for the weekday names in the program message - catalog and wxGetTranslation() wouldn't find them. - - @return A const wxChar*. - - @header{wx/intl.h} -*/ -#define wxTRANSLATE(string) - -/** - This function returns the translation of @a string in the current - @c locale(). If the string is not found in any of the loaded message - catalogs (see @ref overview_i18n), the original string is returned. In - debug build, an error message is logged -- this should help to find the - strings which were not yet translated. If @a domain is specified then only - that domain/catalog is searched for a matching string. As this function is - used very often, an alternative (and also common in Unix world) syntax is - provided: the _() macro is defined to do the same thing as - wxGetTranslation(). - - This function calls wxLocale::GetString(). - - @note This function is not suitable for literal strings in Unicode builds - since the literal strings must be enclosed into _T() or wxT() macro - which makes them unrecognised by @c xgettext, and so they are not - extracted to the message catalog. Instead, use the _() and wxPLURAL() - macro for all literal strings. - - @see wxGetTranslation(const wxString&, const wxString&, size_t, const wxString&) - - @header{wx/intl.h} -*/ -const wxString wxGetTranslation(const wxString& string, - const wxString& domain = wxEmptyString); - -/** - This is an overloaded version of - wxGetTranslation(const wxString&, const wxString&), please see its - documentation for general information. - - This version is used when retrieving translation of string that has - different singular and plural forms in English or different plural forms in - some other language. Like wxGetTranslation(const wxString&,const wxString&), - the @a string parameter must contain the singular form of the string to be - converted and is used as the key for the search in the catalog. The - @a plural parameter is the plural form (in English). The parameter @a n is - used to determine the plural form. If no message catalog is found, - @a string is returned if "n == 1", otherwise @a plural is returned. - - See GNU gettext Manual for additional information on plural forms handling: - - For a shorter alternative see the wxPLURAL() macro. - - This function calls wxLocale::GetString(). - - @header{wx/intl.h} -*/ -const wxString wxGetTranslation(const wxString& string, - const wxString& plural, size_t n, - const wxString& domain = wxEmptyString); - -/** - This macro expands into a call to wxGetTranslation(), so it marks the - message for the extraction by @c xgettext just as wxTRANSLATE() does, but - also returns the translation of the string for the current locale during - execution. - - Don't confuse this with _T()! - - @header{wx/intl.h} -*/ -const wxString _(const wxString& string); - -//@} - diff --git a/interface/ipc.h b/interface/ipc.h deleted file mode 100644 index c6bd35c787..0000000000 --- a/interface/ipc.h +++ /dev/null @@ -1,350 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: ipc.h -// Purpose: interface of wxConnection -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxConnection - @wxheader{ipc.h} - - A wxConnection object represents the connection between a client - and a server. It is created by making a connection using a - wxClient object, or by the acceptance of a - connection by a wxServer object. The - bulk of a DDE-like (Dynamic Data Exchange) conversation is - controlled by calling members in a @b wxConnection object or - by overriding its members. The actual DDE-based implementation - using wxDDEConnection is available on Windows only, but a - platform-independent, socket-based version of this API is - available using wxTCPConnection, which has the same API. - - An application should normally derive a new connection class from - wxConnection, in order to override the communication event - handlers to do something interesting. - - @library{wxbase} - @category{FIXME} - - @see wxClient, wxServer, @ref overview_ipcoverview "Interprocess communications - overview" -*/ -class wxConnection : public wxObject -{ -public: - //@{ - /** - Constructs a connection object. If no user-defined connection - object is to be derived from wxConnection, then the constructor - should not be called directly, since the default connection - object will be provided on requesting (or accepting) a - connection. However, if the user defines his or her own derived - connection object, the wxServer::OnAcceptConnection - and/or wxClient::OnMakeConnection - members should be replaced by functions which construct the new - connection object. - If the arguments of the wxConnection constructor are void then - the wxConnection object manages its own connection buffer, - allocating memory as needed. A programmer-supplied buffer cannot - be increased if necessary, and the program will assert if it is - not large enough. The programmer-supplied buffer is included - mainly for backwards compatibility. - */ - wxConnection(); - wxConnection(void* buffer, size_t size); - //@} - - //@{ - /** - Called by the server application to advise the client of a change - in the data associated with the given item. Causes the client - connection's OnAdvise() member - to be called. Returns @true if successful. - */ - bool Advise(const wxString& item, const void* data, size_t size, - wxIPCFormat format = wxIPC_PRIVATE); - bool Advise(const wxString& item, const char* data); - bool Advise(const wxString& item, const wchar_t* data); - bool Advise(const wxString& item, const wxString data); - //@} - - /** - Called by the client or server application to disconnect from the - other program; it causes the OnDisconnect() - message to be sent to the corresponding connection object in the - other program. Returns @true if successful or already disconnected. - The application that calls @b Disconnect must explicitly delete - its side of the connection. - */ - bool Disconnect(); - - //@{ - /** - Called by the client application to execute a command on the - server. Can also be used to transfer arbitrary data to the server - (similar to Poke() in - that respect). Causes the server connection's OnExec() - member to be called. Returns @true if successful. - */ - bool Execute(const void* data, size_t size, - wxIPCFormat format = wxIPC_PRIVATE); - bool Execute(const char* data); - bool Execute(const wchar_t* data); - bool Execute(const wxString data); - //@} - - /** - Message sent to the client application when the server notifies - it of a change in the data associated with the given item, using - Advise(). - */ - virtual bool OnAdvise(const wxString& topic, - const wxString& item, - const void* data, - size_t size, - wxIPCFormat format); - - /** - Message sent to the client or server application when the other - application notifies it to end the connection. The default - behaviour is to delete the connection object and return @true, so - applications should generally override @b OnDisconnect - (finally calling the inherited method as well) so that they know - the connection object is no longer available. - */ - virtual bool OnDisconnect(); - - /** - Message sent to the server application when the client notifies - it to execute the given data, using Execute(). - Note that there is no item associated with this message. - */ - virtual bool OnExec(const wxString& topic, const wxString& data); - - /** - Message sent to the server application when the client notifies it to - accept the given data. - */ - virtual bool OnPoke(const wxString& topic, const wxString& item, - const void* data, - size_t size, - wxIPCFormat format); - - /** - Message sent to the server application when the client calls - Request(). The - server's OnRequest() method - should respond by returning a character string, or @NULL to - indicate no data, and setting *size. The character string must of - course persist after the call returns. - */ - virtual const void* OnRequest(const wxString& topic, - const wxString& item, - size_t* size, - wxIPCFormat format); - - /** - Message sent to the server application by the client, when the client - wishes to start an 'advise loop' for the given topic and item. The - server can refuse to participate by returning @false. - */ - virtual bool OnStartAdvise(const wxString& topic, - const wxString& item); - - /** - Message sent to the server application by the client, when the client - wishes to stop an 'advise loop' for the given topic and item. The - server can refuse to stop the advise loop by returning @false, although - this doesn't have much meaning in practice. - */ - virtual bool OnStopAdvise(const wxString& topic, - const wxString& item); - - //@{ - /** - Called by the client application to poke data into the server. - Can be used to transfer arbitrary data to the server. Causes the - server connection's OnPoke() member to - be called. If size is -1 the size is computed from the string - length of data. - Returns @true if successful. - */ - bool Poke(const wxString& item, const void* data, size_t size, - wxIPCFormat format = wxIPC_PRIVATE); - bool Poke(const wxString& item, const char* data); - bool Poke(const wxString& item, const wchar_t* data); - bool Poke(const wxString& item, const wxString data); - //@} - - /** - Called by the client application to request data from the server. - Causes the server connection's OnRequest() - member to be called. Size may be @NULL or a pointer to a variable - to receive the size of the requested item. - Returns a character string (actually a pointer to the - connection's buffer) if successful, @NULL otherwise. This buffer - does not need to be deleted. - */ - const void* Request(const wxString& item, size_t* size, - wxIPCFormat format = wxIPC_TEXT); - - /** - Called by the client application to ask if an advise loop can be - started with the server. Causes the server connection's - OnStartAdvise() - member to be called. Returns @true if the server okays it, @false - otherwise. - */ - bool StartAdvise(const wxString& item); - - /** - Called by the client application to ask if an advise loop can be - stopped. Causes the server connection's OnStopAdvise() - member to be called. Returns @true if the server okays it, @false - otherwise. - */ - bool StopAdvise(const wxString& item); -}; - - - -/** - @class wxClient - @wxheader{ipc.h} - - A wxClient object represents the client part of a client-server - DDE-like (Dynamic Data Exchange) conversation. The actual - DDE-based implementation using wxDDEClient is available on Windows - only, but a platform-independent, socket-based version of this - API is available using wxTCPClient, which has the same API. - - To create a client which can communicate with a suitable server, - you need to derive a class from wxConnection and another from - wxClient. The custom wxConnection class will intercept - communications in a 'conversation' with a server, and the custom - wxClient is required so that a user-overridden - wxClient::OnMakeConnection - member can return a wxConnection of the required class, when a - connection is made. Look at the IPC sample and the - @ref overview_ipcoverview "Interprocess communications overview" for - an example of how to do this. - - @library{wxbase} - @category{FIXME} - - @see wxServer, wxConnection, @ref overview_ipcoverview "Interprocess - communications overview" -*/ -class wxClient : public wxObject -{ -public: - /** - Constructs a client object. - */ - wxClient(); - - /** - Tries to make a connection with a server by host (machine name - under UNIX - use 'localhost' for same machine; ignored when using - native DDE in Windows), service name and topic string. If the - server allows a connection, a wxConnection object will be - returned. The type of wxConnection returned can be altered by - overriding the - OnMakeConnection() - member to return your own derived connection object. - Under Unix, the service name may be either an integer port - identifier in which case an Internet domain socket will be used - for the communications, or a valid file name (which shouldn't - exist and will be deleted afterwards) in which case a Unix domain - socket is created. - @b SECURITY NOTE: Using Internet domain sockets if extremely - insecure for IPC as there is absolutely no access control for - them, use Unix domain sockets whenever possible! - */ - wxConnectionBase* MakeConnection(const wxString& host, - const wxString& service, - const wxString& topic); - - /** - Called by MakeConnection(), by - default this simply returns a new wxConnection object. Override - this method to return a wxConnection descendant customised for the - application. - The advantage of deriving your own connection class is that it - will enable you to intercept messages initiated by the server, - such as wxConnection::OnAdvise. You - may also want to store application-specific data in instances of - the new class. - */ - wxConnectionBase* OnMakeConnection(); - - /** - Returns @true if this is a valid host name, @false otherwise. This always - returns @true under MS Windows. - */ - bool ValidHost(const wxString& host); -}; - - - -/** - @class wxServer - @wxheader{ipc.h} - - A wxServer object represents the server part of a client-server - DDE-like (Dynamic Data Exchange) conversation. The actual - DDE-based implementation using wxDDEServer is available on Windows - only, but a platform-independent, socket-based version of this - API is available using wxTCPServer, which has the same API. - - To create a server which can communicate with a suitable client, - you need to derive a class from wxConnection and another from - wxServer. The custom wxConnection class will intercept - communications in a 'conversation' with a client, and the custom - wxServer is required so that a user-overridden wxServer::OnAcceptConnection - member can return a wxConnection of the required class, when a - connection is made. Look at the IPC sample and the @ref overview_ipcoverview - "Interprocess communications overview" for - an example of how to do this. - - @library{wxbase} - @category{FIXME} - - @see wxClient, wxConnection, IPC, overview() -*/ -class wxServer -{ -public: - /** - Constructs a server object. - */ - wxServer(); - - /** - Registers the server using the given service name. Under Unix, - the service name may be either an integer port identifier in - which case an Internet domain socket will be used for the - communications, or a valid file name (which shouldn't exist and - will be deleted afterwards) in which case a Unix domain socket is - created. @false is returned if the call failed (for example, the - port number is already in use). - */ - bool Create(const wxString& service); - - /** - When a client calls @b MakeConnection, the server receives the - message and this member is called. The application should derive a - member to intercept this message and return a connection object of - either the standard wxConnection type, or (more likely) of a - user-derived type. - If the topic is @b STDIO, the application may wish to refuse the - connection. Under UNIX, when a server is created the - OnAcceptConnection message is always sent for standard input and - output, but in the context of DDE messages it doesn't make a lot - of sense. - */ - virtual wxConnectionBase* OnAcceptConnection(const wxString& topic); -}; - diff --git a/interface/ipcbase.h b/interface/ipcbase.h deleted file mode 100644 index f8728ccdc4..0000000000 --- a/interface/ipcbase.h +++ /dev/null @@ -1,53 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: ipcbase.h -// Purpose: interface of wxConnectionBase -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -enum wxIPCFormat -{ - wxIPC_INVALID = 0, - wxIPC_TEXT = 1, ///< CF_TEXT - wxIPC_BITMAP = 2, ///< CF_BITMAP - wxIPC_METAFILE = 3, ///< CF_METAFILEPICT - wxIPC_SYLK = 4, - wxIPC_DIF = 5, - wxIPC_TIFF = 6, - wxIPC_OEMTEXT = 7, ///< CF_OEMTEXT - wxIPC_DIB = 8, ///< CF_DIB - wxIPC_PALETTE = 9, - wxIPC_PENDATA = 10, - wxIPC_RIFF = 11, - wxIPC_WAVE = 12, - wxIPC_UTF16TEXT = 13, ///< CF_UNICODE - wxIPC_ENHMETAFILE = 14, - wxIPC_FILENAME = 15, ///< CF_HDROP - wxIPC_LOCALE = 16, - wxIPC_UTF8TEXT = 17, - wxIPC_UTF32TEXT = 18, - wxIPC_UNICODETEXT = wxIPC_UTF16TEXT, - wxIPC_PRIVATE = 20 -}; - -/** - @class wxConnectionBase - @wxheader{ipcbase.h} - - @todo Document this class. - - This class provides base, common functionality shared between - wxDDEConnection, and wxTCPConnection. - - @library{wxbase} - @category{ipc} - - @see wxDDEConnection, wxTCPConnection -*/ -class wxConnectionBase: public wxObject -{ -public: - -}; - diff --git a/interface/joystick.h b/interface/joystick.h deleted file mode 100644 index d9b739c6ff..0000000000 --- a/interface/joystick.h +++ /dev/null @@ -1,272 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: joystick.h -// Purpose: interface of wxJoystick -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxJoystick - @wxheader{joystick.h} - - wxJoystick allows an application to control one or more joysticks. - - @library{wxadv} - @category{FIXME} - - @see wxJoystickEvent -*/ -class wxJoystick : public wxObject -{ -public: - /** - Constructor. @a joystick may be one of wxJOYSTICK1, wxJOYSTICK2, indicating the - joystick - controller of interest. - */ - wxJoystick(int joystick = wxJOYSTICK1); - - /** - Destroys the wxJoystick object. - */ - ~wxJoystick(); - - //@{ - /** - Returns the state of the specified joystick button. - - @param id - The button id to report, from 0 to GetNumberButtons() - 1 - */ - int GetButtonState() const; - const bool GetButtonState(unsigned id) const; - //@} - - /** - Returns the manufacturer id. - */ - int GetManufacturerId() const; - - /** - Returns the movement threshold, the number of steps outside which the joystick - is deemed to have - moved. - */ - int GetMovementThreshold() const; - - /** - Returns the number of axes for this joystick. - */ - int GetNumberAxes() const; - - /** - Returns the number of buttons for this joystick. - */ - int GetNumberButtons() const; - - /** - Returns the number of joysticks currently attached to the computer. - */ - static int GetNumberJoysticks(); - - /** - Returns the point-of-view position, expressed in continuous, one-hundredth of a - degree units. - Returns -1 on error. - */ - int GetPOVCTSPosition() const; - - /** - Returns the point-of-view position, expressed in continuous, one-hundredth of a - degree units, - but limited to return 0, 9000, 18000 or 27000. - Returns -1 on error. - */ - int GetPOVPosition() const; - - /** - Returns the maximum polling frequency. - */ - int GetPollingMax() const; - - /** - Returns the minimum polling frequency. - */ - int GetPollingMin() const; - - //@{ - /** - Returns the position of the specified joystick axis. - - @param axis - The joystick axis to report, from 0 to GetNumberAxes() - 1. - */ - wxPoint GetPosition() const; - const int GetPosition(unsigned axis) const; - //@} - - /** - Returns the product id for the joystick. - */ - int GetProductId() const; - - /** - Returns the product name for the joystick. - */ - wxString GetProductName() const; - - /** - Returns the maximum rudder position. - */ - int GetRudderMax() const; - - /** - Returns the minimum rudder position. - */ - int GetRudderMin() const; - - /** - Returns the rudder position. - */ - int GetRudderPosition() const; - - /** - Returns the maximum U position. - */ - int GetUMax() const; - - /** - Returns the minimum U position. - */ - int GetUMin() const; - - /** - Gets the position of the fifth axis of the joystick, if it exists. - */ - int GetUPosition() const; - - /** - Returns the maximum V position. - */ - int GetVMax() const; - - /** - Returns the minimum V position. - */ - int GetVMin() const; - - /** - Gets the position of the sixth axis of the joystick, if it exists. - */ - int GetVPosition() const; - - /** - Returns the maximum x position. - */ - int GetXMax() const; - - /** - Returns the minimum x position. - */ - int GetXMin() const; - - /** - Returns the maximum y position. - */ - int GetYMax() const; - - /** - Returns the minimum y position. - */ - int GetYMin() const; - - /** - Returns the maximum z position. - */ - int GetZMax() const; - - /** - Returns the minimum z position. - */ - int GetZMin() const; - - /** - Returns the z position of the joystick. - */ - int GetZPosition() const; - - /** - Returns @true if the joystick has a point of view control. - */ - bool HasPOV() const; - - /** - Returns @true if the joystick point-of-view supports discrete values (centered, - forward, backward, left, and right). - */ - bool HasPOV4Dir() const; - - /** - Returns @true if the joystick point-of-view supports continuous degree bearings. - */ -#define bool HasPOVCTS() const /* implementation is private */ - - /** - Returns @true if there is a rudder attached to the computer. - */ - bool HasRudder() const; - - /** - Returns @true if the joystick has a U axis. - */ - bool HasU() const; - - /** - Returns @true if the joystick has a V axis. - */ - bool HasV() const; - - /** - Returns @true if the joystick has a Z axis. - */ - bool HasZ() const; - - /** - Returns @true if the joystick is functioning. - */ - bool IsOk() const; - - /** - Releases the capture set by @b SetCapture. - - @return @true if the capture release succeeded. - - @see SetCapture(), wxJoystickEvent - */ - bool ReleaseCapture(); - - /** - Sets the capture to direct joystick events to @e win. - - @param win - The window that will receive joystick events. - @param pollingFreq - If zero, movement events are sent when above the - threshold. If greater than zero, events are received every pollingFreq - milliseconds. - - @return @true if the capture succeeded. - - @see ReleaseCapture(), wxJoystickEvent - */ - bool SetCapture(wxWindow* win, int pollingFreq = 0); - - /** - Sets the movement threshold, the number of steps outside which the joystick is - deemed to have - moved. - */ - void SetMovementThreshold(int threshold); -}; - diff --git a/interface/laywin.h b/interface/laywin.h deleted file mode 100644 index a09ff3d194..0000000000 --- a/interface/laywin.h +++ /dev/null @@ -1,416 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: laywin.h -// Purpose: interface of wxLayoutAlgorithm -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxLayoutAlgorithm - @wxheader{laywin.h} - - wxLayoutAlgorithm implements layout of subwindows in MDI or SDI frames. - It sends a wxCalculateLayoutEvent event - to children of the frame, asking them for information about - their size. For MDI parent frames, the algorithm allocates - the remaining space to the MDI client window (which contains the MDI child - frames). - For SDI (normal) frames, a 'main' window is specified as taking up the - remaining space. - - Because the event system is used, this technique can be applied to any windows, - which are not necessarily 'aware' of the layout classes (no virtual functions - in wxWindow refer to wxLayoutAlgorithm or its events). However, you - may wish to use wxSashLayoutWindow for your subwindows - since this class provides handlers for the required events, and accessors - to specify the desired size of the window. The sash behaviour in the base class - can be used, optionally, to make the windows user-resizable. - - wxLayoutAlgorithm is typically used in IDE (integrated development environment) - applications, - where there are several resizable windows in addition to the MDI client window, - or - other primary editing window. Resizable windows might include toolbars, a - project - window, and a window for displaying error and warning messages. - - When a window receives an OnCalculateLayout event, it should call SetRect in - the given event object, to be the old supplied rectangle minus whatever space - the - window takes up. It should also set its own size accordingly. - wxSashLayoutWindow::OnCalculateLayout generates an OnQueryLayoutInfo event - which it sends to itself to determine the orientation, alignment and size of - the window, - which it gets from internal member variables set by the application. - - The algorithm works by starting off with a rectangle equal to the whole frame - client area. - It iterates through the frame children, generating OnCalculateLayout events - which subtract - the window size and return the remaining rectangle for the next window to - process. It - is assumed (by wxSashLayoutWindow::OnCalculateLayout) that a window stretches - the full dimension - of the frame client, according to the orientation it specifies. For example, a - horizontal window - will stretch the full width of the remaining portion of the frame client area. - In the other orientation, the window will be fixed to whatever size was - specified by - OnQueryLayoutInfo. An alignment setting will make the window 'stick' to the - left, top, right or - bottom of the remaining client area. This scheme implies that order of window - creation is important. - Say you wish to have an extra toolbar at the top of the frame, a project window - to the left of - the MDI client window, and an output window above the status bar. You should - therefore create - the windows in this order: toolbar, output window, project window. This ensures - that the toolbar and - output window take up space at the top and bottom, and then the remaining - height in-between is used for - the project window. - - wxLayoutAlgorithm is quite independent of the way in which - OnCalculateLayout chooses to interpret a window's size and alignment. Therefore - you - could implement a different window class with a new OnCalculateLayout event - handler, - that has a more sophisticated way of laying out the windows. It might allow - specification of whether stretching occurs in the specified orientation, for - example, - rather than always assuming stretching. (This could, and probably should, be - added to the existing - implementation). - - @e Note: wxLayoutAlgorithm has nothing to do with wxLayoutConstraints. It is an - alternative - way of specifying layouts for which the normal constraint system is unsuitable. - - @library{wxadv} - @category{winlayout} - - @see wxSashEvent, wxSashLayoutWindow, @ref overview_eventhandlingoverview -*/ -class wxLayoutAlgorithm : public wxObject -{ -public: - /** - Default constructor. - */ - wxLayoutAlgorithm(); - - /** - Destructor. - */ - ~wxLayoutAlgorithm(); - - /** - Lays out the children of a normal frame. @a mainWindow is set to occupy the - remaining space. - This function simply calls LayoutWindow(). - */ - bool LayoutFrame(wxFrame* frame, wxWindow* mainWindow = NULL) const; - - /** - Lays out the children of an MDI parent frame. If @a rect is non-@NULL, the - given rectangle will be used as a starting point instead of the frame's client - area. - The MDI client window is set to occupy the remaining space. - */ - bool LayoutMDIFrame(wxMDIParentFrame* frame, wxRect* rect = NULL) const; - - /** - Lays out the children of a normal frame or other window. - @a mainWindow is set to occupy the remaining space. If this is not specified, - then - the last window that responds to a calculate layout event in query mode will - get the remaining space - (that is, a non-query OnCalculateLayout event will not be sent to this window - and the window will be set - to the remaining size). - */ - bool LayoutWindow(wxWindow* parent, wxWindow* mainWindow = NULL) const; -}; - - - -/** - @class wxSashLayoutWindow - @wxheader{laywin.h} - - wxSashLayoutWindow responds to OnCalculateLayout events generated - by wxLayoutAlgorithm. It allows the - application to use simple accessors to specify how the window should be - laid out, rather than having to respond to events. The fact that - the class derives from wxSashWindow allows sashes to be used if required, - to allow the windows to be user-resizable. - - The documentation for wxLayoutAlgorithm explains - the purpose of this class in more detail. - - @library{wxadv} - @category{miscwnd} - - @see wxLayoutAlgorithm, wxSashWindow, @ref overview_eventhandlingoverview -*/ -class wxSashLayoutWindow : public wxSashWindow -{ -public: - //@{ - /** - Constructs a sash layout window, which can be a child of a frame, dialog or any - other non-control window. - - @param parent - Pointer to a parent window. - @param id - Window identifier. If -1, will automatically create an identifier. - @param pos - Window position. wxDefaultPosition is (-1, -1) which indicates that - wxSashLayoutWindows - should generate a default position for the window. If using the - wxSashLayoutWindow class directly, supply - an actual position. - @param size - Window size. wxDefaultSize is (-1, -1) which indicates that - wxSashLayoutWindows - should generate a default size for the window. - @param style - Window style. For window styles, please see wxSashLayoutWindow. - @param name - Window name. - */ - wxSashLayoutWindow(); - wxSashLayoutWindow(wxSashLayoutWindow* parent, wxWindowID id, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = wxCLIP_CHILDREN | wxSW_3D, - const wxString& name = "layoutWindow"); - //@} - - /** - Initializes a sash layout window, which can be a child of a frame, dialog or - any other non-control window. - - @param parent - Pointer to a parent window. - @param id - Window identifier. If -1, will automatically create an identifier. - @param pos - Window position. wxDefaultPosition is (-1, -1) which indicates that - wxSashLayoutWindows - should generate a default position for the window. If using the - wxSashLayoutWindow class directly, supply - an actual position. - @param size - Window size. wxDefaultSize is (-1, -1) which indicates that - wxSashLayoutWindows - should generate a default size for the window. - @param style - Window style. For window styles, please see wxSashLayoutWindow. - @param name - Window name. - */ - bool Create(wxSashLayoutWindow* parent, wxWindowID id, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = wxCLIP_CHILDREN | wxSW_3D, - const wxString& name = "layoutWindow"); - - /** - Returns the alignment of the window: one of wxLAYOUT_TOP, wxLAYOUT_LEFT, - wxLAYOUT_RIGHT, wxLAYOUT_BOTTOM. - */ - wxLayoutAlignment GetAlignment() const; - - /** - Returns the orientation of the window: one of wxLAYOUT_HORIZONTAL, - wxLAYOUT_VERTICAL. - */ - wxLayoutOrientation GetOrientation() const; - - /** - The default handler for the event that is generated by wxLayoutAlgorithm. The - implementation - of this function calls wxCalculateLayoutEvent::SetRect to shrink the provided - size according to - how much space this window takes up. For further details, - see wxLayoutAlgorithm and wxCalculateLayoutEvent. - */ - void OnCalculateLayout(wxCalculateLayoutEvent& event); - - /** - The default handler for the event that is generated by OnCalculateLayout to get - size, alignment and orientation information for the window. The implementation - of this function uses member variables as set by accessors called by the - application. - For further details, see wxLayoutAlgorithm and wxQueryLayoutInfoEvent. - */ - void OnQueryLayoutInfo(wxQueryLayoutInfoEvent& event); - - /** - Sets the alignment of the window (which edge of the available parent client - area the window - is attached to). @a alignment is one of wxLAYOUT_TOP, wxLAYOUT_LEFT, - wxLAYOUT_RIGHT, wxLAYOUT_BOTTOM. - */ - void SetAlignment(wxLayoutAlignment alignment); - - /** - Sets the default dimensions of the window. The dimension other than the - orientation will be fixed to this - value, and the orientation dimension will be ignored and the window stretched - to fit the available space. - */ - void SetDefaultSize(const wxSize& size); - - /** - Sets the orientation of the window (the direction the window will stretch in, - to fill the available - parent client area). @a orientation is one of wxLAYOUT_HORIZONTAL, - wxLAYOUT_VERTICAL. - */ - void SetOrientation(wxLayoutOrientation orientation); -}; - - - -/** - @class wxQueryLayoutInfoEvent - @wxheader{laywin.h} - - This event is sent when wxLayoutAlgorithm wishes to get - the size, orientation and alignment of a window. More precisely, the event is - sent - by the OnCalculateLayout handler which is itself invoked by wxLayoutAlgorithm. - - @library{wxadv} - @category{events} - - @see wxCalculateLayoutEvent, wxSashLayoutWindow, wxLayoutAlgorithm. -*/ -class wxQueryLayoutInfoEvent : public wxEvent -{ -public: - /** - Constructor. - */ - wxQueryLayoutInfoEvent(wxWindowID id = 0); - - /** - Specifies the alignment of the window (which side of the remaining parent - client area - the window sticks to). One of wxLAYOUT_TOP, wxLAYOUT_LEFT, wxLAYOUT_RIGHT, - wxLAYOUT_BOTTOM. - */ - void GetAlignment() const; - - /** - Returns the flags associated with this event. Not currently used. - */ - int GetFlags() const; - - /** - Returns the orientation that the event handler specified to the event object. - May be one of wxLAYOUT_HORIZONTAL, - wxLAYOUT_VERTICAL. - */ - wxLayoutOrientation GetOrientation() const; - - /** - Returns the requested length of the window in the direction of the window - orientation. This information - is not yet used. - */ - int GetRequestedLength() const; - - /** - Returns the size that the event handler specified to the event object as being - the requested size of the window. - */ - wxSize GetSize() const; - - /** - Call this to specify the alignment of the window (which side of the remaining - parent client area - the window sticks to). May be one of wxLAYOUT_TOP, wxLAYOUT_LEFT, - wxLAYOUT_RIGHT, wxLAYOUT_BOTTOM. - */ - void SetAlignment(wxLayoutAlignment alignment); - - /** - Sets the flags associated with this event. Not currently used. - */ - void SetFlags(int flags); - - /** - Call this to specify the orientation of the window. May be one of - wxLAYOUT_HORIZONTAL, - wxLAYOUT_VERTICAL. - */ - void SetOrientation(wxLayoutOrientation orientation); - - /** - Sets the requested length of the window in the direction of the window - orientation. This information - is not yet used. - */ - void SetRequestedLength(int length); - - /** - Call this to let the calling code know what the size of the window is. - */ - void SetSize(const wxSize& size); -}; - - - -/** - @class wxCalculateLayoutEvent - @wxheader{laywin.h} - - This event is sent by wxLayoutAlgorithm to - calculate the amount of the remaining client area that the window should - occupy. - - @library{wxadv} - @category{events} - - @see wxQueryLayoutInfoEvent, wxSashLayoutWindow, wxLayoutAlgorithm. -*/ -class wxCalculateLayoutEvent : public wxEvent -{ -public: - /** - Constructor. - */ - wxCalculateLayoutEvent(wxWindowID id = 0); - - /** - Returns the flags associated with this event. Not currently used. - */ - int GetFlags() const; - - /** - Before the event handler is entered, returns the remaining parent client area - that the window - could occupy. When the event handler returns, this should contain the remaining - parent client rectangle, - after the event handler has subtracted the area that its window occupies. - */ - wxRect GetRect() const; - - /** - Sets the flags associated with this event. Not currently used. - */ - void SetFlags(int flags); - - /** - Call this to specify the new remaining parent client area, after the space - occupied by the - window has been subtracted. - */ - void SetRect(const wxRect& rect); -}; - diff --git a/interface/link.h b/interface/link.h deleted file mode 100644 index 8bd169380e..0000000000 --- a/interface/link.h +++ /dev/null @@ -1,40 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: link.h -// Purpose: interface of global functions -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** @ingroup group_funcmacro_byteorder */ -//@{ - -/** - This macro can be used in conjunction with the wxFORCE_LINK_MODULE() macro - to force the linker to include in its output a specific object file. - - In particular, you should use this macro in the source file which you want - to force for inclusion. The @c moduleName needs to be a name not already in - use in other wxFORCE_LINK_THIS_MODULE() macros, but is not required to be - e.g. the same name of the source file (even if it's a good choice). - - @header{wx/link.h} -*/ -#define wxFORCE_LINK_THIS_MODULE( moduleName ) - -/** - This macro can be used in conjunction with the wxFORCE_LINK_THIS_MODULE() - macro to force the linker to include in its output a specific object file. - - In particular, you should use this macro in a source file which you know - for sure is linked in the output (e.g. the source file containing the - @c main() of your app). The @c moduleName is the name of the module you - want to forcefully link (i.e. the name you used in the relative - wxFORCE_LINK_THIS_MODULE() macro. - - @header{wx/link.h} -*/ -#define wxFORCE_LINK_MODULE( moduleName ) - -//@} - diff --git a/interface/list.h b/interface/list.h deleted file mode 100644 index e49ae62ed4..0000000000 --- a/interface/list.h +++ /dev/null @@ -1,439 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: list.h -// Purpose: interface of wxList -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @wxheader{list.h} - - The wxList class provides linked list functionality. It has been rewritten - to be type safe and to provide the full API of the STL std::list container and - should be used like it. The exception is that wxList actually stores - pointers and therefore its iterators return pointers and not references - to the actual objets in the list (see example below) and @e value_type - is defined as @e T*. wxList destroys an object after removing it only - if wxList::DeleteContents has been called. - - wxList is not a real template and it requires that you declare and define - each wxListT class in your program. This is done with @e WX_DECLARE_LIST - and @e WX_DEFINE_LIST macros (see example). We hope that we'll be able - to provide a proper template class providing both the STL std::list - and the old wxList API in the future. - - Please refer to the STL std::list documentation for further - information on how to use the class. Below we documented both - the supported STL and the legacy API that originated from the - old wxList class and which can still be used alternatively for - the the same class. - - Note that if you compile wxWidgets in STL mode (wxUSE_STL defined as 1) - then wxList will actually derive from std::list and just add a legacy - compatibility layer for the old wxList class. - - @code - // this part might be in a header or source (.cpp) file - class MyListElement - { - ... // whatever - }; - - // this macro declares and partly implements MyList class - WX_DECLARE_LIST(MyListElement, MyList); - - ... - - // the only requirement for the rest is to be AFTER the full declaration of - // MyListElement (for WX_DECLARE_LIST forward declaration is enough), but - // usually it will be found in the source file and not in the header - - #include - WX_DEFINE_LIST(MyList); - - - MyList list; - MyListElement element; - list.Append(&element); // ok - list.Append(17); // error: incorrect type - - // let's iterate over the list in STL syntax - MyList::iterator iter; - for (iter = list.begin(); iter != list.end(); ++iter) - { - MyListElement *current = *iter; - - ...process the current element... - } - - // the same with the legacy API from the old wxList class - MyList::compatibility_iterator node = list.GetFirst(); - while (node) - { - MyListElement *current = node->GetData(); - - ...process the current element... - - node = node->GetNext(); - } - @endcode - - - @library{wxbase} - @category{FIXME} - - @see wxArray, wxVector -*/ -class wxList -{ -public: - /** - Default constructor. - */ - wxList(); - - /** - Constructor which initialized the list with an array of @count elements. - */ - wxList(size_t count, T* elements[]); - - /** - Destroys the list, but does not delete the objects stored in the list - unless you called DeleteContents(@true ). - */ - ~wxList(); - - /** - Appends the pointer to @a object to the list. - */ - wxList::compatibility_iterator Append(T* object); - - /** - Clears the list. - Deletes the actual objects if DeleteContents( @true ) was called previously. - */ - void Clear(); - - /** - If @a destroy is @true, instructs the list to call @e delete - on objects stored in the list whenever they are removed. - The default is @false. - */ - void DeleteContents(bool destroy); - - /** - Deletes the given element refered to by @a iter from the list - if @a iter is a valid iterator. Returns @true if successful. - - Deletes the actual object if DeleteContents( @true ) was called previously. - */ - bool DeleteNode(const compatibility_iterator& iter); - - /** - Finds the given @a object and removes it from the list, returning - @true if successful. - - Deletes @a object if DeleteContents( @true ) was called previously. - */ - bool DeleteObject(T* object); - - /** - Removes element refered to be @a iter. - - Deletes the actualy object if DeleteContents( @true ) was called previously. - */ - void Erase(const compatibility_iterator& iter); - - /** - Returns the iterator refering to @a object or @NULL if none found. - */ - wxList::compatibility_iterator Find(T* object) const; - - /** - Returns the number of elements in the list. - */ - size_t GetCount() const; - - /** - Returns the first iterator in the list (@NULL if the list is empty). - */ - wxList::compatibility_iterator GetFirst() const; - - /** - Returns the last iterator in the list (@NULL if the list is empty). - */ - wxList::compatibility_iterator GetLast() const; - - /** - Returns the index of @a obj within the list or @c wxNOT_FOUND if - @a obj is not found in the list. - */ - int IndexOf(T* obj) const; - - /** - Inserts @a object at the beginning of the list. - */ - wxList::compatibility_iterator Insert(T* object); - - /** - Inserts @a object at @a position. - */ - wxList::compatibility_iterator Insert(size_t position, - T* object); - - /** - Inserts @a object before the object refered to be @a iter. - */ - wxList::compatibility_iterator Insert(compatibility_iterator iter, - T* object); - - /** - Returns @true if the list is empty, @false otherwise. - */ - bool IsEmpty() const; - - /** - Returns the iterator refering to the object at the given - @a index in the list. - */ - wxList::compatibility_iterator Item(size_t index) const; - - /** - @note This function is deprecated, use Find() instead. - */ - wxList::compatibility_iterator Member(T* object) const; - - /** - @note This function is deprecated, use Item() instead. - */ - wxList::compatibility_iterator Nth(int n) const; - - /** - @note This function is deprecated, use wxList::GetCount instead. - Returns the number of elements in the list. - */ - int Number() const; - - /** - Allows the sorting of arbitrary lists by giving a function to compare - two list elements. We use the system @b qsort function for the actual - sorting process. - */ - void Sort(wxSortCompareFunction compfunc); - - /** - Clears the list and item from @a first to @a last from another list to it. - */ - void assign(const_iterator first, const const_iterator& last); - - /** - Clears the list and adds @a n items with value @a v to it. - */ - void assign(size_type n, const_reference v = value_type()) \ - - /** - Returns the last item of the list. - */ - reference back() const; - - /** - Returns the last item of the list as a const reference. - */ - const_reference back() const; - - /** - Returns an iterator pointing to the beginning of the list. - */ - iterator begin() const; - - /** - Returns a const iterator pointing to the beginning of the list. - */ - const_iterator begin() const; - - /** - Removes all items from the list. - */ - void clear(); - - /** - Returns @e @true if the list is empty. - */ - bool empty() const; - - /** - Returns a const iterator pointing at the end of the list. - */ - const_iterator end() const; - - /** - Returns a iterator pointing at the end of the list. - */ - iterator end() const; - - /** - Erases the given item - */ - iterator erase(const iterator& it); - - /** - Erases the items from @e first to @e last. - */ - iterator erase(const iterator& first, - const iterator& last); - - /** - Returns the first item in the list. - */ - reference front() const; - - /** - Returns the first item in the list as a const reference. - */ - const_reference front() const; - - /** - Inserts an item at the head of the list - */ - iterator insert(const iterator& it); - - /** - Inserts an item at the given position - */ - void insert(const iterator& it, size_type n); - - /** - Inserts several items at the given position. - */ - void insert(const iterator& it, const_iterator first, - const const_iterator& last); - - /** - Returns the largest possible size of the list. - */ - size_type max_size() const; - - /** - Removes the last item from the list. - */ - void pop_back(); - - /** - Removes the first item from the list. - */ - void pop_front(); - - /** - Adds an item to end of the list. - */ - void push_back(); - - /** - Adds an item to the front of the list. - */ - void push_front(); - - /** - Returns a reverse iterator pointing to the beginning of the - reversed list. - */ - reverse_iterator rbegin() const; - - /** - Returns a const reverse iterator pointing to the beginning of the - reversed list. - */ - const_reverse_iterator rbegin() const; - - /** - Removes an item from the list. - */ - void remove(const_reference v); - - /** - Returns a reverse iterator pointing to the end of the - reversed list. - */ - reverse_iterator rend() const; - - /** - Returns a const reverse iterator pointing to the end of the - reversed list. - */ - const_reverse_iterator rend() const; - - /** - Resizes the list. If the the list is enlarges items with - the value @e v are appended to the list. - */ - void resize(size_type n); - - /** - Reverses the list. - */ - void reverse(); - - /** - Returns the size of the list. - */ - size_type size() const; -}; - - - -/** - @class wxNode - @wxheader{list.h} - - wxNodeBase is the node structure used in linked lists (see - wxList) and derived classes. You should never use wxNodeBase - class directly, however, because it works with untyped (@c void *) data and - this is unsafe. Use wxNodeBase-derived classes which are automatically defined - by WX_DECLARE_LIST and WX_DEFINE_LIST macros instead as described in - wxList documentation (see example there). Also note that - although there is a class called wxNode, it is defined for backwards - compatibility only and usage of this class is strongly deprecated. - - In the documentation below, the type @c T should be thought of as a - "template" parameter: this is the type of data stored in the linked list or, - in other words, the first argument of WX_DECLARE_LIST macro. Also, wxNode is - written as wxNodeT even though it isn't really a template class -- but it - helps to think of it as if it were. - - @library{wxbase} - @category{FIXME} - - @see wxList, wxHashTable -*/ -class wxNode -{ -public: - /** - Retrieves the client data pointer associated with the node. - */ - T* GetData() const; - - /** - Retrieves the next node or @NULL if this node is the last one. - */ - wxNode* GetNext() const; - - /** - Retrieves the previous node or @NULL if this node is the first one in the list. - */ - wxNode* GetPrevious(); - - /** - Returns the zero-based index of this node within the list. The return value - will be @c wxNOT_FOUND if the node has not been added to a list yet. - */ - int IndexOf(); - - /** - Sets the data associated with the node (usually the pointer will have been - set when the node was created). - */ - void SetData(T* data); -}; - diff --git a/interface/listbook.h b/interface/listbook.h deleted file mode 100644 index 28855b7ef3..0000000000 --- a/interface/listbook.h +++ /dev/null @@ -1,61 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: listbook.h -// Purpose: interface of wxListbook -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxListbook - @wxheader{listbook.h} - - wxListbook is a class similar to wxNotebook but which - uses a wxListCtrl to show the labels instead of the - tabs. - - The underlying wxListCtrl displays page labels in a one-column report view - by default. Calling wxListbook::SetImageList will implicitly switch the - control to use an icon view. - - There is no documentation for this class yet but its usage is - identical to wxNotebook (except for the features clearly related to tabs - only), so please refer to that class documentation for now. You can also - use the @ref overview_samplenotebook "notebook sample" to see wxListbook in - action. - - @beginStyleTable - @style{wxLB_DEFAULT} - Choose the default location for the labels depending on the current - platform (left everywhere except Mac where it is top). - @style{wxLB_TOP} - Place labels above the page area. - @style{wxLB_LEFT} - Place labels on the left side. - @style{wxLB_RIGHT} - Place labels on the right side. - @style{wxLB_BOTTOM} - Place labels below the page area. - @endStyleTable - - @library{wxcore} - @category{miscwnd} - - @see wxBookCtrl(), wxNotebook, @ref overview_samplenotebook "notebook sample" -*/ -class wxListbook : public wxBookCtrl overview -{ -public: - //@{ - /** - Constructs a listbook control. - */ - wxListbook(); - wxListbook(wxWindow* parent, wxWindowID id, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = 0, - const wxString& name = wxEmptyStr); - //@} -}; - diff --git a/interface/listbox.h b/interface/listbox.h deleted file mode 100644 index 7d9ad3baaa..0000000000 --- a/interface/listbox.h +++ /dev/null @@ -1,250 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: listbox.h -// Purpose: interface of wxListBox -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxListBox - @wxheader{listbox.h} - - A listbox is used to select one or more of a list of strings. The - strings are displayed in a scrolling box, with the selected string(s) - marked in reverse video. A listbox can be single selection (if an item - is selected, the previous selection is removed) or multiple selection - (clicking an item toggles the item on or off independently of other - selections). - - List box elements are numbered from zero. Their number may be limited - under some platforms. - - A listbox callback gets an event wxEVT_COMMAND_LISTBOX_SELECTED for - single clicks, and wxEVT_COMMAND_LISTBOX_DOUBLECLICKED for double clicks. - - @beginStyleTable - @style{wxLB_SINGLE} - Single-selection list. - @style{wxLB_MULTIPLE} - Multiple-selection list: the user can toggle multiple items on and - off. This is the same as wxLB_EXTENDED in wxGTK2 port. - @style{wxLB_EXTENDED} - Extended-selection list: the user can extend the selection by using - @c SHIFT or @c CTRL keys together with the cursor movement keys or - the mouse. - @style{wxLB_HSCROLL} - Create horizontal scrollbar if contents are too wide (Windows only). - @style{wxLB_ALWAYS_SB} - Always show a vertical scrollbar. - @style{wxLB_NEEDED_SB} - Only create a vertical scrollbar if needed. - @style{wxLB_SORT} - The listbox contents are sorted in alphabetical order. - @endStyleTable - - @beginEventTable{wxCommandEvent} - @event{EVT_LISTBOX(id, func)} - Process a wxEVT_COMMAND_LISTBOX_SELECTED event, when an item on the - list is selected or the selection changes. - @event{EVT_LISTBOX_DCLICK(id, func)} - Process a wxEVT_COMMAND_LISTBOXDOUBLECLICKED event, when the - listbox is double-clicked. - @endEventTable - - @library{wxcore} - @category{ctrl} - - - @see wxChoice, wxComboBox, wxListCtrl, wxCommandEvent -*/ -class wxListBox : public wxControlWithItems -{ -public: - /** - Default constructor. - */ - wxListBox(); - - /** - Constructor - - @param n - Number of strings with which to initialise the control. - @param style - Window style. See wxListBox. - */ - - wxListBox(wxWindow* parent, wxWindowID id, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - int n = 0, - const wxString choices[] = NULL, - long style = 0, - const wxValidator& validator = wxDefaultValidator, - const wxString& name = "listBox"); - - /** - Constructor - - @param choices - An array of strings with which to initialise the control. - @param style - Window style. See wxListBox. - */ - - wxListBox(wxWindow* parent, wxWindowID id, - const wxPoint& pos, - const wxSize& size, - const wxArrayString& choices, - long style = 0, - const wxValidator& validator = wxDefaultValidator, - const wxString& name = "listBox"); - - /** - Destructor, destroying the list box. - */ - ~wxListBox(); - - //@{ - /** - Creates the listbox for two-step construction. See wxListBox() - for further details. - */ - bool Create(wxWindow* parent, wxWindowID id, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - int n, - const wxString choices[] = NULL, - long style = 0, - const wxValidator& validator = wxDefaultValidator, - const wxString& name = "listBox"); - bool Create(wxWindow* parent, wxWindowID id, - const wxPoint& pos, - const wxSize& size, - const wxArrayString& choices, - long style = 0, - const wxValidator& validator = wxDefaultValidator, - const wxString& name = "listBox"); - //@} - - /** - Deselects an item in the list box. - - @param n - The zero-based item to deselect. - - @remarks This applies to multiple selection listboxes only. - */ - void Deselect(int n); - - /** - Fill an array of ints with the positions of the currently selected items. - - @param selections - A reference to an wxArrayInt instance that is used to store the result of - the query. - - @return The number of selections. - - @remarks Use this with a multiple selection listbox. - - @see wxControlWithItems::GetSelection, wxControlWithItems::GetStringSelection, - wxControlWithItems::SetSelection - */ - int GetSelections(wxArrayInt& selections) const; - - /** - Returns the item located at @e point, or @c wxNOT_FOUND if there - is no item located at @e point. - - It is currently implemented for wxMSW, wxMac and wxGTK2 ports. - - @param point - Point of item (in client coordinates) to obtain - - @return Item located at point, or wxNOT_FOUND if unimplemented or the - item does not exist. - - @since 2.7.0 - */ - int HitTest(const wxPoint point) const; - - /** - Insert the given number of strings before the specified position. - - @param nItems - Number of items in the array items - @param items - Labels of items to be inserted - @param pos - Position before which to insert the items: if pos is 0 the - items will be inserted in the beginning of the listbox - */ - void InsertItems(int nItems, const wxString *items, - unsigned int pos); - - /** - Insert the given number of strings before the specified position. - - @param items - Labels of items to be inserted - @param pos - Position before which to insert the items: if pos is 0 the - items will be inserted in the beginning of the listbox - */ - void InsertItems(const wxArrayString& items, - unsigned int pos); - - /** - Determines whether an item is selected. - - @param n - The zero-based item index. - - @return @true if the given item is selected, @false otherwise. - */ - bool IsSelected(int n) const; - - /** - Clears the list box and adds the given strings to it. - - @param n - The number of strings to set. - @param choices - An array of strings to set. - @param clientData - Options array of client data pointers - */ - void Set(int n, const wxString* choices, void **clientData = NULL); - - /** - Clears the list box and adds the given strings to it. You may - free the array from the calling program after this method - has been called. - - @param choices - An array of strings to set. - @param clientData - Options array of client data pointers - */ - void Set(const wxArrayString& choices, - void **clientData = NULL); - - /** - Set the specified item to be the first visible item. - - @param n - The zero-based item index that should be visible. - */ - void SetFirstItem(int n); - - /** - Set the specified item to be the first visible item. - - @param string - The string that should be visible. - */ - void SetFirstItem(const wxString& string); -}; - diff --git a/interface/listctrl.h b/interface/listctrl.h deleted file mode 100644 index 812a1c2077..0000000000 --- a/interface/listctrl.h +++ /dev/null @@ -1,1441 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: listctrl.h -// Purpose: interface of wxListCtrl -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxListCtrl - @wxheader{listctrl.h} - - A list control presents lists in a number of formats: list view, report view, - icon view and small icon view. In any case, elements are numbered from zero. - For all these modes, the items are stored in the control and must be added to - it using wxListCtrl::InsertItem method. - - A special case of report view quite different from the other modes of the list - control is a virtual control in which the items data (including text, images - and attributes) is managed by the main program and is requested by the control - itself only when needed which allows to have controls with millions of items - without consuming much memory. To use virtual list control you must use - wxListCtrl::SetItemCount first and overload at least - wxListCtrl::OnGetItemText (and optionally - wxListCtrl::OnGetItemImage or wxListCtrl::OnGetItemColumnImage and - wxListCtrl::OnGetItemAttr) to return the information - about the items when the control requests it. Virtual list control can be used - as a normal one except that no operations which can take time proportional to - the number of items in the control happen -- this is required to allow having a - practically infinite number of items. For example, in a multiple selection - virtual list control, the selections won't be sent when many items are selected - at once because this could mean iterating over all the items. - - Using many of wxListCtrl features is shown in the - @ref overview_samplelistctrl "corresponding sample". - - To intercept events from a list control, use the event table macros described - in wxListEvent. - - @b Mac Note: Starting with 2.8, wxListCtrl uses a native implementation for - report mode, and uses a generic implementation for other modes. You can use the - generic implementation for report mode as well by setting the - mac.listctrl.always_use_generic wxSystemOption() to - 1. - - @beginStyleTable - @style{wxLC_LIST} - Multicolumn list view, with optional small icons. Columns are - computed automatically, i.e. you don't set columns as in - wxLC_REPORT. In other words, the list wraps, unlike a wxListBox. - @style{wxLC_REPORT} - Single or multicolumn report view, with optional header. - @style{wxLC_VIRTUAL} - The application provides items text on demand. May only be used - with wxLC_REPORT. - @style{wxLC_ICON} - Large icon view, with optional labels. - @style{wxLC_SMALL_ICON} - Small icon view, with optional labels. - @style{wxLC_ALIGN_TOP} - Icons align to the top. Win32 default, Win32 only. - @style{wxLC_ALIGN_LEFT} - Icons align to the left. - @style{wxLC_AUTOARRANGE} - Icons arrange themselves. Win32 only. - @style{wxLC_EDIT_LABELS} - Labels are editable: the application will be notified when editing - starts. - @style{wxLC_NO_HEADER} - No header in report mode. - @style{wxLC_SINGLE_SEL} - Single selection (default is multiple). - @style{wxLC_SORT_ASCENDING} - Sort in ascending order. (You must still supply a comparison callback - in wxListCtrl::SortItems.) - @style{wxLC_SORT_DESCENDING} - Sort in descending order. (You must still supply a comparison callback - in wxListCtrl::SortItems.) - @style{wxLC_HRULES} - Draws light horizontal rules between rows in report mode. - @style{wxLC_VRULES} - Draws light vertical rules between columns in report mode. - @endStyleTable - - @library{wxcore} - @category{ctrl} - - - @see @ref overview_listctrl "wxListCtrl Overview", wxListView, - wxListBox, wxTreeCtrl, wxImageList, wxListEvent, wxListItem -*/ -class wxListCtrl : public wxControl -{ -public: - //@{ - /** - Constructor, creating and showing a list control. - */ - wxListCtrl(); - - /** - Constructor, creating and showing a list control. - - @param parent - Parent window. Must not be @NULL. - @param id - Window identifier. The value wxID_ANY indicates a default value. - @param pos - Window position. - @param size - Window size. If wxDefaultSize is specified then the window is - sized appropriately. - @param style - Window style. See wxListCtrl. - @param validator - Window validator. - @param name - Window name. - - @see Create(), wxValidator - */ - wxListCtrl(wxWindow* parent, wxWindowID id, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = wxLC_ICON, - const wxValidator& validator = wxDefaultValidator, - const wxString& name = wxListCtrlNameStr); - //@} - - /** - Destructor, destroying the list control. - */ - ~wxListCtrl(); - - /** - Arranges the items in icon or small icon view. This only has effect on Win32. - @a flag is one of: - - wxLIST_ALIGN_DEFAULT - - Default alignment. - - wxLIST_ALIGN_LEFT - - Align to the left side of the control. - - wxLIST_ALIGN_TOP - - Align to the top side of the control. - - wxLIST_ALIGN_SNAP_TO_GRID - - Snap to grid. - */ - bool Arrange(int flag = wxLIST_ALIGN_DEFAULT); - - /** - Sets the image list associated with the control and - takes ownership of it (i.e. the control will, unlike when using - SetImageList, delete the list when destroyed). @a which is one of - wxIMAGE_LIST_NORMAL, wxIMAGE_LIST_SMALL, wxIMAGE_LIST_STATE (the last is - unimplemented). - - @see SetImageList() - */ - void AssignImageList(wxImageList* imageList, int which); - - /** - Deletes all items and all columns. - */ - void ClearAll(); - - /** - Creates the list control. See wxListCtrl() for further details. - */ - bool Create(wxWindow* parent, wxWindowID id, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = wxLC_ICON, - const wxValidator& validator = wxDefaultValidator, - const wxString& name = wxListCtrlNameStr); - - /** - Deletes all items in the list control. - @note This function does @e not send the - @c wxEVT_COMMAND_LIST_DELETE_ITEM event because deleting many items - from the control would be too slow then (unlike wxListCtrl::DeleteItem). - */ - bool DeleteAllItems(); - - /** - Deletes a column. - */ - bool DeleteColumn(int col); - - /** - Deletes the specified item. This function sends the - @c wxEVT_COMMAND_LIST_DELETE_ITEM event for the item being deleted. - See also: DeleteAllItems() - */ - bool DeleteItem(long item); - - /** - Starts editing the label of the given item. This function generates a - EVT_LIST_BEGIN_LABEL_EDIT event which can be vetoed so that no - text control will appear for in-place editing. - If the user changed the label (i.e. s/he does not press ESC or leave - the text control without changes, a EVT_LIST_END_LABEL_EDIT event - will be sent which can be vetoed as well. - */ - void EditLabel(long item); - - /** - Ensures this item is visible. - */ - bool EnsureVisible(long item); - - //@{ - /** - Find an item nearest this position in the specified direction, starting from - @a start or the beginning if @a start is -1. - - - @b FindItem( start, str, partial = @false ) - - - @b FindItemData( start, data ) - - - @b FindItemAtPos( start, point, direction ) - */ - long FindItem(long start, const wxString& str, - bool partial = false); - long FindItem(long start, long data); - long FindItem(long start, const wxPoint& pt, int direction); - //@} - - /** - Gets information about this column. See SetItem() for more - information. - */ - bool GetColumn(int col, wxListItem& item) const; - - /** - Returns the number of columns. - */ - int GetColumnCount() const; - - /** - Gets the column number by visual order index (report view only). - */ - int GetColumnIndexFromOrder(int order) const; - - /** - Gets the column visual order index (valid in report view only). - */ - int GetColumnOrder(int col) const; - - /** - Gets the column width (report view only). - */ - int GetColumnWidth(int col) const; - - /** - Returns the array containing the orders of all columns. On error, an empty - array is returned. - */ - wxArrayInt GetColumnsOrder() const; - - /** - Gets the number of items that can fit vertically in the - visible area of the list control (list or report view) - or the total number of items in the list control (icon - or small icon view). - */ - int GetCountPerPage() const; - - /** - Returns the edit control being currently used to edit a label. Returns @NULL - if no label is being edited. - @note It is currently only implemented for wxMSW and the generic version, - not for the native Mac OS X version. - */ - wxTextCtrl* GetEditControl() const; - - /** - Returns the specified image list. @a which may be one of: - - @b wxIMAGE_LIST_NORMAL - - The normal (large icon) image list. - - @b wxIMAGE_LIST_SMALL - - The small icon image list. - - @b wxIMAGE_LIST_STATE - - The user-defined state image list (unimplemented). - */ - wxImageList* GetImageList(int which) const; - - /** - Gets information about the item. See SetItem() for more - information. - You must call @e info.SetId() to the ID of item you're interested in - before calling this method. - */ - bool GetItem(wxListItem& info) const; - - /** - Returns the colour for this item. If the item has no specific colour, returns - an invalid colour (and not the default background control of the control - itself). - - @see GetItemTextColour() - */ - wxColour GetItemBackgroundColour(long item) const; - - /** - Returns the number of items in the list control. - */ - int GetItemCount() const; - - /** - Gets the application-defined data associated with this item. - */ - long GetItemData(long item) const; - - /** - Returns the item's font. - */ - wxFont GetItemFont(long item) const; - - /** - Returns the position of the item, in icon or small icon view. - */ - bool GetItemPosition(long item, wxPoint& pos) const; - - /** - Returns the rectangle representing the item's size and position, in physical - coordinates. - @a code is one of wxLIST_RECT_BOUNDS, wxLIST_RECT_ICON, wxLIST_RECT_LABEL. - */ - bool GetItemRect(long item, wxRect& rect, - int code = wxLIST_RECT_BOUNDS) const; - - /** - Retrieves the spacing between icons in pixels: horizontal spacing is returned - as @c x component of the wxSize object and the vertical - spacing as its @c y component. - */ - wxSize GetItemSpacing() const; - - /** - Gets the item state. For a list of state flags, see SetItem(). - The @b stateMask indicates which state flags are of interest. - */ - int GetItemState(long item, long stateMask) const; - - /** - Gets the item text for this item. - */ - wxString GetItemText(long item) const; - - /** - Returns the colour for this item. If the item has no specific colour, returns - an invalid colour (and not the default foreground control of the control itself - as this wouldn't allow distinguishing between items having the same colour as - the current control foreground and items with default colour which, hence, have - always the same colour as the control). - */ - wxColour GetItemTextColour(long item) const; - - /** - Searches for an item with the given geometry or state, starting from - @a item but excluding the @a item itself. If @a item is -1, - the first item that matches the specified flags will be returned. - Returns the first item with given state following @a item or -1 if - no such item found. - This function may be used to find all selected items in the control like this: - - @a geometry can be one of: - - wxLIST_NEXT_ABOVE - - Searches for an item above the specified item. - - wxLIST_NEXT_ALL - - Searches for subsequent item by index. - - wxLIST_NEXT_BELOW - - Searches for an item below the specified item. - - wxLIST_NEXT_LEFT - - Searches for an item to the left of the specified item. - - wxLIST_NEXT_RIGHT - - Searches for an item to the right of the specified item. - - @note this parameter is only supported by wxMSW currently and ignored on - other platforms. - @a state can be a bitlist of the following: - - wxLIST_STATE_DONTCARE - - Don't care what the state is. - - wxLIST_STATE_DROPHILITED - - The item indicates it is a drop target. - - wxLIST_STATE_FOCUSED - - The item has the focus. - - wxLIST_STATE_SELECTED - - The item is selected. - - wxLIST_STATE_CUT - - The item is selected as part of a cut and paste operation. - */ - long GetNextItem(long item, int geometry = wxLIST_NEXT_ALL, - int state = wxLIST_STATE_DONTCARE) const; - - /** - Returns the number of selected items in the list control. - */ - int GetSelectedItemCount() const; - - /** - Returns the rectangle representing the size and position, in physical - coordinates, of the given subitem, i.e. the part of the row @a item in the - column @e subItem. - This method is only meaningfull when the wxListCtrl is in the report mode. If - @a subItem parameter is equal to the special value - @c wxLIST_GETSUBITEMRECT_WHOLEITEM the return value is the same as - for GetItemRect(). - @a code can be one of @c wxLIST_RECT_BOUNDS, - @c wxLIST_RECT_ICON or @c wxLIST_RECT_LABEL. - - @since 2.7.0 - */ - bool GetSubItemRect(long item, long subItem, wxRect& rect, - int code = wxLIST_RECT_BOUNDS) const; - - /** - Gets the text colour of the list control. - */ - wxColour GetTextColour() const; - - /** - Gets the index of the topmost visible item when in - list or report view. - */ - long GetTopItem() const; - - /** - Returns the rectangle taken by all items in the control. In other words, if the - controls client size were equal to the size of this rectangle, no scrollbars - would be needed and no free space would be left. - Note that this function only works in the icon and small icon views, not in - list or report views (this is a limitation of the native Win32 control). - */ - wxRect GetViewRect() const; - - /** - Determines which item (if any) is at the specified point, - giving details in @e flags. Returns index of the item or @c wxNOT_FOUND - if no item is at the specified point. - @a flags will be a combination of the following flags: - - wxLIST_HITTEST_ABOVE - - Above the client area. - - wxLIST_HITTEST_BELOW - - Below the client area. - - wxLIST_HITTEST_NOWHERE - - In the client area but below the last item. - - wxLIST_HITTEST_ONITEMICON - - On the bitmap associated with an item. - - wxLIST_HITTEST_ONITEMLABEL - - On the label (string) associated with an item. - - wxLIST_HITTEST_ONITEMRIGHT - - In the area to the right of an item. - - wxLIST_HITTEST_ONITEMSTATEICON - - On the state icon for a tree view item that is in a user-defined state. - - wxLIST_HITTEST_TOLEFT - - To the right of the client area. - - wxLIST_HITTEST_TORIGHT - - To the left of the client area. - - wxLIST_HITTEST_ONITEM - - Combination of wxLIST_HITTEST_ONITEMICON, wxLIST_HITTEST_ONITEMLABEL, - wxLIST_HITTEST_ONITEMSTATEICON. - - If @a ptrSubItem is not @NULL and the wxListCtrl is in the report - mode the subitem (or column) number will also be provided. - This feature is only available in version 2.7.0 or higher and is currently only - implemented under wxMSW and requires at least comctl32.dll of verion 4.70 on - the host system or the value stored in @a ptrSubItem will be always -1. To - compile this feature into wxWidgets library you need to have access to - commctrl.h of version 4.70 that is provided by Microsoft. - */ - long HitTest(const wxPoint& point, int& flags, - long* ptrSubItem) const; - - //@{ - /** - For report view mode (only), inserts a column. For more details, see SetItem(). - */ - long InsertColumn(long col, wxListItem& info); - long InsertColumn(long col, const wxString& heading, - int format = wxLIST_FORMAT_LEFT, - int width = -1); - //@} - - //@{ - /** - Insert a wxListItem. - @param info - wxListItem object - */ - long InsertItem(wxListItem& info); - - /** - Insert an string item. - @param index - Index of the new item, supplied by the application - @param label - String label - */ - long InsertItem(long index, const wxString& label); - - /** - Insert an image item. - @param index - Index of the new item, supplied by the application - @param imageIndex - Index into the image list associated with this control and view style - */ - long InsertItem(long index, int imageIndex); - - /** - Insert an image/string item. - @param index - Index of the new item, supplied by the application - @param label - String label - @param imageIndex - Index into the image list associated with this control and view style - */ - long InsertItem(long index, const wxString& label, - int imageIndex); - //@} - - /** - This function may be overloaded in the derived class for a control with - @c wxLC_VIRTUAL style. It should return the attribute for the - for the specified @c item or @NULL to use the default appearance - parameters. - wxListCtrl will not delete the pointer or keep a reference of it. You can - return the same wxListItemAttr pointer for every OnGetItemAttr call. - The base class version always returns @NULL. - - @see OnGetItemImage(), OnGetItemColumnImage(), - OnGetItemText() - */ - virtual wxListItemAttr* OnGetItemAttr(long item) const; - - /** - Overload this function in the derived class for a control with - @c wxLC_VIRTUAL and @c wxLC_REPORT styles in order to specify the image - index for the given line and column. - The base class version always calls OnGetItemImage for the first column, else - it returns -1. - - @see OnGetItemText(), OnGetItemImage(), - OnGetItemAttr() - */ - virtual int OnGetItemColumnImage(long item, long column) const; - - /** - This function must be overloaded in the derived class for a control with - @c wxLC_VIRTUAL style having an @ref SetImageList() "image list" - (if the control doesn't have an image list, it is not necessary to overload - it). It should return the index of the items image in the controls image list - or -1 for no image. - In a control with @c wxLC_REPORT style, OnGetItemImage only gets called for - the first column of each line. - The base class version always returns -1. - - @see OnGetItemText(), OnGetItemColumnImage(), - OnGetItemAttr() - */ - virtual int OnGetItemImage(long item) const; - - /** - This function @b must be overloaded in the derived class for a control with - @c wxLC_VIRTUAL style. It should return the string containing the text of - the given @a column for the specified @c item. - - @see SetItemCount(), OnGetItemImage(), - OnGetItemColumnImage(), OnGetItemAttr() - */ - virtual wxString OnGetItemText(long item, long column) const; - - /** - Redraws the given @e item. This is only useful for the virtual list controls - as without calling this function the displayed value of the item doesn't change - even when the underlying data does change. - - @see RefreshItems() - */ - void RefreshItem(long item); - - /** - Redraws the items between @a itemFrom and @e itemTo. The starting item - must be less than or equal to the ending one. - Just as RefreshItem() this is only useful for - virtual list controls. - */ - void RefreshItems(long itemFrom, long itemTo); - - /** - Scrolls the list control. If in icon, small icon or report view mode, - @a dx specifies the number of pixels to scroll. If in list view mode, - @a dx specifies the number of columns to scroll. @a dy always specifies - the number of pixels to scroll vertically. - @note This method is currently only implemented in the Windows version. - */ - bool ScrollList(int dx, int dy); - - /** - Sets the background colour (GetBackgroundColour already implicit in - wxWindow class). - */ - void SetBackgroundColour(const wxColour& col); - - /** - Sets information about this column. See SetItem() for more - information. - */ - bool SetColumn(int col, wxListItem& item); - - /** - Sets the column width. - @a width can be a width in pixels or wxLIST_AUTOSIZE (-1) or - wxLIST_AUTOSIZE_USEHEADER (-2). - wxLIST_AUTOSIZE will resize the column to the length of its longest item. - wxLIST_AUTOSIZE_USEHEADER - will resize the column to the length of the header (Win32) or 80 pixels (other - platforms). - In small or normal icon view, @a col must be -1, and the column width is set - for all columns. - */ - bool SetColumnWidth(int col, int width); - - /** - Sets the order of all columns at once. The @a orders array must have the - same number elements as the number of columns and contain each position exactly - once. - This function is valid in report view only. - */ - bool SetColumnOrder(const wxArrayInt& orders) const; - - /** - Sets the image list associated with the control. @a which is one of - wxIMAGE_LIST_NORMAL, wxIMAGE_LIST_SMALL, wxIMAGE_LIST_STATE (the last is - unimplemented). - This method does not take ownership of the image list, you have to - delete it yourself. - - @see AssignImageList() - */ - void SetImageList(wxImageList* imageList, int which); - - //@{ - /** - Sets a string field at a particular column. - */ - bool SetItem(wxListItem& info); - long SetItem(long index, int col, const wxString& label, - int imageId = -1); - m_mask m_state field is valid. - - - - - - wxLIST_MASK_TEXT - - - - - The m_text field is valid. - - - - - - wxLIST_MASK_IMAGE - - - - - The m_image field is valid. - - - - - - wxLIST_MASK_DATA - - - - - The m_data field is valid. - - - - - - wxLIST_MASK_WIDTH - - - - - The m_width field is valid. - - - - - - wxLIST_MASK_FORMAT - - - - - The m_format field is valid. - - - - - -The m_stateMask and m_state members take flags from the following: - - - - - - - - wxLIST_STATE_DONTCARE - - - - - Don't care what the state is. Win32 only. - - - - - - wxLIST_STATE_DROPHILITED - - - - - The item is highlighted to receive a drop event. Win32 only. - - - - - - wxLIST_STATE_FOCUSED - - - - - The item has the focus. - - - - - - wxLIST_STATE_SELECTED - - - - - The item is selected. - - - - - - wxLIST_STATE_CUT - - - - - The item is in the cut state. Win32 only. - - - - - - The wxListItem object can also contain item-specific colour and font - information: for this you need to call one of SetTextColour(), - SetBackgroundColour() or SetFont() functions on it passing it the colour/font - to use. If the colour/font is not specified, the default list control - colour/font is used. - long SetItem(long index, int col, const wxString& label, - int imageId = -1); - //@} - - /** - Sets the background colour for this item. This function only works in report - view. - The colour can be retrieved using - GetItemBackgroundColour(). - */ - void SetItemBackgroundColour(long item, const wxColour& col); - - /** - Sets the image associated with the item. In report view, you can specify the - column. - The image is an index into the image list associated with the list control. - */ - bool SetItemColumnImage(long item, long column, int image); - - /** - This method can only be used with virtual list controls. - - It is used to indicate to the control the number of items it contains. - After calling it, the main program should be ready to handle calls to - various item callbacks (such as wxListCtrl::OnGetItemText) for all - items in the range from 0 to @a count. - - Notice that the control is not necessarily redrawn after this call as - it may be undesirable if an item which is not visible on the screen - anyhow was added to or removed from a control displaying many items, if - you do need to refresh the display you can just call Refresh() manually. - */ - void SetItemCount(long count); - - /** - Associates application-defined data with this item. - Notice that this function cannot be used to associate pointers with the control - items, use SetItemPtrData() instead. - */ - bool SetItemData(long item, long data); - - /** - Sets the item's font. - */ - void SetItemFont(long item, const wxFont& font); - - //@{ - /** - Sets the unselected and selected images associated with the item. The images - are indices into the - image list associated with the list control. This form is deprecated: @a - selImage is not - used. - */ - bool SetItemImage(long item, int image); - bool SetItemImage(long item, int image, int selImage); - //@} - - /** - Sets the position of the item, in icon or small icon view. Windows only. - */ - bool SetItemPosition(long item, const wxPoint& pos); - - /** - Associates application-defined data with this item. The @a data parameter may - be either an integer or a pointer cast to the @c wxUIntPtr type which is - guaranteed to be large enough to be able to contain all integer types and - pointers. - - @since 2.8.4 - */ - bool SetItemPtrData(long item, wxUIntPtr data); - - /** - Sets the item state. For a list of state flags, see SetItem(). - The @b stateMask indicates which state flags are valid. - */ - bool SetItemState(long item, long state, long stateMask); - - /** - Sets the item text for this item. - */ - void SetItemText(long item, const wxString& text); - - /** - Sets the colour for this item. This function only works in report view. - The colour can be retrieved using - GetItemTextColour(). - */ - void SetItemTextColour(long item, const wxColour& col); - - /** - Adds or removes a single window style. - */ - void SetSingleStyle(long style, bool add = true); - - /** - Sets the text colour of the list control. - */ - void SetTextColour(const wxColour& col); - - /** - Sets the whole window style, deleting all items. - */ - void SetWindowStyleFlag(long style); - - /** - Call this function to sort the items in the list control. Sorting is done - using the specified @a fnSortCallBack function. This function must have the - following prototype: - - It is called each time when the two items must be compared and should return 0 - if the items are equal, negative value if the first item is less than the - second one and positive value if the first one is greater than the second one - (the same convention as used by @c qsort(3)). - - @param item1 - client data associated with the first item (NOT the index). - @param item2 - client data associated with the second item (NOT the index). - @param data - the value passed to SortItems() itself. - */ - bool SortItems(wxListCtrlCompare fnSortCallBack, long data); -}; - - - -/** - @class wxListEvent - @wxheader{listctrl.h} - - A list event holds information about events associated with wxListCtrl objects. - - @library{wxbase} - @category{events} - - @see wxListCtrl -*/ -class wxListEvent : public wxNotifyEvent -{ -public: - /** - Constructor. - */ - wxListEvent(wxEventType commandType = 0, int id = 0); - - /** - For @c EVT_LIST_CACHE_HINT event only: return the first item which the - list control advises us to cache. - */ - long GetCacheFrom() const; - - /** - For @c EVT_LIST_CACHE_HINT event only: return the last item (inclusive) - which the list control advises us to cache. - */ - long GetCacheTo() const; - - /** - The column position: it is only used with @c COL events. For the column - dragging events, it is the column to the left of the divider being dragged, for - the column click events it may be -1 if the user clicked in the list control - header outside any column. - */ - int GetColumn() const; - - /** - The data. - */ - long GetData() const; - - /** - The image. - */ - int GetImage() const; - - /** - The item index. - */ - long GetIndex() const; - - /** - An item object, used by some events. See also wxListCtrl::SetItem. - */ - const wxListItem GetItem() const; - - /** - Key code if the event is a keypress event. - */ - int GetKeyCode() const; - - /** - The (new) item label for @c EVT_LIST_END_LABEL_EDIT event. - */ - const wxString GetLabel() const; - - /** - The mask. - */ - long GetMask() const; - - /** - The position of the mouse pointer if the event is a drag event. - */ - wxPoint GetPoint() const; - - /** - The text. - */ - const wxString GetText() const; - - /** - This method only makes sense for @c EVT_LIST_END_LABEL_EDIT message - and returns @true if it the label editing has been cancelled by the user - (GetLabel() returns an empty string in this case - but it doesn't allow the application to distinguish between really cancelling - the edit and - the admittedly rare case when the user wants to rename it to an empty string). - */ - bool IsEditCancelled() const; -}; - - - -/** - @class wxListItemAttr - @wxheader{listctrl.h} - - Represents the attributes (color, font, ...) of a - wxListCtrl wxListItem. - - @library{wxbase} - @category{FIXME} - - @see @ref overview_listctrl "wxListCtrl Overview", wxListCtrl, - wxListItem -*/ -class wxListItemAttr -{ -public: - //@{ - /** - Construct a wxListItemAttr with the specified foreground and - background colors and font. - */ - wxListItemAttr(); - wxListItemAttr(const wxColour colText, - const wxColour colBack, - const wxFont font); - //@} - - /** - Returns the currently set background color. - */ - const wxColour GetBackgroundColour() const; - - /** - Returns the currently set font. - */ - const wxFont GetFont() const; - - /** - Returns the currently set text color. - */ - const wxColour GetTextColour() const; - - /** - Returns @true if the currently set background color is valid. - */ - bool HasBackgroundColour() const; - - /** - Returns @true if the currently set font is valid. - */ - bool HasFont() const; - - /** - Returns @true if the currently set text color is valid. - */ - bool HasTextColour() const; - - /** - Sets a new background color. - */ - void SetBackgroundColour(const wxColour& colour); - - /** - Sets a new font. - */ - void SetFont(const wxFont& font); - - /** - Sets a new text color. - */ - void SetTextColour(const wxColour& colour); -}; - - - -/** - @class wxListView - @wxheader{listctrl.h} - - This class currently simply presents a simpler to use interface for the - wxListCtrl -- it can be thought of as a @e faade - for that complicated class. Using it is preferable to using - wxListCtrl directly whenever possible because in the - future some ports might implement wxListView but not the full set of wxListCtrl - features. - - Other than different interface, this class is identical to wxListCtrl. In - particular, it uses the same events, same window styles and so on. - - @library{wxcore} - @category{ctrl} - - - @see wxListView::SetColumnImage -*/ -class wxListView : public wxListCtrl -{ -public: - /** - Resets the column image -- after calling this function, no image will be shown. - - @param col - the column to clear image for - - @see SetColumnImage() - */ - void ClearColumnImage(int col); - - /** - Sets focus to the item with the given @e index. - */ - void Focus(long index); - - /** - Returns the first selected item in a (presumably) multiple selection control. - Together with GetNextSelected() it can be - used to iterate over all selected items in the control. - - @return The first selected item, if any, -1 otherwise. - */ - long GetFirstSelected() const; - - /** - Returns the currently focused item or -1 if none. - - @see IsSelected(), Focus() - */ - long GetFocusedItem() const; - - /** - Used together with GetFirstSelected() to - iterate over all selected items in the control. - - @return Returns the next selected item or -1 if there are no more of - them. - */ - long GetNextSelected(long item) const; - - /** - Returns @true if the item with the given @a index is selected, - @false otherwise. - - @see GetFirstSelected(), GetNextSelected() - */ - bool IsSelected(long index) const; - - /** - Selects or unselects the given item. - - @param n - the item to select or unselect - @param on - if @true (default), selects the item, otherwise unselects it - - @see wxListCtrl::SetItemState - */ - void Select(bool on = true); - - /** - Sets the column image for the specified column. To use the column images, the - control must have a valid image list with at least one image. - - @param col - the column to set image for - @param image - the index of the column image in the controls image list - */ - void SetColumnImage(int col, int image); -}; - - - -/** - @class wxListItem - @wxheader{listctrl.h} - - This class stores information about a wxListCtrl item or column. - - @library{wxbase} - @category{FIXME} -*/ -class wxListItem : public wxObject -{ -public: - /** - Constructor. - */ - wxListItem(); - - /** - Resets the item state to the default. - */ - void Clear(); - - /** - Returns the alignment for this item. Can be one of - wxLIST_FORMAT_LEFT, wxLIST_FORMAT_RIGHT or wxLIST_FORMAT_CENTRE. - */ - wxListColumnFormat GetAlign() const; - - /** - Returns the background colour for this item. - */ - wxColour GetBackgroundColour() const; - - /** - Returns the zero-based column; meaningful only in report mode. - */ - int GetColumn() const; - - /** - Returns client data associated with the control. Please note that - client data is associated with the item and not with subitems. - */ - long GetData() const; - - /** - Returns the font used to display the item. - */ - wxFont GetFont() const; - - /** - Returns the zero-based item position. - */ - long GetId() const; - - /** - Returns the zero-based index of the image - associated with the item into the image list. - */ - int GetImage() const; - - /** - Returns a bit mask indicating which fields of the structure are valid; - can be any combination of the following values: - - wxLIST_MASK_STATE - - @b GetState is valid. - - wxLIST_MASK_TEXT - - @b GetText is valid. - - wxLIST_MASK_IMAGE - - @b GetImage is valid. - - wxLIST_MASK_DATA - - @b GetData is valid. - - wxLIST_MASK_WIDTH - - @b GetWidth is valid. - - wxLIST_MASK_FORMAT - - @b GetFormat is valid. - */ - long GetMask() const; - - /** - Returns a bit field representing the state of the item. Can be any - combination of: - - wxLIST_STATE_DONTCARE - - Don't care what the state is. Win32 only. - - wxLIST_STATE_DROPHILITED - - The item is highlighted to receive a drop event. Win32 only. - - wxLIST_STATE_FOCUSED - - The item has the focus. - - wxLIST_STATE_SELECTED - - The item is selected. - - wxLIST_STATE_CUT - - The item is in the cut state. Win32 only. - */ - long GetState() const; - - /** - Returns the label/header text. - */ - const wxString GetText() const; - - /** - Returns the text colour. - */ - wxColour GetTextColour() const; - - /** - Meaningful only for column headers in report mode. Returns the column width. - */ - int GetWidth() const; - - /** - Sets the alignment for the item. See also - GetAlign() - */ - void SetAlign(wxListColumnFormat align); - - /** - Sets the background colour for the item. - */ - void SetBackgroundColour(const wxColour& colBack); - - /** - Sets the zero-based column. Meaningful only in report mode. - */ - void SetColumn(int col); - - //@{ - /** - Sets client data for the item. Please note that - client data is associated with the item and not with subitems. - */ - void SetData(long data); - void SetData(void* data); - //@} - - /** - Sets the font for the item. - */ - void SetFont(const wxFont& font); - - /** - Sets the zero-based item position. - */ - void SetId(long id); - - /** - Sets the zero-based index of the image associated with the item - into the image list. - */ - void SetImage(int image); - - /** - Sets the mask of valid fields. See GetMask(). - */ - void SetMask(long mask); - - /** - Sets the item state flags (note that the valid state flags are influenced - by the value of the state mask, see - wxListItem::SetStateMask). - See GetState() for valid flag - values. - */ - void SetState(long state); - - /** - Sets the bitmask that is used to determine which of the state flags - are to be set. See also SetState(). - */ - void SetStateMask(long stateMask); - - /** - Sets the text label for the item. - */ - void SetText(const wxString& text); - - /** - Sets the text colour for the item. - */ - void SetTextColour(const wxColour& colText); - - /** - Meaningful only for column headers in report mode. Sets the column width. - */ - void SetWidth(int width); -}; - diff --git a/interface/log.h b/interface/log.h deleted file mode 100644 index bb96ae2926..0000000000 --- a/interface/log.h +++ /dev/null @@ -1,1023 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: log.h -// Purpose: interface of wxLogWindow -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxLogWindow - @wxheader{log.h} - - This class represents a background log window: to be precise, it collects all - log messages in the log frame which it manages but also passes them on to the - log target which was active at the moment of its creation. This allows you, for - example, to show all the log messages in a frame but still continue to process - them normally by showing the standard log dialog. - - @library{wxbase} - @category{logging} - - @see wxLogTextCtrl -*/ -class wxLogWindow : public wxLogInterposer -{ -public: - /** - Creates the log frame window and starts collecting the messages in it. - - @param parent - The parent window for the log frame, may be @NULL - @param title - The title for the log frame - @param show - @true to show the frame initially (default), otherwise - Show() must be called later. - @param passToOld - @true to process the log messages normally in addition to - logging them in the log frame (default), @false to only log them in the - log frame. - */ - wxLogWindow(wxFrame parent, const wxChar title, bool show = true, - bool passToOld = true); - - /** - Returns the associated log frame window. This may be used to position or resize - it but use Show() to show or hide it. - */ - wxFrame* GetFrame() const; - - /** - Called if the user closes the window interactively, will not be - called if it is destroyed for another reason (such as when program - exits). - Return @true from here to allow the frame to close, @false to - prevent this from happening. - - @see OnFrameDelete() - */ - virtual bool OnFrameClose(wxFrame frame); - - /** - Called immediately after the log frame creation allowing for - any extra initializations. - */ - virtual void OnFrameCreate(wxFrame frame); - - /** - Called right before the log frame is going to be deleted: will - always be called unlike OnFrameClose(). - */ - virtual void OnFrameDelete(wxFrame frame); - - /** - Shows or hides the frame. - */ - void Show(bool show = true); -}; - - - -/** - @class wxLogInterposerTemp - @wxheader{log.h} - - A special version of wxLogChain which uses itself as the - new log target. It forwards log messages to the previously installed one in - addition to - processing them itself. Unlike wxLogInterposer, it doesn't - delete the old target which means it can be used to temporarily redirect log - output. - - As per wxLogInterposer, this class must be derived from to implement - wxLog::DoLog - and/or wxLog::DoLogString methods. - - @library{wxbase} - @category{logging} -*/ -class wxLogInterposerTemp : public wxLogChain -{ -public: - /** - The default constructor installs this object as the current active log target. - */ -}; - - - -/** - @class wxLogChain - @wxheader{log.h} - - This simple class allows you to chain log sinks, that is to install a new sink but - keep passing log messages to the old one instead of replacing it completely as - wxLog::SetActiveTarget does. - - It is especially useful when you want to divert the logs somewhere (for - example to a file or a log window) but also keep showing the error messages - using the standard dialogs as wxLogGui does by default. - - Example of usage: - - @code - wxLogChain *logChain = new wxLogChain(new wxLogStderr); - - // all the log messages are sent to stderr and also processed as usually - ... - - // don't delete logChain directly as this would leave a dangling - // pointer as active log target, use SetActiveTarget() instead - delete wxLog::SetActiveTarget(...something else or @NULL...); - @endcode - - @library{wxbase} - @category{logging} -*/ -class wxLogChain : public wxLog -{ -public: - /** - Sets the specified @c logger (which may be @NULL) as the default log - target but the log messages are also passed to the previous log target if any. - */ - wxLogChain(wxLog* logger); - - /** - Destroys the previous log target. - */ - ~wxLogChain(); - - /** - Detaches the old log target so it won't be destroyed when the wxLogChain object - is destroyed. - */ - void DetachOldLog(); - - /** - Returns the pointer to the previously active log target (which may be @NULL). - */ - wxLog* GetOldLog() const; - - /** - Returns @true if the messages are passed to the previously active log - target (default) or @false if PassMessages() - had been called. - */ - bool IsPassingMessages() const; - - /** - By default, the log messages are passed to the previously active log target. - Calling this function with @false parameter disables this behaviour - (presumably temporarily, as you shouldn't use wxLogChain at all otherwise) and - it can be reenabled by calling it again with @a passMessages set to @true. - */ - void PassMessages(bool passMessages); - - /** - Sets another log target to use (may be @NULL). The log target specified - in the wxLogChain(wxLog*) constructor or in a previous call to - this function is deleted. - This doesn't change the old log target value (the one the messages are - forwarded to) which still remains the same as was active when wxLogChain - object was created. - */ - void SetLog(wxLog* logger); -}; - - - -/** - @class wxLogGui - @wxheader{log.h} - - This is the default log target for the GUI wxWidgets applications. It is passed - to wxLog::SetActiveTarget at the program - startup and is deleted by wxWidgets during the program shut down. - - @library{wxbase} - @category{logging} -*/ -class wxLogGui : public wxLog -{ -public: - /** - Default constructor. - */ - wxLogGui(); -}; - - - -/** - @class wxLogStream - @wxheader{log.h} - - This class can be used to redirect the log messages to a C++ stream. - - Please note that this class is only available if wxWidgets was compiled with - the standard iostream library support (@c wxUSE_STD_IOSTREAM must be on). - - @library{wxbase} - @category{logging} - - @see wxLogStderr, wxStreamToTextRedirector -*/ -class wxLogStream : public wxLog -{ -public: - /** - Constructs a log target which sends all the log messages to the given - output stream. If it is @NULL, the messages are sent to @c cerr. - */ - wxLogStream(std::ostream ostr = NULL); -}; - - - -/** - @class wxLogStderr - @wxheader{log.h} - - This class can be used to redirect the log messages to a C file stream (not to - be confused with C++ streams). It is the default log target for the non-GUI - wxWidgets applications which send all the output to @c stderr. - - @library{wxbase} - @category{logging} - - @see wxLogStream -*/ -class wxLogStderr : public wxLog -{ -public: - /** - Constructs a log target which sends all the log messages to the given - @c FILE. If it is @NULL, the messages are sent to @c stderr. - */ - wxLogStderr(FILE fp = NULL); -}; - - - -/** - @class wxLogBuffer - @wxheader{log.h} - - wxLogBuffer is a very simple implementation of log sink which simply collects - all the logged messages in a string (except the debug messages which are output - in the usual way immediately as we're presumably not interested in collecting - them for later). The messages from different log function calls are separated - by the new lines. - - All the messages collected so far can be shown to the user (and the current - buffer cleared) by calling the overloaded wxLogBuffer::Flush - method. - - @library{wxbase} - @category{logging} -*/ -class wxLogBuffer : public wxLog -{ -public: - /** - Shows all the messages collected so far to the user (using a message box in the - GUI applications or by printing them out to the console in text mode) and - clears the internal buffer. - */ - virtual void Flush(); - - /** - Returns the current buffer contains. Messages from different log function calls - are separated with the new lines in the buffer. - The buffer can be cleared by Flush() which will - also show the current contents to the user. - */ - const wxString GetBuffer(); -}; - - - -/** - @class wxLogInterposer - @wxheader{log.h} - - A special version of wxLogChain which uses itself as the - new log target. It forwards log messages to the previously installed one in - addition to - processing them itself. - - Unlike wxLogChain which is usually used directly as is, - this class must be derived from to implement wxLog::DoLog - and/or wxLog::DoLogString methods. - - wxLogInterposer destroys the previous log target in its destructor. If you - don't want this to happen, use wxLogInterposerTemp instead. - - @library{wxbase} - @category{logging} -*/ -class wxLogInterposer : public wxLogChain -{ -public: - /** - The default constructor installs this object as the current active log target. - */ -}; - - - -/** - @class wxLogTextCtrl - @wxheader{log.h} - - Using these target all the log messages can be redirected to a text control. - The text control must have been created with @c wxTE_MULTILINE style by the - caller previously. - - @library{wxbase} - @category{logging} - - @see wxTextCtrl, wxStreamToTextRedirector -*/ -class wxLogTextCtrl : public wxLog -{ -public: - /** - Constructs a log target which sends all the log messages to the given text - control. The @a textctrl parameter cannot be @NULL. - */ - wxLogTextCtrl(wxTextCtrl textctrl); -}; - - - -/** - @class wxLog - @wxheader{log.h} - - wxLog class defines the interface for the @e log targets used by wxWidgets - logging functions as explained in the @ref overview_log. - The only situations when you need to directly use this class is when you want - to derive your own log target because the existing ones don't satisfy your - needs. Another case is if you wish to customize the behaviour of the standard - logging classes (all of which respect the wxLog settings): for example, set - which trace messages are logged and which are not or change (or even remove - completely) the timestamp on the messages. - - Otherwise, it is completely hidden behind the @e wxLogXXX() functions and - you may not even know about its existence. - - @section overview_wxLog_deriving Deriving your own log target - - There are two functions which must be implemented by any derived class to - actually process the log messages: DoLog() and - DoLogString(). The second function receives a string - which just has to be output in some way and the easiest way to write a new log - target is to override just this function in the derived class. If more control - over the output format is needed, then the first function must be overridden - which allows to construct custom messages depending on the log level or even - do completely different things depending on the message severity (for example, - throw away all messages except warnings and errors, show warnings on the - screen and forward the error messages to the user's (or programmer's) cell - phone - maybe depending on whether the timestamp tells us if it is day or - night in the current time zone). - There also functions to support message buffering. Why are they needed? - Some of wxLog implementations, most notably the standard wxLogGui class, - buffer the messages (for example, to avoid showing the user a zillion of modal - message boxes one after another -- which would be really annoying). - Flush() shows them all and clears the buffer contents. - This function doesn't do anything if the buffer is already empty. - See also: - @li Flush() - @li FlushActive() - - @section overview_wxLog_Trace_Masks Using trace masks - - The functions below allow some limited customization of wxLog behaviour - without writing a new log target class (which, aside from being a matter of - several minutes, allows you to do anything you want). - The verbose messages are the trace messages which are not disabled in the - release mode and are generated by wxLogVerbose(). They - are not normally shown to the user because they present little interest, but - may be activated, for example, in order to help the user find some program - problem. - As for the (real) trace messages, their handling depends on the settings of - the (application global) @e trace mask which can either be specified using - SetTraceMask(), GetTraceMask() and wxLogTrace() which takes an integer mask - or using AddTraceMask() for string trace masks. - The difference between bit-wise and string trace masks is that a message using - integer trace mask will only be logged if all bits of the mask are set in the - current mask while a message using string mask will be logged simply if the - mask had been added before to the list of allowed ones. - For example, - - @code - wxLogTrace( wxTraceRefCount|wxTraceOleCalls, "Active object ref count: %d", nRef ); - @endcode - - will do something only if the current trace mask contains both - @c wxTraceRefCount and @c wxTraceOle, but - - @code - wxLogTrace( wxTRACE_OleCalls, "IFoo::Bar() called" ); - @endcode - - will log the message if it was preceded by - - @code - wxLog::AddTraceMask( wxTRACE_OleCalls); - @endcode - - Using string masks is simpler and allows you to easily add custom ones, so this is - the preferred way of working with trace messages. The integer trace mask is - kept for compatibility and for additional (but very rarely needed) flexibility - only. - The standard trace masks are given in wxLogTrace() documentation. - Finally, the @e wxLog::DoLog() function automatically prepends a time stamp - to all the messages. The format of the time stamp may be changed: it can be - any string with % specifications fully described in the documentation of the - standard @e strftime() function. For example, the default format is - "[%d/%b/%y %H:%M:%S] " which gives something like "[17/Sep/98 22:10:16] " - (without quotes) for the current date. Setting an empty string as the time - format disables timestamping of the messages completely. - See also - @li AddTraceMask() - @li RemoveTraceMask() - @li ClearTraceMasks() - @li GetTraceMasks() - @li IsAllowedTraceMask() - @li SetVerbose() - @li GetVerbose() - @li SetTimestamp() - @li GetTimestamp() - @li SetTraceMask() - @li GetTraceMask() - @li SetRepetitionCounting() - @li GetRepetitionCounting() - - @note Timestamping is disabled for Visual C++ users in debug builds by - default because otherwise it would be impossible to directly go to the line - from which the log message was generated by simply clicking in the debugger - window on the corresponding error message. If you wish to enable it, please - use SetTimestamp() explicitly. - - @section overview_wxLog_Target Manipulating the log target - - The functions in this section work with and manipulate the active log - target. The OnLog() is called by the @e wxLogXXX() functions - and invokes the DoLog() of the active log target if any. - Get/Set methods are used to install/query the current active target and, - finally, DontCreateOnDemand() disables the automatic creation of a standard - log target if none actually exists. It is only useful when the application - is terminating and shouldn't be used in other situations because it may - easily lead to a loss of messages. See also - @li OnLog() - @li GetActiveTarget() - @li SetActiveTarget() - @li DontCreateOnDemand() - @li Suspend() - @li Resume() - - @library{wxcore} - @category{logging} - - @see @ref overview_log -*/ -class wxLog -{ -public: - /** - Add the @a mask to the list of allowed masks for - wxLogTrace(). - - @see RemoveTraceMask(), GetTraceMasks() - */ - static void AddTraceMask(const wxString& mask); - - /** - Removes all trace masks previously set with - AddTraceMask(). - - @see RemoveTraceMask() - */ - static void ClearTraceMasks(); - - */ - - - /** - Disables time stamping of the log messages. - This function is new since wxWidgets version 2.9 - */ - void SetTimestamp(const wxString& format); - - /** - Called to process the message of the specified severity. @a msg is the text - of the message as specified in the call of @e wxLogXXX() function which - generated it and @a timestamp is the moment when the message was generated. - The base class version prepends the timestamp to the message, adds a prefix - corresponding to the log level and then calls - DoLogString() with the resulting string. - */ - virtual void DoLog(wxLogLevel level, const wxString& msg, - time_t timestamp); - - /** - Called to log the specified string. The timestamp is already included in the - string but still passed to this function. - A simple implementation may just send the string to @c stdout or, better, - @c stderr. - */ - virtual void DoLogString(const wxString& msg, time_t timestamp); - - /** - Instructs wxLog to not create new log targets on the fly if there is none - currently. (Almost) for internal use only: it is supposed to be called by the - application shutdown code. - Note that this function also calls - ClearTraceMasks(). - */ - static void DontCreateOnDemand(); - - /** - Shows all the messages currently in buffer and clears it. If the buffer - is already empty, nothing happens. - */ - virtual void Flush(); - - /** - Flushes the current log target if any, does nothing if there is none. - - @see Flush() - */ - static void FlushActive(); - - /** - Returns the pointer to the active log target (may be @NULL). - */ - static wxLog* GetActiveTarget(); - - /** - Returns the current log level limit. - */ - static wxLogLevel GetLogLevel(); - - /** - Returns whether the repetition counting mode is enabled. - */ - static bool GetRepetitionCounting(); - - /** - Returns the current timestamp format string. - */ - static const wxString GetTimestamp(); - - /** - Returns the current trace mask, see Customization() section - for details. - */ - static wxTraceMask GetTraceMask(); - - /** - Returns the currently allowed list of string trace masks. - - @see AddTraceMask(). - */ - static const wxArrayString GetTraceMasks(); - - /** - Returns whether the verbose mode is currently active. - */ - static bool GetVerbose(); - - /** - Returns @true if the @a mask is one of allowed masks for - wxLogTrace(). - - See also: AddTraceMask(), RemoveTraceMask() - */ - static bool IsAllowedTraceMask(const wxString& mask); - - /** - There are two functions which must be implemented by any derived class to - actually process the log messages: DoLog() and - DoLogString(). The second function receives a string - which just has to be output in some way and the easiest way to write a new log - target is to override just this function in the derived class. If more control - over the output format is needed, then the first function must be overridden - which allows you to construct custom messages depending on the log level or even - do completely different things depending on the message severity (for example, - throw away all messages except warnings and errors, show warnings on the - screen and forward the error messages to the user's (or programmer's) cell - phone - maybe depending on whether the timestamp tells us if it is day or - night in the current time zone). - There also functions to support message buffering. Why are they needed? - Some of wxLog implementations, most notably the standard wxLogGui class, - buffer the messages (for example, to avoid showing the user a zillion of modal - message boxes one after another -- which would be really annoying). - Flush() shows them all and clears the buffer contents. - This function doesn't do anything if the buffer is already empty. - Flush() - - FlushActive() - */ - - - /** - Forwards the message at specified level to the @e DoLog() function of the - active log target if there is any, does nothing otherwise. - */ - static void OnLog(wxLogLevel level, const wxString& message); - - /** - Remove the @a mask from the list of allowed masks for - wxLogTrace(). - See also: AddTraceMask() - */ - static void RemoveTraceMask(const wxString& mask); - - /** - Resumes logging previously suspended by a call to - Suspend(). All messages logged in the meanwhile will be - flushed soon. - */ - static void Resume(); - - /** - Sets the specified log target as the active one. Returns the pointer to the - previous active log target (may be @NULL). To suppress logging use a new - instance of wxLogNull not @NULL. If the active log target is set to @NULL a - new default log target will be created when logging occurs. - */ - static wxLog* SetActiveTarget(wxLog* logtarget); - - /** - Specifies that log messages with level logLevel should be ignored - and not sent to the active log target. - */ - static void SetLogLevel(wxLogLevel logLevel); - - /** - Enables logging mode in which a log message is logged once, and in case exactly - the same message successively repeats one or more times, only the number of - repetitions is logged. - */ - static void SetRepetitionCounting(bool repetCounting = true); - - /** - Sets the timestamp format prepended by the default log targets to all - messages. The string may contain any normal characters as well as % - prefixed format specificators, see @e strftime() manual for details. - Passing an empty string to this function disables message time stamping. - */ - static void SetTimestamp(const wxString& format); - - /** - Sets the trace mask, see Customization() - section for details. - */ - static void SetTraceMask(wxTraceMask mask); - - /** - Activates or deactivates verbose mode in which the verbose messages are - logged as the normal ones instead of being silently dropped. - */ - static void SetVerbose(bool verbose = true); - - /** - Suspends the logging until Resume() is called. Note that - the latter must be called the same number of times as the former to undo it, - i.e. if you call Suspend() twice you must call Resume() twice as well. - Note that suspending the logging means that the log sink won't be be flushed - periodically, it doesn't have any effect if the current log target does the - logging immediately without waiting for Flush() to be - called (the standard GUI log target only shows the log dialog when it is - flushed, so Suspend() works as expected with it). - - @see Resume(), wxLogNull - */ - static void Suspend(); -}; - - - -/** - @class wxLogNull - @wxheader{log.h} - - This class allows you to temporarily suspend logging. All calls to the log - functions during the life time of an object of this class are just ignored. - - In particular, it can be used to suppress the log messages given by wxWidgets - itself but it should be noted that it is rarely the best way to cope with this - problem as @b all log messages are suppressed, even if they indicate a - completely different error than the one the programmer wanted to suppress. - - For instance, the example of the overview: - - @code - wxFile file; - - // wxFile.Open() normally complains if file can't be opened, we don't want it - { - wxLogNull logNo; - if ( !file.Open("bar") ) - ... process error ourselves ... - } // ~wxLogNull called, old log sink restored - - wxLogMessage("..."); // ok - @endcode - - would be better written as: - - @code - wxFile file; - - // don't try to open file if it doesn't exist, we are prepared to deal with - // this ourselves - but all other errors are not expected - if ( wxFile::Exists("bar") ) - { - // gives an error message if the file couldn't be opened - file.Open("bar"); - } - else - { - ... - } - @endcode - - - @library{wxbase} - @category{logging} -*/ -class wxLogNull : public wxLog -{ -public: - /** - Suspends logging. - */ - wxLogNull(); - - /** - Resumes logging. - */ -}; - - - -// ============================================================================ -// Global functions/macros -// ============================================================================ - -/** @ingroup group_funcmacro_log */ -//@{ - -/** - This function shows a message to the user in a safe way and should be safe - to call even before the application has been initialized or if it is - currently in some other strange state (for example, about to crash). Under - Windows this function shows a message box using a native dialog instead of - wxMessageBox() (which might be unsafe to call), elsewhere it simply prints - the message to the standard output using the title as prefix. - - @param title - The title of the message box shown to the user or the prefix of the - message string. - @param text - The text to show to the user. - - @see wxLogFatalError() - - @header{wx/log.h} -*/ -void wxSafeShowMessage(const wxString& title, const wxString& text); - -/** - Returns the error code from the last system call. This function uses - @c errno on Unix platforms and @c GetLastError under Win32. - - @see wxSysErrorMsg(), wxLogSysError() - - @header{wx/log.h} -*/ -unsigned long wxSysErrorCode(); - -/** - Returns the error message corresponding to the given system error code. If - @a errCode is 0 (default), the last error code (as returned by - wxSysErrorCode()) is used. - - @see wxSysErrorCode(), wxLogSysError() - - @header{wx/log.h} -*/ -const wxChar* wxSysErrorMsg(unsigned long errCode = 0); - -//@} - -/** @ingroup group_funcmacro_log */ -//@{ -/** - For all normal, informational messages. They also appear in a message box - by default (but it can be changed). - - @header{wx/log.h} -*/ -void wxLogMessage(const char* formatString, ... ); -void wxVLogMessage(const char* formatString, va_list argPtr); -//@} - -/** @ingroup group_funcmacro_log */ -//@{ -/** - For verbose output. Normally, it is suppressed, but might be activated if - the user wishes to know more details about the program progress (another, - but possibly confusing name for the same function could be @c wxLogInfo). - - @header{wx/log.h} -*/ -void wxLogVerbose(const char* formatString, ... ); -void wxVLogVerbose(const char* formatString, va_list argPtr); -//@} - -/** @ingroup group_funcmacro_log */ -//@{ -/** - For warnings - they are also normally shown to the user, but don't - interrupt the program work. - - @header{wx/log.h} -*/ -void wxLogWarning(const char* formatString, ... ); -void wxVLogWarning(const char* formatString, va_list argPtr); -//@} - -/** @ingroup group_funcmacro_log */ -//@{ -/** - Like wxLogError(), but also terminates the program with the exit code 3. - Using @e abort() standard function also terminates the program with this - exit code. - - @header{wx/log.h} -*/ -void wxLogFatalError(const char* formatString, ... ); -void wxVLogFatalError(const char* formatString, va_list argPtr); -//@} - -/** @ingroup group_funcmacro_log */ -//@{ -/** - The functions to use for error messages, i.e. the messages that must be - shown to the user. The default processing is to pop up a message box to - inform the user about it. - - @header{wx/log.h} -*/ -void wxLogError(const char* formatString, ... ); -void wxVLogError(const char* formatString, va_list argPtr); -//@} - -/** @ingroup group_funcmacro_log */ -//@{ -/** - Like wxLogDebug(), trace functions only do something in debug builds and - expand to nothing in the release one. The reason for making it a separate - function is that usually there are a lot of trace messages, so it might - make sense to separate them from other debug messages. - - wxLogDebug(const char*,const char*,...) and - wxLogDebug(wxTraceMask,const char*,...) can be used instead if you would - like to be able to separate trace messages into different categories which - can be enabled or disabled with the static functions provided in wxLog. - - @header{wx/log.h} -*/ -void wxLogTrace(const char* formatString, ... ); -void wxVLogTrace(const char* formatString, va_list argPtr); -//@} - -/** @ingroup group_funcmacro_log */ -//@{ -/** - Like wxLogDebug(), trace functions only do something in debug builds and - expand to nothing in the release one. The reason for making it a separate - function is that usually there are a lot of trace messages, so it might - make sense to separate them from other debug messages. - - In this version of wxLogTrace(), trace messages can be separated into - different categories and calls using this function only log the message if - the given @a mask is currently enabled in wxLog. This lets you selectively - trace only some operations and not others by enabling the desired trace - masks with wxLog::AddTraceMask() or by setting the - @ref overview_envvars "@c WXTRACE environment variable". - - The predefined string trace masks used by wxWidgets are: - - @beginDefList - @itemdef{ wxTRACE_MemAlloc, Trace memory allocation (new/delete) } - @itemdef{ wxTRACE_Messages, Trace window messages/X callbacks } - @itemdef{ wxTRACE_ResAlloc, Trace GDI resource allocation } - @itemdef{ wxTRACE_RefCount, Trace various ref counting operations } - @itemdef{ wxTRACE_OleCalls, Trace OLE method calls (Win32 only) } - @endDefList - - @note Since both the mask and the format string are strings, this might - lead to function signature confusion in some cases: if you intend to - call the format string only version of wxLogTrace(), add a "%s" - format string parameter and then supply a second string parameter for - that "%s", the string mask version of wxLogTrace() will erroneously - get called instead, since you are supplying two string parameters to - the function. In this case you'll unfortunately have to avoid having - two leading string parameters, e.g. by adding a bogus integer (with - its "%d" format string). - - @header{wx/log.h} -*/ -void wxLogTrace(const char* mask, const char* formatString, ... ); -void wxVLogTrace(const char* mask, - const char* formatString, - va_list argPtr); -//@} - -/** @ingroup group_funcmacro_log */ -//@{ -/** - Like wxLogDebug(), trace functions only do something in debug builds and - expand to nothing in the release one. The reason for making it a separate - function is that usually there are a lot of trace messages, so it might - make sense to separate them from other debug messages. - - This version of wxLogTrace() only logs the message if all the bits - corresponding to the @a mask are set in the wxLog trace mask which can be - set by calling wxLog::SetTraceMask(). This version is less flexible than - wxLogDebug(const char*,const char*,...) because it doesn't allow defining - the user trace masks easily. This is why it is deprecated in favour of - using string trace masks. - - The following bitmasks are defined for wxTraceMask: - - @beginDefList - @itemdef{ wxTraceMemAlloc, Trace memory allocation (new/delete) } - @itemdef{ wxTraceMessages, Trace window messages/X callbacks } - @itemdef{ wxTraceResAlloc, Trace GDI resource allocation } - @itemdef{ wxTraceRefCount, Trace various ref counting operations } - @itemdef{ wxTraceOleCalls, Trace OLE method calls (Win32 only) } - @endDefList - - @header{wx/log.h} -*/ -void wxLogTrace(wxTraceMask mask, const char* formatString, ... ); -void wxVLogTrace(wxTraceMask mask, const char* formatString, va_list argPtr); -//@} - -/** @ingroup group_funcmacro_log */ -//@{ -/** - The right functions for debug output. They only do something in debug mode - (when the preprocessor symbol @c __WXDEBUG__ is defined) and expand to - nothing in release mode (otherwise). - - @header{wx/log.h} -*/ -void wxLogDebug(const char* formatString, ... ); -void wxVLogDebug(const char* formatString, va_list argPtr); -//@} - -/** @ingroup group_funcmacro_log */ -//@{ -/** - Messages logged by this function will appear in the statusbar of the - @a frame or of the top level application window by default (i.e. when using - the second version of the functions). - - If the target frame doesn't have a statusbar, the message will be lost. - - @header{wx/log.h} -*/ -void wxLogStatus(wxFrame* frame, const char* formatString, ... ); -void wxVLogStatus(wxFrame* frame, const char* formatString, va_list argPtr); -void wxLogStatus(const char* formatString, ... ); -void wxVLogStatus(const char* formatString, va_list argPtr); -//@} - -/** @ingroup group_funcmacro_log */ -//@{ -/** - Mostly used by wxWidgets itself, but might be handy for logging errors - after system call (API function) failure. It logs the specified message - text as well as the last system error code (@e errno or @e ::GetLastError() - depending on the platform) and the corresponding error message. The second - form of this function takes the error code explicitly as the first - argument. - - @see wxSysErrorCode(), wxSysErrorMsg() - - @header{wx/log.h} -*/ -void wxLogSysError(const char* formatString, ... ); -void wxVLogSysError(const char* formatString, va_list argPtr); -//@} - diff --git a/interface/longlong.h b/interface/longlong.h deleted file mode 100644 index e3eaef7ec6..0000000000 --- a/interface/longlong.h +++ /dev/null @@ -1,202 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: longlong.h -// Purpose: interface of wxLongLong -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxLongLong - @wxheader{longlong.h} - - This class represents a signed 64 bit long number. It is implemented using the - native 64 bit type where available (machines with 64 bit longs or compilers - which have (an analog of) @e long long type) and uses the emulation code in - the other cases which ensures that it is the most efficient solution for - working with 64 bit integers independently of the architecture. - - wxLongLong defines all usual arithmetic operations such as addition, - subtraction, bitwise shifts and logical operations as well as multiplication - and division (not yet for the machines without native @e long long). It - also has operators for implicit construction from and conversion to the native - @e long long type if it exists and @e long. - - You would usually use this type in exactly the same manner as any other - (built-in) arithmetic type. Note that wxLongLong is a signed type, if you - want unsigned values use wxULongLong which has exactly the same API as - wxLongLong except when explicitly mentioned otherwise. - - If a native (i.e. supported directly by the compiler) 64 bit integer type was - found to exist, @e wxLongLong_t macro will be defined to correspond to it. - Also, in this case only, two additional macros will be defined: - wxLongLongFmtSpec() for printing 64 bit integers - using the standard @c printf() function (but see also - wxLongLong::ToString for a more portable solution) and - wxLL() for defining 64 bit integer compile-time constants. - - @library{wxbase} - @category{data} -*/ -class wxLongLong -{ -public: - /** - Constructor from 2 longs: the high and low part are combined into one - wxLongLong. - */ - wxLongLong(long hi, unsigned long lo); - - //@{ - /** - Returns an absolute value of wxLongLong - either making a copy (const version) - or modifying it in place (the second one). Not in wxULongLong. - */ - wxLongLong Abs(); - const wxLongLong& Abs(); - //@} - - /** - This allows to convert a double value to wxLongLong type. Such conversion is - not always possible in which case the result will be silently truncated in a - platform-dependent way. Not in wxULongLong. - */ - wxLongLong Assign(double d); - - /** - Returns the high 32 bits of 64 bit integer. - */ - long GetHi() const; - - /** - Returns the low 32 bits of 64 bit integer. - */ - unsigned long GetLo() const; - - /** - Convert to native long long (only for compilers supporting it) - */ - wxLongLong_t GetValue() const; - - /** - Returns the value as @c double. - */ - double ToDouble() const; - - /** - Truncate wxLongLong to long. If the conversion loses data (i.e. the wxLongLong - value is outside the range of built-in long type), an assert will be triggered - in debug mode. - */ - long ToLong() const; - - /** - Returns the string representation of a wxLongLong. - */ - wxString ToString() const; - - /** - Adds 2 wxLongLongs together and returns the result. - */ - wxLongLong operator+(const wxLongLong& ll) const; - - //@{ - /** - Pre/post increment operator. - */ - wxLongLong operator++(); - wxLongLong operator++(int ); - //@} - - /** - Add another wxLongLong to this one. - */ - wxLongLong operator+(const wxLongLong& ll); - - /** - Subtracts 2 wxLongLongs and returns the result. - */ - wxLongLong operator-(const wxLongLong& ll) const; - - //@{ - /** - Pre/post decrement operator. - */ - wxLongLong operator--(); - wxLongLong operator--(int ); - //@} - - /** - Subtracts another wxLongLong from this one. - */ - wxLongLong operator-(const wxLongLong& ll); - - /** - Assignment operator from unsigned long long. The sign bit will be copied too. - - @since 2.7.0 - */ - wxLongLong& operator operator=(const wxULongLong& ll); -}; - - - -// ============================================================================ -// Global functions/macros -// ============================================================================ - -/** @ingroup group_funcmacro_misc */ -//@{ - -/** - This macro is defined to contain the @c printf() format specifier using - which 64 bit integer numbers (i.e. those of type @c wxLongLong_t) can be - printed. Example of using it: - - @code - #ifdef wxLongLong_t - wxLongLong_t ll = wxLL(0x1234567890abcdef); - printf("Long long = %" wxLongLongFmtSpec "x\n", ll); - #endif - @endcode - - @see wxLL() - - @header{wx/longlong.h} -*/ -#define wxLongLongFmtSpec - -/** - This macro is defined for the platforms with a native 64 bit integer type - and allow the use of 64 bit compile time constants: - - @code - #ifdef wxLongLong_t - wxLongLong_t ll = wxLL(0x1234567890abcdef); - #endif - @endcode - - @see wxULL(), wxLongLong - - @header{wx/longlong.h} -*/ -wxLongLong_t wxLL(number); - -/** - This macro is defined for the platforms with a native 64 bit integer type - and allow the use of 64 bit compile time constants: - - @code - #ifdef wxLongLong_t - unsigned wxLongLong_t ll = wxULL(0x1234567890abcdef); - #endif - @endcode - - @see wxLL(), wxLongLong - - @header{wx/longlong.h} -*/ -wxLongLong_t wxULL(number); - -//@} - diff --git a/interface/math.h b/interface/math.h deleted file mode 100644 index e60620eaa5..0000000000 --- a/interface/math.h +++ /dev/null @@ -1,28 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: math.h -// Purpose: interface of global functions -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** @ingroup group_funcmacro_math */ -//@{ - -/** - Returns a non-zero value if @a x is neither infinite nor NaN (not a - number), returns 0 otherwise. - - @header{wx/math.h} -*/ -int wxFinite(double x); - -/** - Returns a non-zero value if x is NaN (not a number), returns 0 otherwise. - - @header{wx/math.h} -*/ -bool wxIsNaN(double x); - -//@} - diff --git a/interface/mdi.h b/interface/mdi.h deleted file mode 100644 index 3d5f3b80bc..0000000000 --- a/interface/mdi.h +++ /dev/null @@ -1,405 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: mdi.h -// Purpose: interface of wxMDIClientWindow -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxMDIClientWindow - @wxheader{mdi.h} - - An MDI client window is a child of wxMDIParentFrame, and manages zero or - more wxMDIChildFrame objects. - - @library{wxcore} - @category{FIXME} - - @see wxMDIChildFrame, wxMDIParentFrame, wxFrame -*/ -class wxMDIClientWindow : public wxWindow -{ -public: - //@{ - /** - Constructor, creating the window. - - @param parent - The window parent. - @param style - The window style. Currently unused. - - @remarks The second style of constructor is called within - wxMDIParentFrame::OnCreateClient. - - @see wxMDIParentFrame::wxMDIParentFrame, wxMDIParentFrame::OnCreateClient - */ - wxMDIClientWindow(); - wxMDIClientWindow(wxMDIParentFrame* parent, long style = 0); - //@} - - /** - Destructor. - */ - ~wxMDIClientWindow(); - - /** - Used in two-step frame construction. See wxMDIClientWindow() - for further details. - */ - bool CreateClient(wxMDIParentFrame* parent, long style = 0); -}; - - - -/** - @class wxMDIParentFrame - @wxheader{mdi.h} - - An MDI (Multiple Document Interface) parent frame is a window which can contain - MDI child frames in its own 'desktop'. It is a convenient way to avoid window - clutter, - and is used in many popular Windows applications, such as Microsoft Word(TM). - - @beginStyleTable - @style{wxCAPTION} - Puts a caption on the frame. - @style{wxDEFAULT_FRAME_STYLE} - Defined as wxMINIMIZE_BOX | wxMAXIMIZE_BOX | wxTHICK_FRAME | - wxSYSTEM_MENU | wxCAPTION. - @style{wxHSCROLL} - Displays a horizontal scrollbar in the client window, allowing the - user to view child frames that are off the current view. - @style{wxICONIZE} - Display the frame iconized (minimized) (Windows only). - @style{wxMAXIMIZE} - Displays the frame maximized (Windows only). - @style{wxMAXIMIZE_BOX} - Displays a maximize box on the frame (Windows and Motif only). - @style{wxMINIMIZE} - Identical to wxICONIZE. - @style{wxMINIMIZE_BOX} - Displays a minimize box on the frame (Windows and Motif only). - @style{wxRESIZE_BORDER} - Displays a resizeable border around the window (Motif only; for - Windows, it is implicit in wxTHICK_FRAME). - @style{wxSTAY_ON_TOP} - Stay on top of other windows (Windows only). - @style{wxSYSTEM_MENU} - Displays a system menu (Windows and Motif only). - @style{wxTHICK_FRAME} - Displays a thick frame around the window (Windows and Motif only). - @style{wxVSCROLL} - Displays a vertical scrollbar in the client window, allowing the - user to view child frames that are off the current view. - @style{wxFRAME_NO_WINDOW_MENU} - Under Windows, removes the Window menu that is normally added - automatically. - @endStyleTable - - @library{wxcore} - @category{managedwnd} - - @see wxMDIChildFrame, wxMDIClientWindow, wxFrame, wxDialog -*/ -class wxMDIParentFrame : public wxFrame -{ -public: - //@{ - /** - Constructor, creating the window. - - @param parent - The window parent. This should be @NULL. - @param id - 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. - @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 wxMDIParentFrame. - @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 - individual windows. - - @remarks During the construction of the frame, the client window will be - created. To use a different class from - wxMDIClientWindow, override - OnCreateClient(). - - @see Create(), OnCreateClient() - */ - wxMDIParentFrame(); - wxMDIParentFrame(wxWindow* parent, wxWindowID id, - const wxString& title, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = wxDEFAULT_FRAME_STYLE | wxVSCROLL | wxHSCROLL, - const wxString& name = "frame"); - //@} - - /** - Destructor. Destroys all child windows and menu bar if present. - */ - ~wxMDIParentFrame(); - - /** - Activates the MDI child following the currently active one. - - @see ActivatePrevious() - */ - void ActivateNext(); - - /** - Activates the MDI child preceding the currently active one. - - @see ActivateNext() - */ - void ActivatePrevious(); - - /** - Arranges any iconized (minimized) MDI child windows. - - @see Cascade(), Tile() - */ - void ArrangeIcons(); - - /** - Arranges the MDI child windows in a cascade. - - @see Tile(), ArrangeIcons() - */ - void Cascade(); - - /** - Used in two-step frame construction. See wxMDIParentFrame() - for further details. - */ - bool Create(wxWindow* parent, wxWindowID id, - const wxString& title, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = wxDEFAULT_FRAME_STYLE | wxVSCROLL | wxHSCROLL, - const wxString& name = "frame"); - - /** - Returns a pointer to the active MDI child, if there is one. - */ - wxMDIChildFrame* GetActiveChild() const; - - /** - This gets the size of the frame 'client area' in pixels. - - @param width - Receives the client width in pixels. - @param height - Receives the client height in pixels. - - @remarks The client area is the area which may be drawn on by the - programmer, excluding title bar, border, status bar, - and toolbar if present. - - @see GetToolBar(), SetToolBar(), - wxMDIClientWindow - */ - virtual void GetClientSize(int* width, int* height) const; - - /** - Returns a pointer to the client window. - - @see OnCreateClient() - */ - wxMDIClientWindow* GetClientWindow() const; - - /** - Returns the window being used as the toolbar for this frame. - - @see SetToolBar() - */ - virtual wxWindow* GetToolBar() const; - - /** - Returns the current Window menu (added by wxWidgets to the menubar). This - function - is available under Windows only. - */ - wxMenu* GetWindowMenu() const; - - /** - Override this to return a different kind of client window. If you override this - function, - you must create your parent frame in two stages, or your function will never be - called, - due to the way C++ treats virtual functions called from constructors. For - example: - - @remarks You might wish to derive from wxMDIClientWindow in order to - implement different erase behaviour, for example, such - as painting a bitmap on the background. - - @see GetClientWindow(), wxMDIClientWindow - */ - virtual wxMDIClientWindow* OnCreateClient(); - - /** - Sets the window to be used as a toolbar for this - MDI parent window. It saves the application having to manage the positioning - of the toolbar MDI client window. - - @param toolbar - Toolbar to manage. - - @remarks When the frame is resized, the toolbar is resized to be the - width of the frame client area, and the toolbar height - is kept the same. - - @see GetToolBar(), GetClientSize() - */ - virtual void SetToolBar(wxWindow* toolbar); - - /** - Call this to change the current Window menu. Ownership of the menu object - passes to - the frame when you call this function. - This call is available under Windows only. - To remove the window completely, use the wxFRAME_NO_WINDOW_MENU window style. - */ - void SetWindowMenu(wxMenu* menu); - - /** - Tiles the MDI child windows either horizontally or vertically depending on - whether @a orient is wxHORIZONTAL or wxVERTICAL. - Currently only implemented for MSW, does nothing under the other platforms. - */ - void Tile(wxOrientation orient = wxHORIZONTAL); -}; - - - -/** - @class wxMDIChildFrame - @wxheader{mdi.h} - - An MDI child frame is a frame that can only exist on a wxMDIClientWindow, - which is itself a child of wxMDIParentFrame. - - @beginStyleTable - @style{wxCAPTION} - Puts a caption on the frame. - @style{wxDEFAULT_FRAME_STYLE} - Defined as wxMINIMIZE_BOX | wxMAXIMIZE_BOX | wxTHICK_FRAME | - wxSYSTEM_MENU | wxCAPTION. - @style{wxICONIZE} - Display the frame iconized (minimized) (Windows only). - @style{wxMAXIMIZE} - Displays the frame maximized (Windows only). - @style{wxMAXIMIZE_BOX} - Displays a maximize box on the frame (Windows and Motif only). - @style{wxMINIMIZE} - Identical to wxICONIZE. - @style{wxMINIMIZE_BOX} - Displays a minimize box on the frame (Windows and Motif only). - @style{wxRESIZE_BORDER} - Displays a resizeable border around the window (Motif only; for - Windows, it is implicit in wxTHICK_FRAME). - @style{wxSTAY_ON_TOP} - Stay on top of other windows (Windows only). - @style{wxSYSTEM_MENU} - Displays a system menu (Windows and Motif only). - @style{wxTHICK_FRAME} - Displays a thick frame around the window (Windows and Motif only). - @endStyleTable - - @library{wxcore} - @category{managedwnd} - - @see wxMDIClientWindow, wxMDIParentFrame, wxFrame -*/ -class wxMDIChildFrame : public wxFrame -{ -public: - //@{ - /** - Constructor, creating the window. - - @param parent - The window parent. This should not be @NULL. - @param id - 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. - @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 wxMDIChildFrame. - @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 - individual windows. - - @remarks None. - - @see Create() - */ - wxMDIChildFrame(); - wxMDIChildFrame(wxMDIParentFrame* 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. - */ - ~wxMDIChildFrame(); - - /** - Activates this MDI child frame. - - @see Maximize(), Restore() - */ - void Activate(); - - /** - Used in two-step frame construction. See wxMDIChildFrame() - for further details. - */ - bool Create(wxWindow* parent, wxWindowID id, - const wxString& title, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = wxDEFAULT_FRAME_STYLE, - const wxString& name = "frame"); - - /** - Maximizes this MDI child frame. - - @see Activate(), Restore() - */ - void Maximize(bool maximize); - - /** - Restores this MDI child frame (unmaximizes). - */ - void Restore(); -}; - diff --git a/interface/mediactrl.h b/interface/mediactrl.h deleted file mode 100644 index 6a1fcb3c5f..0000000000 --- a/interface/mediactrl.h +++ /dev/null @@ -1,400 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: mediactrl.h -// Purpose: interface of wxMediaEvent -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxMediaEvent - @wxheader{mediactrl.h} - - Event wxMediaCtrl uses. - - @library{wxmedia} - @category{FIXME} -*/ -class wxMediaEvent : public wxNotifyEvent -{ -public: - -}; - - - -/** - @class wxMediaCtrl - @wxheader{mediactrl.h} - - wxMediaCtrl is a class for displaying types of - media, such as videos, audio files, natively through native codecs. - - wxMediaCtrl uses native backends to render media, for example on Windows - there is a ActiveMovie/DirectShow backend, and on Macintosh there is a - QuickTime backend. - - @library{wxmedia} - @category{media} - - @see wxMediaEvent -*/ -class wxMediaCtrl : public wxControl -{ -public: - //@{ - /** - , - wxPoint& - - @param pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = 0, - const wxString& szBackend = wxT(""), - const wxValidatorvalidator = wxDefaultValidator, - const wxString& name = wxPanelNameStr - ) - - Constructor that calls Create. You may prefer to call Create directly to check - to see if wxMediaCtrl is available on the system. - - parent - parent of this control. Must not be @NULL. - @param id - id to use for events - @param fileName - If not empty, the path of a file to open. - @param pos - Position to put control at. - @param size - Size to put the control at and to stretch movie to. - @param style - Optional styles. - @param szBackend - Name of backend you want to use, leave blank to make - wxMediaCtrl figure it out. - @param validator - validator to use. - @param name - Window name. - */ - wxMediaCtrl() const; - wxMediaCtrl(wxWindow* parent, wxWindowID id) const; - //@} - - /** - Generally, you should almost certainly leave this part up to - wxMediaCtrl - but if you need a certain backend for a particular - reason, such as QuickTime for playing .mov files, all you need - to do to choose a specific backend is to pass the - name of the backend class to - Create(). - The following are valid backend identifiers - - - @b wxMEDIABACKEND_DIRECTSHOW - - - Use ActiveMovie/DirectShow. Uses the native ActiveMovie - (I.E. DirectShow) control. Default backend on Windows and - supported by nearly all Windows versions, even some - Windows CE versions. May display a windows media player - logo while inactive. - - @b wxMEDIABACKEND_QUICKTIME - - Use QuickTime. Mac Only. - WARNING: May not working correctly embedded in a wxNotebook. - - @b wxMEDIABACKEND_GSTREAMER - - Use GStreamer. Unix Only. Requires GStreamer 0.8 along - with at the very least the xvimagesink, xoverlay, and - gst-play modules of gstreamer to function. You need the correct - modules to play the relavant files, for example the mad module - to play mp3s, etc. - - @b wxMEDIABACKEND_WMP10 - - Uses Windows Media Player 10 (Windows only) - works on mobile - machines with Windows Media Player 10 and desktop machines with - either Windows Media Player 9 or 10 - - Note that other backends such as wxMEDIABACKEND_MCI can now be - found at wxCode. - */ - - - /** - , - wxPoint& - - @param pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = 0, - const wxString& szBackend = wxT(""), - const wxValidatorvalidator = wxDefaultValidator, - const wxString& name = wxPanelNameStr - ) - - Creates this control. Returns @false if it can't load the movie located at - fileName or it cannot load one of its native backends. - - If you specify a file to open via fileName and you don't specify a backend to - use, wxMediaCtrl tries each of its backends until one that can render the path referred to by fileName can be found. - - parent - parent of this control. Must not be @NULL. - @param id - id to use for events - @param fileName - If not empty, the path of a file to open. - @param pos - Position to put control at. - @param size - Size to put the control at and to stretch movie to. - @param style - Optional styles. - @param szBackend - Name of backend you want to use, leave blank to make - wxMediaCtrl figure it out. - @param validator - validator to use. - @param name - Window name. - */ - bool Create(wxWindow* parent, wxWindowID id) const; - - /** - Creating a backend for wxMediaCtrl is a rather simple process. Simply derive - from wxMediaBackendCommonBase and implement the methods you want. The methods - in wxMediaBackend correspond to those in wxMediaCtrl except for CreateControl - which does the actual creation of the control, in cases where a custom control - is not needed you may simply call wxControl::Create. - You need to make sure to use the DECLARE_CLASS and IMPLEMENT_CLASS macros. - The only real tricky part is that you need to make sure the file in compiled - in, which if there are just backends in there will not happen and you may need - to use a force link hack (see http://www.wxwidgets.org/wiki/index.php/RTTI). - This is a rather simple example of how to create a backend in the - wxActiveXContainer documentation. - */ - - - /** - Obtains the best size relative to the original/natural size of the - video, if there is any. See @ref overview_videosizewxmediactrl "Video size" - for more information. - */ - wxSize GetBestSize(); - - /** - Obtains the playback rate, or speed of the media. @c 1.0 represents normal - speed, while @c 2.0 represents twice the normal speed of the media, for - example. Not supported on the GStreamer (Unix) backend. - Returns 0 on failure. - */ - double GetPlaybackrate(); - - /** - Obtains the state the playback of the media is in - - - @b wxMEDIASTATE_STOPPED - - The movie has stopped. - - @b wxMEDIASTATE_PAUSED - - The movie is paused. - - @b wxMEDIASTATE_PLAYING - - The movie is currently playing. - */ - wxMediaCtrlState GetState(); - - /** - Gets the volume of the media from a 0.0 to 1.0 range. Note that due to rounding - and other errors this may not be the exact value sent to SetVolume. - */ - double GetVolume(); - - /** - Obtains the length - the total amount of time the movie has in milliseconds. - */ - wxFileOffset Length(); - - /** - Loads the location that @c uri refers to with the proxy @c proxy. Not - implemented on most backends so it should be called with caution. Returns @false if loading fails. - */ - bool Load(const wxURI& uri, const wxURI& proxy); - - /** - Same as @ref loaduri() Load. Kept for wxPython compatability. - */ - bool LoadURI(const wxURI& uri); - - /** - Same as @ref loaduriwithproxy() Load. Kept for wxPython compatability. - */ - bool LoadURIWithProxy(const wxURI& uri, const wxURI& proxy); - - /** - When wxMediaCtrl plays a file, it plays until the stop position - is reached (currently the end of the file/stream). Right before - it hits the end of the stream, it fires off a EVT_MEDIA_STOP - event to its parent window, at which point the event handler - can choose to veto the event, preventing the stream from actually - stopping. - Example: - - When wxMediaCtrl stops, either by the EVT_MEDIA_STOP not being - vetoed, or by manually calling - Stop(), where it actually - stops is not at the beginning, rather, but at the beginning of - the stream. That is, when it stops and play is called, playback - is gauranteed to start at the beginning of the media. This is - because some streams are not seekable, and when stop is called - on them they return to the beginning, thus wxMediaCtrl tries - to keep consistant for all types of media. - Note that when changing the state of the media through Play() - and other methods, the media may not actually be in the - wxMEDIASTATE_PLAYING, for example. If you are relying on the - media being in certain state catch the event relevant to the state. - See wxMediaEvent for the kinds of events - that you can catch. - */ - - - /** - Pauses playback of the movie. - */ - bool Pause(); - - /** - Resumes playback of the movie. - */ - bool Play(); - - /** - Normally, when you use wxMediaCtrl it is just a window for the video to - play in. However, some toolkits have their own media player interface. - For example, QuickTime generally has a bar below the video with a slider. - A special feature available to wxMediaCtrl, you can use the toolkit's interface - instead of - making your own by using the ShowPlayerControls() - function. There are several options for the flags parameter, with - the two general flags being wxMEDIACTRLPLAYERCONTROLS_NONE which turns off - the native interface, and wxMEDIACTRLPLAYERCONTROLS_DEFAULT which lets - wxMediaCtrl decide what native controls on the interface. Be sure to review - the caveats outlined in @ref overview_videosizewxmediactrl "Video size" before - doing so. - */ - - - /** - Depending upon the backend, wxMediaCtrl can render - and display pretty much any kind of media that the native system can - - such as an image, mpeg video, or mp3 (without license restrictions - - since it relies on native system calls that may not technically - have mp3 decoding available, for example, it falls outside the - realm of licensing restrictions). - For general operation, all you need to do is call - Load() to load the file - you want to render, catch the EVT_MEDIA_LOADED event, - and then call Play() - to show the video/audio of the media in that event. - More complex operations are generally more heavily dependant on the - capabilities of the backend. For example, QuickTime cannot set - the playback rate of certain streaming media - while DirectShow is - slightly more flexible in that regard. - */ - - - /** - Seeks to a position within the movie. - */ - wxFileOffset Seek(wxFileOffset where, wxSeekMode mode); - - /** - Sets the playback rate, or speed of the media, to that referred by @c dRate. - @c 1.0 represents normal speed, while @c 2.0 represents twice the normal - speed of the media, for example. Not supported on the GStreamer (Unix) backend. - Returns @true if successful. - */ - bool SetPlaybackRate(double dRate); - - /** - Sets the volume of the media from a 0.0 to 1.0 range to that referred - by @c dVolume. @c 1.0 represents full volume, while @c 0.5 - represents half (50 percent) volume, for example. Note that this may not be - exact due to conversion and rounding errors, although setting the volume to - full or none is always exact. Returns @true if successful. - */ - bool SetVolume(double dVolume); - - /** - A special feature to wxMediaCtrl. Applications using native toolkits such as - QuickTime usually have a scrollbar, play button, and more provided to - them by the toolkit. By default wxMediaCtrl does not do this. However, on - the directshow and quicktime backends you can show or hide the native controls - provided by the underlying toolkit at will using ShowPlayerControls. Simply - calling the function with default parameters tells wxMediaCtrl to use the - default controls provided by the toolkit. The function takes a - @c wxMediaCtrlPlayerControls enumeration as follows: - - @b wxMEDIACTRLPLAYERCONTROLS_NONE - - No controls. return wxMediaCtrl to it's default state. - - @b wxMEDIACTRLPLAYERCONTROLS_STEP - - Step controls like fastfoward, step one frame etc. - - @b wxMEDIACTRLPLAYERCONTROLS_VOLUME - - Volume controls like the speaker icon, volume slider, etc. - - @b wxMEDIACTRLPLAYERCONTROLS_DEFAULT - - Default controls for the toolkit. Currently a typedef for - wxMEDIACTRLPLAYERCONTROLS_STEP and wxMEDIACTRLPLAYERCONTROLS_VOLUME. - - For more see @ref overview_playercontrolswxmediactrl "Player controls". - Currently - only implemented on the QuickTime and DirectShow backends. The function - returns @true on success. - */ - bool ShowPlayerControls(wxMediaCtrlPlayerControls flags = wxMEDIACTRLPLAYERCONTROLS_DEFAULT); - - /** - Stops the media. - See Operation() for an overview of how - stopping works. - */ - bool Stop(); - - /** - Obtains the current position in time within the movie in milliseconds. - */ - wxFileOffset Tell(); - - /** - By default, wxMediaCtrl will scale the size of the video to the - requested amount passed to either it's constructor or Create(). - After calling Load or performing an equivilant operation, you - can subsequently obtain the "real" size of the video (if there - is any) by calling GetBestSize(). Note that the actual result - on the display will be slightly different when ShowPlayerControls - is activated and the actual video size will be less then - specified due to the extra controls provided by the native toolkit. - In addition, the backend may modify GetBestSize() to include the - size of the extra controls - so if you want the real size of the - video just disable ShowPlayerControls(). - The idea with setting GetBestSize to the size of the video is - that GetBestSize is a wxWindow-derived function that is called - when sizers on a window recalculate. What this means is that - if you use sizers by default the video will show in it's - original size without any extra assistance needed from the user. - */ -}; - diff --git a/interface/memory.h b/interface/memory.h deleted file mode 100644 index ec1fbed3de..0000000000 --- a/interface/memory.h +++ /dev/null @@ -1,295 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: memory.h -// Purpose: interface of wxDebugStreamBuf -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxDebugStreamBuf - @wxheader{memory.h} - - This class allows you to treat debugging output in a similar - (stream-based) fashion on different platforms. Under - Windows, an ostream constructed with this buffer outputs - to the debugger, or other program that intercepts debugging - output. On other platforms, the output goes to standard error (cerr). - - This is soon to be obsolete, replaced by wxLog functionality. - - @library{wxbase} - @category{FIXME} - - @see Overview() -*/ -class wxDebugStreamBuf -{ -public: - -}; - - - -/** - @class wxDebugContext - @wxheader{memory.h} - - A class for performing various debugging and memory tracing - operations. Full functionality (such as printing out objects - currently allocated) is only present in a debugging build of wxWidgets, - i.e. if the __WXDEBUG__ symbol is defined. wxDebugContext - and related functions and macros can be compiled out by setting - wxUSE_DEBUG_CONTEXT to 0 is setup.h - - @library{wxbase} - @category{debugging} - - @see Overview() -*/ -class wxDebugContext -{ -public: - /** - Checks the memory blocks for errors, starting from the currently set - checkpoint. - - @return Returns the number of errors, so a value of zero represents - success. Returns -1 if an error was detected that - prevents further checking. - */ - int Check(); - - /** - Performs a memory dump from the currently set checkpoint, writing to the - current debug stream. Calls the @b Dump member function for each wxObject - derived instance. - - @return @true if the function succeeded, @false otherwise. - */ - bool Dump(); - - /** - Returns @true if the memory allocator checks all previous memory blocks for - errors. - By default, this is @false since it slows down execution considerably. - - @see SetCheckPrevious() - */ - bool GetCheckPrevious(); - - /** - Returns @true if debug mode is on. If debug mode is on, the wxObject new and - delete - operators store or use information about memory allocation. Otherwise, - a straight malloc and free will be performed by these operators. - - @see SetDebugMode() - */ - bool GetDebugMode(); - - /** - Gets the debug level (default 1). The debug level is used by the wxTraceLevel - function and - the WXTRACELEVEL macro to specify how detailed the trace information is; setting - a different level will only have an effect if trace statements in the - application - specify a value other than one. - This is obsolete, replaced by wxLog functionality. - - @see SetLevel() - */ - int GetLevel(); - - /** - Returns the output stream associated with the debug context. - This is obsolete, replaced by wxLog functionality. - - @see SetStream() - */ - ostream GetStream(); - - /** - Returns a pointer to the output stream buffer associated with the debug context. - There may not necessarily be a stream buffer if the stream has been set - by the user. - This is obsolete, replaced by wxLog functionality. - */ - streambuf* GetStreamBuf(); - - /** - Returns @true if there is a stream currently associated - with the debug context. - This is obsolete, replaced by wxLog functionality. - - @see SetStream(), GetStream() - */ - bool HasStream(); - - /** - Prints a list of the classes declared in this application, giving derivation - and whether instances of this class can be dynamically created. - - @see PrintStatistics() - */ - bool PrintClasses(); - - /** - Performs a statistics analysis from the currently set checkpoint, writing - to the current debug stream. The number of object and non-object - allocations is printed, together with the total size. - - @param detailed - If @true, the function will also print how many - objects of each class have been allocated, and the space taken by - these class instances. - - @see PrintStatistics() - */ - bool PrintStatistics(bool detailed = true); - - /** - Tells the memory allocator to check all previous memory blocks for errors. - By default, this is @false since it slows down execution considerably. - - @see GetCheckPrevious() - */ - void SetCheckPrevious(bool check); - - /** - Sets the current checkpoint: Dump and PrintStatistics operations will - be performed from this point on. This allows you to ignore allocations - that have been performed up to this point. - - @param all - If @true, the checkpoint is reset to include all - memory allocations since the program started. - */ - void SetCheckpoint(bool all = false); - - /** - Sets the debug mode on or off. If debug mode is on, the wxObject new and delete - operators store or use information about memory allocation. Otherwise, - a straight malloc and free will be performed by these operators. - By default, debug mode is on if __WXDEBUG__ is defined. If the application - uses this function, it should make sure that all object memory allocated - is deallocated with the same value of debug mode. Otherwise, the - delete operator might try to look for memory information that does not - exist. - - @see GetDebugMode() - */ - void SetDebugMode(bool debug); - - /** - Sets the current debug file and creates a stream. This will delete any existing - stream and stream buffer. By default, the debug context stream - outputs to the debugger (Windows) or standard error (other platforms). - */ - bool SetFile(const wxString& filename); - - /** - Sets the debug level (default 1). The debug level is used by the wxTraceLevel - function and - the WXTRACELEVEL macro to specify how detailed the trace information is; setting - a different level will only have an effect if trace statements in the - application - specify a value other than one. - This is obsolete, replaced by wxLog functionality. - - @see GetLevel() - */ - void SetLevel(int level); - - /** - Installs a function to be called at the end of wxWidgets shutdown. It will be - called after - all files with global instances of wxDebugContextDumpDelayCounter have run - their destructors. - The shutdown function must be take no parameters and return nothing. - */ - void SetShutdownNotifyFunction(wxShutdownNotifyFunction func); - - /** - Sets the debugging stream to be the debugger (Windows) or standard error (other - platforms). - This is the default setting. The existing stream will be flushed and deleted. - This is obsolete, replaced by wxLog functionality. - */ - bool SetStandardError(); - - /** - Sets the stream and optionally, stream buffer associated with the debug context. - This operation flushes and deletes the existing stream (and stream buffer if - any). - This is obsolete, replaced by wxLog functionality. - - @param stream - Stream to associate with the debug context. Do not set this to @NULL. - @param streamBuf - Stream buffer to associate with the debug context. - */ - void SetStream(ostream* stream, streambuf* streamBuf = NULL); -}; - - - -// ============================================================================ -// Global functions/macros -// ============================================================================ - -/** @ingroup group_funcmacro_log */ -//@{ - -/** - @deprecated Use one of the wxLogTrace() functions or one of the - wxVLogTrace() functions instead. - - Calls wxTrace() with printf-style variable argument syntax. Output is - directed to the current output stream (see wxDebugContext). - - @header{wx/memory.h} -*/ -#define WXTRACE(format, ...) - -/** - @deprecated Use one of the wxLogTrace() functions or one of the - wxVLogTrace() functions instead. - - Calls wxTraceLevel with printf-style variable argument syntax. Output is - directed to the current output stream (see wxDebugContext). The first - argument should be the level at which this information is appropriate. It - will only be output if the level returned by wxDebugContext::GetLevel is - equal to or greater than this value. - - @header{wx/memory.h} -*/ -#define WXTRACELEVEL(level, format, ...) - -/** - @deprecated Use one of the wxLogTrace() functions or one of the - wxVLogTrace() functions instead. - - Takes printf-style variable argument syntax. Output is directed to the - current output stream (see wxDebugContext). - - @header{wx/memory.h} -*/ -void wxTrace(const wxString& format, ...); - -/** - @deprecated Use one of the wxLogTrace() functions or one of the - wxVLogTrace() functions instead. - - Takes @e printf() style variable argument syntax. Output is directed to the - current output stream (see wxDebugContext). The first argument should be - the level at which this information is appropriate. It will only be output - if the level returned by wxDebugContext::GetLevel() is equal to or greater - than this value. - - @header{wx/memory.h} -*/ -void wxTraceLevel(int level, const wxString& format, ...); - -//@} - diff --git a/interface/menu.h b/interface/menu.h deleted file mode 100644 index f19fc4ca04..0000000000 --- a/interface/menu.h +++ /dev/null @@ -1,872 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: menu.h -// Purpose: interface of wxMenuBar -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxMenuBar - @wxheader{menu.h} - - A menu bar is a series of menus accessible from the top of a frame. - - @library{wxcore} - @category{menus} - - @see wxMenu, @ref overview_eventhandling "Event Handling Overview" -*/ -class wxMenuBar : public wxWindow -{ -public: - /** - Construct an empty menu barM - - @param style - If wxMB_DOCKABLE the menu bar can be detached (wxGTK only). - */ - wxMenuBar(long style = 0); - - /** - Construct a menu bar from arrays of menus and titles. - - @param n - The number of menus. - @param menus - An array of menus. Do not use this array again - it now belongs to - the menu bar. - @param titles - An array of title strings. Deallocate this array after creating - the menu bar. - @param style - If wxMB_DOCKABLE the menu bar can be detached (wxGTK only). - */ - wxMenuBar(size_t n, wxMenu* menus[], const wxString titles[], - long style = 0); - - /** - Destructor, destroying the menu bar and removing it from the parent frame (if - any). - */ - ~wxMenuBar(); - - /** - Adds the item to the end of the menu bar. - - @param menu - The menu to add. Do not deallocate this menu after calling Append. - @param title - The title of the menu. - - @return @true on success, @false if an error occurred. - - @see Insert() - */ - bool Append(wxMenu* menu, const wxString& title); - - /** - Checks or unchecks a menu item. - - @param id - The menu item identifier. - @param check - If @true, checks the menu item, otherwise the item is unchecked. - - @remarks Only use this when the menu bar has been associated with a - frame; otherwise, use the wxMenu equivalent call. - */ - void Check(int id, const bool check); - - /** - Enables or disables (greys out) a menu item. - - @param id - The menu item identifier. - @param enable - @true to enable the item, @false to disable it. - - @remarks Only use this when the menu bar has been associated with a - frame; otherwise, use the wxMenu equivalent call. - */ - void Enable(int id, const bool enable); - - /** - Enables or disables a whole menu. - - @param pos - The position of the menu, starting from zero. - @param enable - @true to enable the menu, @false to disable it. - - @remarks Only use this when the menu bar has been associated with a frame. - */ - void EnableTop(int pos, const bool enable); - - /** - Finds the menu item object associated with the given menu item identifier. - - @param id - Menu item identifier. - @param menu - If not @NULL, menu will get set to the associated menu. - - @return The found menu item object, or @NULL if one was not found. - */ - wxMenuItem* FindItem(int id, wxMenu menu = NULL) const; - - /** - Returns the index of the menu with the given @a title or @c wxNOT_FOUND if no - such menu exists in this menubar. The @a title parameter may specify either - the menu title (with accelerator characters, i.e. @c "File") or just the - menu label (@c "File") indifferently. - */ - int FindMenu(const wxString& title) const; - - /** - Finds the menu item id for a menu name/menu item string pair. - - @param menuString - Menu title to find. - @param itemString - Item to find. - - @return The menu item identifier, or wxNOT_FOUND if none was found. - - @remarks Any special menu codes are stripped out of source and target - strings before matching. - */ - int FindMenuItem(const wxString& menuString, - const wxString& itemString) const; - - /** - Gets the help string associated with the menu item identifier. - - @param id - The menu item identifier. - - @return The help string, or the empty string if there was no help string - or the menu item was not found. - - @see SetHelpString() - */ - wxString GetHelpString(int id) const; - - /** - Gets the label associated with a menu item. - - @param id - The menu item identifier. - - @return The menu item label, or the empty string if the item was not - found. - - @remarks Use only after the menubar has been associated with a frame. - */ - wxString GetLabel(int id) const; - - /** - Returns the label of a top-level menu. Note that the returned string does not - include the accelerator characters which could have been specified in the menu - title string during its construction. - - @param pos - Position of the menu on the menu bar, starting from zero. - - @return The menu label, or the empty string if the menu was not found. - - @remarks Use only after the menubar has been associated with a frame. - - @see SetLabelTop() - */ - wxString GetLabelTop(int pos) const; - - /** - Returns the menu at @a menuIndex (zero-based). - */ - wxMenu* GetMenu(int menuIndex) const; - - /** - Returns the number of menus in this menubar. - */ - size_t GetMenuCount() const; - - /** - Returns the label of a top-level menu. Note that the returned string - includes the accelerator characters that have been specified in the menu - title string during its construction. - - @param pos - Position of the menu on the menu bar, starting from zero. - - @return The menu label, or the empty string if the menu was not found. - - @remarks Use only after the menubar has been associated with a frame. - - @see GetMenuLabelText(), SetMenuLabel() - */ - wxString GetMenuLabel(int pos) const; - - /** - Returns the label of a top-level menu. Note that the returned string does not - include any accelerator characters that may have been specified in the menu - title string during its construction. - - @param pos - Position of the menu on the menu bar, starting from zero. - - @return The menu label, or the empty string if the menu was not found. - - @remarks Use only after the menubar has been associated with a frame. - - @see GetMenuLabel(), SetMenuLabel() - */ - wxString GetMenuLabelText(int pos) const; - - /** - Inserts the menu at the given position into the menu bar. Inserting menu at - position 0 will insert it in the very beginning of it, inserting at position - GetMenuCount() is the same as calling - Append(). - - @param pos - The position of the new menu in the menu bar - @param menu - The menu to add. wxMenuBar owns the menu and will free it. - @param title - The title of the menu. - - @return @true on success, @false if an error occurred. - - @see Append() - */ - bool Insert(size_t pos, wxMenu* menu, const wxString& title); - - /** - Determines whether an item is checked. - - @param id - The menu item identifier. - - @return @true if the item was found and is checked, @false otherwise. - */ - bool IsChecked(int id) const; - - /** - Determines whether an item is enabled. - - @param id - The menu item identifier. - - @return @true if the item was found and is enabled, @false otherwise. - */ - bool IsEnabled(int id) const; - - /** - Redraw the menu bar - */ - void Refresh(); - - /** - Removes the menu from the menu bar and returns the menu object - the caller is - responsible for deleting it. This function may be used together with - Insert() to change the menubar - dynamically. - - @see Replace() - */ - wxMenu* Remove(size_t pos); - - /** - Replaces the menu at the given position with another one. - - @param pos - The position of the new menu in the menu bar - @param menu - The menu to add. - @param title - The title of the menu. - - @return The menu which was previously at position pos. The caller is - responsible for deleting it. - - @see Insert(), Remove() - */ - wxMenu* Replace(size_t pos, wxMenu* menu, const wxString& title); - - /** - Sets the help string associated with a menu item. - - @param id - Menu item identifier. - @param helpString - Help string to associate with the menu item. - - @see GetHelpString() - */ - void SetHelpString(int id, const wxString& helpString); - - /** - Sets the label of a menu item. - - @param id - Menu item identifier. - @param label - Menu item label. - - @remarks Use only after the menubar has been associated with a frame. - - @see GetLabel() - */ - void SetLabel(int id, const wxString& label); - - /** - Sets the label of a top-level menu. - - @param pos - The position of a menu on the menu bar, starting from zero. - @param label - The menu label. - - @remarks Use only after the menubar has been associated with a frame. - - @see GetLabelTop() - */ - void SetLabelTop(int pos, const wxString& label); - - /** - Sets the label of a top-level menu. - - @param pos - The position of a menu on the menu bar, starting from zero. - @param label - The menu label. - - @remarks Use only after the menubar has been associated with a frame. - */ - void SetMenuLabel(int pos, const wxString& label); -}; - - - -/** - @class wxMenu - @wxheader{menu.h} - - A menu is a popup (or pull down) list of items, one of which may be - selected before the menu goes away (clicking elsewhere dismisses the - menu). Menus may be used to construct either menu bars or popup menus. - - A menu item has an integer ID associated with it which can be used to - identify the selection, or to change the menu item in some way. A menu item - with a special identifier -1 is a separator item and doesn't have an - associated command but just makes a separator line appear in the menu. - - @note Please note that @e wxID_ABOUT and @e wxID_EXIT are - predefined by wxWidgets and have a special meaning since entries - using these IDs will be taken out of the normal menus under MacOS X - and will be inserted into the system menu (following the appropriate - MacOS X interface guideline). On PalmOS @e wxID_EXIT is disabled according - to Palm OS Companion guidelines. - - Menu items may be either normal items, check items or radio items. Normal items - don't have any special properties while the check items have a boolean flag - associated to them and they show a checkmark in the menu when the flag is set. - wxWidgets automatically toggles the flag value when the item is clicked and its - value may be retrieved using either wxMenu::IsChecked method - of wxMenu or wxMenuBar itself or by using - wxEvent::IsChecked when you get the menu - notification for the item in question. - - The radio items are similar to the check items except that all the other items - in the same radio group are unchecked when a radio item is checked. The radio - group is formed by a contiguous range of radio items, i.e. it starts at the - first item of this kind and ends with the first item of a different kind (or - the end of the menu). Notice that because the radio groups are defined in terms - of the item positions inserting or removing the items in the menu containing - the radio items risks to not work correctly. Finally note that radio items - are not supported under Motif. - - @library{wxcore} - @category{menus} - - @see wxMenuBar, wxWindow::PopupMenu, - @ref overview_eventhandling "Event Handling Overview", - @ref wxFileHistory "wxFileHistory (most recently used files menu)" -*/ -class wxMenu : public wxEvtHandler -{ -public: - /** - Constructs a wxMenu object. - - @param style - If set to wxMENU_TEAROFF, the menu will be detachable (wxGTK only). - */ - wxMenu(long style); - - /** - Constructs a wxMenu object with a title - - @param title - Title at the top of the menu (not always supported). - @param style - If set to wxMENU_TEAROFF, the menu will be detachable (wxGTK only). - */ - wxMenu(const wxString& title = "", long style = 0); - - /** - Destructor, destroying the menu. - Note: under Motif, a popup menu must have a valid parent (the window - it was last popped up on) when being destroyed. Therefore, make sure - you delete or re-use the popup menu @e before destroying the - parent window. Re-use in this context means popping up the menu on - a different window from last time, which causes an implicit destruction - and recreation of internal data structures. - */ - ~wxMenu(); - - /** - Adds a menu item. - - @param id - The menu command identifier. - @param item - The string to appear on the menu item. - @param helpString - An optional help string associated with the item. - By default, the handler for the wxEVT_MENU_HIGHLIGHT event displays - this string in the status line. - @param kind - May be wxITEM_SEPARATOR, wxITEM_NORMAL, - wxITEM_CHECK or wxITEM_RADIO - - @see AppendSeparator(), AppendCheckItem(), AppendRadioItem(), - AppendSubMenu(), Insert(), SetLabel(), - GetHelpString(), SetHelpString(), wxMenuItem - */ - wxMenuItem* Append(int id, const wxString& item = wxEmptyString, - const wxString& helpString = wxEmptyString, - wxItemKind kind = wxITEM_NORMAL); - - /** - Adds a submenu. - - @deprecated This function is deprecated, use AppendSubMenu() instead. - - @param id - The menu command identifier. - @param item - The string to appear on the menu item. - @param subMenu - Pull-right submenu. - @param helpString - An optional help string associated with the item. - By default, the handler for the wxEVT_MENU_HIGHLIGHT event displays - this string in the status line. - - @see AppendSeparator(), AppendCheckItem(), AppendRadioItem(), - AppendSubMenu(), Insert(), SetLabel(), - GetHelpString(), SetHelpString(), wxMenuItem - */ - wxMenuItem* Append(int id, const wxString& item, - wxMenu* subMenu, - const wxString& helpString = wxEmptyString); - - /** - Adds a menu item object. This is the most generic variant of Append() method - because it may be used for both items (including separators) and submenus and - because you can also specify various extra properties of a menu item this way, - such as bitmaps and fonts. - - @param menuItem - A menuitem object. It will be owned by the wxMenu object after this function - is called, so do not delete it yourself. - - @see AppendSeparator(), AppendCheckItem(), AppendRadioItem(), - AppendSubMenu(), Insert(), SetLabel(), - GetHelpString(), SetHelpString(), wxMenuItem - */ - wxMenuItem* Append(wxMenuItem* menuItem); - - /** - Adds a checkable item to the end of the menu. - - @see Append(), InsertCheckItem() - */ - wxMenuItem* AppendCheckItem(int id, const wxString& item, - const wxString& helpString = ""); - - /** - Adds a radio item to the end of the menu. All consequent radio items form a - group and when an item in the group is checked, all the others are - automatically unchecked. - - @see Append(), InsertRadioItem() - */ - wxMenuItem* AppendRadioItem(int id, const wxString& item, - const wxString& helpString = ""); - - /** - Adds a separator to the end of the menu. - - @see Append(), InsertSeparator() - */ - wxMenuItem* AppendSeparator(); - - /** - Adds the given @a submenu to this menu. @a text is the text shown in the - menu for it and @a help is the help string shown in the status bar when the - submenu item is selected. - */ - wxMenuItem* AppendSubMenu(wxMenu* submenu, const wxString& text, - const wxString& help = wxEmptyString); - - /** - Inserts a break in a menu, causing the next appended item to appear in a new - column. - */ - void Break(); - - /** - Checks or unchecks the menu item. - - @param id - The menu item identifier. - @param check - If @true, the item will be checked, otherwise it will be unchecked. - - @see IsChecked() - */ - void Check(int id, const bool check); - - /** - Deletes the menu item from the menu. If the item is a submenu, it will - @b not be deleted. Use Destroy() if you want to delete a submenu. - - @param id - Id of the menu item to be deleted. - - @see FindItem(), Destroy(), Remove() - */ - void Delete(int id); - - /** - Deletes the menu item from the menu. If the item is a submenu, it will - @b not be deleted. Use Destroy() if you want to delete a submenu. - - @param item - Menu item to be deleted. - - @see FindItem(), Destroy(), Remove() - */ - void Delete(wxMenuItem* item); - - /** - Deletes the menu item from the menu. If the item is a submenu, it will - be deleted. Use Remove() if you want to keep the submenu (for example, - to reuse it later). - - @param id - Id of the menu item to be deleted. - - @see FindItem(), Deletes(), Remove() - */ - void Destroy(int id); - - /** - Deletes the menu item from the menu. If the item is a submenu, it will - be deleted. Use Remove() if you want to keep the submenu (for example, - to reuse it later). - - @param item - Menu item to be deleted. - - @see FindItem(), Deletes(), Remove() - */ - void Destroy(wxMenuItem* item); - - /** - Enables or disables (greys out) a menu item. - - @param id - The menu item identifier. - @param enable - @true to enable the menu item, @false to disable it. - - @see IsEnabled() - */ - void Enable(int id, const bool enable); - - /** - Finds the menu id for a menu item string. - - @param itemString - Menu item string to find. - - @return Menu item identifier, or wxNOT_FOUND if none is found. - - @remarks Any special menu codes are stripped out of source and target - strings before matching. - */ - int FindItem(const wxString& itemString) const; - - /** - Finds the menu item object associated with the given menu item identifier and, - optionally, the (sub)menu it belongs to. - - @param id - Menu item identifier. - @param menu - If the pointer is not @NULL, it will be filled with the item's - parent menu (if the item was found) - - @return Menu item object or NULL if none is found. - */ - const wxMenuItem * FindItem(int id, wxMenu** menu = NULL) const; - - /** - Returns the wxMenuItem given a position in the menu. - */ - wxMenuItem* FindItemByPosition(size_t position) const; - - /** - Returns the help string associated with a menu item. - - @param id - The menu item identifier. - - @return The help string, or the empty string if there is no help string - or the item was not found. - - @see SetHelpString(), Append() - */ - wxString GetHelpString(int id) const; - - /** - Returns a menu item label. - - @param id - The menu item identifier. - - @return The item label, or the empty string if the item was not found. - - @see GetLabelText(), SetLabel() - */ - wxString GetLabel(int id) const; - - /** - Returns a menu item label, without any of the original mnemonics and - accelerators. - - @param id - The menu item identifier. - - @return The item label, or the empty string if the item was not found. - - @see GetLabel(), SetLabel() - */ - wxString GetLabelText(int id) const; - - /** - Returns the number of items in the menu. - */ - size_t GetMenuItemCount() const; - - /** - Returns the list of items in the menu. wxMenuItemList is a pseudo-template - list class containing wxMenuItem pointers, see wxList. - */ - wxMenuItemList GetMenuItems() const; - - /** - Returns the title of the menu. - - @remarks This is relevant only to popup menus, use - wxMenuBar::GetMenuLabel for the menus in the menubar. - - @see SetTitle() - */ - wxString GetTitle() const; - - /** - Inserts the given @a item before the position @e pos. Inserting the item - at position GetMenuItemCount() is the same - as appending it. - - @see Append(), Prepend() - */ - wxMenuItem* Insert(size_t pos, wxMenuItem* item); - - /** - Inserts the given @a item before the position @e pos. Inserting the item - at position GetMenuItemCount() is the same - as appending it. - - @see Append(), Prepend() - */ - wxMenuItem* Insert(size_t pos, int id, - const wxString& item = "", - const wxString& helpString = "", - wxItemKind kind = wxITEM_NORMAL); - - /** - Inserts a checkable item at the given position. - - @see Insert(), AppendCheckItem() - */ - wxMenuItem* InsertCheckItem(size_t pos, int id, - const wxString& item, - const wxString& helpString = ""); - - /** - Inserts a radio item at the given position. - - @see Insert(), AppendRadioItem() - */ - wxMenuItem* InsertRadioItem(size_t pos, int id, - const wxString& item, - const wxString& helpString = ""); - - /** - Inserts a separator at the given position. - - @see Insert(), AppendSeparator() - */ - wxMenuItem* InsertSeparator(size_t pos); - - /** - Determines whether a menu item is checked. - - @param id - The menu item identifier. - - @return @true if the menu item is checked, @false otherwise. - - @see Check() - */ - bool IsChecked(int id) const; - - /** - Determines whether a menu item is enabled. - - @param id - The menu item identifier. - - @return @true if the menu item is enabled, @false otherwise. - - @see Enable() - */ - bool IsEnabled(int id) const; - - /** - Inserts the given @a item at position 0, i.e. before all the other - existing items. - - @see Append(), Insert() - */ - wxMenuItem* Prepend(wxMenuItem* item); - - /** - Inserts the given @a item at position 0, i.e. before all the other - existing items. - - @see Append(), Insert() - */ - wxMenuItem* Prepend(int id, const wxString& item = "", - const wxString& helpString = "", - wxItemKind kind = wxITEM_NORMAL); - - /** - Inserts a checkable item at position 0. - - @see Prepend(), AppendCheckItem() - */ - wxMenuItem* PrependCheckItem(int id, const wxString& item, - const wxString& helpString = ""); - - /** - Inserts a radio item at position 0. - - @see Prepend(), AppendRadioItem() - */ - wxMenuItem* PrependRadioItem(int id, const wxString& item, - const wxString& helpString = ""); - - /** - Inserts a separator at position 0. - - @see Prepend(), AppendSeparator() - */ - wxMenuItem* PrependSeparator(); - - /** - Removes the menu item from the menu but doesn't delete the associated C++ - object. This allows you to reuse the same item later by adding it back to the menu - (especially useful with submenus). - - @param id - The identifier of the menu item to remove. - - @return A pointer to the item which was detached from the menu. - */ - wxMenuItem* Remove(int id); - - /** - Removes the menu item from the menu but doesn't delete the associated C++ - object. This allows you to reuse the same item later by adding it back to the menu - (especially useful with submenus). - - @param item - The menu item to remove. - - @return A pointer to the item which was detached from the menu. - */ - wxMenuItem* Remove(wxMenuItem* item); - - /** - Sets an item's help string. - - @param id - The menu item identifier. - @param helpString - The help string to set. - - @see GetHelpString() - */ - void SetHelpString(int id, const wxString& helpString); - - /** - Sets the label of a menu item. - - @param id - The menu item identifier. - @param label - The menu item label to set. - - @see Append(), GetLabel() - */ - void SetLabel(int id, const wxString& label); - - /** - Sets the title of the menu. - - @param title - The title to set. - - @remarks This is relevant only to popup menus, use - wxMenuBar::SetLabelTop for the menus in the menubar. - - @see GetTitle() - */ - void SetTitle(const wxString& title); - - /** - Sends events to @a source (or owning window if @NULL) to update the - menu UI. This is called just before the menu is popped up with - wxWindow::PopupMenu, but - the application may call it at other times if required. - */ - void UpdateUI(wxEvtHandler* source = NULL) const; -}; - diff --git a/interface/menuitem.h b/interface/menuitem.h deleted file mode 100644 index f9372b5b7c..0000000000 --- a/interface/menuitem.h +++ /dev/null @@ -1,281 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: menuitem.h -// Purpose: interface of wxMenuItem -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxMenuItem - @wxheader{menuitem.h} - - A menu item represents an item in a menu. Note that you usually don't have to - deal with it directly as wxMenu methods usually construct an - object of this class for you. - - Also please note that the methods related to fonts and bitmaps are currently - only implemented for Windows and GTK+. - - @library{wxcore} - @category{menus} - - @see wxMenuBar, wxMenu -*/ -class wxMenuItem : public wxObject -{ -public: - /** - Constructs a wxMenuItem object. - Menu items can be standard, or "stock menu items", or custom. For the - standard menu items (such as commands to open a file, exit the program and so - on, see @ref page_stockitems "Stock Items" for the full list) it is enough - to specify just the stock ID and leave @a text and @a helpString empty. In - fact, leaving at least @a text empty for the stock menu items is strongly - recommended as they will have appearance and keyboard interface (including - standard accelerators) familiar to the user. - For the custom (non-stock) menu items, @a text must be specified and while - @a helpString may be left empty, it's recommended to pass the item - description (which is automatically shown by the library in the status bar when - the menu item is selected) in this parameter. - Finally note that you can e.g. use a stock menu label without using its stock - help string; that is, stock properties are set independently one from the other. - - @param parentMenu - Menu that the menu item belongs to. Can be @NULL if the item is - going to be added to the menu later. - @param id - Identifier for this menu item. May be @c wxID_SEPARATOR, in which - case the given kind is ignored and taken to be @c wxITEM_SEPARATOR - instead. - @param text - Text for the menu item, as shown on the menu. An accelerator - key can be specified using the ampersand " character. In order to embed an - ampersand character in the menu item text, the ampersand must be doubled. - @param helpString - Optional help string that will be shown on the status bar. - @param kind - May be @c wxITEM_SEPARATOR, @c wxITEM_NORMAL, @c wxITEM_CHECK or @c - wxITEM_RADIO - @param subMenu - If non-@NULL, indicates that the menu item is a submenu. - */ - wxMenuItem(wxMenu* parentMenu = NULL, int id = wxID_SEPARATOR, - const wxString& text = "", - const wxString& helpString = "", - wxItemKind kind = wxITEM_NORMAL, - wxMenu* subMenu = NULL); - - /** - Destructor. - */ - ~wxMenuItem(); - - /** - Checks or unchecks the menu item. - Note that this only works when the item is already appended to a menu. - */ - void Check(bool check = true); - - /** - Enables or disables the menu item. - */ - void Enable(bool enable = true); - - /** - Returns the background colour associated with the menu item (Windows only). - */ - wxColour GetBackgroundColour() const; - - /** - Returns the checked or unchecked bitmap (Windows only). - */ - wxBitmap GetBitmap(bool checked = true) const; - - /** - Returns the font associated with the menu item (Windows only). - */ - wxFont GetFont() const; - - /** - Returns the help string associated with the menu item. - */ - wxString GetHelp() const; - - /** - Returns the menu item identifier. - */ - int GetId() const; - - /** - Returns the text associated with the menu item including any accelerator - characters that were passed to the constructor or SetItemLabel. - - @see GetItemLabelText(), GetLabelText() - */ - wxString GetItemLabel() const; - - /** - Returns the text associated with the menu item, without any accelerator - characters. - - @see GetItemLabel(), GetLabelText() - */ - wxString GetItemLabelText() const; - - /** - Returns the item kind, one of @c wxITEM_SEPARATOR, @c wxITEM_NORMAL, - @c wxITEM_CHECK or @c wxITEM_RADIO. - */ - wxItemKind GetKind() const; - - /** - Returns the text associated with the menu item without any accelerator - characters it might contain. - @deprecated This function is deprecated in favour of GetItemLabelText(). - @see GetText(), GetLabelFromText() - */ - wxString GetLabel() const; - - /** - @deprecated This function is deprecated; please use GetLabelText() instead. - @see GetText(), GetLabel() - */ - static wxString GetLabelFromText(const wxString& text); - - /** - Strips all accelerator characters and mnemonics from the given @e text. - For example: - - @code - wxMenuItem::GetLabelfromText( "&Hello\tCtrl-h"); - @endcode - - will return just @c "Hello". - - @see GetItemLabelText(), GetItemLabel() - */ - static wxString GetLabelText(const wxString& text); - - /** - Gets the width of the menu item checkmark bitmap (Windows only). - */ - int GetMarginWidth() const; - - /** - Returns the menu this menu item is in, or @NULL if this menu item is not - attached. - */ - wxMenu* GetMenu() const; - - /** - Returns the text associated with the menu item. - @deprecated This function is deprecated. Please use - GetItemLabel() or GetItemLabelText() instead. - */ - wxString GetName() const; - - /** - Returns the submenu associated with the menu item, or @NULL if there isn't one. - */ - wxMenu* GetSubMenu() const; - - /** - Returns the text associated with the menu item, such as it was passed to the - wxMenuItem constructor, i.e. with any accelerator characters it may contain. - @deprecated This function is deprecated in favour of GetItemLabel(). - @see GetLabel(), GetLabelFromText() - */ - wxString GetText() const; - - /** - Returns the text colour associated with the menu item (Windows only). - */ - wxColour GetTextColour() const; - - /** - Returns @true if the item is checkable. - */ - bool IsCheckable() const; - - /** - Returns @true if the item is checked. - */ - bool IsChecked() const; - - /** - Returns @true if the item is enabled. - */ - bool IsEnabled() const; - - /** - Returns @true if the item is a separator. - */ - bool IsSeparator() const; - - /** - Returns @true if the item is a submenu. - */ - bool IsSubMenu() const; - - /** - Sets the background colour associated with the menu item (Windows only). - */ - void SetBackgroundColour(const wxColour& colour) const; - - /** - Sets the bitmap for the menu item (Windows and GTK+ only). It is - equivalent to wxMenuItem::SetBitmaps(bmp, wxNullBitmap). - */ - void SetBitmap(const wxBitmap& bmp); - - /** - Sets the checked/unchecked bitmaps for the menu item (Windows only). The first - bitmap - is also used as the single bitmap for uncheckable menu items. - */ - void SetBitmaps(const wxBitmap& checked, - const wxBitmap& unchecked = wxNullBitmap); - - /** - Sets the font associated with the menu item (Windows only). - */ - void SetFont(const wxFont& font); - - /** - Sets the help string. - */ - void SetHelp(const wxString& helpString); - - /** - Sets the label associated with the menu item. - */ - void SetItemLabel(const wxString& label); - - /** - Sets the width of the menu item checkmark bitmap (Windows only). - */ - void SetMarginWidth(int width) const; - - /** - Sets the parent menu which will contain this menu item. - */ - void SetMenu(const wxMenu* menu); - - /** - Sets the submenu of this menu item. - */ - void SetSubMenu(const wxMenu* menu); - - /** - Sets the text associated with the menu item. - @deprecated This function is deprecated in favour of SetItemLabel(). - */ - void SetText(const wxString& text); - - /** - Sets the text colour associated with the menu item (Windows only). - */ - void SetTextColour(const wxColour& colour); -}; - diff --git a/interface/metafile.h b/interface/metafile.h deleted file mode 100644 index f994f22cec..0000000000 --- a/interface/metafile.h +++ /dev/null @@ -1,156 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: metafile.h -// Purpose: interface of wxMetafileDC -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxMetafileDC - @wxheader{metafile.h} - - This is a type of device context that allows a metafile object to be - created (Windows only), and has most of the characteristics of a normal - @b wxDC. The wxMetafileDC::Close member must be called after drawing into the - device context, to return a metafile. The only purpose for this at - present is to allow the metafile to be copied to the clipboard (see wxMetafile). - - Adding metafile capability to an application should be easy if you - already write to a wxDC; simply pass the wxMetafileDC to your drawing - function instead. You may wish to conditionally compile this code so it - is not compiled under X (although no harm will result if you leave it - in). - - Note that a metafile saved to disk is in standard Windows metafile format, - and cannot be imported into most applications. To make it importable, - call the function ::wxMakeMetafilePlaceable after - closing your disk-based metafile device context. - - @library{wxcore} - @category{dc} - - @see wxMetafile, wxDC -*/ -class wxMetafileDC : public wxDC -{ -public: - /** - Constructor. If no filename is passed, the metafile is created - in memory. - */ - wxMetafileDC(const wxString& filename = ""); - - /** - Destructor. - */ - ~wxMetafileDC(); - - /** - This must be called after the device context is finished with. A - metafile is returned, and ownership of it passes to the calling - application (so it should be destroyed explicitly). - */ - wxMetafile* Close(); -}; - - - -/** - @class wxMetafile - @wxheader{metafile.h} - - A @b wxMetafile represents the MS Windows metafile object, so metafile - operations have no effect in X. In wxWidgets, only sufficient functionality - has been provided for copying a graphic to the clipboard; this may be extended - in a future version. Presently, the only way of creating a metafile - is to use a wxMetafileDC. - - @library{wxcore} - @category{FIXME} - - @see wxMetafileDC -*/ -class wxMetafile : public wxObject -{ -public: - /** - Constructor. If a filename is given, the Windows disk metafile is - read in. Check whether this was performed successfully by - using the @ref isok() wxMetafile:IsOk member. - */ - wxMetafile(const wxString& filename = ""); - - /** - Destructor. - See @ref overview_refcountdestruct "reference-counted object destruction" for - more info. - */ - ~wxMetafile(); - - /** - Returns @true if the metafile is valid. - */ - bool Ok(); - - /** - Plays the metafile into the given device context, returning - @true if successful. - */ - bool Play(wxDC* dc); - - /** - Passes the metafile data to the clipboard. The metafile can no longer be - used for anything, but the wxMetafile object must still be destroyed by - the application. - Below is a example of metafile, metafile device context and clipboard use - from the @c hello.cpp example. Note the way the metafile dimensions - are passed to the clipboard, making use of the device context's ability - to keep track of the maximum extent of drawing commands. - */ - bool SetClipboard(int width = 0, int height = 0); -}; - - - -// ============================================================================ -// Global functions/macros -// ============================================================================ - -/** @ingroup group_funcmacro_gdi */ -//@{ - -/** - Given a filename for an existing, valid metafile (as constructed using - wxMetafileDC) makes it into a placeable metafile by prepending a header - containing the given bounding box. The bounding box may be obtained from a - device context after drawing into it, using the functions wxDC::MinX(), - wxDC::MinY(), wxDC::MaxX() and wxDC::MaxY(). - - In addition to adding the placeable metafile header, this function adds the - equivalent of the following code to the start of the metafile data: - - @code - SetMapMode(dc, MM_ANISOTROPIC); - SetWindowOrg(dc, minX, minY); - SetWindowExt(dc, maxX - minX, maxY - minY); - @endcode - - This simulates the wxMM_TEXT mapping mode, which wxWidgets assumes. - - Placeable metafiles may be imported by many Windows applications, and can - be used in RTF (Rich Text Format) files. - - @a scale allows the specification of scale for the metafile. - - This function is only available under Windows. - - @header{wx/metafile.h} -*/ -bool wxMakeMetafilePlaceable(const wxString& filename, - int minX, int minY, - int maxX, int maxY, - float scale = 1.0); - -//@} - diff --git a/interface/mimetype.h b/interface/mimetype.h deleted file mode 100644 index 3e753b05f0..0000000000 --- a/interface/mimetype.h +++ /dev/null @@ -1,344 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: mimetype.h -// Purpose: interface of wxMimeTypesManager -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxMimeTypesManager - @wxheader{mimetype.h} - - This class allows the application to retrieve the information about all known - MIME types from a system-specific location and the filename extensions to the - MIME types and vice versa. After initialization the functions - wxMimeTypesManager::GetFileTypeFromMimeType - and wxMimeTypesManager::GetFileTypeFromExtension - may be called: they will return a wxFileType object which - may be further queried for file description, icon and other attributes. - - @b Windows: MIME type information is stored in the registry and no additional - initialization is needed. - - @b Unix: MIME type information is stored in the files mailcap and mime.types - (system-wide) and .mailcap and .mime.types in the current user's home directory: - all of these files are searched for and loaded if found by default. However, - additional functions - wxMimeTypesManager::ReadMailcap and - wxMimeTypesManager::ReadMimeTypes are - provided to load additional files. - - If GNOME or KDE desktop environment is installed, then wxMimeTypesManager - gathers MIME information from respective files (e.g. .kdelnk files under KDE). - - @note Currently, wxMimeTypesManager is limited to reading MIME type information - but it will support modifying it as well in future versions. - - @library{wxbase} - @category{misc} - - @see wxFileType -*/ -class wxMimeTypesManager -{ -public: - /** - Constructor puts the object in the "working" state, no additional initialization - are needed - but @ref init() ReadXXX may be used to load - additional mailcap/mime.types files. - */ - wxMimeTypesManager(); - - /** - Destructor is not virtual, so this class should not be derived from. - */ - ~wxMimeTypesManager(); - - /** - This function may be used to provide hard-wired fallbacks for the MIME types - and extensions that might not be present in the system MIME database. - Please see the typetest sample for an example of using it. - */ - void AddFallbacks(const wxFileTypeInfo* fallbacks); - - /** - @note You won't normally need to use more than one wxMimeTypesManager object in a - program. - @ref ctor() wxMimeTypesManager - - @ref dtor() ~wxMimeTypesManager - */ - - - /** - Gather information about the files with given extension and return the - corresponding wxFileType object or @NULL if the extension - is unknown. - The @a extension parameter may have, or not, the leading dot, if it has it, - it is stripped automatically. It must not however be empty. - */ - wxFileType* GetFileTypeFromExtension(const wxString& extension); - - /** - Gather information about the files with given MIME type and return the - corresponding wxFileType object or @NULL if the MIME type - is unknown. - */ - wxFileType* GetFileTypeFromMimeType(const wxString& mimeType); - - /** - All of these functions are static (i.e. don't need a wxMimeTypesManager object - to call them) and provide some useful operations for string representations of - MIME types. Their usage is recommended instead of directly working with MIME - types using wxString functions. - IsOfType() - */ - - - /** - @b Unix: These functions may be used to load additional files (except for the - default ones which are loaded automatically) containing MIME - information in either mailcap(5) or mime.types(5) format. - ReadMailcap() - - ReadMimeTypes() - - AddFallbacks() - */ - - - /** - This function returns @true if either the given @a mimeType is exactly the - same as @a wildcard or if it has the same category and the subtype of - @a wildcard is '*'. Note that the '*' wildcard is not allowed in - @a mimeType itself. - The comparison don by this function is case insensitive so it is not - necessary to convert the strings to the same case before calling it. - */ - bool IsOfType(const wxString& mimeType, const wxString& wildcard); - - /** - These functions are the heart of this class: they allow to find a @ref - overview_wxfiletype "file type" object - from either file extension or MIME type. - If the function is successful, it returns a pointer to the wxFileType object - which @b must be deleted by the caller, otherwise @NULL will be returned. - GetFileTypeFromMimeType() - - GetFileTypeFromExtension() - */ - - - /** - Load additional file containing information about MIME types and associated - information in mailcap format. See metamail(1) and mailcap(5) for more - information. - @a fallback parameter may be used to load additional mailcap files without - overriding the settings found in the standard files: normally, entries from - files loaded with ReadMailcap will override the entries from files loaded - previously (and the standard ones are loaded in the very beginning), but this - will not happen if this parameter is set to @true (default is @false). - The return value is @true if there were no errors in the file or @false - otherwise. - */ - bool ReadMailcap(const wxString& filename, bool fallback = false); - - /** - Load additional file containing information about MIME types and associated - information in mime.types file format. See metamail(1) and mailcap(5) for more - information. - The return value is @true if there were no errors in the file or @false - otherwise. - */ - bool ReadMimeTypes(const wxString& filename); -}; - - - -/** - @class wxFileType - @wxheader{mimetype.h} - - This class holds information about a given @e file type. File type is the same - as - MIME type under Unix, but under Windows it corresponds more to an extension than - to MIME type (in fact, several extensions may correspond to a file type). This - object may be created in several different ways: the program might know the file - extension and wish to find out the corresponding MIME type or, conversely, it - might want to find the right extension for the file to which it writes the - contents of given MIME type. Depending on how it was created some fields may be - unknown so the return value of all the accessors @b must be checked: @false - will be returned if the corresponding information couldn't be found. - - The objects of this class are never created by the application code but are - returned by wxMimeTypesManager::GetFileTypeFromMimeType and - wxMimeTypesManager::GetFileTypeFromExtension methods. - But it is your responsibility to delete the returned pointer when you're done - with it! - - A brief reminder about what the MIME types are (see the RFC 1341 for more - information): basically, it is just a pair category/type (for example, - "text/plain") where the category is a basic indication of what a file is. - Examples of categories are "application", "image", "text", "binary", and - type is a precise definition of the document format: "plain" in the example - above means just ASCII text without any formatting, while "text/html" is the - HTML document source. - - A MIME type may have one or more associated extensions: "text/plain" will - typically correspond to the extension ".txt", but may as well be associated with - ".ini" or ".conf". - - @library{wxbase} - @category{FIXME} - - @see wxMimeTypesManager -*/ -class wxFileType -{ -public: - /** - The default constructor is private because you should never create objects of - this type: they are only returned by wxMimeTypesManager methods. - */ - wxFileType(); - - /** - The destructor of this class is not virtual, so it should not be derived from. - */ - ~wxFileType(); - - /** - This function is primarily intended for GetOpenCommand and GetPrintCommand - usage but may be also used by the application directly if, for example, you want - to use some non-default command to open the file. - The function replaces all occurrences of - - format specification - - with - - %s - - the full file name - - %t - - the MIME type - - %{param} - - the value of the parameter @e param - - using the MessageParameters object you pass to it. - If there is no '%s' in the command string (and the string is not empty), it is - assumed that the command reads the data on stdin and so the effect is the same - as " %s" were appended to the string. - Unlike all other functions of this class, there is no error return for this - function. - */ - static wxString ExpandCommand(const wxString& command, - MessageParameters& params); - - /** - If the function returns @true, the string pointed to by @a desc is filled - with a brief description for this file type: for example, "text document" for - the "text/plain" MIME type. - */ - bool GetDescription(wxString* desc); - - /** - If the function returns @true, the array @a extensions is filled - with all extensions associated with this file type: for example, it may - contain the following two elements for the MIME type "text/html" (notice the - absence of the leading dot): "html" and "htm". - @b Windows: This function is currently not implemented: there is no - (efficient) way to retrieve associated extensions from the given MIME type on - this platform, so it will only return @true if the wxFileType object was - created - by wxMimeTypesManager::GetFileTypeFromExtension - function in the first place. - */ - bool GetExtensions(wxArrayString& extensions); - - /** - If the function returns @true, the @c iconLoc is filled with the - location of the icon for this MIME type. A wxIcon may be - created from @a iconLoc later. - @b Windows: The function returns the icon shown by Explorer for the files of - the specified type. - @b Mac: This function is not implemented and always returns @false. - @b Unix: MIME manager gathers information about icons from GNOME - and KDE settings and thus GetIcon's success depends on availability - of these desktop environments. - */ - bool GetIcon(wxIconLocation* iconLoc); - - /** - If the function returns @true, the string pointed to by @a mimeType is filled - with full MIME type specification for this file type: for example, "text/plain". - */ - bool GetMimeType(wxString* mimeType); - - /** - Same as GetMimeType() but returns array of MIME - types. This array will contain only one item in most cases but sometimes, - notably under Unix with KDE, may contain more MIME types. This happens when - one file extension is mapped to different MIME types by KDE, mailcap and - mime.types. - */ - bool GetMimeType(wxArrayString& mimeTypes); - - //@{ - /** - With the first version of this method, if the @true is returned, the - string pointed to by @a command is filled with the command which must be - executed (see wxExecute()) in order to open the file of the - given type. In this case, the name of the file as well as any other parameters - is retrieved from MessageParameters() - class. - In the second case, only the filename is specified and the command to be used - to open this kind of file is returned directly. An empty string is returned to - indicate that an error occurred (typically meaning that there is no standard way - to open this kind of files). - */ - bool GetOpenCommand(wxString* command, - MessageParameters& params); - wxString GetOpenCommand(const wxString& filename); - //@} - - /** - If the function returns @true, the string pointed to by @a command is filled - with the command which must be executed (see wxExecute()) in - order to print the file of the given type. The name of the file is - retrieved from MessageParameters() class. - */ - bool GetPrintCommand(wxString* command, - MessageParameters& params); - - /** - One of the most common usages of MIME is to encode an e-mail message. The MIME - type of the encoded message is an example of a @e message parameter. These - parameters are found in the message headers ("Content-XXX"). At the very least, - they must specify the MIME type and the version of MIME used, but almost always - they provide additional information about the message such as the original file - name or the charset (for the text documents). - These parameters may be useful to the program used to open, edit, view or print - the message, so, for example, an e-mail client program will have to pass them to - this program. Because wxFileType itself can not know about these parameters, - it uses MessageParameters class to query them. The default implementation only - requires the caller to provide the file name (always used by the program to be - called - it must know which file to open) and the MIME type and supposes that - there are no other parameters. If you wish to supply additional parameters, you - must derive your own class from MessageParameters and override GetParamValue() - function, for example: - - Now you only need to create an object of this class and pass it to, for example, - GetOpenCommand() like this: - - @b Windows: As only the file name is used by the program associated with the - given extension anyhow (but no other message parameters), there is no need to - ever derive from MessageParameters class for a Windows-only program. - */ -}; - diff --git a/interface/minifram.h b/interface/minifram.h deleted file mode 100644 index c11b24e602..0000000000 --- a/interface/minifram.h +++ /dev/null @@ -1,112 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: minifram.h -// Purpose: interface of wxMiniFrame -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxMiniFrame - @wxheader{minifram.h} - - A miniframe is a frame with a small title bar. It is suitable for floating - toolbars that must not - take up too much screen area. - - An example of mini frame can be seen in the @ref overview_sampledialogs - "dialogs sample" - using the "Mini frame" command of the "Generic dialogs" submenu. - - @beginStyleTable - @style{wxICONIZE} - Display the frame iconized (minimized) (Windows only). - @style{wxCAPTION} - Puts a caption on the frame. - @style{wxMINIMIZE} - Identical to wxICONIZE. - @style{wxMINIMIZE_BOX} - Displays a minimize box on the frame (Windows and Motif only). - @style{wxMAXIMIZE} - Displays the frame maximized (Windows only). - @style{wxMAXIMIZE_BOX} - Displays a maximize box on the frame (Windows and Motif only). - @style{wxCLOSE_BOX} - Displays a close box on the frame. - @style{wxSTAY_ON_TOP} - Stay on top of other windows (Windows only). - @style{wxSYSTEM_MENU} - Displays a system menu (Windows and Motif only). - @style{wxTINY_CAPTION_HORIZ} - This style is obsolete and not used any longer. - @style{wxTINY_CAPTION_VERT} - This style is obsolete and not used any longer. - @style{wxRESIZE_BORDER} - Displays a resizeable border around the window. - @endStyleTable - - @library{wxcore} - @category{managedwnd} - - @see wxMDIParentFrame, wxMDIChildFrame, wxFrame, wxDialog -*/ -class wxMiniFrame : public wxFrame -{ -public: - //@{ - /** - Constructor, creating the window. - - @param parent - 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. - @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. - @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 wxMiniFrame. - @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 - individual windows. - - @remarks The frame behaves like a normal frame on non-Windows platforms. - - @see Create() - */ - wxMiniFrame(); - wxMiniFrame(wxWindow* parent, wxWindowID id, - const wxString& title, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = wxCAPTION | wxRESIZE_BORDER, - const wxString& name = "frame"); - //@} - - /** - Destructor. Destroys all child windows and menu bar if present. - */ - ~wxMiniFrame(); - - /** - Used in two-step frame construction. See wxMiniFrame() - for further details. - */ - bool Create(wxWindow* parent, wxWindowID id, - const wxString& title, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = wxCAPTION | wxRESIZE_BORDER, - const wxString& name = "frame"); -}; - diff --git a/interface/module.h b/interface/module.h deleted file mode 100644 index ec801b608e..0000000000 --- a/interface/module.h +++ /dev/null @@ -1,126 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: module.h -// Purpose: interface of wxModule -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxModule - @wxheader{module.h} - - The module system is a very simple mechanism to allow applications (and parts - of wxWidgets itself) to define initialization and cleanup functions that are - automatically called on wxWidgets startup and exit. - - To define a new kind of module, derive a class from wxModule, override the - wxModule::OnInit and wxModule::OnExit - functions, and add the DECLARE_DYNAMIC_CLASS and IMPLEMENT_DYNAMIC_CLASS to - header and implementation files (which can be the same file). On - initialization, wxWidgets will find all classes derived from wxModule, create - an instance of each, and call each OnInit function. On exit, wxWidgets will - call the OnExit function for each module instance. - - Note that your module class does not have to be in a header file. - - For example: - - @code - // A module to allow DDE initialization/cleanup - // without calling these functions from app.cpp or from - // the user's application. - class wxDDEModule: public wxModule - { - public: - wxDDEModule() { } - virtual bool OnInit() { wxDDEInitialize(); return @true; }; - virtual void OnExit() { wxDDECleanUp(); }; - - private: - DECLARE_DYNAMIC_CLASS(wxDDEModule) - }; - - IMPLEMENT_DYNAMIC_CLASS(wxDDEModule, wxModule) - - // Another module which uses DDE in its OnInit() - class MyModule: public wxModule - { - public: - MyModule() { AddDependency(CLASSINFO(wxDDEModule)); } - virtual bool OnInit() { ... code using DDE ... } - virtual void OnExit() { ... } - - private: - DECLARE_DYNAMIC_CLASS(MyModule) - }; - - IMPLEMENT_DYNAMIC_CLASS(MyModule, wxModule) - - // Another module which uses DDE in its OnInit() - // but uses a named dependency - class MyModule2: public wxModule - { - public: - MyModule2() { AddDependency("wxDDEModule"); } - virtual bool OnInit() { ... code using DDE ... } - virtual void OnExit() { ... } - - private: - DECLARE_DYNAMIC_CLASS(MyModule2) - }; - - IMPLEMENT_DYNAMIC_CLASS(MyModule2, wxModule) - @endcode - - @library{wxbase} - @category{FIXME} -*/ -class wxModule : public wxObject -{ -public: - /** - Constructs a wxModule object. - */ - wxModule(); - - /** - Destructor. - */ - ~wxModule(); - - //@{ - /** - Call this function from the constructor of the derived class. @a dep must be - the CLASSINFO() of a wxModule-derived class and the - corresponding module will be loaded before and unloaded after - this module. - The second version of this function allows a dependency to be added by - name without access to the class info. This is useful when a module is - declared entirely in a source file and there is no header for the declaration - of the module needed by CLASSINFO(), however errors are - not detected until run-time, instead of compile-time, then. - Note that circular dependencies are detected and result in a fatal error. - - @param dep - The class information object for the dependent module. - @param classname - The class name of the dependent module. - */ - void AddDependency(wxClassInfo* dep); - void AddDependency(const char* classname); - //@} - - /** - Provide this function with appropriate cleanup for your module. - */ - virtual void OnExit(); - - /** - Provide this function with appropriate initialization for your module. If the - function - returns @false, wxWidgets will exit immediately. - */ - virtual bool OnInit(); -}; - diff --git a/interface/msgdlg.h b/interface/msgdlg.h deleted file mode 100644 index 197224859b..0000000000 --- a/interface/msgdlg.h +++ /dev/null @@ -1,204 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: msgdlg.h -// Purpose: interface of wxMessageDialog -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxMessageDialog - @wxheader{msgdlg.h} - - This class represents a dialog that shows a single or multi-line message, - with a choice of OK, Yes, No and Cancel buttons. - - @library{wxcore} - @category{cmndlg} - - @see @ref overview_wxmessagedialogoverview "wxMessageDialog overview" -*/ -class wxMessageDialog : public wxDialog -{ -public: - /** - Constructor specifying the message box properties. - - Use ShowModal() to show the dialog. - - @a style may be a bit list of the following identifiers: - - @beginStyleTable - @style{wxOK} - Puts an Ok button in the message box. May be combined with @c - wxCANCEL. - @style{wxCANCEL} - Puts a Cancel button in the message box. Must be combined with - either @c wxOK or @c wxYES_NO. - @style{wxYES_NO} - Puts Yes and No buttons in the message box. May be combined with - @c wxCANCEL. - @style{wxNO_DEFAULT} - Makes the "No" button default, can only be used with @c wxYES_NO. - @style{wxYES_DEFAULT} - Makes the "Yes" button default, this is the default behaviour and - this flag exists solely for symmetry with @c wxNO_DEFAULT. - @style{wxICON_EXCLAMATION} - Displays an exclamation mark symbol. - @style{wxICON_ERROR} - Displays an error symbol. - @style{wxICON_HAND} - Displays an error symbol, this is a MSW-inspired synonym for @c - wxICON_ERROR. - @style{wxICON_QUESTION} - Displays a question mark symbol. This icon is automatically used - with @c wxYES_NO so it's usually unnecessary to specify it - explicitly. - @style{wxICON_INFORMATION} - Displays an information symbol. This icon is used by default if @c - wxYES_NO is not given so it is usually unnecessary to specify it - explicitly. - @style{wxSTAY_ON_TOP} - Makes the message box stay on top of all other windows (currently - implemented only under MSW). - @endStyleTable - - @param parent - Parent window. - @param message - Message to show in the dialog. - @param caption - The dialog title. - @param style - Combination of style flags described above. - @param pos - Dialog position (ignored under MSW). - */ - wxMessageDialog(wxWindow* parent, const wxString& message, - const wxString& caption = "Message box", - long style = wxOK | wxCANCEL, - const wxPoint& pos = wxDefaultPosition); - - /** - Sets the extended message for the dialog: this message is usually an - extension of the short message specified in the constructor or set with - SetMessage(). - - If it is set, the main message appears highlighted -- if supported -- - and this message appears beneath it in normal font. On the platforms - which don't support extended messages, it is simply appended to the - normal message with a new line separating them. - */ - void SetExtendedMessage(const wxString extendedMessage); - - /** - Sets the message shown by the dialog. - */ - void SetMessage(const wxString msg); - - /** - Overrides the default labels of the OK and Cancel buttons. - - Please see the remarks in SetYesNoLabels() documentation. - */ - bool SetOKCancelLabels(const wxString ok, const wxString cancel); - - /** - Overrides the default label of the OK button. - - Please see the remarks in SetYesNoLabels() documentation. - */ - bool SetOKLabel(const wxString ok); - - /** - Overrides the default labels of the Yes, No and Cancel buttons. - - Please see the remarks in SetYesNoLabels() documentation. - */ - bool SetYesNoCancelLabels(const wxString yes, const wxString no, - const wxString cancel); - - /** - Overrides the default labels of the Yes and No buttons. - - Notice that this function is not currently available on all platforms, - so it may return @false to indicate that the labels couldn't be - changed. If it returns @true (currently only under wxMac), the labels - were set successfully. Typically, if the function was used - successfully, the main dialog message may need to be changed, e.g.: - @code - wxMessageDialog dlg(...); - if ( dlg.SetYesNoLabels(_("&Quit"), _("&Don't quit")) ) - dlg.SetMessage(_("What do you want to do?")); - else // buttons have standard "Yes"/"No" values, so rephrase the question - dlg.SetMessage(_("Do you really want to quit?")); - @endcode - */ - bool SetYesNoLabels(const wxString yes, const wxString no); - - /** - Shows the dialog, returning one of wxID_OK, wxID_CANCEL, wxID_YES, - wxID_NO. - - Notice that this method returns the identifier of the button which was - clicked unlike wxMessageBox() function. - */ - int ShowModal(); -}; - - - -// ============================================================================ -// Global functions/macros -// ============================================================================ - -/** @ingroup group_funcmacro_dialog */ -//@{ - -/** - Show a general purpose message dialog. - - This is a convenient function which is usually used instead of using - wxMessageDialog directly. Notice however that some of the features, such as - extended text and custom labels for the message box buttons, are not - provided by this function but only by wxMessageDialog. - - The return value is one of: @c wxYES, @c wxNO, @c wxCANCEL or @c wxOK - (notice that this return value is @b different from the return value of - wxMessageDialog::ShowModal()). - - For example: - @code - int answer = wxMessageBox("Quit program?", "Confirm", - wxYES_NO | wxCANCEL, main_frame); - if (answer == wxYES) - main_frame->Close(); - @endcode - - @a message may contain newline characters, in which case the message will - be split into separate lines, to cater for large messages. - - @param message - Message to show in the dialog. - @param caption - The dialog title. - @param parent - Parent window. - @param style - Combination of style flags described in wxMessageDialog documentation. - @param x - Horizontal dialog position (ignored under MSW). Use @c wxDefaultCoord - for @a x and @a y to let the system position the window. - @param y - Vertical dialog position (ignored under MSW). - @header{wx/msgdlg.h} -*/ -int wxMessageBox(const wxString& message, - const wxString& caption = "Message", - int style = wxOK, - wxWindow* parent = NULL, - int x = wxDefaultCoord, - int y = wxDefaultCoord); - -//@} - diff --git a/interface/msgqueue.h b/interface/msgqueue.h deleted file mode 100644 index 2b23de8b9a..0000000000 --- a/interface/msgqueue.h +++ /dev/null @@ -1,69 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: msgqueue.h -// Purpose: interface of wxMessageQueue -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @wxheader{msgqueue.h} - - wxMessageQueue allows passing messages between threads. - - This class should be typically used to communicate between the main and worker - threads. The main thread calls wxMessageQueue::Post and - the worker thread calls wxMessageQueue::Receive. - - For this class a message is an object of arbitrary type T. Notice that - often there is a some special message indicating that the thread - should terminate as there is no other way to gracefully shutdown a thread - waiting on the message queue. - - @nolibrary - @category{FIXME} - - @see wxThread -*/ -class wxMessageQueue -{ -public: - /** - Returns @true if the object had been initialized successfully, @false - if an error occurred. - */ - bool IsOk() const; - - /** - Add a message to this queue and signal the threads waiting for messages - (i.e. the threads which called wxMessageQueue::Receive or - wxMessageQueue::ReceiveTimeout). - This method is safe to call from multiple threads in parallel. - */ - wxMessageQueueError Post(T const& msg); - - /** - Block until a message becomes available in the queue. Waits indefinitely long - or until an error occurs. - The message is returned in @e msg. - */ - wxMessageQueueError Receive(T& msg); - - /** - Block until a message becomes available in the queue, but no more than - @a timeout milliseconds has elapsed. - If no message is available after @a timeout milliseconds then returns - @b wxMSGQUEUE_TIMEOUT. - If @a timeout is 0 then checks for any messages present in the queue - and returns immediately without waiting. - The message is returned in @e msg. - */ - wxMessageQueueError ReceiveTimeout(long timeout, T& msg); - - /** - Default and only constructor. Use wxMessageQueue::IsOk to check - if the object was successfully initialized. - */ - wxMessageQueue(); -}; - diff --git a/interface/mstream.h b/interface/mstream.h deleted file mode 100644 index 37319f10b2..0000000000 --- a/interface/mstream.h +++ /dev/null @@ -1,87 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: mstream.h -// Purpose: interface of wxMemoryOutputStream -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxMemoryOutputStream - @wxheader{mstream.h} - - - @library{wxbase} - @category{streams} - - @see wxStreamBuffer -*/ -class wxMemoryOutputStream : public wxOutputStream -{ -public: - /** - If @a data is @NULL, then it will initialize a new empty buffer which will - grow if required. - */ - wxMemoryOutputStream(char* data = NULL, size_t length = 0); - - /** - Destructor. - */ - ~wxMemoryOutputStream(); - - /** - CopyTo allowed you to transfer data from the internal buffer of - wxMemoryOutputStream to an external buffer. @a len specifies the size of - the buffer. - */ - size_t CopyTo(char* buffer, size_t len) const; - - /** - Returns the pointer to the stream object used as an internal buffer - for that stream. - */ - wxStreamBuffer* GetOutputStreamBuffer() const; -}; - - - -/** - @class wxMemoryInputStream - @wxheader{mstream.h} - - - @library{wxbase} - @category{streams} - - @see wxStreamBuffer, wxMemoryOutputStream -*/ -class wxMemoryInputStream : public wxInputStream -{ -public: - //@{ - /** - Creates a new read-only memory stream, initializing it with the - data from the given input stream @e stream. - The @a len argument specifies the amount of data to read from - the @e stream. Setting it to @e wxInvalidOffset means that - the @a stream is to be read entirely (i.e. till the EOF is reached). - */ - wxMemoryInputStream(const char* data, size_t len); - wxMemoryInputStream(const wxMemoryOutputStream& stream); - wxMemoryInputStream(wxInputStream& stream, - wxFileOffset len = wxInvalidOffset); - //@} - - /** - Destructor. - */ - ~wxMemoryInputStream(); - - /** - Returns the pointer to the stream object used as an internal buffer - for that stream. - */ - wxStreamBuffer* GetInputStreamBuffer() const; -}; - diff --git a/interface/msw/ole/activex.h b/interface/msw/ole/activex.h deleted file mode 100644 index 84dd86c428..0000000000 --- a/interface/msw/ole/activex.h +++ /dev/null @@ -1,99 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: msw/ole/activex.h -// Purpose: interface of wxActiveXEvent -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxActiveXEvent - @headerfile ole/activex.h wx/msw/ole/activex.h - - An event class for handling activex events passed from wxActiveXContainer. - - ActiveX events are basically a function call with the parameters passed - through an array of wxVariants along with a return value that is a wxVariant - itself. What type the parameters or return value are depends on the context - (i.e. what the .idl specifies). - - Note that unlike the third party wxActiveX function names are not supported. - - @onlyfor{wxmsw} - - @library{wxbase} - @category{FIXME} -*/ -class wxActiveXEvent : public wxCommandEvent -{ -public: - /** - Returns the dispatch id of this activex event. This is the numeric value from - the .idl file specified by the id(). - */ - DISPID GetDispatchId(int idx) const; - - /** - Obtains the number of parameters passed through the activex event. - */ - size_t ParamCount() const; - - /** - Obtains the param name of the param number idx specifies as a string. - */ - wxString ParamName(size_t idx) const; - - /** - Obtains the param type of the param number idx specifies as a string. - */ - wxString ParamType(size_t idx) const; - - /** - Obtains the actual parameter value specified by idx. - */ - wxVariant operator[](size_t idx); -}; - - - -/** - @class wxActiveXContainer - @headerfile ole/activex.h wx/msw/ole/activex.h - - wxActiveXContainer is a host for an activex control on Windows (and - as such is a platform-specific class). Note that the HWND that the class - contains is the actual HWND of the activex control so using dynamic events - and connecting to wxEVT_SIZE, for example, will recieve the actual size - message sent to the control. - - It is somewhat similar to the ATL class CAxWindow in operation. - - The size of the activex control's content is generally gauranteed to be that - of the client size of the parent of this wxActiveXContainer. - - You can also process activex events through wxEVT_ACTIVEX or the - corresponding message map macro EVT_ACTIVEX. - - @onlyfor{wxmsw} - - @library{wxbase} - @category{FIXME} - - @see wxActiveXEvent -*/ -class wxActiveXContainer : public wxControl -{ -public: - /** - Creates this activex container. - - @param parent - parent of this control. Must not be @NULL. - @param iid - COM IID of pUnk to query. Must be a valid interface to an activex control. - @param pUnk - Interface of activex control. - */ - wxActiveXContainer(wxWindow* parent, REFIID iid, IUnknown* pUnk); -}; - diff --git a/interface/msw/ole/automtn.h b/interface/msw/ole/automtn.h deleted file mode 100644 index e8fe35671b..0000000000 --- a/interface/msw/ole/automtn.h +++ /dev/null @@ -1,197 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: msw/ole/automtn.h -// Purpose: interface of wxAutomationObject -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxAutomationObject - @headerfile ole/automtn.h wx/msw/ole/automtn.h - - The @b wxAutomationObject class represents an OLE automation object containing - a single data member, - an IDispatch pointer. It contains a number of functions that make it easy to - perform - automation operations, and set and get properties. The class makes heavy use of - the wxVariant class. - - The usage of these classes is quite close to OLE automation usage in Visual - Basic. The API is - high-level, and the application can specify multiple properties in a single - string. The following example - gets the current Excel instance, and if it exists, makes the active cell bold. - - @code - wxAutomationObject excelObject; - if (excelObject.GetInstance("Excel.Application")) - excelObject.PutProperty("ActiveCell.Font.Bold", @true); - @endcode - - Note that this class obviously works under Windows only. - - @onlyfor{wxmsw} - - @library{wxcore} - @category{misc} - - @see wxVariant -*/ -class wxAutomationObject : public wxObject -{ -public: - /** - Constructor, taking an optional IDispatch pointer which will be released when - the - object is deleted. - */ - wxAutomationObject(WXIDISPATCH* dispatchPtr = NULL); - - /** - Destructor. If the internal IDispatch pointer is non-null, it will be released. - */ - ~wxAutomationObject(); - - //@{ - /** - Calls an automation method for this object. The first form takes a method name, - number of - arguments, and an array of variants. The second form takes a method name and - zero to six - constant references to variants. Since the variant class has constructors for - the basic - data types, and C++ provides temporary objects automatically, both of the - following lines - are syntactically valid: - - Note that @a method can contain dot-separated property names, to save the - application - needing to call GetProperty several times using several temporary objects. For - example: - */ - wxVariant CallMethod(const wxString& method, int noArgs, - wxVariant args[]) const; - const wxVariant CallMethod(const wxString& method, ... ) const; - //@} - - /** - Creates a new object based on the class id, returning @true if the object was - successfully created, - or @false if not. - */ - bool CreateInstance(const wxString& classId) const; - - /** - Gets the IDispatch pointer. - */ - IDispatch* GetDispatchPtr() const; - - /** - Retrieves the current object associated with a class id, and attaches the - IDispatch pointer - to this object. Returns @true if a pointer was successfully retrieved, @false - otherwise. - Note that this cannot cope with two instances of a given OLE object being - active simultaneously, - such as two copies of Excel running. Which object is referenced cannot - currently be specified. - */ - bool GetInstance(const wxString& classId) const; - - /** - Retrieves a property from this object, assumed to be a dispatch pointer, and - initialises @a obj with it. - To avoid having to deal with IDispatch pointers directly, use this function in - preference - to GetProperty() when retrieving objects - from other objects. - Note that an IDispatch pointer is stored as a void* pointer in wxVariant - objects. - - @see GetProperty() - */ - bool GetObject(wxAutomationObject& obj, const wxString& property, - int noArgs = 0, - wxVariant args[] = NULL) const; - - //@{ - /** - Gets a property value from this object. The first form takes a property name, - number of - arguments, and an array of variants. The second form takes a property name and - zero to six - constant references to variants. Since the variant class has constructors for - the basic - data types, and C++ provides temporary objects automatically, both of the - following lines - are syntactically valid: - - Note that @a property can contain dot-separated property names, to save the - application - needing to call GetProperty several times using several temporary objects. - */ - wxVariant GetProperty(const wxString& property, int noArgs, - wxVariant args[]) const; - const wxVariant GetProperty(const wxString& property, ... ) const; - //@} - - /** - This function is a low-level implementation that allows access to the IDispatch - Invoke function. - It is not meant to be called directly by the application, but is used by other - convenience functions. - - @param member - The member function or property name. - @param action - Bitlist: may contain DISPATCH_PROPERTYPUT, DISPATCH_PROPERTYPUTREF, - DISPATCH_METHOD. - @param retValue - Return value (ignored if there is no return value) - @param noArgs - Number of arguments in args or ptrArgs. - @param args - If non-null, contains an array of variants. - @param ptrArgs - If non-null, contains an array of constant pointers to variants. - - @return @true if the operation was successful, @false otherwise. - - @remarks Two types of argument array are provided, so that when possible - pointers are used for efficiency. - */ - bool Invoke(const wxString& member, int action, - wxVariant& retValue, int noArgs, - wxVariant args[], - const wxVariant* ptrArgs[] = 0) const; - - //@{ - /** - Puts a property value into this object. The first form takes a property name, - number of - arguments, and an array of variants. The second form takes a property name and - zero to six - constant references to variants. Since the variant class has constructors for - the basic - data types, and C++ provides temporary objects automatically, both of the - following lines - are syntactically valid: - - Note that @a property can contain dot-separated property names, to save the - application - needing to call GetProperty several times using several temporary objects. - */ - bool PutProperty(const wxString& property, int noArgs, - wxVariant args[]); - const bool PutProperty(const wxString& property, ... ); - //@} - - /** - Sets the IDispatch pointer. This function does not check if there is already an - IDispatch pointer. - You may need to cast from IDispatch* to WXIDISPATCH* when calling this function. - */ - void SetDispatchPtr(WXIDISPATCH* dispatchPtr); -}; - diff --git a/interface/msw/registry.h b/interface/msw/registry.h deleted file mode 100644 index 6937ac4b45..0000000000 --- a/interface/msw/registry.h +++ /dev/null @@ -1,239 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: msw/registry.h -// Purpose: interface of wxRegKey -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxRegKey - @wxheader{msw/registry.h} - - wxRegKey is a class representing the Windows registry (it is only available - under Windows). One can create, query and delete registry keys using this - class. - - The Windows registry is easy to understand. There are five registry keys, - namely: - - @li @c HKEY_CLASSES_ROOT (HKCR) - @li @c HKEY_CURRENT_USER (HKCU) - @li @c HKEY_LOCAL_MACHINE (HKLM) - @li @c HKEY_CURRENT_CONFIG (HKCC) - @li @c HKEY_USERS (HKU) - - After creating a key, it can hold a value. The values can be: - - @li String Value - @li Binary Value - @li DWORD Value - @li Multi String Value - @li Expandable String Value - - @onlyfor{wxmsw} - - @library{wxbase} - @category{misc} - - @b Example: - - @code - wxRegKey *key = new wxRegKey("HKEY_LOCAL_MACHINE\\Software\\MyKey"); - - // Create the key if it does not exist. - if( !key->Exists() ) - key->Create(); - - // Create a new value "MYVALUE" and set it to 12. - key->SetValue("MYVALUE", 12); - - // Read the value back. - long value; - key->QueryValue("MYVALUE", &value); - wxMessageBox(wxString::Format("%d", value), "Registry Value", wxOK); - - // Get the number of subkeys and enumerate them. - size_t subkeys; - key->GetKeyInfo(&subkeys, NULL, NULL, NULL); - - wxString key_name; - key->GetFirstKey(key_name, 1); - for(int i = 0; i < subkeys; i++) - { - wxMessageBox(key_name, "Subkey Name", wxOK); - key->GetNextKey(key_name, 1); - } - @endcode -*/ -class wxRegKey -{ -public: - /** - Default constructor, initializes to @c HKEY_CLASSES_ROOT. - */ - wxRegKey(); - /** - The constructor to set the full name of the key. - */ - wxRegKey(const wxString& strKey); - /** - The constructor to set the full name of the key under a previously created - parent. - */ - wxRegKey(const wxRegKey& keyParent, const wxString& strKey); - - /** - Access modes for wxRegKey. - */ - enum AccessMode - { - Read, ///< Read-only - Write ///< Read and Write - }; - - /** - Closes the key. - */ - void Close(); - - /** - Creates the key. Will fail if the key already exists and @a bOkIfExists is - @false. - */ - bool Create(bool bOkIfExists = true); - - /** - Deletes the subkey with all of its subkeys/values recursively. - */ - void DeleteKey(const wxChar* szKey); - - /** - Deletes this key and all of its subkeys and values recursively. - */ - void DeleteSelf(); - - /** - Deletes the named value. - */ - void DeleteValue(const wxChar* szKey); - - /** - Returns @true if the key exists. - */ - bool Exists() const; - - /** - Gets the first key. - */ - bool GetFirstKey(wxString& strKeyName, long& lIndex); - - /** - Gets the first value of this key. - */ - bool GetFirstValue(wxString& strValueName, long& lIndex); - - /** - Gets information about the key. - - @param pnSubKeys - The number of subkeys. - @param pnMaxKeyLen - The maximum length of the subkey name. - @param pnValues - The number of values. - @param pnMaxValueLen - The maximum length of a value. - */ - bool GetKeyInfo(size_t* pnSubKeys, size_t* pnMaxKeyLen, - size_t* pnValues, size_t* pnMaxValueLen) const; - - /** - Gets the name of the registry key. - */ - wxString GetName(bool bShortPrefix = true) const; - - /** - Gets the next key. - */ - bool GetNextKey(wxString& strKeyName, long& lIndex) const; - - /** - Gets the next key value for this key. - */ - bool GetNextValue(wxString& strValueName, long& lIndex) const; - - /** - Returns @true if given subkey exists. - */ - bool HasSubKey(const wxChar* szKey) const; - - /** - Returns @true if any subkeys exist. - */ - bool HasSubKeys() const; - - /** - Returns @true if the value exists. - */ - bool HasValue(const wxChar* szValue) const; - - /** - Returns @true if any values exist. - */ - bool HasValues() const; - - /** - Returns @true if this key is empty, nothing under this key. - */ - bool IsEmpty() const; - - /** - Returns @true if the key is opened. - */ - bool IsOpened() const; - - /** - Explicitly opens the key. This method also allows the key to be opened in - read-only mode by passing wxRegKey::Read instead of default - wxRegKey::Write parameter. - */ - bool Open(AccessMode mode = Write); - - /** - Retrieves the string value. - */ - bool QueryValue(const wxChar* szValue, wxString& strValue) const; - - /** - Retrieves the numeric value. - */ - const bool QueryValue(const wxChar* szValue, long* plValue) const; - - /** - Renames the key. - */ - bool Rename(const wxChar* szNewName); - - /** - Renames a value. - */ - bool RenameValue(const wxChar* szValueOld, - const wxChar* szValueNew); - - /** - Sets the given @a szValue which must be numeric. - If the value doesn't exist, it is created. - */ - bool SetValue(const wxChar* szValue, long lValue); - /** - Sets the given @a szValue which must be string. - If the value doesn't exist, it is created. - */ - bool SetValue(const wxChar* szValue, const wxString& strValue); - /** - Sets the given @a szValue which must be binary. - If the value doesn't exist, it is created. - */ - bool SetValue(const wxChar* szValue, const wxMemoryBuffer& buf); -}; diff --git a/interface/notebook.h b/interface/notebook.h deleted file mode 100644 index 807e42c1db..0000000000 --- a/interface/notebook.h +++ /dev/null @@ -1,425 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: notebook.h -// Purpose: interface of wxNotebookEvent -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxNotebookEvent - @wxheader{notebook.h} - - This class represents the events generated by a notebook control: currently, - there are two of them. The PAGE_CHANGING event is sent before the current - page is changed. It allows the program to examine the current page (which - can be retrieved with - wxNotebookEvent::GetOldSelection) and to veto the page - change by calling wxNotifyEvent::Veto if, for example, the - current values in the controls of the old page are invalid. - - The second event - PAGE_CHANGED - is sent after the page has been changed and - the program cannot veto it any more, it just informs it about the page change. - - To summarize, if the program is interested in validating the page values - before allowing the user to change it, it should process the PAGE_CHANGING - event, otherwise PAGE_CHANGED is probably enough. In any case, it is probably - unnecessary to process both events at once. - - @library{wxcore} - @category{events} - - @see wxNotebook -*/ -class wxNotebookEvent : public wxNotifyEvent -{ -public: - /** - Constructor (used internally by wxWidgets only). - */ - wxNotebookEvent(wxEventType eventType = wxEVT_NULL, int id = 0, - int sel = -1, - int oldSel = -1); - - /** - Returns the page that was selected before the change, -1 if none was selected. - */ - int GetOldSelection() const; - - /** - Returns the currently selected page, or -1 if none was selected. - @note under Windows, GetSelection() will return the same value as - GetOldSelection() when called from - @c EVT_NOTEBOOK_PAGE_CHANGING handler and not the page which is going to - be selected. Also note that the values of selection and old selection returned - for an event generated in response to a call to - wxNotebook::SetSelection shouldn't be trusted - as they are currently inconsistent under different platforms (but in this case - you presumably don't need them anyhow as you already have the corresponding - information). - */ - int GetSelection() const; - - /** - Sets the id of the page selected before the change. - */ - void SetOldSelection(int page); - - /** - Sets the selection member variable. - */ - void SetSelection(int page); -}; - - - -/** - @class wxNotebook - @wxheader{notebook.h} - - This class represents a notebook control, which manages multiple windows with - associated tabs. - - To use the class, create a wxNotebook object and call wxNotebook::AddPage or - wxNotebook::InsertPage, - passing a window to be used as the page. Do not explicitly delete the window - for a page that is currently - managed by wxNotebook. - - @b wxNotebookPage is a typedef for wxWindow. - - @beginStyleTable - @style{wxNB_TOP} - Place tabs on the top side. - @style{wxNB_LEFT} - Place tabs on the left side. - @style{wxNB_RIGHT} - Place tabs on the right side. - @style{wxNB_BOTTOM} - Place tabs under instead of above the notebook pages. - @style{wxNB_FIXEDWIDTH} - (Windows only) All tabs will have same width. - @style{wxNB_MULTILINE} - (Windows only) There can be several rows of tabs. - @style{wxNB_NOPAGETHEME} - (Windows only) Display a solid colour on notebook pages, and not a - gradient, which can reduce performance. - @style{wxNB_FLAT} - (Windows CE only) Show tabs in a flat style. - @endStyleTable - - @library{wxcore} - @category{miscwnd} - - @see wxBookCtrl(), wxNotebookEvent, wxImageList, @ref overview_samplenotebook - "notebook sample" -*/ -class wxNotebook : public wxBookCtrl overview -{ -public: - //@{ - /** - Constructs a notebook control. - Note that sometimes you can reduce flicker by passing the wxCLIP_CHILDREN - window style. - - @param parent - The parent window. Must be non-@NULL. - @param id - The window identifier. - @param pos - The window position. - @param size - The window size. - @param style - The window style. See wxNotebook. - @param name - The name of the control (used only under Motif). - */ - wxNotebook(); - wxNotebook(wxWindow* parent, wxWindowID id, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = 0, - const wxString& name = wxNotebookNameStr); - //@} - - /** - Destroys the wxNotebook object. - */ - virtual ~wxNotebook(); - - /** - Adds a new page. - The call to this function may generate the page changing events. - - @param page - Specifies the new page. - @param text - Specifies the text for the new page. - @param select - Specifies whether the page should be selected. - @param imageId - Specifies the optional image index for the new page. - - @return @true if successful, @false otherwise. - - @remarks Do not delete the page, it will be deleted by the notebook. - - @see InsertPage() - */ - bool AddPage(wxNotebookPage* page, const wxString& text, - bool select = false, - int imageId = -1); - - /** - Cycles through the tabs. - The call to this function generates the page changing events. - */ - void AdvanceSelection(bool forward = true); - - /** - Sets the image list for the page control and takes ownership of - the list. - - @see wxImageList, SetImageList() - */ - void AssignImageList(wxImageList* imageList); - - /** - Changes the selection for the given page, returning the previous selection. - The call to this function does not generate the page changing events. - This is the only difference with SetSelection(). - See @ref overview_progevent "this topic" for more info. - */ - virtual int ChangeSelection(size_t page); - - /** - Creates a notebook control. See wxNotebook() for a description - of the parameters. - */ - bool Create(wxWindow* parent, wxWindowID id, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = 0, - const wxString& name = wxNotebookNameStr); - - /** - Deletes all pages. - */ - virtual bool DeleteAllPages(); - - /** - Deletes the specified page, and the associated window. - The call to this function generates the page changing events. - */ - bool DeletePage(size_t page); - - /** - Returns the currently selected notebook page or @NULL. - */ - wxWindow* GetCurrentPage() const; - - /** - Returns the associated image list. - - @see wxImageList, SetImageList() - */ - wxImageList* GetImageList() const; - - /** - Returns the window at the given page position. - */ - wxNotebookPage* GetPage(size_t page); - - /** - Returns the number of pages in the notebook control. - */ - size_t GetPageCount() const; - - /** - Returns the image index for the given page. - */ - virtual int GetPageImage(size_t nPage) const; - - /** - Returns the string for the given page. - */ - virtual wxString GetPageText(size_t nPage) const; - - /** - Returns the number of rows in the notebook control. - */ - virtual int GetRowCount() const; - - /** - Returns the currently selected page, or -1 if none was selected. - Note that this method may return either the previously or newly selected page - when called from the @c EVT_NOTEBOOK_PAGE_CHANGED handler depending on - the platform and so - wxNotebookEvent::GetSelection should be - used instead in this case. - */ - virtual int GetSelection() const; - - /** - If running under Windows and themes are enabled for the application, this - function - returns a suitable colour for painting the background of a notebook page, and - can be passed - to @c SetBackgroundColour. Otherwise, an uninitialised colour will be returned. - */ - virtual wxColour GetThemeBackgroundColour() const; - - /** - Returns the index of the tab at the specified position or @c wxNOT_FOUND - if none. If @a flags parameter is non-@NULL, the position of the point - inside the tab is returned as well. - - @param pt - Specifies the point for the hit test. - @param flags - Return value for detailed information. One of the following values: - - - - - - - - wxBK_HITTEST_NOWHERE - - - - - There was no tab under this point. - - - - - - wxBK_HITTEST_ONICON - - - - - The point was over an icon (currently wxMSW only). - - - - - - wxBK_HITTEST_ONLABEL - - - - - The point was over a label (currently wxMSW only). - - - - - - wxBK_HITTEST_ONITEM - - - - - The point was over an item, but not on the label or icon. - - - - - - wxBK_HITTEST_ONPAGE - - - - - The point was over a currently selected page, not over any tab. Note that - this flag is present only if wxNOT_FOUND is returned. - - @return Returns the zero-based tab index or wxNOT_FOUND if there is no - tab is at the specified position. - */ - virtual int HitTest(const wxPoint& pt, long* = NULL) const; - - /** - Inserts a new page at the specified position. - - @param index - Specifies the position for the new page. - @param page - Specifies the new page. - @param text - Specifies the text for the new page. - @param select - Specifies whether the page should be selected. - @param imageId - Specifies the optional image index for the new page. - - @return @true if successful, @false otherwise. - - @remarks Do not delete the page, it will be deleted by the notebook. - - @see AddPage() - */ - bool InsertPage(size_t index, wxNotebookPage* page, - const wxString& text, - bool select = false, - int imageId = -1); - - /** - An event handler function, called when the page selection is changed. - - @see wxNotebookEvent - */ - void OnSelChange(wxNotebookEvent& event); - - /** - Deletes the specified page, without deleting the associated window. - */ - bool RemovePage(size_t page); - - /** - Sets the image list for the page control. It does not take - ownership of the image list, you must delete it yourself. - - @see wxImageList, AssignImageList() - */ - void SetImageList(wxImageList* imageList); - - /** - Sets the amount of space around each page's icon and label, in pixels. - @note The vertical padding cannot be changed in wxGTK. - */ - void SetPadding(const wxSize& padding); - - /** - Sets the image index for the given page. @a image is an index into - the image list which was set with SetImageList(). - */ - virtual bool SetPageImage(size_t page, int image); - - /** - Sets the width and height of the pages. - @note This method is currently not implemented for wxGTK. - */ - virtual void SetPageSize(const wxSize& size); - - /** - Sets the text for the given page. - */ - virtual bool SetPageText(size_t page, const wxString& text); - - /** - Sets the selection for the given page, returning the previous selection. - The call to this function generates the page changing events. - This function is deprecated and should not be used in new code. Please use the - ChangeSelection() function instead. - - @see GetSelection() - */ - virtual int SetSelection(size_t page); -}; - diff --git a/interface/notifmsg.h b/interface/notifmsg.h deleted file mode 100644 index ecc14510e9..0000000000 --- a/interface/notifmsg.h +++ /dev/null @@ -1,89 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: notifmsg.h -// Purpose: interface of wxNotificationMessage -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxNotificationMessage - @wxheader{notifmsg.h} - - This class allows to show the user a message non intrusively. Currently it is - implemented natively only for the Maemo platform and uses (non-modal) dialogs - for the display of the notifications under the other platforms but it will be - extended to use the platform-specific notifications in the other ports in the - future. - - Notice that this class is not a window and so doesn't derive from wxWindow. - - @library{wxbase} - @category{FIXME} -*/ -class wxNotificationMessage : public wxEvtHandler -{ -public: - //@{ - /** - , @b wxWindow*@e parent = @NULL, @b int@e flags = @c wxICON_INFORMATION) - Create a notification object with the given attributes. - See SetTitle(), - SetMessage(), - SetParent() and - SetFlags() for the description of the - corresponding parameters. - */ - wxNotificationMessage(); - wxNotificationMessage(const wxString& title); - //@} - - /** - Hides the notification. - Returns @true if it was hidden or @false if it couldn't be done (e.g. on - some - systems automatically hidden notifications can't be hidden manually) - */ - bool Close(); - - /** - This parameter can be currently used to specify the icon to show in the - notification. Valid values are @c wxICON_INFORMATION, - @c wxICON_WARNING and @c wxICON_ERROR (notice that - @c wxICON_QUESTION is not allowed here). - Some implementations of this class may not support the icons. - */ - void SetFlags(int flags); - - /** - Set the main text of the notification. This should be a more detailed - description than the title but still limited to reasonable length (not more - than 256 characters). - */ - void SetMessage(const wxString& message); - - /** - Set the parent for this notification: the notification will be associated with - the top level parent of this window or, if this method is not called, with the - main application window by default - */ - void SetParent(wxWindow* parent); - - /** - Set the title, it must be a concise string (not more than 64 characters), use - SetMessage() to give the user more - details. - */ - void SetTitle(const wxString& title); - - /** - Show the notification to the user and hides it after timeout seconds - pass. Special values @c Timeout_Auto and @c Timeout_Never can be - used here, notice that you shouldn't rely on @a timeout being exactly - respected because the current platform may only support default timeout value - and also because the user may be able to close the notification. - Returns @false if an error occurred. - */ - bool Show(int timeout = Timeout_Auto); -}; - diff --git a/interface/numdlg.h b/interface/numdlg.h deleted file mode 100644 index 904f67e2e8..0000000000 --- a/interface/numdlg.h +++ /dev/null @@ -1,37 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: numdlg.h -// Purpose: interface of global functions -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** @ingroup group_funcmacro_dialog */ -//@{ - -/** - Shows a dialog asking the user for numeric input. The dialogs title is set - to @c caption, it contains a (possibly) multiline @c message above the - single line @c prompt and the zone for entering the number. - - The number entered must be in the range @c min to @c max (both of which - should be positive) and @c value is the initial value of it. If the user - enters an invalid value or cancels the dialog, the function will return - -1. - - Dialog is centered on its @c parent unless an explicit position is given - in @c pos. - - @header{wx/numdlg.h} -*/ -long wxGetNumberFromUser(const wxString& message, - const wxString& prompt, - const wxString& caption, - long value, - long min = 0, - long max = 100, - wxWindow* parent = NULL, - const wxPoint& pos = wxDefaultPosition); - -//@} - diff --git a/interface/object.h b/interface/object.h deleted file mode 100644 index b6467e9fe6..0000000000 --- a/interface/object.h +++ /dev/null @@ -1,853 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: object.h -// Purpose: interface of wxObjectRefData -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxObjectRefData - @wxheader{object.h} - - This class is used to store reference-counted data. - - Derive classes from this to store your own data. When retrieving information - from a wxObject's reference data, you will need to cast to your own derived class. - - @b Example: - - @code - // include file - - class MyCar: public wxObject - { - public: - MyCar() { } - MyCar( int price ); - - bool IsOk() const { return m_refData != NULL; } - - bool operator == ( const MyCar& car ) const; - bool operator != (const MyCar& car) const { return !(*this == car); } - - void SetPrice( int price ); - int GetPrice() const; - - protected: - virtual wxObjectRefData *CreateRefData() const; - virtual wxObjectRefData *CloneRefData(const wxObjectRefData *data) const; - - DECLARE_DYNAMIC_CLASS(MyCar) - }; - - - // implementation - - class MyCarRefData: public wxObjectRefData - { - public: - MyCarRefData() - { - m_price = 0; - } - - MyCarRefData( const MyCarRefData& data ) - : wxObjectRefData() - { - m_price = data.m_price; - } - - bool operator == (const MyCarRefData& data) const - { - return m_price == data.m_price; - } - - int m_price; - }; - - - #define M_CARDATA ((MyCarRefData *)m_refData) - - IMPLEMENT_DYNAMIC_CLASS(MyCar,wxObject) - - MyCar::MyCar( int price ) - { - m_refData = new MyCarRefData(); - M_CARDATA->m_price = price; - } - - wxObjectRefData *MyCar::CreateRefData() const - { - return new MyCarRefData; - } - - wxObjectRefData *MyCar::CloneRefData(const wxObjectRefData *data) const - { - return new MyCarRefData(*(MyCarRefData *)data); - } - - bool MyCar::operator == ( const MyCar& car ) const - { - if (m_refData == car.m_refData) return true; - - if (!m_refData || !car.m_refData) return false; - - return ( *(MyCarRefData*)m_refData == *(MyCarRefData*)car.m_refData ); - } - - void MyCar::SetPrice( int price ) - { - UnShare(); - - M_CARDATA->m_price = price; - } - - int MyCar::GetPrice() const - { - wxCHECK_MSG( IsOk(), -1, "invalid car" ); - - return (M_CARDATA->m_price); - } - @endcode - - - @library{wxbase} - @category{rtti} - - @see wxObject, wxObjectDataPtr, @ref overview_refcount -*/ -class wxObjectRefData -{ -protected: - /** - Destructor. - - It's declared @c protected so that wxObjectRefData instances - will never be destroyed directly but only as result of a DecRef() call. - */ - ~wxObjectRefData(); - -public: - /** - Default constructor. Initialises the internal reference count to 1. - */ - wxObjectRefData(); - - /** - Decrements the reference count associated with this shared data and, if - it reaches zero, destroys this instance of wxObjectRefData releasing its - memory. - - Please note that after calling this function, the caller should - absolutely avoid to use the pointer to this instance since it may not be - valid anymore. - */ - void DecRef(); - - /** - Returns the reference count associated with this shared data. - - When this goes to zero during a DecRef() call, the object will auto-free itself. - */ - int GetRefCount() const; - - /** - Increments the reference count associated with this shared data. - */ - void IncRef(); -}; - - - -/** - @class wxObject - @wxheader{object.h} - - This is the root class of many of the wxWidgets classes. - - It declares a virtual destructor which ensures that destructors get called - for all derived class objects where necessary. - - wxObject is the hub of a dynamic object creation scheme, enabling a program - to create instances of a class only knowing its string class name, and to - query the class hierarchy. - - The class contains optional debugging versions of @b new and @b delete, which - can help trace memory allocation and deallocation problems. - - wxObject can be used to implement @ref overview_refcount "reference counted" - objects, such as wxPen, wxBitmap and others - (see @ref overview_refcount_list "this list"). - - @library{wxbase} - @category{rtti} - - @see wxClassInfo, @ref overview_debugging, wxObjectRefData -*/ -class wxObject -{ -public: - - wxObject(); - - /** - Copy ctor. - */ - wxObject(const wxObject& other); - - - /** - Destructor. - - Performs dereferencing, for those objects that use reference counting. - */ - wxObject(); - - /** - A virtual function that may be redefined by derived classes to allow dumping of - memory states. - - This function is only defined in debug build and exists only if @c __WXDEBUG__ - is defined. - - @param stream - Stream on which to output dump information. - - @remarks Currently wxWidgets does not define Dump() for derived classes, - but programmers may wish to use it for their own applications. - Be sure to call the Dump member of the class's base class to allow all - information to be dumped. - The implementation of this function in wxObject just writes - the class name of the object. - */ - void Dump(ostream& stream); - - /** - This virtual function is redefined for every class that requires run-time - type information, when using the ::DECLARE_CLASS macro (or similar). - */ - wxClassInfo* GetClassInfo(); - - /** - Returns the wxObject::m_refData pointer, i.e. the data referenced by this object. - - @see Ref(), UnRef(), wxObject::m_refData, SetRefData(), wxObjectRefData - */ - wxObjectRefData* GetRefData() const; - - /** - Determines whether this class is a subclass of (or the same class as) - the given class. - - Example: - - @code - bool tmp = obj->IsKindOf(CLASSINFO(wxFrame)); - @endcode - - @param info - A pointer to a class information object, which may be obtained - by using the ::CLASSINFO macro. - - @return @true if the class represented by info is the same class as this - one or is derived from it. - */ - bool IsKindOf(wxClassInfo* info); - - /** - Returns @true if this object has the same data pointer as @a obj. - - Notice that @true is returned if the data pointers are @NULL in both objects. - - This function only does a @e shallow comparison, i.e. it doesn't compare - the objects pointed to by the data pointers of these objects. - - @see @ref overview_refcount - */ - bool IsSameAs(const wxObject& obj); - - /** - Makes this object refer to the data in @a clone. - - @param clone - The object to 'clone'. - - @remarks First this function calls UnRef() on itself to decrement - (and perhaps free) the data it is currently referring to. - It then sets its own wxObject::m_refData to point to that of @a clone, - and increments the reference count inside the data. - - @see UnRef(), SetRefData(), GetRefData(), wxObjectRefData - */ - void Ref(const wxObject& clone); - - /** - Sets the wxObject::m_refData pointer. - - @see Ref(), UnRef(), GetRefData(), wxObjectRefData - */ - void SetRefData(wxObjectRefData* data); - - /** - Decrements the reference count in the associated data, and if it is zero, - deletes the data. - - The wxObject::m_refData member is set to @NULL. - - @see Ref(), SetRefData(), GetRefData(), wxObjectRefData - */ - void UnRef(); - - /** - Ensure that this object's data is not shared with any other object. - - If we have no data, it is created using CreateRefData() below, - if we have shared data, it is copied using CloneRefData(), - otherwise nothing is done. - */ - void UnShare(); - - /** - The @e delete operator is defined for debugging versions of the library only, - when the identifier @c __WXDEBUG__ is defined. - - It takes over memory deallocation, allowing wxDebugContext operations. - */ - void operator delete(void *buf); - - /** - The @e new operator is defined for debugging versions of the library only, when - the identifier @c __WXDEBUG__ is defined. - - It takes over memory allocation, allowing wxDebugContext operations. - */ - void* operator new(size_t size, const wxString& filename = NULL, int lineNum = 0); - -protected: - - /** - Pointer to an object which is the object's reference-counted data. - - @see Ref(), UnRef(), SetRefData(), GetRefData(), wxObjectRefData - */ - wxObjectRefData* m_refData; -}; - - - -/** - @class wxClassInfo - @wxheader{object.h} - - This class stores meta-information about classes. - - Instances of this class are not generally defined directly by an application, - but indirectly through use of macros such as ::DECLARE_DYNAMIC_CLASS and - ::IMPLEMENT_DYNAMIC_CLASS. - - @library{wxbase} - @category{rtti} - - @see @ref overview_rtti_classinfo, wxObject -*/ -class wxClassInfo -{ -public: - /** - Constructs a wxClassInfo object. - - The supplied macros implicitly construct objects of this class, so there is no - need to create such objects explicitly in an application. - */ - wxClassInfo(const wxChar* className, - const wxClassInfo* baseClass1, - const wxClassInfo* baseClass2, - int size, wxObjectConstructorFn fn); - - /** - Creates an object of the appropriate kind. - - @return @NULL if the class has not been declared dynamically creatable - (typically, this happens for abstract classes). - */ - wxObject* CreateObject() const; - - /** - Finds the wxClassInfo object for a class with the given @a name. - */ - static wxClassInfo* FindClass(wxChar* name); - - /** - Returns the name of the first base class (@NULL if none). - */ - wxChar* GetBaseClassName1() const; - - /** - Returns the name of the second base class (@NULL if none). - */ - wxChar* GetBaseClassName2() const; - - /** - Returns the string form of the class name. - */ - wxChar* GetClassName() const; - - /** - Returns the size of the class. - */ - int GetSize() const; - - /** - Initializes pointers in the wxClassInfo objects for fast execution of IsKindOf(). - Called in base wxWidgets library initialization. - */ - static void InitializeClasses(); - - /** - Returns @true if this class info can create objects of the associated class. - */ - bool IsDynamic() const; - - /** - Returns @true if this class is a kind of (inherits from) the given class. - */ - bool IsKindOf(wxClassInfo* info); -}; - - - -/** - @wxheader{object.h} - - This is helper template class primarily written to avoid memory leaks because of - missing calls to wxObjectRefData::DecRef(). - - Despite the name this template can actually be used as a smart pointer for any - class implementing the reference counting interface which only consists of the two - methods @b T::IncRef() and @b T::DecRef(). - - The difference to wxSharedPtr is that wxObjectDataPtr relies on the reference - counting to be in the class pointed to where instead wxSharedPtr implements the - reference counting itself. - - - @b Example: - - @code - class MyCarRefData: public wxObjectRefData - { - public: - MyCarRefData() { m_price = 0; } - - MyCarRefData( const MyCarRefData& data ) - : wxObjectRefData() - { - m_price = data.m_price; - } - - void SetPrice( int price ) { m_price = price; } - int GetPrice() { return m_price; } - - protected: - int m_price; - }; - - class MyCar - { - public: - MyCar( int price ) : m_data( new MyCarRefData ) - { - m_data->SetPrice( price ); - } - - MyCar& operator =( const MyCar& tocopy ) - { - m_data = tocopy.m_data; - return *this; - } - - bool operator == ( const MyCar& other ) const - { - if (m_data.get() == other.m_data.get()) return true; - return (m_data->GetPrice() == other.m_data->GetPrice()); - } - - void SetPrice( int price ) - { - UnShare(); - m_data->SetPrice( price ); - } - - int GetPrice() const - { - return m_data->GetPrice(); - } - - wxObjectDataPtr m_data; - - protected: - void UnShare() - { - if (m_data->GetRefCount() == 1) - return; - - m_data.reset( new MyCarRefData( *m_data ) ); - } - }; - @endcode - - - @library{wxbase} - @category{rtti,smartpointers} - - @see wxObject, wxObjectRefData, @ref overview_refcount, wxSharedPtr, - wxScopedPtr, wxWeakRef -*/ -class wxObjectDataPtr -{ -public: - /** - Constructor. - - @a ptr is a pointer to the reference counted object to which this class points. - If @a ptr is not NULL @b T::IncRef() will be called on the object. - */ - wxObjectDataPtr(T* ptr = NULL); - - /** - This copy constructor increases the count of the reference counted object to - which @a tocopy points and then this class will point to, as well. - */ - wxObjectDataPtr(const wxObjectDataPtr& tocopy); - - - /** - Decreases the reference count of the object to which this class points. - */ - ~wxObjectDataPtr(); - - /** - Gets a pointer to the reference counted object to which this class points. - */ - T* get() const; - - /** - Reset this class to ptr which points to a reference counted object and - calls T::DecRef() on the previously owned object. - */ - void reset(T *ptr); - - /** - Conversion to a boolean expression (in a variant which is not - convertable to anything but a boolean expression). - - If this class contains a valid pointer it will return @true, if it contains - a @NULL pointer it will return @false. - */ - operator unspecified_bool_type() const; - - /** - Returns a reference to the object. - - If the internal pointer is @NULL this method will cause an assert in debug mode. - */ - T& operator*() const; - - /** - Returns a pointer to the reference counted object to which this class points. - - If this the internal pointer is @NULL, this method will assert in debug mode. - */ - T* operator->() const; - - //@{ - /** - Assignment operator. - */ - wxObjectDataPtr& operator=(const wxObjectDataPtr& tocopy); - wxObjectDataPtr& operator=(T* ptr); - //@} -}; - - - -// ============================================================================ -// Global functions/macros -// ============================================================================ - -/** @ingroup group_funcmacro_rtti */ -//@{ - -/** - Returns a pointer to the wxClassInfo object associated with this class. - - @header{wx/object.h} -*/ -#define CLASSINFO( className ) - -/** - Used inside a class declaration to declare that the class should be made - known to the class hierarchy, but objects of this class cannot be created - dynamically. The same as DECLARE_ABSTRACT_CLASS(). - - @header{wx/object.h} -*/ -#define DECLARE_CLASS( className ) - -/** - Used inside a class declaration to declare that the class should be - made known to the class hierarchy, but objects of this class cannot be created - dynamically. The same as DECLARE_CLASS(). - - @header{wx/object.h} - - Example: - - @code - class wxCommand: public wxObject - { - DECLARE_ABSTRACT_CLASS(wxCommand) - - private: - ... - public: - ... - }; - @endcode -*/ -#define DECLARE_ABSTRACT_CLASS( className ) - -/** - Used inside a class declaration to make the class known to wxWidgets RTTI - system and also declare that the objects of this class should be - dynamically creatable from run-time type information. Notice that this - implies that the class should have a default constructor, if this is not - the case consider using DECLARE_CLASS(). - - @header{wx/object.h} - - Example: - - @code - class wxFrame: public wxWindow - { - DECLARE_DYNAMIC_CLASS(wxFrame) - - private: - const wxString& frameTitle; - public: - ... - }; - @endcode -*/ -#define DECLARE_DYNAMIC_CLASS( className ) - -/** - Used in a C++ implementation file to complete the declaration of a class - that has run-time type information. The same as IMPLEMENT_ABSTRACT_CLASS(). - - @header{wx/object.h} -*/ -#define IMPLEMENT_CLASS( className, baseClassName ) - -/** - Used in a C++ implementation file to complete the declaration of a class - that has run-time type information and two base classes. The same as - IMPLEMENT_ABSTRACT_CLASS2(). - - @header{wx/object.h} -*/ -#define IMPLEMENT_CLASS2( className, baseClassName1, baseClassName2 ) - -/** - Used in a C++ implementation file to complete the declaration of a class - that has run-time type information. The same as IMPLEMENT_CLASS(). - - @header{wx/object.h} - - Example: - - @code - IMPLEMENT_ABSTRACT_CLASS(wxCommand, wxObject) - - wxCommand::wxCommand(void) - { - ... - } - @endcode -*/ -#define IMPLEMENT_ABSTRACT_CLASS( className, baseClassName ) - -/** - Used in a C++ implementation file to complete the declaration of a class - that has run-time type information and two base classes. The same as - IMPLEMENT_CLASS2(). - - @header{wx/object.h} -*/ -#define IMPLEMENT_ABSTRACT_CLASS2( className, baseClassName1, baseClassName2 ) - -/** - Used in a C++ implementation file to complete the declaration of a class - that has run-time type information, and whose instances can be created - dynamically. - - @header{wx/object.h} - - Example: - - @code - IMPLEMENT_DYNAMIC_CLASS(wxFrame, wxWindow) - - wxFrame::wxFrame(void) - { - ... - } - @endcode -*/ -#define IMPLEMENT_DYNAMIC_CLASS( className, baseClassName ) - -/** - Used in a C++ implementation file to complete the declaration of a class - that has run-time type information, and whose instances can be created - dynamically. Use this for classes derived from two base classes. - - @header{wx/object.h} -*/ -#define IMPLEMENT_DYNAMIC_CLASS2( className, baseClassName1, baseClassName2 ) - -/** - Same as @c const_cast(x) if the compiler supports const cast or @c (T)x for - old compilers. Unlike wxConstCast(), the cast it to the type @c T and not to - T * and also the order of arguments is the same as for the standard cast. - - @header{wx/defs.h} - - @see wx_reinterpret_cast(), wx_static_cast() -*/ -#define wx_const_cast(T, x) - -/** - Same as @c reinterpret_cast(x) if the compiler supports reinterpret cast or - @c (T)x for old compilers. - - @header{wx/defs.h} - - @see wx_const_cast(), wx_static_cast() -*/ -#define wx_reinterpret_cast(T, x) - -/** - Same as @c static_cast(x) if the compiler supports static cast or @c (T)x for - old compilers. Unlike wxStaticCast(), there are no checks being done and - the meaning of the macro arguments is exactly the same as for the standard - static cast, i.e. @a T is the full type name and star is not appended to it. - - @header{wx/defs.h} - - @see wx_const_cast(), wx_reinterpret_cast(), wx_truncate_cast() -*/ -#define wx_static_cast(T, x) - -/** - This case doesn’t correspond to any standard cast but exists solely to make - casts which possibly result in a truncation of an integer value more - readable. - - @header{wx/defs.h} -*/ -#define wx_truncate_cast(T, x) - -/** - This macro expands into const_cast(ptr) if the compiler - supports const_cast or into an old, C-style cast, otherwise. - - @header{wx/defs.h} - - @see wx_const_cast(), wxDynamicCast(), wxStaticCast() -*/ -#define wxConstCast( ptr, classname ) - -/** - This macro returns the pointer @e ptr cast to the type @e classname * if - the pointer is of this type (the check is done during the run-time) or - @NULL otherwise. Usage of this macro is preferred over obsoleted - wxObject::IsKindOf() function. - - The @e ptr argument may be @NULL, in which case @NULL will be returned. - - @header{wx/object.h} - - Example: - - @code - wxWindow *win = wxWindow::FindFocus(); - wxTextCtrl *text = wxDynamicCast(win, wxTextCtrl); - if ( text ) - { - // a text control has the focus... - } - else - { - // no window has the focus or it is not a text control - } - @endcode - - @see @ref overview_rtti, wxDynamicCastThis(), wxConstCast(), wxStaticCast() -*/ -#define wxDynamicCast( ptr, classname ) - -/** - This macro is equivalent to wxDynamicCast(this, classname) but the latter provokes - spurious compilation warnings from some compilers (because it tests whether - @c this pointer is non-@NULL which is always true), so this macro should be - used to avoid them. - - @header{wx/object.h} - - @see wxDynamicCast() -*/ -#define wxDynamicCastThis( classname ) - -/** - This macro checks that the cast is valid in debug mode (an assert failure - will result if wxDynamicCast(ptr, classname) == @NULL) and then returns the - result of executing an equivalent of static_cast(ptr). - - @header{wx/object.h} - - @see wx_static_cast(), wxDynamicCast(), wxConstCast() -*/ -#define wxStaticCast( ptr, classname ) - -/** - Creates and returns an object of the given class, if the class has been - registered with the dynamic class system using DECLARE... and IMPLEMENT... - macros. - - @header{wx/object.h} -*/ -wxObject *wxCreateDynamicObject(const wxString& className); - -//@} - -/** @ingroup group_funcmacro_debug */ -//@{ - -/** - This is defined in debug mode to be call the redefined new operator - with filename and line number arguments. The definition is: - - @code - #define WXDEBUG_NEW new(__FILE__,__LINE__) - @endcode - - In non-debug mode, this is defined as the normal new operator. - - @header{wx/object.h} -*/ -#define WXDEBUG_NEW( arg ) - -//@} - diff --git a/interface/odcombo.h b/interface/odcombo.h deleted file mode 100644 index a47cd424e8..0000000000 --- a/interface/odcombo.h +++ /dev/null @@ -1,209 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: odcombo.h -// Purpose: interface of wxOwnerDrawnComboBox -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - - -enum wxOwnerDrawnComboBoxPaintingFlags -{ - /** - Combo control is being painted, instead of a list item. - Argument item may be @c wxNOT_FOUND in this case. - */ - wxODCB_PAINTING_CONTROL = 0x0001, - - /** - An item with selection background is being painted. - DC text colour should already be correct. - */ - wxODCB_PAINTING_SELECTED = 0x0002 -}; - -/** - @class wxOwnerDrawnComboBox - @wxheader{odcombo.h} - - wxOwnerDrawnComboBox is a combobox with owner-drawn list items. - 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 - OnDrawItem(), OnMeasureItem() and OnMeasureItemWidth(). - - @beginStyleTable - @style{wxODCB_DCLICK_CYCLES} - Double-clicking cycles item if wxCB_READONLY is also used. - Synonymous with wxCC_SPECIAL_DCLICK. - @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. - @endStyleTable - - @see wxComboCtrl window styles and @ref overview_windowstyles. - - @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 - value of selection. - @endEventTable - - @see Events emitted by wxComboCtrl. - - @library{wxadv} - @category{ctrl} - - - @see wxComboCtrl, wxComboBox, wxVListBox, wxCommandEvent -*/ -class wxOwnerDrawnComboBox : public wxComboCtrl -{ -public: - /** - Default constructor. - */ - wxOwnerDrawnComboBox(); - - //@{ - /** - Constructor, creating and showing a owner-drawn combobox. - - @param parent - Parent window. Must not be @NULL. - @param id - 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 sized appropriately. - @param n - Number of strings with which to initialise the control. - @param choices - An array of strings with which to initialise the control. - @param style - Window style. See wxOwnerDrawnComboBox. - @param validator - Window validator. - @param name - Window name. - - @see Create(), wxValidator - */ - wxOwnerDrawnComboBox(wxWindow* parent, wxWindowID id, - const wxString& value = "", - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - int n = 0, - const wxString[] choices = NULL, - long style = 0, - const wxValidator& validator = wxDefaultValidator, - const wxString& name = "comboBox"); - wxOwnerDrawnComboBox(wxWindow* parent, wxWindowID id, - const wxString& value, - const wxPoint& pos, - const wxSize& size, - const wxArrayString& choices, - long style = 0, - const wxValidator& validator = wxDefaultValidator, - const wxString& name = "comboBox"); - //@} - - /** - Destructor, destroying the owner-drawn combobox. - */ - ~wxOwnerDrawnComboBox(); - - //@{ - /** - 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 = "", - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - int n, const wxString choices[], - long style = 0, - const wxValidator& validator = wxDefaultValidator, - const wxString& name = "comboBox"); - bool Create(wxWindow* parent, wxWindowID id, - const wxString& value, - const wxPoint& pos, - const wxSize& size, - const wxArrayString& choices, - long style = 0, - const wxValidator& validator = wxDefaultValidator, - const wxString& name = "comboBox"); - //@} - - /** - Returns index to the widest item in the list. - */ - int GetWidestItem() const; - - /** - Returns width of the widest item in the list. - */ - int GetWidestItemWidth() const; - - /** - 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(). - */ - 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. - - @param dc - The device context to use for drawing - @param rect - The bounding rectangle for the item being drawn (DC clipping - region is set to this rectangle before calling this function) - @param item - The index of the item to be drawn - @param flags - A combination of the ::wxOwnerDrawnComboBoxPaintingFlags enumeration values. - */ - void OnDrawItem(wxDC& dc, const wxRect& rect, int item, - int flags) const; - - /** - 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. - */ - wxCoord OnMeasureItem(size_t item) const; - - /** - 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 deleted file mode 100644 index f1a9a4bdc0..0000000000 --- a/interface/palette.h +++ /dev/null @@ -1,156 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: palette.h -// Purpose: interface of wxPalette -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxPalette - @wxheader{palette.h} - - A palette is a table that maps pixel values to RGB colours. It allows the - colours of a low-depth bitmap, for example, to be mapped to the available - colours in a display. The notion of palettes is becoming more and more - obsolete nowadays and only the MSW port is still using a native palette. - All other ports use generic code which is basically just an array of - colours. - - It is likely that in the future the only use for palettes within wxWidgets - will be for representing colour indeces from images (such as GIF or PNG). - The image handlers for these formats have been modified to create a palette - if there is such information in the original image file (usually 256 or less - colour images). See wxImage for more information. - - @library{wxcore} - @category{gdi} - - @stdobjects - ::wxNullPalette - - @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 @a n, one for each red, blue or - green component. - - @param palette - A pointer or reference to the palette to copy. - @param n - The number of indices in the palette. - @param red - An array of red values. - @param green - An array of green values. - @param blue - An array of blue values. - - @see Create() - */ - wxPalette(int n, const unsigned char* red, - const unsigned char* green, - const unsigned char* blue); - - /** - Destructor. - - @see @ref overview_refcount_destruct "reference-counted object destruction" - */ - ~wxPalette(); - - /** - Creates a palette from arrays of size @a n, one for each red, blue or - green component. - - @param n - The number of indices in the palette. - @param red - An array of red values. - @param green - An array of green values. - @param blue - An array of blue values. - - @return @true if the creation was successful, @false otherwise. - - @see wxPalette() - */ - bool Create(int n, const unsigned char* red, - const unsigned char* green, - const unsigned char* blue); - - /** - Returns number of entries in palette. - */ - int GetColoursCount() const; - - /** - Returns a pixel value (index into the palette) for the given RGB values. - - @param red - Red value. - @param green - Green value. - @param blue - Blue value. - - @return The nearest palette index or @c wxNOT_FOUND for unexpected errors. - - @see GetRGB() - */ - int GetPixel(unsigned char red, unsigned char green, - unsigned char blue) const; - - /** - Returns RGB values for a given palette index. - - @param pixel - The palette index. - @param red - Receives the red value. - @param green - Receives the green value. - @param blue - Receives the blue value. - - @return @true if the operation was successful. - - @see GetPixel() - */ - bool GetRGB(int pixel, const unsigned char* red, - const unsigned char* green, - const unsigned char* blue) const; - - /** - Returns @true if palette data is present. - */ - bool IsOk() const; - - /** - Assignment operator, using @ref overview_refcount. - */ - wxPalette& operator =(const wxPalette& palette); -}; - - -/** - An empty palette. -*/ -wxPalette wxNullPalette; - - diff --git a/interface/panel.h b/interface/panel.h deleted file mode 100644 index 6e6e8b3d68..0000000000 --- a/interface/panel.h +++ /dev/null @@ -1,136 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: panel.h -// Purpose: interface of wxPanel -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxPanel - @wxheader{panel.h} - - A panel is a window on which controls are placed. It is usually placed within - a frame. Its main feature over its parent class wxWindow is code for handling - child windows and TAB traversal. Since wxWidgets 2.9, there is support both - for TAB traversal implemented by wxWidgets itself as well as native TAB - traversal (such as for GTK 2.0). - - @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 @c wx/containr.h - and @c wx/panel.h to find out how this is achieved. - - @note if not all characters are being intercepted by your OnKeyDown or - OnChar handler, it may be because you are using the @c wxTAB_TRAVERSAL style, - which grabs some keypresses for use by child controls. - - @remarks By default, a panel has the same colouring as a dialog. - - @library{wxbase} - @category{miscwnd} - - @see wxDialog -*/ -class wxPanel : public wxWindow -{ -public: - - /** - Default constructor. - */ - wxPanel(); - - /** - Constructor. - - @param parent - The parent window. - @param id - An identifier for the panel. @c wxID_ANY is taken to mean a default. - @param pos - 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 @c wxDefaultSize indicates a default size, chosen by - either the windowing system or wxWidgets, depending on platform. - @param style - The window style. See wxPanel. - @param name - Window name. - - @see Create() - */ - 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. - */ - ~wxPanel(); - - /** - 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. - */ - bool AcceptsFocus() const; - - /** - Used for two-step panel construction. See wxPanel() for details. - */ - bool Create(wxWindow* parent, wxWindowID id = wxID_ANY, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = wxTAB_TRAVERSAL, - const wxString& name = "panel"); - - /** - Sends a wxInitDialogEvent, which in turn transfers data to the dialog via - validators. - - @see wxInitDialogEvent - */ - void InitDialog(); - - /** - The default handler for wxEVT_SYS_COLOUR_CHANGED. - - @param event - The colour change event. - - @remarks Changes the panel's colour to conform to the current settings - (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 - the notification to child windows and controls. - - @see wxSysColourChangedEvent - */ - void OnSysColourChanged(wxSysColourChangedEvent& event); - - /** - 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() - */ - virtual void SetFocus(); - - /** - In contrast to SetFocus() (see above) this will set the focus to the panel - even if there are child windows in the panel. This is only rarely needed. - */ - virtual void SetFocusIgnoringChildren(); -}; - diff --git a/interface/pen.h b/interface/pen.h deleted file mode 100644 index 02368092d5..0000000000 --- a/interface/pen.h +++ /dev/null @@ -1,479 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: pen.h -// Purpose: interface of wxPen* classes -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - The possible styles for a wxPen. -*/ -enum wxPenStyle -{ - wxPENSTYLE_INVALID = -1, - - wxPENSTYLE_SOLID, - /**< Solid style. */ - - wxPENSTYLE_DOT, - /**< Dotted style. */ - - wxPENSTYLE_LONG_DASH, - /**< Long dashed style. */ - - wxPENSTYLE_SHORT_DASH, - /**< Short dashed style. */ - - wxPENSTYLE_DOT_DASH, - /**< Dot and dash style. */ - - wxPENSTYLE_USER_DASH, - /**< Use the user dashes: see wxPen::SetDashes. */ - - wxPENSTYLE_TRANSPARENT, - /**< No pen is used. */ - - wxPENSTYLE_STIPPLE_MASK_OPAQUE, - /**< @todo WHAT's this? */ - - wxPENSTYLE_STIPPLE_MASK, - /**< @todo WHAT's this? */ - - wxPENSTYLE_STIPPLE, - /**< Use the stipple bitmap. */ - - wxPENSTYLE_BDIAGONAL_HATCH, - /**< Backward diagonal hatch. */ - - wxPENSTYLE_CROSSDIAG_HATCH, - /**< Cross-diagonal hatch. */ - - wxPENSTYLE_FDIAGONAL_HATCH, - /**< Forward diagonal hatch. */ - - wxPENSTYLE_CROSS_HATCH, - /**< Cross hatch. */ - - wxPENSTYLE_HORIZONTAL_HATCH, - /**< Horizontal hatch. */ - - wxPENSTYLE_VERTICAL_HATCH, - /**< Vertical hatch. */ - - wxPENSTYLE_FIRST_HATCH = wxPENSTYLE_BDIAGONAL_HATCH, - wxPENSTYLE_LAST_HATCH = wxPENSTYLE_VERTICAL_HATCH -}; - -/** - The possible join values of a wxPen. - - @todo use wxPENJOIN_ prefix -*/ -enum wxPenJoin -{ - wxJOIN_INVALID = -1, - - wxJOIN_BEVEL = 120, - wxJOIN_MITER, - wxJOIN_ROUND, -}; - - -/** - The possible cap values of a wxPen. - - @todo use wxPENCAP_ prefix -*/ -enum wxPenCap -{ - wxCAP_INVALID = -1, - - wxCAP_ROUND = 130, - wxCAP_PROJECTING, - wxCAP_BUTT -}; - - - -/** - @class wxPen - @wxheader{pen.h} - - A pen is a drawing tool for drawing outlines. It is used for drawing - lines and painting the outline of rectangles, ellipses, etc. - It has a colour, a width and a style. - - @note 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() - 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 - wxPenList::FindOrCreatePen(). - See wxPenList for more info. - - 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 - counting, are not affected. - - @library{wxcore} - @category{gdi} - - @stdobjects - @li ::wxNullPen - @li ::wxRED_PEN - @li ::wxCYAN_PEN - @li ::wxGREEN_PEN - @li ::wxBLACK_PEN - @li ::wxWHITE_PEN - @li ::wxTRANSPARENT_PEN - @li ::wxBLACK_DASHED_PEN - @li ::wxGREY_PEN - @li ::wxMEDIUM_GREY_PEN - @li ::wxLIGHT_GREY_PEN - - @see wxPenList, wxDC, wxDC::SetPen() -*/ -class wxPen : public wxGDIObject -{ -public: - /** - Default constructor. The pen will be uninitialised, and IsOk() will return @false. - */ - wxPen(); - - /** - Constructs a pen from a colour object, pen width and style. - - @param colour - A colour object. - @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 style - The style may be one of the ::wxPenStyle values. - - @remarks Different versions of Windows and different versions of other - platforms support very different subsets of the styles - above - there is no similarity even between Windows95 - and Windows98 - so handle with care. - - @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_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 - itself. This is because wxWidgets cannot know if a - pointer to the pen object is stored in an application - data structure, and there is a risk of double deletion. - */ - ~wxPen(); - - /** - 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() - */ - virtual wxPenCap GetCap() const; - - /** - Returns a reference to the pen colour. - - @see SetColour() - */ - virtual wxColour GetColour() const; - - /** - 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. - - @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 @c wxJOIN_BEVEL, @c - wxJOIN_ROUND and @c wxJOIN_MITER. - - The default is @c wxJOIN_ROUND. - - @see SetJoin() - */ - virtual wxPenJoin GetJoin() const; - - /** - Gets a pointer to the stipple bitmap. - - @see SetStipple() - */ - virtual wxBitmap* GetStipple() const; - - /** - Returns the pen style. - - @see wxPen(), SetStyle() - */ - virtual wxPenStyle GetStyle() const; - - /** - Returns the pen width. - - @see SetWidth() - */ - virtual int GetWidth() const; - - /** - Returns @true if the pen is initialised. - */ - bool IsOk() const; - - /** - 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() - */ - virtual void SetCap(wxPenCap capStyle); - - //@{ - /** - The pen's colour is changed to the given colour. - - @see GetColour() - */ - virtual void SetColour(wxColour& colour); - virtual void SetColour(unsigned char red, unsigned char green, unsigned char blue); - //@} - - /** - 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. - - @see GetDashes() - */ - virtual void SetDashes(int n, wxDash* dashes); - - /** - 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() - */ - virtual void SetJoin(wxPenJoin join_style); - - /** - Sets the bitmap for stippling. - - @see GetStipple() - */ - virtual void SetStipple(wxBitmap* stipple); - - /** - Set the pen style. - - @see wxPen() - */ - virtual void SetStyle(wxPenStyle style); - - /** - Sets the pen width. - - @see GetWidth() - */ - virtual void SetWidth(int width); - - /** - Inequality operator. - - See @ref overview_refcount_equality "reference-counted object comparison" for - more info. - */ - bool operator !=(const wxPen& pen); - - /** - Assignment operator, using @ref overview_refcount. - */ - wxPen operator =(const wxPen& pen); - - /** - Equality operator. - - See @ref overview_refcount_equality "reference-counted object comparison" for - more info. - */ - bool operator ==(const wxPen& pen); -}; - -/** - An empty pen. -*/ -wxPen wxNullPen; - -/** - Red pen. -*/ -wxPen* wxRED_PEN; - -/** - Cyan pen. -*/ -wxPen* wxCYAN_PEN; - -/** - Green pen. -*/ -wxPen* wxGREEN_PEN; - -/** - Black pen. -*/ -wxPen* wxBLACK_PEN; - -/** - White pen. -*/ -wxPen* wxWHITE_PEN; - -/** - Transparent pen. -*/ -wxPen* wxTRANSPARENT_PEN; - -/** - Black dashed pen. -*/ -wxPen* wxBLACK_DASHED_PEN; - -/** - Grey pen. -*/ -wxPen* wxGREY_PEN; - -/** - Medium-grey pen. -*/ -wxPen* wxMEDIUM_GREY_PEN; - -/** - Light-grey pen. -*/ -wxPen* wxLIGHT_GREY_PEN; - - - -/** - @class wxPenList - @wxheader{gdicmn.h} - - There is only one instance of this class: ::wxThePenList. - Use this object to search for a previously created pen of the desired - type and create it if not already found. In some windowing systems, - the pen may be a scarce resource, so it can pay to reuse old - resources if possible. When an application finishes, all pens will - be deleted and their resources freed, eliminating the possibility of - 'memory leaks'. However, it is best not to rely on this automatic - cleanup because it can lead to double deletion in some circumstances. - - There are two mechanisms in recent versions of wxWidgets which make the - pen list less useful than it once was. Under Windows, scarce resources - are cleaned up internally if they are not being used. Also, a referencing - counting mechanism applied to all GDI objects means that some sharing - of underlying resources is possible. You don't have to keep track of pointers, - working out when it is safe delete a pen, because the referencing counting does - it for you. For example, you can set a pen in a device context, and then - immediately delete the pen you passed, because the pen is 'copied'. - - So you may find it easier to ignore the pen list, and instead create - and copy pens as you see fit. If your Windows resource meter suggests - your application is using too many resources, you can resort to using - GDI lists to share objects explicitly. - - The only compelling use for the pen list is for wxWidgets to keep - track of pens in order to clean them up on exit. It is also kept for - backward compatibility with earlier versions of wxWidgets. - - @library{wxcore} - @category{gdi} - - @stdobjects - ::wxThePenList - - @see wxPen -*/ -class wxPenList -{ -public: - /** - Constructor. The application should not construct its own pen list: - use the object pointer ::wxThePenList. - */ - wxPenList(); - - /** - Finds a pen with the specified attributes and returns it, else creates a - new pen, adds it to the pen list, and returns it. - - @param colour - Colour object. - @param width - Width of pen. - @param style - Pen style. See ::wxPenStyle for a list of styles. - */ - wxPen* FindOrCreatePen(const wxColour& colour, - int width = 1, - wxPenStyle style = wxPENSTYLE_SOLID); -}; - -/** - The global list of wxPen objects ready to be re-used (for better performances). -*/ -wxPenList* wxThePenList; - diff --git a/interface/pickerbase.h b/interface/pickerbase.h deleted file mode 100644 index 8fca81bdd4..0000000000 --- a/interface/pickerbase.h +++ /dev/null @@ -1,123 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: pickerbase.h -// Purpose: interface of wxPickerBase -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxPickerBase - @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. - - @beginStyleTable - @style{wxPB_USE_TEXTCTRL} - Creates a text control to the left of the picker which is - completely managed by this wxPickerBase class. - @endStyleTable - - @library{wxcore} - @category{pickers} - - @see wxColourPickerCtrl -*/ -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; - - /** - Returns the proportion value of the picker. - */ - int GetPickerCtrlProportion() const; - - /** - Returns a pointer to the text control handled by this window or @NULL if the - @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 @c - wxPB_USE_TEXTCTRL style was given when creating this control). - */ - bool HasTextCtrl() const; - - /** - Returns @true if the picker control is growable. - */ - bool IsPickerCtrlGrowable() const; - - /** - 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); - - /** - Sets the picker control as growable when @c grow is @true. - */ - void SetPickerCtrlGrowable(bool grow = true); - - /** - Sets the proportion value of the picker. - - Look at the detailed description of wxPickerBase for more info. - */ - 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 detailed description of wxPickerBase for more info. - - This function can be used only when HasTextCtrl() returns @true. - */ - void SetTextCtrlProportion(int prop); -}; - diff --git a/interface/platform.h b/interface/platform.h deleted file mode 100644 index 73ff643e01..0000000000 --- a/interface/platform.h +++ /dev/null @@ -1,46 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: platform.h -// Purpose: interface of global functions -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** @ingroup group_funcmacro_version */ -//@{ - -/** - Returns @true if the compiler being used is GNU C++ and its version is - at least major.minor or greater. Returns @false otherwise. - - @header{wx/platform.h} -*/ -#define wxCHECK_GCC_VERSION( major, minor ) - -/** - Returns @true if the compiler being used is Sun CC Pro and its version is - at least major.minor or greater. Returns @false otherwise. - - @header{wx/platform.h} -*/ -#define wxCHECK_SUNCC_VERSION( major, minor ) - -/** - Returns @true if the compiler being used is Visual C++ and its version is - at least major or greater. Returns @false otherwise. - - @header{wx/platform.h} -*/ -#define wxCHECK_VISUALC_VERSION( major ) - -/** - Returns @true if the version of w32api headers used is major.minor or - greater. Otherwise, and also if we are not compiling with MinGW32/Cygwin - under Win32 at all, returns @false. - - @header{wx/platform.h} -*/ -#define wxCHECK_W32API_VERSION( major, minor ) - -//@} - diff --git a/interface/platinfo.h b/interface/platinfo.h deleted file mode 100644 index 71439b625d..0000000000 --- a/interface/platinfo.h +++ /dev/null @@ -1,394 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: platinfo.h -// Purpose: interface of wxPlatformInfo -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - - -/** - 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. -*/ -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 -}; - -/** - 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. -*/ -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 -}; - - -/** - The architecture of the operating system - (regardless of the build environment of wxWidgets library - see ::wxIsPlatform64bit() - documentation for more info). -*/ -enum wxArchitecture -{ - wxARCH_INVALID = -1, //!< returned on error - - wxARCH_32, //!< 32 bit - wxARCH_64, - - wxARCH_MAX -}; - - -/** - The endian-ness of the machine. -*/ -enum wxEndianness -{ - wxENDIAN_INVALID = -1, //!< returned on error - - wxENDIAN_BIG, //!< 4321 - wxENDIAN_LITTLE, //!< 1234 - wxENDIAN_PDP, //!< 3412 - - wxENDIAN_MAX -}; - - -/** - @class wxPlatformInfo - @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. - - @library{wxbase} - @category{misc} - - @see ::wxGetOsVersion(), wxIsPlatformLittleEndian(), wxIsPlatform64Bit(), - wxAppTraits -*/ -class wxPlatformInfo : public wxObject -{ -public: - - /** - 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, - wxOperatingSystemId id = wxOS_UNKNOWN, - int osMajor = -1, - int osMinor = -1, - wxArchitecture arch = wxARCH_INVALID, - wxEndianness endian = wxENDIAN_INVALID); - - - /** - Returns @true if the OS version is at least @c major.minor. - - @see GetOSMajorVersion(), GetOSMinorVersion(), - CheckToolkitVersion() - */ - bool CheckOSVersion(int major, int minor) const; - - /** - Returns @true if the toolkit version is at least @c major.minor. - - @see GetToolkitMajorVersion(), - GetToolkitMinorVersion(), CheckOSVersion() - */ - bool CheckToolkitVersion(int major, int minor) const; - - /** - 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 - @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 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; - - /** - 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 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(), CheckOSVersion() - */ - int GetOSMajorVersion() const; - - /** - Returns the run-time minor version of the OS associated with this - wxPlatformInfo instance. - - @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. - */ - wxString GetOperatingSystemFamilyName() const; - - /** - 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. - */ - wxString GetOperatingSystemIdName() const; - - - /** - 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. - */ - wxString GetPortIdName() const; - - /** - 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 @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() - */ - int GetToolkitMajorVersion() const; - - /** - Returns the run-time minor version of the toolkit associated with this - wxPlatformInfo instance. - - 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() - */ - int GetToolkitMinorVersion() const; - - /** - Returns @true if this instance is fully initialized with valid values. - */ - bool IsOk() const; - - /** - Returns @true if this wxPlatformInfo describes wxUniversal build. - */ - bool IsUsingUniversalWidgets() const; - - /** - Sets the architecture enum value associated with this wxPlatformInfo instance. - */ - void SetArchitecture(wxArchitecture n); - - /** - Sets the endianness enum value associated with this wxPlatformInfo instance. - */ - void SetEndianness(wxEndianness n); - - /** - Sets the version of the operating system associated with this wxPlatformInfo - instance. - */ - void SetOSVersion(int major, int minor); - - /** - Sets the operating system associated with this wxPlatformInfo instance. - */ - void SetOperatingSystemId(wxOperatingSystemId n); - - /** - Sets the wxWidgets port ID associated with this wxPlatformInfo instance. - */ - void SetPortId(wxPortId n); - - /** - Sets the version of the toolkit associated with this wxPlatformInfo instance. - */ - void SetToolkitVersion(int major, int minor); - - /** - Inequality operator. Tests all class' internal variables. - */ - bool operator!=(const wxPlatformInfo& t) const; - - /** - Equality operator. Tests all class' internal variables. - */ - bool operator==(const wxPlatformInfo& t) const; -}; - diff --git a/interface/popupwin.h b/interface/popupwin.h deleted file mode 100644 index 870ec9feb4..0000000000 --- a/interface/popupwin.h +++ /dev/null @@ -1,50 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: popupwind.h -// Purpose: interface of wxPoppWindow -// Author: wxWidgets team -// RCS-ID: $Id:$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxPopupWindow - @wxheader{popupwin.h} - - A special kind of top level window used for popup menus, - combobox popups and such. - - @library{wxcore} - @category{managedwnd} - - @see wxDialog, wxFrame -*/ - -class wxPopupWindow: public wxNonOwnedWindow -{ -public: - - /** - Constructor - */ - wxPopupWindow(wxWindow *parent, int flags = wxBORDER_NONE); - - /** - Create method for two-step creation - */ - bool Create(wxWindow *parent, int flags = wxBORDER_NONE); - - /** - Move the popup window to the right position, i.e. such that it is - entirely visible. - - The popup is positioned at ptOrigin + size if it opens below and to the - right (default), at ptOrigin - sizePopup if it opens above and to the - left etc. - - @param ptOrigin - Must be given in screen coordinates! - */ - virtual void Position(const wxPoint& ptOrigin, - const wxSize& size); -}; - diff --git a/interface/position.h b/interface/position.h deleted file mode 100644 index ba5dfbd499..0000000000 --- a/interface/position.h +++ /dev/null @@ -1,87 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: position.h -// Purpose: interface of wxPosition -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxPosition - @wxheader{position.h} - - This class represents the position of an item in any kind of grid of rows and - columns such as wxGridBagSizer, or wxHVScrolledWindow. - - @todo rename this class to wxItemPosition or such, wxPosition is too generic - - @library{wxbase} - @category{data} - - @see wxPoint, wxSize -*/ -class wxPosition -{ -public: - - /** - Construct a new wxPosition, setting the row and column to the - default value of (0, 0). - */ - wxPosition(); - - /** - Construct a new wxPosition, setting the row and column to the - value of (@a row, @a col). - */ - wxPosition(int row, int col); - - /** - A synonym for GetColumn(). - */ - int GetCol() const; - - /** - Get the current row value. - */ - int GetColumn() const; - - /** - Get the current row value. - */ - int GetRow() const; - - /** - A synonym for SetColumn(). - */ - void SetCol(int column); - - /** - Set a new column value. - */ - void SetColumn(int column); - - /** - Set a new row value. - */ - void SetRow(int row); - - - /** - @name Miscellaneous operators - - @{ - */ - bool operator ==(const wxPosition& p) const; - bool operator !=(const wxPosition& p) const; - wxPosition& operator +=(const wxPosition& p) const; - wxPosition& operator -=(const wxPosition& p) const; - wxPosition& operator +=(const wxSize& s) const; - wxPosition& operator -=(const wxSize& s) const; - wxPosition& operator +(const wxPosition& p) const; - wxPosition& operator -(const wxPosition& p) const; - wxPosition& operator +(const wxSize& s) const; - wxPosition& operator -(const wxSize& s) const; - //@} -}; - diff --git a/interface/power.h b/interface/power.h deleted file mode 100644 index b54808f562..0000000000 --- a/interface/power.h +++ /dev/null @@ -1,54 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: power.h -// Purpose: interface of wxPowerEvent -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxPowerEvent - @wxheader{power.h} - - The power events are generated when the system power state changes, e.g. the - system is suspended, hibernated, plugged into or unplugged from the wall socket - and so on. - - Notice that currently only suspend and resume events are generated and only - under MS Windows platform. To avoid the need to change the code using this - event later when these events are implemented on the other platforms please - use the test ifdef wxHAS_POWER_EVENTS instead of directly testing for - the platform in your code: this symbol will be defined for all platforms - supporting the power events. - - @beginEventTable{wxPowerEvent} - @event{EVT_POWER_SUSPENDING(func)}: - System is about to be suspended, this event can be vetoed to prevent - suspend from taking place. - @event{EVT_POWER_SUSPENDED(func)}: - System is about to suspend: normally the application should quickly - (i.e. without user intervention) close all the open files and network - connections here, possibly remembering them to reopen them later when - the system is resumed. - @event{EVT_POWER_SUSPEND_CANCEL(func)}: - System suspension was cancelled because some application vetoed it. - @event{EVT_POWER_RESUME(func)}: - System resumed from suspend: normally the application should restore - the state in which it had been before the suspension. - @endEventTable - - @library{wxbase} - @category{events} - - @see ::wxGetPowerType(), ::wxGetBatteryState() -*/ -class wxPowerEvent : public wxEvent -{ -public: - /** - Call this to prevent suspend from taking place in @c wxEVT_POWER_SUSPENDING - handler (it is ignored for all the others). - */ - void Veto(); -}; - diff --git a/interface/print.h b/interface/print.h deleted file mode 100644 index 8ad4c4512b..0000000000 --- a/interface/print.h +++ /dev/null @@ -1,816 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: print.h -// Purpose: interface of wxPreviewControlBar -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxPreviewControlBar - @wxheader{print.h} - - This is the default implementation of the preview control bar, a panel - with buttons and a zoom control. - - You can derive a new class from this and override some or all member functions - to change the behaviour and appearance; or you can leave it as it is. - - @library{wxbase} - @category{printing} - - @see wxPreviewFrame, wxPreviewCanvas, wxPrintPreview -*/ -class wxPreviewControlBar : public wxPanel -{ -public: - - /** - Constructor. - - The @a buttons parameter may be a combination of the following, using the bitwise - 'or' operator: - - @beginFlagTable - @flag{wxPREVIEW_PRINT} - Create a print button. - @flag{wxPREVIEW_NEXT} - Create a next page button. - @flag{wxPREVIEW_PREVIOUS} - Create a previous page button. - @flag{wxPREVIEW_ZOOM} - Create a zoom control. - @flag{wxPREVIEW_DEFAULT} - Equivalent to a combination of @c wxPREVIEW_PREVIOUS, @c wxPREVIEW_NEXT - and @c wxPREVIEW_ZOOM. - @endFlagTable - */ - wxPreviewControlBar(wxPrintPreview* preview, - long buttons, - wxWindow* parent, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = 0, - const wxString& name = "panel"); - - /** - Destructor. - */ - ~wxPreviewControlBar(); - - /** - Creates buttons, according to value of the button style flags. - - @todo which flags?? - */ - void CreateButtons(); - - /** - Gets the print preview object associated with the control bar. - */ - wxPrintPreview* GetPrintPreview(); - - /** - Gets the current zoom setting in percent. - */ - int GetZoomControl(); - - /** - Sets the zoom control. - */ - void SetZoomControl(int percent); - -}; - - - -/** - @class wxPreviewCanvas - @wxheader{print.h} - - A preview canvas is the default canvas used by the print preview - system to display the preview. - - @library{wxbase} - @category{printing} - - @see wxPreviewFrame, wxPreviewControlBar, wxPrintPreview -*/ -class wxPreviewCanvas : public wxScrolledWindow -{ -public: - /** - Constructor. - */ - wxPreviewCanvas(wxPrintPreview* preview, wxWindow* parent, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = 0, - const wxString& name = "canvas"); - - /** - Destructor. - */ - ~wxPreviewCanvas(); - - /** - Calls wxPrintPreview::PaintPage() to refresh the canvas. - */ - void OnPaint(wxPaintEvent& event); -}; - - - -/** - @class wxPreviewFrame - @wxheader{print.h} - - This class provides the default method of managing the print preview interface. - Member functions may be overridden to replace functionality, or the - class may be used without derivation. - - @library{wxbase} - @category{printing} - - @see wxPreviewCanvas, wxPreviewControlBar, wxPrintPreview -*/ -class wxPreviewFrame : public wxFrame -{ -public: - /** - Constructor. - - Pass a print preview object plus other normal frame arguments. - The print preview object will be destroyed by the frame when it closes. - */ - wxPreviewFrame(wxPrintPreview* preview, wxWindow* parent, - const wxString& title, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size size = wxDefaultSize, - long style = wxDEFAULT_FRAME_STYLE, - const wxString& name = "frame"); - - /** - Destructor. - */ - ~wxPreviewFrame(); - - /** - Creates a wxPreviewCanvas. - - Override this function to allow a user-defined preview canvas object - to be created. - */ - void CreateCanvas(); - - /** - Creates a wxPreviewControlBar. - - Override this function to allow a user-defined preview control bar object - to be created. - */ - void CreateControlBar(); - - /** - Creates the preview canvas and control bar, and calls wxWindow::MakeModal(@true) - to disable other top-level windows in the application. - - This function should be called by the application prior to showing the frame. - */ - void Initialize(); - - /** - Enables the other frames in the application, and deletes the print preview - object, implicitly deleting any printout objects associated with the print - preview object. - */ - void OnCloseWindow(wxCloseEvent& event); -}; - - - -/** - @class wxPrintPreview - @wxheader{print.h} - - Objects of this class manage the print preview process. The object is passed - a wxPrintout object, and the wxPrintPreview object itself is passed to - a wxPreviewFrame object. Previewing is started by initializing and showing - the preview frame. Unlike wxPrinter::Print(), flow of control returns to the - application immediately after the frame is shown. - - @note - The preview shown is only exact on Windows. On other platforms, the wxDC - used for preview is different from what is used for printing and the - results may be significantly different, depending on how is the output - created. In particular, printing code relying on wxDC::GetTextExtent() - heavily (for example, wxHtmlEasyPrinting and other wxHTML classes do) is - affected. It is recommended to use native preview functionality on - platforms that offer it (OS X, GTK+). - - @library{wxbase} - @category{printing} - - @see @ref overview_printing, wxPrinterDC, wxPrintDialog, wxPrintout, wxPrinter, - wxPreviewCanvas, wxPreviewControlBar, wxPreviewFrame -*/ -class wxPrintPreview : public wxObject -{ -public: - /** - Constructor. - - Pass a printout object, an optional printout object to be used for actual - printing, and the address of an optional block of printer data, which will - be copied to the print preview object's print data. - - If @a printoutForPrinting is non-@NULL, a @b "Print..." button will be placed on - the preview frame so that the user can print directly from the preview interface. - - @remarks - Do not explicitly delete the printout objects once this destructor has been - called, since they will be deleted in the wxPrintPreview constructor. - The same does not apply to the @a data argument. - - Use IsOk() to check whether the wxPrintPreview object was created correctly. - */ - wxPrintPreview(wxPrintout* printout, - wxPrintout* printoutForPrinting, - wxPrintData* data = NULL); - - /** - Destructor. - - Deletes both print preview objects, so do not destroy these objects - in your application. - */ - ~wxPrinter(); - - /** - Gets the preview window used for displaying the print preview image. - */ - wxPreviewCanvas* GetCanvas(); - - /** - Gets the page currently being previewed. - */ - int GetCurrentPage(); - - /** - Gets the frame used for displaying the print preview canvas - and control bar. - */ - wxFrame* GetFrame(); - - /** - Returns the maximum page number. - */ - int GetMaxPage(); - - /** - Returns the minimum page number. - */ - int GetMinPage(); - - /** - Gets the preview printout object associated with the wxPrintPreview object. - */ - wxPrintout* GetPrintout(); - - /** - Gets the printout object to be used for printing from within the preview - interface, - or @NULL if none exists. - */ - wxPrintout* GetPrintoutForPrinting(); - - /** - Returns @true if the wxPrintPreview is valid, @false otherwise. - - It could return @false if there was a problem initializing the printer - device context (current printer not set, for example). - */ - bool IsOk(); - - /** - This refreshes the preview window with the preview image. - It must be called from the preview window's OnPaint member. - - The implementation simply blits the preview bitmap onto - the canvas, creating a new preview bitmap if none exists. - */ - bool PaintPage(wxPreviewCanvas* canvas, wxDC dc); - - /** - Invokes the print process using the second wxPrintout object - supplied in the wxPrintPreview constructor. - Will normally be called by the @b Print... panel item on the - preview frame's control bar. - - Returns @false in case of error -- call wxPrinter::GetLastError() - to get detailed information about the kind of the error. - */ - bool Print(bool prompt); - - /** - Renders a page into a wxMemoryDC. Used internally by wxPrintPreview. - */ - bool RenderPage(int pageNum); - - /** - Sets the window to be used for displaying the print preview image. - */ - void SetCanvas(wxPreviewCanvas* window); - - /** - Sets the current page to be previewed. - */ - void SetCurrentPage(int pageNum); - - /** - Sets the frame to be used for displaying the print preview canvas - and control bar. - */ - void SetFrame(wxFrame* frame); - - /** - Associates a printout object with the wxPrintPreview object. - */ - void SetPrintout(wxPrintout* printout); - - /** - Sets the percentage preview zoom, and refreshes the preview canvas accordingly. - */ - void SetZoom(int percent); -}; - - - -/** - @class wxPrinter - @wxheader{print.h} - - This class represents the Windows or PostScript printer, and is the vehicle - through which printing may be launched by an application. - - Printing can also be achieved through using of lower functions and classes, - but this and associated classes provide a more convenient and general method - of printing. - - @library{wxbase} - @category{printing} - - @see @ref overview_printing, wxPrinterDC, wxPrintDialog, wxPrintout, wxPrintPreview -*/ -class wxPrinter : public wxObject -{ -public: - /** - Constructor. - - Pass an optional pointer to a block of print dialog data, which will be - copied to the printer object's local data. - - @see wxPrintDialogData, wxPrintData - */ - wxPrinter(wxPrintDialogData* data = NULL); - - /** - Creates the default printing abort window, with a cancel button. - */ - void CreateAbortWindow(wxWindow* parent, wxPrintout* printout); - - /** - Returns @true if the user has aborted the print job. - */ - bool GetAbort(); - - /** - Return last error. Valid after calling Print(), PrintDialog() or - wxPrintPreview::Print(). - - These functions set last error to @c wxPRINTER_NO_ERROR if no error happened. - - Returned value is one of the following: - - @beginTable - @row2col{wxPRINTER_NO_ERROR, No error happened.} - @row2col{wxPRINTER_CANCELLED, The user cancelled printing.} - @row2col{wxPRINTER_ERROR, There was an error during printing.} - @endTable - */ - static wxPrinterError GetLastError(); - - /** - Returns the @ref overview_printing_printdata "print data" associated with - the printer object. - */ - wxPrintDialogData& GetPrintDialogData(); - - /** - Starts the printing process. Provide a parent window, a user-defined wxPrintout - object which controls the printing of a document, and whether the print dialog - should be invoked first. - - Print() could return @false if there was a problem initializing the printer device - context (current printer not set, for example) or the user cancelled printing. - Call GetLastError() to get detailed information about the kind of the error. - */ - bool Print(wxWindow* parent, wxPrintout* printout, - bool prompt = true); - - /** - Invokes the print dialog. - - If successful (the user did not press Cancel and no error occurred), - a suitable device context will be returned; otherwise @NULL is returned; - call GetLastError() to get detailed information about the kind of the error. - - @remarks - The application must delete this device context to avoid a memory leak. - */ - wxDC* PrintDialog(wxWindow* parent); - - /** - Default error-reporting function. - */ - void ReportError(wxWindow* parent, wxPrintout* printout, - const wxString& message); - - /** - Invokes the print setup dialog. - - @remarks - The setup dialog is obsolete from Windows 95, though retained - for backward compatibility. - */ - bool Setup(wxWindow* parent); -}; - - - -/** - @class wxPrintout - @wxheader{print.h} - - This class encapsulates the functionality of printing out an application document. - - A new class must be derived and members overridden to respond to calls such as - OnPrintPage() and HasPage() and to render the print image onto an associated wxDC. - Instances of this class are passed to wxPrinter::Print() or - to a wxPrintPreview object to initiate printing or previewing. - - Your derived wxPrintout is responsible for drawing both the preview image and - the printed page. If your windows' drawing routines accept an arbitrary DC as an - argument, you can re-use those routines within your wxPrintout subclass to draw - the printout image. You may also add additional drawing elements within your - wxPrintout subclass, like headers, footers, and/or page numbers. However, the - image on the printed page will often differ from the image drawn on the screen, - as will the print preview image -- not just in the presence of headers and - footers, but typically in scale. A high-resolution printer presents a much - larger drawing surface (i.e., a higher-resolution DC); a zoomed-out preview - image presents a much smaller drawing surface (lower-resolution DC). By using - the routines FitThisSizeToXXX() and/or MapScreenSizeToXXX() within your - wxPrintout subclass to set the user scale and origin of the associated DC, you - can easily use a single drawing routine to draw on your application's windows, - to create the print preview image, and to create the printed paper image, and - achieve a common appearance to the preview image and the printed page. - - @library{wxbase} - @category{printing} - - @see @ref overview_printing, wxPrinterDC, wxPrintDialog, wxPageSetupDialog, - wxPrinter, wxPrintPreview -*/ -class wxPrintout : public wxObject -{ -public: - /** - Constructor. - - Pass an optional title argument - the current filename would be a - good idea. This will appear in the printing list (at least in MSW) - */ - wxPrintout(const wxString& title = "Printout"); - - /** - Destructor. - */ - ~wxPrintout(); - - /** - Set the user scale and device origin of the wxDC associated with this wxPrintout - so that the given image size fits entirely within the page rectangle and the - origin is at the top left corner of the page rectangle. - - On MSW and Mac, the page rectangle is the printable area of the page. - On other platforms and PostScript printing, the page rectangle is the entire paper. - - Use this if you want your printed image as large as possible, but with the caveat - that on some platforms, portions of the image might be cut off at the edges. - */ - void FitThisSizeToPage(const wxSize& imageSize); - - /** - Set the user scale and device origin of the wxDC associated with this wxPrintout - so that the given image size fits entirely within the page margins set in the - given wxPageSetupDialogData object. - - This function provides the greatest consistency across all platforms because it - does not depend on having access to the printable area of the paper. - - @remarks - On Mac, the native wxPageSetupDialog does not let you set the page margins; - you'll have to provide your own mechanism, or you can use the Mac-only class - wxMacPageMarginsDialog. - */ - void FitThisSizeToPageMargins(const wxSize& imageSize, - const wxPageSetupDialogData& pageSetupData); - - /** - Set the user scale and device origin of the wxDC associated with this wxPrintout - so that the given image size fits entirely within the paper and the origin is at - the top left corner of the paper. - - Use this if you're managing your own page margins. - - @note - With most printers, the region around the edges of the paper are not - printable so that the edges of the image could be cut off. - - */ - void FitThisSizeToPaper(const wxSize& imageSize); - - /** - Returns the device context associated with the printout (given to the printout - at start of printing or previewing). - - The application can use GetDC() to obtain a device context to draw on. - - This will be a wxPrinterDC if printing under Windows or Mac, a wxPostScriptDC - if printing on other platforms, and a wxMemoryDC if previewing. - */ - wxDC* GetDC(); - - /** - Return the rectangle corresponding to the page margins specified by the given - wxPageSetupDialogData object in the associated wxDC's logical coordinates for - the current user scale and device origin. - - The page margins are specified with respect to the edges of the paper on all - platforms. - */ - wxRect GetLogicalPageMarginsRect(const wxPageSetupDialogData& pageSetupData); - - /** - Return the rectangle corresponding to the page in the associated wxDC 's - logical coordinates for the current user scale and device origin. - - On MSW and Mac, this will be the printable area of the paper. - On other platforms and PostScript printing, this will be the full paper - rectangle. - */ - wxRect GetLogicalPageRect(); - - /** - Return the rectangle corresponding to the paper in the associated wxDC 's - logical coordinates for the current user scale and device origin. - */ - wxRect GetLogicalPaperRect(); - - /** - Returns the number of pixels per logical inch of the printer device context. - - Dividing the printer PPI by the screen PPI can give a suitable scaling factor - for drawing text onto the printer. - - Remember to multiply this by a scaling factor to take the preview DC size into - account. - Or you can just use the FitThisSizeToXXX() and MapScreenSizeToXXX routines below, - which do most of the scaling calculations for you. - - @beginWxPythonOnly - This method returns the output-only parameters as a tuple. - @endWxPythonOnly - */ - void GetPPIPrinter(int* w, int* h); - - /** - Returns the number of pixels per logical inch of the screen device context. - - Dividing the printer PPI by the screen PPI can give a suitable scaling factor - for drawing text onto the printer. - - If you are doing your own scaling, remember to multiply this by a scaling - factor to take the preview DC size into account. - - @beginWxPythonOnly - This method returns the output-only parameters as a tuple. - @endWxPythonOnly - */ - void GetPPIScreen(int* w, int* h); - - /** - Called by the framework to obtain information from the application about minimum - and maximum page values that the user can select, and the required page range to - be printed. - - By default this returns (1, 32000) for the page minimum and maximum values, and - (1, 1) for the required page range. - - @a minPage must be greater than zero and @a maxPage must be greater - than @a minPage. - - @beginWxPythonOnly - When this method is implemented in a derived Python class, it should be designed - to take no parameters (other than the self reference) and to return a tuple of - four integers. - @endWxPythonOnly - */ - void GetPageInfo(int* minPage, int* maxPage, int* pageFrom, - int* pageTo); - - /** - Returns the size of the printer page in millimetres. - - @beginWxPythonOnly - This method returns the output-only parameters as a tuple. - @endWxPythonOnly - */ - void GetPageSizeMM(int* w, int* h); - - /** - Returns the size of the printer page in pixels, called the page rectangle. - - The page rectangle has a top left corner at (0,0) and a bottom right corner at - (w,h). These values may not be the same as the values returned from - wxDC::GetSize(); if the printout is being used for - previewing, a memory device context is used, which uses a bitmap size reflecting - the current preview zoom. The application must take this discrepancy into - account if previewing is to be supported. - - @beginWxPythonOnly - This method returns the output-only parameters as a tuple. - @endWxPythonOnly - */ - void GetPageSizePixels(int* w, int* h); - - /** - Returns the rectangle that corresponds to the entire paper in pixels, called the - paper rectangle. - - This distinction between paper rectangle and page rectangle reflects the fact that - most printers cannot print all the way to the edge of the paper. - The page rectangle is a rectangle whose top left corner is at (0,0) and whose width - and height are given by wxDC::GetPageSizePixels(). - - On MSW and Mac, the page rectangle gives the printable area of the paper, while the - paper rectangle represents the entire paper, including non-printable borders. - Thus, the rectangle returned by wxDC::GetPaperRectPixels() will have a top left corner - whose coordinates are small negative numbers and the bottom right corner will have - values somewhat larger than the width and height given by wxDC::GetPageSizePixels(). - - On other platforms and for PostScript printing, the paper is treated as if its entire - area were printable, so this function will return the same rectangle as the page - rectangle. - */ - wxRect GetPaperRectPixels(); - - /** - Returns the title of the printout. - - @todo the python note here was wrong - */ - wxString GetTitle(); - - /** - Should be overridden to return @true if the document has this page, or @false - if not. - - Returning @false signifies the end of the document. By default, - HasPage behaves as if the document has only one page. - */ - bool HasPage(int pageNum); - - /** - Returns @true if the printout is currently being used for previewing. - */ - bool IsPreview(); - - /** - Set the user scale and device origin of the wxDC associated with this wxPrintout - so that one screen pixel maps to one device pixel on the DC. - That is, the user scale is set to (1,1) and the device origin is set to (0,0). - - Use this if you want to do your own scaling prior to calling wxDC drawing calls, - for example, if your underlying model is floating-point and you want to achieve - maximum drawing precision on high-resolution printers. - - You can use the GetLogicalXXXRect() routines below to obtain the paper rectangle, - page rectangle, or page margins rectangle to perform your own scaling. - - @note - While the underlying drawing model of Mac OS X is floating-point, - wxWidgets's drawing model scales from integer coordinates. - */ - void MapScreenSizeToDevice(); - - /** - This sets the user scale of the wxDC assocated with this wxPrintout to the same - scale as MapScreenSizeToPaper() but sets the logical origin to the top left corner - of the page rectangle. - */ - void MapScreenSizeToPage(); - - /** - This sets the user scale of the wxDC assocated with this wxPrintout to the same - scale as MapScreenSizeToPageMargins() but sets the logical origin to the top left - corner of the page margins specified by the given wxPageSetupDialogData object. - */ - void MapScreenSizeToPageMargins(const wxPageSetupDialogData& pageSetupData); - - /** - Set the user scale and device origin of the wxDC associated with this wxPrintout - so that the printed page matches the screen size as closely as possible - and the logical origin is in the top left corner of the paper rectangle. - - That is, a 100-pixel object on screen should appear at the same size on the - printed page. - (It will, of course, be larger or smaller in the preview image, depending on the - zoom factor.) - - Use this if you want WYSIWYG behavior, e.g., in a text editor. - */ - void MapScreenSizeToPaper(); - - /** - Shift the device origin by an amount specified in logical coordinates. - */ - void OffsetLogicalOrigin(wxCoord xoff, wxCoord yoff); - - /** - Called by the framework at the start of document printing. Return @false from - this function cancels the print job. - - OnBeginDocument() is called once for every copy printed. - - @remarks - The base OnBeginDocument() must be called (and the return value - checked) from within the overridden function, since it calls wxDC::StartDoc(). - - @beginWxPythonOnly - If this method is overridden in a Python class then the base class version can - be called by using the method base_OnBeginDocument(startPage, endPage). - @endWxPythonOnly - */ - bool OnBeginDocument(int startPage, int endPage); - - /** - Called by the framework at the start of printing. - - OnBeginPrinting() is called once for every print job - (regardless of how many copies are being printed). - */ - void OnBeginPrinting(); - - /** - Called by the framework at the end of document printing. - - OnEndDocument() is called once for every copy printed. - - @remarks - The base OnEndDocument() must be called from within the overridden function, - since it calls wxDC::EndDoc(). - */ - void OnEndDocument(); - - /** - Called by the framework at the end of printing. - - OnEndPrinting is called once for every print job - (regardless of how many copies are being printed). - */ - void OnEndPrinting(); - - /** - Called once by the framework before any other demands are made of the - wxPrintout object. - - This gives the object an opportunity to calculate the number of pages - in the document, for example. - */ - void OnPreparePrinting(); - - /** - Called by the framework when a page should be printed. Returning @false cancels - the print job. - */ - bool OnPrintPage(int pageNum); - - /** - Set the device origin of the associated wxDC so that the current logical point - becomes the new logical origin. - */ - void SetLogicalOrigin(wxCoord x, wxCoord y); -}; - diff --git a/interface/printdlg.h b/interface/printdlg.h deleted file mode 100644 index 4a174546bb..0000000000 --- a/interface/printdlg.h +++ /dev/null @@ -1,128 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: printdlg.h -// Purpose: interface of wxPrintDialog -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxPrintDialog - @wxheader{printdlg.h} - - This class represents the print and print setup common dialogs. - You may obtain a wxPrinterDC device context from a successfully dismissed - print dialog. - - @library{wxcore} - @category{printing} - - @see @ref overview_printing, @ref overview_cmndlg_print -*/ -class wxPrintDialog : public wxDialog -{ -public: - /** - Constructor. - - Pass a parent window, and optionally a pointer to a block of print - data, which will be copied to the print dialog's print data. - - @see wxPrintDialogData - */ - wxPrintDialog(wxWindow* parent, wxPrintDialogData* data = NULL); - - /** - Destructor. - - If GetPrintDC() has not been called, the device context obtained by - the dialog (if any) will be deleted. - */ - ~wxPrintDialog(); - - /** - Returns the device context created by the print dialog, if any. - - When this function has been called, the ownership of the device context - is transferred to the application, so it must then be deleted - explicitly. - */ - wxDC* GetPrintDC(); - - /** - Returns the @ref overview_printing_printdata "print dialog data" associated - with the print dialog. - */ - wxPrintDialogData GetPrintDialogData(); - - /** - Shows the dialog, returning @c wxID_OK if the user pressed OK, and @c - wxID_CANCEL otherwise. - - After this function is called, a device context may be retrievable using - GetPrintDC(). - */ - int ShowModal(); -}; - - - -/** - @class wxPageSetupDialog - @wxheader{printdlg.h} - - This class represents the page setup common dialog. In MSW, the page setup - dialog is standard from Windows 95 on, replacing the print setup dialog (which - is retained in Windows and wxWidgets for backward compatibility). - On Windows 95 and NT 4.0 and above, the page setup dialog is native to the windowing - system, otherwise it is emulated. - - The page setup dialog contains controls for paper size (A4, A5 etc.), - orientation (landscape or portrait), and controls for setting left, top, right - and bottom margin sizes in millimetres. - - On Macintosh, the native page setup dialog is used, which lets you select paper - size and orientation but it does not let you change the page margins. - - On other platforms, a generic dialog is used. - - When the dialog has been closed, you need to query the wxPageSetupDialogData - object associated with the dialog. - - Note that the OK and Cancel buttons do not destroy the dialog; this must be done - by the application. - - @library{wxcore} - @category{printing} - - @see @ref overview_printing "Printing framework overview", - wxPrintDialog, wxPageSetupDialogData -*/ -class wxPageSetupDialog : public wxDialog -{ -public: - /** - Constructor. - - Pass a parent window, and optionally a pointer to a block of page - setup data, which will be copied to the print dialog's internal data. - */ - wxPageSetupDialog(wxWindow* parent, wxPageSetupDialogData* data = NULL); - - /** - Destructor. - */ - ~wxPageSetupDialog(); - - /** - Returns the wxPageSetupDialogData object associated with the dialog. - */ - wxPageSetupDialogData& GetPageSetupData(); - - /** - Shows the dialog, returning @c wxID_OK if the user pressed OK, and - @c wxID_CANCEL otherwise. - */ - int ShowModal(); -}; - diff --git a/interface/process.h b/interface/process.h deleted file mode 100644 index 1401717d76..0000000000 --- a/interface/process.h +++ /dev/null @@ -1,297 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: process.h -// Purpose: interface of wxProcess -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - Signal constants used by wxProcess. -*/ -enum wxSignal -{ - wxSIGNONE = 0, //!< verify if the process exists under Unix - wxSIGHUP, - wxSIGINT, - wxSIGQUIT, - wxSIGILL, - wxSIGTRAP, - wxSIGABRT, - wxSIGEMT, - wxSIGFPE, - wxSIGKILL, //!< forcefully kill, dangerous! - wxSIGBUS, - wxSIGSEGV, - wxSIGSYS, - wxSIGPIPE, - wxSIGALRM, - wxSIGTERM //!< terminate the process gently -}; - -/** - Return values for wxProcess::Kill. -*/ -enum wxKillError -{ - wxKILL_OK, //!< no error - wxKILL_BAD_SIGNAL, //!< no such signal - wxKILL_ACCESS_DENIED, //!< permission denied - wxKILL_NO_PROCESS, //!< no such process - wxKILL_ERROR //!< another, unspecified error -}; - - -/** - @class wxProcess - @wxheader{process.h} - - The objects of this class are used in conjunction with the ::wxExecute() function. - When a wxProcess object is passed to ::wxExecute(), its OnTerminate() virtual method - is called when the process terminates. This allows the program to be (asynchronously) - notified about the process termination and also retrieve its exit status which is - unavailable from ::wxExecute() in the case of asynchronous execution. - - @note If the process termination notification is processed by the - parent, it is responsible for deleting the wxProcess object which sent it. - However, if it is not processed, the object will delete itself and so the - library users should only delete those objects whose notifications have been - processed (and call wxProcess::Detach for others). - - wxProcess also supports IO redirection of the child process. For this, you have - to call its Redirect() method before passing it to ::wxExecute(). - If the child process was launched successfully, GetInputStream(), GetOutputStream() - and GetErrorStream() can then be used to retrieve the streams corresponding to the - child process standard output, input and error output respectively. - - @library{wxbase} - @category{appmanagement} - - @see wxExecute(), @ref page_samples_exec "exec sample" -*/ -class wxProcess : public wxEvtHandler -{ -public: - /** - Constructs a process object. @a id is only used in the case you want to - use wxWidgets events. It identifies this object, or another window that will - receive the event. - - If the @a parent parameter is different from @NULL, it will receive - a @c wxEVT_END_PROCESS notification event (you should insert @c EVT_END_PROCESS - macro in the event table of the parent to handle it) with the given @a id. - - @param parent - The event handler parent. - @param id - id of an event. - */ - wxProcess(wxEvtHandler* parent = NULL, int id = -1); - - /** - Creates an object without any associated parent (and hence no id neither) - but allows to specify the @a flags which can have the value of - @c wxPROCESS_DEFAULT or @c wxPROCESS_REDIRECT. - - Specifying the former value has no particular effect while using the latter - one is equivalent to calling Redirect(). - */ - wxProcess(int flags); - - /** - Destroys the wxProcess object. - */ - ~wxProcess(); - - /** - Closes the output stream (the one connected to the stdin of the child - process). - - This function can be used to indicate to the child process that - there is no more data to be read - usually, a filter program will only - terminate when the input stream is closed. - */ - void CloseOutput(); - - /** - Normally, a wxProcess object is deleted by its parent when it receives the - notification about the process termination. However, it might happen that the - parent object is destroyed before the external process is terminated (e.g. a - window from which this external process was launched is closed by the user) - and in this case it @b should not delete the wxProcess object, but - @b should call Detach() instead. After the wxProcess object is detached - from its parent, no notification events will be sent to the parent and the - object will delete itself upon reception of the process termination - notification. - */ - void Detach(); - - /** - Returns @true if the given process exists in the system. - - @see Kill(), @ref page_samples_exec "Exec sample" - */ - static bool Exists(int pid); - - /** - Returns an input stream which corresponds to the standard error output (stderr) - of the child process. - */ - wxInputStream* GetErrorStream() const; - - /** - It returns an input stream corresponding to the standard output stream of the - subprocess. If it is @NULL, you have not turned on the redirection. - - @see Redirect(). - */ - wxInputStream* GetInputStream() const; - - /** - It returns an output stream correspoding to the input stream of the subprocess. - If it is @NULL, you have not turned on the redirection. - - @see Redirect(). - */ - wxOutputStream* GetOutputStream() const; - - /** - Returns the process ID of the process launched by Open(). - */ - long GetPid() const; - - /** - Returns @true if there is data to be read on the child process standard - error stream. - - @see IsInputAvailable() - */ - bool IsErrorAvailable() const; - - /** - Returns @true if there is data to be read on the child process standard - output stream. - - This allows to write simple (and extremely inefficient) polling-based code - waiting for a better mechanism in future wxWidgets versions. - See the @ref page_samples_exec "exec sample" for an example of using this - function. - - @see IsInputOpened() - */ - bool IsInputAvailable() const; - - /** - Returns @true if the child process standard output stream is opened. - */ - bool IsInputOpened() const; - - /** - Send the specified signal to the given process. Possible signal values - can be one of the ::wxSignal enumeration values. - - @c wxSIGNONE, @c wxSIGKILL and @c wxSIGTERM have the same meaning - under both Unix and Windows but all the other signals are equivalent to - @c wxSIGTERM under Windows. - - The @a flags parameter can be @c wxKILL_NOCHILDREN (the default), - or @c wxKILL_CHILDREN, in which case the child processes of this - process will be killed too. Note that under Unix, for @c wxKILL_CHILDREN - to work you should have created the process passing @c wxEXEC_MAKE_GROUP_LEADER. - - Returns the element of ::wxKillError enum. - - @see Exists(), wxKill(), @ref page_samples_exec "Exec sample" - */ - static wxKillError Kill(int pid, wxSignal signal = wxSIGNONE, - int flags = wxKILL_NOCHILDREN); - - /** - It is called when the process with the pid @a pid finishes. - It raises a wxWidgets event when it isn't overridden. - - @param pid - The pid of the process which has just terminated. - @param status - The exit code of the process. - */ - void OnTerminate(int pid, int status); - - /** - This static method replaces the standard @c popen() function: it launches - the process specified by the @a cmd parameter and returns the wxProcess - object which can be used to retrieve the streams connected to the standard - input, output and error output of the child process. - - If the process couldn't be launched, @NULL is returned. - - @remarks - In any case the returned pointer should @b not be deleted, rather the process - object will be destroyed automatically when the child process terminates. This - does mean that the child process should be told to quit before the main program - exits to avoid memory leaks. - - @param cmd - The command to execute, including optional arguments. - @param flags - The flags to pass to ::wxExecute(). - Note: @c wxEXEC_SYNC should not be used. - - @return A pointer to new wxProcess object or @NULL on error. - - @see ::wxExecute() - */ - static wxProcess* Open(const wxString& cmd, - int flags = wxEXEC_ASYNC); - - /** - Turns on redirection. - - ::wxExecute() will try to open a couple of pipes to catch the subprocess stdio. - The caught input stream is returned by GetOutputStream() as a non-seekable stream. - The caught output stream is returned by GetInputStream() as a non-seekable stream. - */ - void Redirect(); -}; - - - -/** - @class wxProcessEvent - @wxheader{process.h} - - A process event is sent when a process is terminated. - - @beginEventTable{wxProcessEvent} - @event{EVT_END_PROCESS(id, func)} - Process a @c wxEVT_END_PROCESS event. @a id is the identifier of the process - object (the id passed to the wxProcess constructor) or a window to receive - the event. - @endEventTable - - @library{wxbase} - @category{events} - - @see wxProcess, @ref overview_eventhandling -*/ -class wxProcessEvent : public wxEvent -{ -public: - /** - Constructor. - - Takes a wxProcessObject or window id, a process id and an exit status. - */ - wxProcessEvent(int id = 0, int pid = 0, int exitcode = 0); - - /** - Returns the exist status. - */ - int GetExitCode(); - - /** - Returns the process id. - */ - int GetPid() const; -}; - diff --git a/interface/progdlg.h b/interface/progdlg.h deleted file mode 100644 index 45af3f8e81..0000000000 --- a/interface/progdlg.h +++ /dev/null @@ -1,113 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: progdlg.h -// Purpose: interface of wxProgressDialog -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxProgressDialog - @wxheader{progdlg.h} - - This class represents a dialog that shows a short message and a - progress bar. Optionally, it can display ABORT and SKIP buttons, - the elapsed, remaining and estimated time for the end of the progress. - - @beginStyleTable - @style{wxPD_APP_MODAL} - Make the progress dialog modal. If this flag is not given, it is - only "locally" modal - that is the input to the parent window is - disabled, but not to the other ones. - @style{wxPD_AUTO_HIDE} - Causes the progress dialog to disappear from screen as soon as the - maximum value of the progress meter has been reached. - @style{wxPD_SMOOTH} - Causes smooth progress of the gauge control. - @style{wxPD_CAN_ABORT} - This flag tells the dialog that it should have a "Cancel" button - which the user may press. If this happens, the next call to - Update() will return @false. - @style{wxPD_CAN_SKIP} - This flag tells the dialog that it should have a "Skip" button - which the user may press. If this happens, the next call to - Update() will return @true in its skip parameter. - @style{wxPD_ELAPSED_TIME} - This flag tells the dialog that it should show elapsed time (since - creating the dialog). - @style{wxPD_ESTIMATED_TIME} - This flag tells the dialog that it should show estimated time. - @style{wxPD_REMAINING_TIME} - This flag tells the dialog that it should show remaining time. - @endStyleTable - - @library{wxbase} - @category{cmndlg} -*/ -class wxProgressDialog : public wxDialog -{ -public: - /** - Constructor. Creates the dialog, displays it and disables user input - for other windows, or, if @c wxPD_APP_MODAL flag is not given, for its - parent window only. - - @param title - Dialog title to show in titlebar. - @param message - Message displayed above the progress bar. - @param maximum - Maximum value for the progress bar. - @param parent - Parent window. - @param style - The dialog style. See wxProgressDialog. - */ - wxProgressDialog(const wxString& title, const wxString& message, - int maximum = 100, - wxWindow* parent = NULL, - int style = wxPD_AUTO_HIDE | wxPD_APP_MODAL); - - /** - Destructor. Deletes the dialog and enables all top level windows. - */ - ~wxProgressDialog(); - - /** - Works like Update() but makes the gauge control run in indeterminate mode - (see wxGauge documentation); sets the remaining and the estimated time labels - (if present) to "Unknown" or to @a newmsg (if it's non-empty); moves the progress - bar a bit to indicate that some progress was done. - */ - virtual bool Pulse(const wxString& newmsg = "", - bool* skip = NULL); - - /** - Can be used to continue with the dialog, after the user had clicked the "Abort" button. - */ - void Resume(); - - /** - Updates the dialog, setting the progress bar to the new value and, if - given changes the message above it. Returns @true unless the "Cancel" button - has been pressed. - - If @false is returned, the application can either immediately destroy the - dialog or ask the user for the confirmation and if the abort is not confirmed - the dialog may be resumed with Resume() function. - - @param value - The new value of the progress meter. It should be less than or equal to - the maximum value given to the constructor and the dialog is closed if - it is equal to the maximum. - @param newmsg - The new messages for the progress dialog text, if it is - empty (which is the default) the message is not changed. - @param skip - If "Skip" button was pressed since last Update() call, - this is set to @true. - */ - virtual bool Update(int value, const wxString& newmsg = "", - bool* skip = NULL); -}; - diff --git a/interface/propdlg.h b/interface/propdlg.h deleted file mode 100644 index 77cd2f43ed..0000000000 --- a/interface/propdlg.h +++ /dev/null @@ -1,200 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: propdlg.h -// Purpose: interface of wxPropertySheetDialog -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - - -/** - Values used by wxPropertySheetDialog::SetSheetStyle -*/ -enum wxPropertySheetDialogFlags -{ - /** - Uses the default look and feel for the controller window, - normally a notebook except on Smartphone where a choice control is used. - */ - wxPROPSHEET_DEFAULT = 0x0001, - - /** - Uses a notebook for the controller window. - */ - wxPROPSHEET_NOTEBOOK = 0x0002, - - /** - Uses a toolbook for the controller window. - */ - wxPROPSHEET_TOOLBOOK = 0x0004, - - /** - Uses a choicebook for the controller window. - */ - wxPROPSHEET_CHOICEBOOK = 0x0008, - - /** - Uses a listbook for the controller window. - */ - wxPROPSHEET_LISTBOOK = 0x0010, - - /** - Uses a button toolbox for the controller window. - */ - wxPROPSHEET_BUTTONTOOLBOOK = 0x0020, - - /** - Uses a treebook for the controller window. - */ - wxPROPSHEET_TREEBOOK = 0x0040, - - /** - Shrinks the dialog window to fit the currently selected page - (common behaviour for property sheets on Mac OS X). - */ - wxPROPSHEET_SHRINKTOFIT = 0x0100, -}; - - -/** - @class wxPropertySheetDialog - @wxheader{propdlg.h} - - This class represents a property sheet dialog: a tabbed dialog - for showing settings. It is optimized to show flat tabs - on PocketPC devices, and can be customized to use different - controllers instead of the default notebook style. - - To use this class, call Create() from your own Create function. - Then call CreateButtons(), and create pages, adding them to the book control. - Finally call LayoutDialog(). - - For example: - - @code - bool MyPropertySheetDialog::Create(...) - { - if (!wxPropertySheetDialog::Create(...)) - return @false; - - CreateButtons(wxOK|wxCANCEL|wxHELP); - - // Add page - wxPanel* panel = new wxPanel(GetBookCtrl(), ...); - GetBookCtrl()->AddPage(panel, wxT("General")); - - LayoutDialog(); - return @true; - } - @endcode - - If necessary, override CreateBookCtrl() and AddBookCtrl() to create and add a - different kind of book control. You will then need to use two-step construction - for the dialog or change the style of the book control by calling SetSheetStyle() - before calling Create(). - - The @ref page_samples_dialogs shows this class being used with notebook and toolbook - controllers (for Windows-style and Mac-style settings dialogs). - - To make pages of the dialog scroll when the display is too small to fit the - whole dialog, you can switch layout adaptation on globally with - wxDialog::EnableLayoutAdaptation() or per dialog with - wxDialog::SetLayoutAdaptationMode(). - - For more about layout adaptation, see @ref overview_dialog_autoscrolling. - - @library{wxadv} - @category{managedwnd} -*/ -class wxPropertySheetDialog : public wxDialog -{ -public: - /** - Constructor. - */ - wxPropertySheetDialog(wxWindow* parent, wxWindowID id, - const wxString& title, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = wxDEFAULT_DIALOG_STYLE, - const wxString& name = "dialogBox"); - - /** - Override this if you wish to add the book control in a way different from the - standard way (for example, using different spacing). - */ - virtual void AddBookCtrl(wxSizer* sizer); - - /** - Call this from your own Create function, before adding buttons and pages. - */ - bool Create(wxWindow* parent, wxWindowID id, - const wxString& title, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = wxDEFAULT_DIALOG_STYLE, - const wxString& name = "dialogBox"); - - /** - Override this if you wish to create a different kind of book control; by - default, the value passed to SetSheetStyle() is used to determine the control. - - The default behaviour is to create a notebook except on Smartphone, where a - choicebook is used. - */ - virtual wxBookCtrlBase* CreateBookCtrl(); - - /** - Call this to create the buttons for the dialog. - This calls wxDialog::CreateButtonSizer(), and the flags are the same. - - @note On PocketPC, no buttons are created. - */ - void CreateButtons(int flags = wxOK|wxCANCEL); - - /** - Returns the book control that will contain your settings pages. - */ - wxBookCtrlBase* GetBookCtrl() const; - - /** - Returns the inner sizer that contains the book control and button sizer. - */ - wxSizer* GetInnerSizer() const; - - /** - Returns the sheet style. - - See SetSheetStyle() for allowed values. - */ - long GetSheetStyle() const; - - /** - Call this to lay out the dialog. - - @note On PocketPC, this does nothing, since the dialog will be shown full-screen, - and the layout will be done when the dialog receives a size event. - */ - void LayoutDialog(int centreFlags = wxBOTH); - - /** - Sets the book control used for the dialog. - - You will normally not need to use this. - */ - void SetBookCtrl(wxBookCtrlBase* bookCtrl); - - /** - Sets the inner sizer that contains the book control and button sizer. - - You will normally not need to use this. - */ - void SetInnerSizer(wxSizer* sizer); - - /** - You can customize the look and feel of the dialog by setting the sheet style. - It is a bit list of the ::wxPropertySheetDialogFlags values. - */ - void SetSheetStyle(long style); -}; - diff --git a/interface/protocol/ftp.h b/interface/protocol/ftp.h deleted file mode 100644 index a99c957787..0000000000 --- a/interface/protocol/ftp.h +++ /dev/null @@ -1,285 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: protocol/ftp.h -// Purpose: interface of wxFTP -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - Transfer modes used by wxFTP. -*/ -enum TransferMode -{ - NONE, //!< not set by user explicitly. - ASCII, - BINARY -}; - -/** - @class wxFTP - @headerfile ftp.h wx/protocol/ftp.h - - wxFTP can be used to establish a connection to an FTP server and perform all the - usual operations. Please consult the RFC 959 for more details about the FTP - protocol. - - To use a command which doesn't involve file transfer (i.e. directory oriented - commands) you just need to call a corresponding member function or use the - generic wxFTP::SendCommand() method. - However to actually transfer files you just get or give a stream to or from this - class and the actual data are read or written using the usual stream methods. - - Example of using wxFTP for file downloading: - - @code - wxFTP ftp; - - // if you don't use these lines anonymous login will be used - ftp.SetUser("user"); - ftp.SetPassword("password"); - - if ( !ftp.Connect("ftp.wxwindows.org") ) - { - wxLogError("Couldn't connect"); - return; - } - - ftp.ChDir("/pub"); - wxInputStream *in = ftp.GetInputStream("wxWidgets-4.2.0.tar.gz"); - if ( !in ) - { - wxLogError("Coudln't get file"); - } - else - { - size_t size = in-GetSize(); - char *data = new char[size]; - if ( !in->Read(data, size) ) - { - wxLogError("Read error"); - } - else - { - // file data is in the buffer - ... - } - - delete [] data; - delete in; - } - @endcode - - To upload a file you would do (assuming the connection to the server was opened - successfully): - - @code - wxOutputStream *out = ftp.GetOutputStream("filename"); - if ( out ) - { - out->Write(...); // your data - delete out; - } - @endcode - - @library{wxnet} - @category{net} - - @see wxSocketBase -*/ -class wxFTP : public wxProtocol -{ -public: - /** - Default constructor. - */ - wxFTP(); - - /** - Destructor will close the connection if connected. - */ - ~wxFTP(); - - /** - Aborts the download currently in process, returns @true if ok, @false - if an error occurred. - */ - bool Abort(); - - /** - Change the current FTP working directory. - Returns @true if successful. - */ - bool ChDir(const wxString& dir); - - /** - Send the specified @a command to the FTP server. @a ret specifies - the expected result. - - @return @true if the command has been sent successfully, else @false. - */ - bool CheckCommand(const wxString& command, char ret); - - /** - Returns @true if the given remote file exists, @false otherwise. - */ - bool FileExists(const wxString& filename); - - /** - The GetList() function is quite low-level. It returns the list of the files in - the current directory. The list can be filtered using the @a wildcard string. - - If @a wildcard is empty (default), it will return all files in directory. - The form of the list can change from one peer system to another. For example, - for a UNIX peer system, it will look like this: - - @verbatim - -r--r--r-- 1 guilhem lavaux 12738 Jan 16 20:17 cmndata.cpp - -r--r--r-- 1 guilhem lavaux 10866 Jan 24 16:41 config.cpp - -rw-rw-rw- 1 guilhem lavaux 29967 Dec 21 19:17 cwlex_yy.c - -rw-rw-rw- 1 guilhem lavaux 14342 Jan 22 19:51 cwy_tab.c - -r--r--r-- 1 guilhem lavaux 13890 Jan 29 19:18 date.cpp - -r--r--r-- 1 guilhem lavaux 3989 Feb 8 19:18 datstrm.cpp - @endverbatim - - But on Windows system, it will look like this: - - @verbatim - winamp~1 exe 520196 02-25-1999 19:28 winamp204.exe - 1 file(s) 520 196 bytes - @endverbatim - - @return @true if the file list was successfully retrieved, @false otherwise. - - @see GetFilesList() - */ - bool GetDirList(wxArrayString& files, - const wxString& wildcard = ""); - - /** - Returns the file size in bytes or -1 if the file doesn't exist or the size - couldn't be determined. - - Notice that this size can be approximative size only and shouldn't be used - for allocating the buffer in which the remote file is copied, for example. - */ - int GetFileSize(const wxString& filename); - - /** - This function returns the computer-parsable list of the files in the current - directory (optionally only of the files matching the @e wildcard, all files - by default). - - This list always has the same format and contains one full (including the - directory path) file name per line. - - @return @true if the file list was successfully retrieved, @false otherwise. - - @see GetDirList() - */ - bool GetFilesList(wxArrayString& files, - const wxString& wildcard = ""); - - /** - Creates a new input stream on the specified path. - - You can use all but the seek functionality of wxStreamBase. - wxStreamBase::Seek() isn't available on all streams. For example, HTTP or FTP - streams do not deal with it. Other functions like wxStreamBase::Tell() are - not available for this sort of stream, at present. - - You will be notified when the EOF is reached by an error. - - @return Returns @NULL if an error occurred (it could be a network failure - or the fact that the file doesn't exist). - */ - wxInputStream* GetInputStream(const wxString& path); - - /** - Returns the last command result, i.e. the full server reply for the last command. - */ - const wxString GetLastResult(); - - /** - Initializes an output stream to the specified @e file. - - The returned stream has all but the seek functionality of wxStreams. - When the user finishes writing data, he has to delete the stream to close it. - - @return An initialized write-only stream. - - @see wxOutputStream - */ - wxOutputStream* GetOutputStream(const wxString& file); - - /** - Create the specified directory in the current FTP working directory. - Returns @true if successful. - */ - bool MkDir(const wxString& dir); - - /** - Returns the current FTP working directory. - */ - wxString Pwd(); - - /** - Rename the specified @a src element to @e dst. Returns @true if successful. - */ - bool Rename(const wxString& src, const wxString& dst); - - /** - Remove the specified directory from the current FTP working directory. - Returns @true if successful. - */ - bool RmDir(const wxString& dir); - - /** - Delete the file specified by @e path. Returns @true if successful. - */ - bool RmFile(const wxString& path); - - /** - Send the specified @a command to the FTP server and return the first - character of the return code. - */ - char SendCommand(const wxString& command); - - /** - Sets the transfer mode to ASCII. It will be used for the next transfer. - */ - bool SetAscii(); - - /** - Sets the transfer mode to binary (IMAGE). It will be used for the next transfer. - */ - bool SetBinary(); - - /** - If @a pasv is @true, passive connection to the FTP server is used. - - This is the default as it works with practically all firewalls. - If the server doesn't support passive move, you may call this function with - @false argument to use active connection. - */ - void SetPassive(bool pasv); - - /** - Sets the password to be sent to the FTP server to be allowed to log in. - */ - void SetPassword(const wxString& passwd); - - /** - Sets the transfer mode to the specified one. It will be used for the next - transfer. - - If this function is never called, binary transfer mode is used by default. - */ - bool SetTransferMode(TransferMode mode); - - /** - Sets the user name to be sent to the FTP server to be allowed to log in. - */ - void SetUser(const wxString& user); -}; - diff --git a/interface/protocol/http.h b/interface/protocol/http.h deleted file mode 100644 index 6cd1332ae8..0000000000 --- a/interface/protocol/http.h +++ /dev/null @@ -1,73 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: protocol/http.h -// Purpose: interface of wxHTTP -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxHTTP - @headerfile http.h wx/protocol/http.h - - wxHTTP can be used to establish a connection to an HTTP server. - - @library{wxnet} - @category{net} - - @see wxSocketBase, wxURL -*/ -class wxHTTP : public wxProtocol -{ -public: - /** - Returns the data attached with a field whose name is specified by @e header. - If the field doesn't exist, it will return an empty string and not a @NULL string. - - @note - The header is not case-sensitive, i.e. "CONTENT-TYPE" and "content-type" - represent the same header. - */ - wxString GetHeader(const wxString& header); - - /** - Creates a new input stream on the specified path. - - Notice that this stream is unseekable, i.e. SeekI() and TellI() methods - shouldn't be used. - - Note that you can still know the size of the file you are getting using - wxStreamBase::GetSize(). However there is a limitation: in HTTP protocol, - the size is not always specified so sometimes @c (size_t)-1 can returned to - indicate that the size is unknown. - In such case, you may want to use wxInputStream::LastRead() method in a loop - to get the total size. - - @return Returns the initialized stream. You must delete it yourself - once you don't use it anymore and this must be done before - the wxHTTP object itself is destroyed. The destructor - closes the network connection. The next time you will - try to get a file the network connection will have to - be reestablished, but you don't have to take care of - this since wxHTTP reestablishes it automatically. - - @see wxInputStream - */ - wxInputStream* GetInputStream(const wxString& path); - - /** - Returns the HTTP response code returned by the server. - - Please refer to RFC 2616 for the list of responses. - */ - int GetResponse() const; - - /** - It sets data of a field to be sent during the next request to the HTTP server. - - The field name is specified by @a header and the content by @e h_data. - This is a low level function and it assumes that you know what you are doing. - */ - void SetHeader(const wxString& header, const wxString& h_data); -}; - diff --git a/interface/protocol/protocol.h b/interface/protocol/protocol.h deleted file mode 100644 index af8d45e12e..0000000000 --- a/interface/protocol/protocol.h +++ /dev/null @@ -1,98 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: protocol/protocol.h -// Purpose: interface of wxProtocol -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - Error values returned by wxProtocol. -*/ -enum wxProtocolError -{ - wxPROTO_NOERR = 0, //!< No error. - wxPROTO_NETERR, //!< A generic network error occurred. - wxPROTO_PROTERR, //!< An error occurred during negotiation. - wxPROTO_CONNERR, //!< The client failed to connect the server. - wxPROTO_INVVAL, //!< Invalid value. - wxPROTO_NOHNDLR, //!< Not currently used. - wxPROTO_NOFILE, //!< The remote file doesn't exist. - wxPROTO_ABRT, //!< Last action aborted. - wxPROTO_RCNCT, //!< An error occurred during reconnection. - wxPROTO_STREAMING //!< Someone tried to send a command during a transfer. -}; - -/** - @class wxProtocol - @headerfile protocol.h wx/protocol/protocol.h - - Represents a protocol for use with wxURL. - - @library{wxnet} - @category{net} - - @see wxSocketBase, wxURL -*/ -class wxProtocol : public wxSocketClient -{ -public: - /** - Abort the current stream. - - @warning - It is advised to destroy the input stream instead of aborting the stream - this way. - - @return Returns @true, if successful, else @false. - */ - bool Abort(); - - /** - Returns the type of the content of the last opened stream. It is a mime-type. - */ - wxString GetContentType(); - - /** - Returns the last occurred error. - - @see wxProtocolError - */ - wxProtocolError GetError(); - - /** - Creates a new input stream on the specified path. - - You can use all but seek() functionality of wxStream. - Seek() isn't available on all streams. For example, HTTP or FTP streams - don't deal with it. Other functions like StreamSize() and Tell() aren't - available for the moment for this sort of stream. - You will be notified when the EOF is reached by an error. - - @return Returns the initialized stream. You will have to delete it - yourself once you don't use it anymore. The destructor - closes the network connection. - - @see wxInputStream - */ - wxInputStream* GetInputStream(const wxString& path); - - /** - Tries to reestablish a previous opened connection (close and renegotiate - connection). - - @return @true, if the connection is established, else @false. - */ - bool Reconnect(); - - /** - Sets the authentication password. It is mainly useful when FTP is used. - */ - void SetPassword(const wxString& user); - - /** - Sets the authentication user. It is mainly useful when FTP is used. - */ - void SetUser(const wxString& user); -}; - diff --git a/interface/ptr_scpd.h b/interface/ptr_scpd.h deleted file mode 100644 index 11180b1a55..0000000000 --- a/interface/ptr_scpd.h +++ /dev/null @@ -1,368 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: ptr_scpd.h -// Purpose: interface of wxScopedPtr -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxScopedPtr - @wxheader{ptr_scpd.h} - - This is a simple scoped smart pointer implementation that is similar to - the Boost smart pointers (see http://www.boost.org) but rewritten - to use macros instead. - - Since wxWidgets 2.9.0 there is also a templated version of this class - with the same name. See wxScopedPtr. - - A smart pointer holds a pointer to an object. The memory used by the object is - deleted when the smart pointer goes out of scope. This class is different from - the @c std::auto_ptr<> in so far as it doesn't provide copy constructor - nor assignment operator. This limits what you can do with it but is much less - surprizing than the "destructive copy" behaviour of the standard class. - - @b Example: - - Below is an example of using a wxWidgets scoped smart pointer and pointer array. - - @code - class MyClass{ ... }; - - // declare a smart pointer to a MyClass called wxMyClassPtr - wxDECLARE_SCOPED_PTR(MyClass, wxMyClassPtr) - // declare a smart pointer to an array of chars - wxDECLARE_SCOPED_ARRAY(char, wxCharArray) - - ... - - // define the first pointer class, must be complete - wxDEFINE_SCOPED_PTR(MyClass, wxMyClassPtr) - // define the second pointer class - wxDEFINE_SCOPED_ARRAY(char, wxCharArray) - - // create an object with a new pointer to MyClass - wxMyClassPtr theObj(new MyClass()); - // reset the pointer (deletes the previous one) - theObj.reset(new MyClass()); - - // access the pointer - theObj->MyFunc(); - - // create an object with a new array of chars - wxCharArray theCharObj(new char[100]); - - // access the array - theCharObj[0] = "!"; - @endcode - - @section wxscopedptr_newpointers Declaring new smart pointer types - - To declare the smart pointer class @c CLASSNAME containing pointes to - a (possibly incomplete) type @c TYPE you should use - @code - wxDECLARE_SCOPED_PTR( TYPE, // type of the values - CLASSNAME ); // name of the class - @endcode - And later, when @c TYPE is fully defined, you must also use - @code - wxDEFINE_SCOPED_PTR( TYPE, CLASSNAME ); - @endcode - to implement the scoped pointer class. - - The first argument of these macro is the pointer type, the second is the name - of the new smart pointer class being created. Below we will use wxScopedPtr - to represent the scoped pointer class, but the user may create the class with - any legal name. - - Alternatively, if you don't have to separate the point of declaration and - definition of this class and if you accept the standard naming convention, - that is that the scoped pointer for the class @c Foo is called @c FooPtr, - you can use a single macro which replaces two macros above: - @code - wxDEFINE_SCOPED_PTR_TYPE( TYPE ); - @endcode - Once again, in this cass @c CLASSNAME will be @c TYPEPtr. - - @library{wxbase} - @category{smartpointers} - - @see wxScopedArray -*/ -class wxScopedPtr -{ -public: - /** - Creates the smart pointer with the given pointer or none if @NULL. - - On compilers that support it, this uses the explicit keyword. - */ - explicit wxScopedPtr(type* T = NULL); - - /** - Destructor frees the pointer help by this object if it is not @NULL. - */ - ~wxScopedPtr(); - - /** - This operator gets the pointer stored in the smart pointer or returns - @NULL if there is none. - */ - const T* get(); - - /** - This operator works like the standard C++ pointer operator to return the object - being pointed to by the pointer. - - @note - If the pointer is @NULL or invalid this will crash. - */ - const T& operator *(); - - /** - This operator works like the standard C++ pointer operator to return the pointer - in the smart pointer or @NULL if it is empty. - */ - const T* operator ->(); - - /** - Returns the currently hold pointer and resets the smart pointer object to - @NULL. - - @remarks - After a call to this function the caller is responsible for deleting the - pointer. - */ - T* release(); - - /** - Deletes the currently held pointer and sets it to @a p or to @NULL if no - arguments are specified. - - @note - This function does check to make sure that the pointer you are assigning - is not the same pointer that is already stored. - */ - reset(T* p = NULL); - - /** - Swap the pointer inside the smart pointer with @a other. The pointer being - swapped must be of the same type (hence the same class name). - */ - swap(wxScopedPtr& other); -}; - - - -/** - @class wxScopedArray - @wxheader{ptr_scpd.h} - - This is a simple scoped smart pointer array implementation that is similar to - the Boost smart pointers (see http://www.boost.org/) but rewritten to - use macros instead. - - @b Example: - - Below is an example of using a wxWidgets scoped smart pointer and pointer array. - - @code - class MyClass { ... }; - - // declare a smart pointer to a MyClass called wxMyClassPtr - wxDECLARE_SCOPED_PTR(MyClass, wxMyClassPtr) - // declare a smart pointer to an array of chars - wxDECLARE_SCOPED_ARRAY(char, wxCharArray) - - ... - - // define the first pointer class, must be complete - wxDEFINE_SCOPED_PTR(MyClass, wxMyClassPtr) - // define the second pointer class - wxDEFINE_SCOPED_ARRAY(char, wxCharArray) - - // create an object with a new pointer to MyClass - wxMyClassPtr theObj(new MyClass()); - // reset the pointer (deletes the previous one) - theObj.reset(new MyClass()); - - // access the pointer - theObj->MyFunc(); - - // create an object with a new array of chars - wxCharArray theCharObj(new char[100]); - - // access the array - theCharObj[0] = "!"; - @endcode - - Declaring new smart pointer types: - @code - wxDECLAR_SCOPED_ARRAY( TYPE, // type of the values - CLASSNAME ); // name of the class - @endcode - - A smart pointer holds a pointer to an object (which must be complete when - wxDEFINE_SCOPED_ARRAY() is called). - - The memory used by the object is deleted when the smart pointer goes out of - scope. The first argument of the macro is the pointer type, the second is the - name of the new smart pointer class being created. Below we will use wxScopedArray - to represent the scoped pointer array class, but the user may create the class with - any legal name. - - @library{wxbase} - @category{smartpointers} - - @see wxScopedPtr -*/ -class wxScopedArray -{ -public: - /** - Creates the smart pointer with the given pointer or none if @NULL. On - compilers that support it, this uses the explicit keyword. - */ - wxScopedArray(type* T = NULL); - - /** - This operator gets the pointer stored in the smart pointer or returns @NULL if - there is none. - */ - const T* get(); - - /** - This operator acts like the standard [] indexing operator for C++ arrays. The - function does not do bounds checking. - */ - const T& operator [](long int i); - - /** - Deletes the currently held pointer and sets it to 'p' or to @NULL if no - arguments are specified. This function does check to make sure that the - pointer you are assigning is not the same pointer that is already stored. - */ - reset(T* p = NULL); - - /** - Swap the pointer inside the smart pointer with @a ot. The pointer being swapped - must be of the same type (hence the same class name). - */ - swap(wxScopedPtr& ot); -}; - - - -/** - @class wxScopedTiedPtr - @wxheader{ptr_scpd.h} - - This is a variation on the topic of wxScopedPtr. This class is also a smart pointer - but in addition it "ties" the pointer value to another variable. In other words, - during the life time of this class the value of that variable is set to be the same - as the value of the pointer itself and it is reset to its old value when the object - is destroyed. This class is especially useful when converting the existing code - (which may already store the pointers value in some variable) to the smart pointers. - - @library{wxbase} - @category{smartpointers} -*/ -class wxScopedTiedPtr : public wxScopedPtr -{ -public: - /** - Constructor creates a smart pointer initialized with @a ptr and stores - @a ptr in the location specified by @a ppTie which must not be @NULL. - */ - wxScopedTiedPtr(T** ppTie, T* ptr); - - /** - Destructor frees the pointer help by this object and restores the value stored - at the tied location (as specified in the @ref ctor() constructor) - to the old value. - - @warning - This location may now contain an uninitialized value if it hadn't been - initialized previously, in particular don't count on it magically being @NULL! - */ - ~wxScopedTiedPtr(); -}; - - - -/** - @wxheader{ptr_scpd.h} - - A scoped pointer template class. It is the template version of - the old-style @ref classwx_scoped_ptr "scoped pointer macros". - - @library{wxbase} - @category{smartpointers} - - @see wxSharedPtr, wxWeakRef -*/ -template -class wxScopedPtr -{ -public: - /** - Constructor. - */ - wxScopedPtr(T* ptr = NULL); - - /** - Destructor. - */ - ~wxScopedPtr(); - - /** - Returns pointer to object or @NULL. - */ - T* get() const; - - /** - Conversion to a boolean expression (in a variant which is not - convertable to anything but a boolean expression). - - If this class contains a valid pointer it will return @true, if it contains - a @NULL pointer it will return @false. - */ - operator unspecified_bool_type() const; - - /** - Returns a reference to the object. - - @note - If the internal pointer is @NULL this method will cause an assert - in debug mode. - */ - T operator*() const; - - /** - Returns pointer to object. If the pointer is @NULL this method will - cause an assert in debug mode. - */ - T* operator->() const; - - /** - Releases the current pointer and returns it. - - @remarks - Afterwards the caller is responsible for deleting - the data contained in the scoped pointer before. - */ - T* release(); - - /** - Reset pointer to the value of @a ptr. - The previous pointer will be deleted. - */ - void reset(T* ptr = NULL); - - /** - Swaps pointers. - */ - void swap(wxScopedPtr& ot); -}; - diff --git a/interface/ptr_shrd.h b/interface/ptr_shrd.h deleted file mode 100644 index ab24ca063f..0000000000 --- a/interface/ptr_shrd.h +++ /dev/null @@ -1,102 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: ptr_shrd.h -// Purpose: interface of wxSharedPtr -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @wxheader{ptr_shrd.h} - - A smart pointer with non-intrusive reference counting. It is modeled after - @c boost::shared_ptr<> and can be used with STL containers and wxVector - - unlike @c std::auto_ptr<> and wxScopedPtr. - - @library{wxbase} - @category{smartpointers} - - @see wxScopedPtr, wxWeakRef, wxObjectDataPtr -*/ - -template -class wxSharedPtr -{ -public: - /** - Constructor. - - Creates shared pointer from the raw pointer @a ptr and takes ownership - of it. - */ - wxEXPLICIT wxSharedPtr(T* ptr = NULL); - - /** - Copy constructor. - */ - wxSharedPtr(const wxSharedPtr& tocopy); - - /** - Destructor. - */ - ~wxSharedPtr(); - - /** - Returns pointer to its object or @NULL. - */ - T* get() const; - - /** - Conversion to a boolean expression (in a variant which is not - convertable to anything but a boolean expression). - - If this class contains a valid pointer it will return @true, if it contains - a @NULL pointer it will return @false. - */ - operator unspecified_bool_type() const; - - /** - Returns a reference to the object. - - If the internal pointer is @NULL this method will cause an assert in debug mode. - */ - T operator*() const; - - /** - Returns pointer to its object or @NULL. - */ - T* operator->() const; - - /** - Assignment operator. - - Releases any previously held pointer and creates a reference to @a ptr. - */ - wxSharedPtr& operator=(T* ptr); - - /** - Assignment operator. - - Releases any previously held pointer and creates a reference to the - same object as @a topcopy. - */ - wxSharedPtr& operator=(const wxSharedPtr& tocopy) - - /** - Reset pointer to @a ptr. - - If the reference count of the previously owned pointer was 1 it will be deleted. - */ - void reset(T* ptr = NULL); - - /** - Returns @true if this is the only pointer pointing to its object. - */ - bool unique() const; - - /** - Returns the number of pointers pointing to its object. - */ - long use_count() const; -}; - diff --git a/interface/quantize.h b/interface/quantize.h deleted file mode 100644 index eeea5bcad9..0000000000 --- a/interface/quantize.h +++ /dev/null @@ -1,66 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: quantize.h -// Purpose: interface of wxQuantize -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxQuantize - @wxheader{quantize.h} - - Performs quantization, or colour reduction, on a wxImage. - - Functions in this class are static and so a wxQuantize object need not be - created. - - @library{wxcore} - @category{misc} -*/ -class wxQuantize : public wxObject -{ -public: - /** - Constructor. You do not need to construct a wxQuantize object since its - functions are static. - */ - wxQuantize(); - - /** - Converts input bitmap(s) into 8bit representation with custom palette. - @a in_rows and @a out_rows are arrays [0..h-1] of pointer to rows - (@a in_rows contains @a w * 3 bytes per row, @a out_rows @a w bytes per row). - Fills @a out_rows with indexes into palette (which is also stored into @a palette - variable). - */ - void DoQuantize(unsigned w, unsigned h, unsigned char** in_rows, - unsigned char** out_rows, unsigned char* palette, - int desiredNoColours); - - /** - Reduce the colours in the source image and put the result into the destination image. - Both images may be the same, to overwrite the source image. - - Specify an optional palette pointer to receive the resulting palette. - This palette may be passed to ConvertImageToBitmap, for example. - */ - bool Quantize(const wxImage& src, wxImage& dest, - wxPalette** pPalette, int desiredNoColours = 236, - unsigned char** eightBitData = 0, - int flags = wxQUANTIZE_INCLUDE_WINDOWS_COLOURS - |wxQUANTIZE_FILL_DESTINATION_IMAGE - |wxQUANTIZE_RETURN_8BIT_DATA); - - /** - This version sets a palette in the destination image so you don't - have to manage it yourself. - */ - bool Quantize(const wxImage& src, wxImage& dest, - int desiredNoColours = 236, - unsigned char** eightBitData = 0, - int flags = wxQUANTIZE_INCLUDE_WINDOWS_COLOURS - |wxQUANTIZE_FILL_DESTINATION_IMAGE - |wxQUANTIZE_RETURN_8BIT_DATA); -}; - diff --git a/interface/radiobox.h b/interface/radiobox.h deleted file mode 100644 index 2aeb3772fa..0000000000 --- a/interface/radiobox.h +++ /dev/null @@ -1,318 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: radiobox.h -// Purpose: interface of wxRadioBox -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxRadioBox - @wxheader{radiobox.h} - - A radio box item is used to select one of number of mutually exclusive - choices. It is displayed as a vertical column or horizontal row of - labelled buttons. - - @beginStyleTable - @style{wxRA_SPECIFY_ROWS} - The major dimension parameter refers to the maximum number of rows. - @style{wxRA_SPECIFY_COLS} - The major dimension parameter refers to the maximum number of - columns. - @style{wxRA_USE_CHECKBOX} - Use of the checkbox controls instead of radio buttons (currently - supported only on PalmOS) - @endStyleTable - - @beginEventTable{wxCommandEvent} - @event{EVT_RADIOBOX(id, func)} - Process a @c wxEVT_COMMAND_RADIOBOX_SELECTED event, when a radiobutton - is clicked. - @endEventTable - - @library{wxcore} - @category{ctrl} - - - @see @ref overview_eventhandling, wxRadioButton, wxCheckBox -*/ -class wxRadioBox : public wxControl, wxItemContainerImmutable -{ -public: - - /** - Default constructor. - - @see Create(), wxValidator - */ - wxRadioBox(); - - /** - Constructor, creating and showing a radiobox. - - @param parent - Parent window. Must not be @NULL. - @param id - Window identifier. The value @c wxID_ANY indicates a default value. - @param label - Label for the static box surrounding the radio buttons. - @param pos - Window position. If @c wxDefaultPosition is specified then a - default position is chosen. - @param size - Window size. If @c wxDefaultSize is specified then a default size - is chosen. - @param n - Number of choices with which to initialize the radiobox. - @param choices - An array of choices with which to initialize the radiobox. - @param majorDimension - Specifies the maximum number of rows (if style contains - @c wxRA_SPECIFY_ROWS) or columns (if style contains - @c wxRA_SPECIFY_COLS) for a two-dimensional radiobox. - @param style - Window style. See wxRadioBox. - @param validator - Window validator. - @param name - Window name. - - @see Create(), wxValidator - */ - wxRadioBox(wxWindow* parent, wxWindowID id, - const wxString& label, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - int n = 0, - const wxString choices[] = NULL, - int majorDimension = 0, - long style = wxRA_SPECIFY_COLS, - const wxValidator& validator = wxDefaultValidator, - const wxString& name = "radioBox"); - - /** - Constructor, creating and showing a radiobox. - - @param parent - Parent window. Must not be @NULL. - @param id - Window identifier. The value @c wxID_ANY indicates a default value. - @param label - Label for the static box surrounding the radio buttons. - @param pos - Window position. If @c wxDefaultPosition is specified then a - default position is chosen. - @param size - Window size. If @c wxDefaultSize is specified then a default size - is chosen. - @param choices - An array of choices with which to initialize the radiobox. - @param majorDimension - Specifies the maximum number of rows (if style contains - @c wxRA_SPECIFY_ROWS) or columns (if style contains - @c wxRA_SPECIFY_COLS) for a two-dimensional radiobox. - @param style - Window style. See wxRadioBox. - @param validator - Window validator. - @param name - Window name. - - @see Create(), wxValidator - */ - wxRadioBox(wxWindow* parent, wxWindowID id, - const wxString& label, - const wxPoint& pos, - const wxSize& size, - const wxArrayString& choices, - int majorDimension = 0, - long style = wxRA_SPECIFY_COLS, - const wxValidator& validator = wxDefaultValidator, - const wxString& name = "radioBox"); - - /** - Destructor, destroying the radiobox item. - */ - ~wxRadioBox(); - - /** - Creates the radiobox for two-step construction. See wxRadioBox() - for further details. - */ - bool Create(wxWindow* parent, wxWindowID id, - const wxString& label, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - int n = 0, - const wxString choices[] = NULL, - int majorDimension = 0, - long style = wxRA_SPECIFY_COLS, - const wxValidator& validator = wxDefaultValidator, - const wxString& name = "radioBox"); - - /** - Creates the radiobox for two-step construction. See wxRadioBox() - for further details. - */ - bool Create(wxWindow* parent, wxWindowID id, - const wxString& label, - const wxPoint& pos, - const wxSize& size, - const wxArrayString& choices, - int majorDimension = 0, - long style = wxRA_SPECIFY_COLS, - const wxValidator& validator = wxDefaultValidator, - const wxString& name = "radioBox"); - - /** - Enables or disables an individual button in the radiobox. - - @param enable - @true to enable, @false to disable. - @param n - The zero-based button to enable or disable. - - @see wxWindow::Enable() - - @beginWxPythonOnly - In place of a single overloaded method name, wxPython implements the following methods: - - @beginTable - @row2col{Enable(flag), Enables or disables the entire radiobox.} - @row2col{EnableItem(n\, flag), Enables or disables an individual button in the radiobox.} - @endTable - - @endWxPythonOnly - */ - virtual bool Enable(unsigned int n, bool enable = true); - - - /** - Finds a button matching the given string, returning the position if found, or - -1 if not found. - - @param string - The string to find. - */ - int FindString(const wxString& string) const; - - /** - Returns the number of columns in the radiobox. - */ - unsigned int GetColumnCount() const; - - /** - Returns a radio box item under the point, a zero-based item index, or @c - wxNOT_FOUND if no item is under the point. - - @param pt - Point in client coordinates. - */ - int GetItemFromPoint(const wxPoint pt) const; - - /** - Returns the helptext associated with the specified @a item if any or @c - wxEmptyString. - - @param item - The zero-based item index. - - @see SetItemHelpText() - */ - wxString GetItemHelpText(unsigned int item) const; - - /** - Returns the tooltip associated with the specified @a item if any or @NULL. - - @see SetItemToolTip(), wxWindow::GetToolTip() - */ - wxToolTip* GetItemToolTip(unsigned int item) const; - - /** - Returns the number of rows in the radiobox. - */ - unsigned int GetRowCount() const; - - /** - Returns @true if the item is enabled or @false if it was disabled using - @ref Enable(unsigned int,bool) "Enable(n, false)". - - This function is currently only implemented in wxMSW, wxGTK and - wxUniversal and always returns @true in the other ports. - - @param n - The zero-based button position. - */ - bool IsItemEnabled(unsigned int n) const; - - /** - Returns @true if the item is currently shown or @false if it was hidden - using @ref Show(unsigned int,bool) "Show(n, false)". - - Note that this function returns @true for an item which hadn't been hidden - even if the entire radiobox is not currently shown. - - This function is currently only implemented in wxMSW, wxGTK and - wxUniversal and always returns @true in the other ports. - - @param n - The zero-based button position. - */ - bool IsItemShown(unsigned int n) const; - - /** - Sets the helptext for an item. Empty string erases any existing helptext. - - @param item - The zero-based item index. - @param helptext - The help text to set for the item. - - @see GetItemHelpText() - */ - void SetItemHelpText(unsigned int item, const wxString& helptext); - - /** - Sets the tooltip text for the specified item in the radio group. - - This function is currently only implemented in wxMSW and wxGTK2 and - does nothing in the other ports. - - @param item - Index of the item the tooltip will be shown for. - @param text - Tooltip text for the item, the tooltip is removed if empty. - - @see GetItemToolTip(), wxWindow::SetToolTip() - */ - void SetItemToolTip(unsigned int item, const wxString& text); - - /** - Shows or hides individual buttons. - - @param show - @true to show, @false to hide. - @param item - The zero-based position of the button to show or hide. - - @return - @true if the item has been shown or hidden or @false if nothing - was done because it already was in the requested state. - - @see - wxWindow::Show() - - @beginWxPythonOnly - In place of a single overloaded method name, wxPython implements the following methods: - - @beginTable - @row2col{Show(flag), Shows or hides the entire radiobox.} - @row2col{ShowItem(n\, flag), Shows or hides individual buttons.} - @endTable - - @endWxPythonOnly - - */ - virtual bool Show(unsigned int item, const bool show = true); -}; diff --git a/interface/radiobut.h b/interface/radiobut.h deleted file mode 100644 index dfce977c50..0000000000 --- a/interface/radiobut.h +++ /dev/null @@ -1,120 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: radiobut.h -// Purpose: interface of wxRadioButton -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxRadioButton - @wxheader{radiobut.h} - - A radio button item is a button which usually denotes one of several - mutually exclusive options. It has a text label next to a (usually) round - button. - - You can create a group of mutually-exclusive radio buttons by specifying - @c wxRB_GROUP for the first in the group. The group ends when another - radio button group is created, or there are no more radio buttons. - - @beginStyleTable - @style{wxRB_GROUP} - Marks the beginning of a new group of radio buttons. - @style{wxRB_SINGLE} - In some circumstances, radio buttons that are not consecutive - siblings trigger a hang bug in Windows (only). If this happens, add - this style to mark the button as not belonging to a group, and - implement the mutually-exclusive group behaviour yourself. - @style{wxRB_USE_CHECKBOX} - Use a checkbox button instead of radio button (currently supported - only on PalmOS). - @endStyleTable - - @beginEventTable{wxCommandEvent} - @event{EVT_RADIOBUTTON(id, func)} - Process a @c wxEVT_COMMAND_RADIOBUTTON_SELECTED event, when the - radiobutton is clicked. - @endEventTable - - @library{wxcore} - @category{ctrl} - - - @see @ref overview_eventhandling, wxRadioBox, wxCheckBox -*/ -class wxRadioButton : public wxControl -{ -public: - - /** - Default constructor. - - @see Create(), wxValidator - */ - wxRadioButton(); - - /** - Constructor, creating and showing a radio button. - - @param parent - Parent window. Must not be @NULL. - @param id - Window identifier. The value @c wxID_ANY indicates a default value. - @param label - Label for the radio button. - @param pos - Window position. If @c wxDefaultPosition is specified then a default - position is chosen. - @param size - Window size. If @c wxDefaultSize is specified then a default size - is chosen. - @param style - Window style. See wxRadioButton. - @param validator - Window validator. - @param name - Window name. - - @see Create(), wxValidator - */ - wxRadioButton(wxWindow* parent, wxWindowID id, - const wxString& label, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = 0, - const wxValidator& validator = wxDefaultValidator, - const wxString& name = "radioButton"); - - /** - Destructor, destroying the radio button item. - */ - ~wxRadioButton(); - - /** - Creates the choice for two-step construction. See wxRadioButton() for - further details. - */ - bool Create(wxWindow* parent, wxWindowID id, - const wxString& label, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = 0, - const wxValidator& validator = wxDefaultValidator, - const wxString& name = "radioButton"); - - /** - Returns @true if the radio button is depressed, @false otherwise. - */ - bool GetValue() const; - - /** - Sets the radio button to selected or deselected status. This does not cause a - @c wxEVT_COMMAND_RADIOBUTTON_SELECTED event to get emitted. - - @param value - @true to select, @false to deselect. - */ - void SetValue(const bool value); -}; - diff --git a/interface/rawbmp.h b/interface/rawbmp.h deleted file mode 100644 index df9ac84567..0000000000 --- a/interface/rawbmp.h +++ /dev/null @@ -1,215 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: rawbmp.h -// Purpose: interface of wxPixelData -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxPixelData - @wxheader{rawbmp.h} - - A class template with ready to use implementations for getting - direct and efficient access to wxBitmap's internal data and - wxImage's internal data through a standard interface. It is - possible to extend this class (interface) to other types of - image content. - - Implemented on Windows, GTK+ and OS X: - @li wxNativePixelData: Class to access to wxBitmap's internal data - without alpha channel (RGB). - @li wxAlphaPixelData: Class to access to wxBitmap's internal data with - alpha channel (RGBA). - - Implemented everywhere: - @li wxImagePixelData: Class to access to wxImage's internal data with - alpha channel (RGBA). - - Example: - - @code - wxBitmap bmp; - wxNativePixelData data(bmp); - if ( !data ) - { - // ... raw access to bitmap data unavailable, do something else ... - return; - } - - if ( data.GetWidth() < 20 || data.GetHeight() < 20 ) - { - // ... complain: the bitmap it too small ... - return; - } - - wxNativePixelData::Iterator p(data); - - // we draw a (10, 10)-(20, 20) rect manually using the given r, g, b - p.Offset(data, 10, 10); - - for ( int y = 0; y < 10; ++y ) - { - wxNativePixelData::Iterator rowStart = p; - - for ( int x = 0; x < 10; ++x, ++p ) - { - p.Red() = r; - p.Green() = g; - p.Blue() = b; - } - - p = rowStart; - p.OffsetY(data, 1); - } - @endcode - - @library{wxcore} - @category{gdi} - - @see wxBitmap, wxImage -*/ -template > -class wxPixelData : - public wxPixelDataOut::template wxPixelDataIn -{ -public: - /** - The type of the class we're working with. - */ - typedef Image ImageType; - - /** - Create pixel data object representing the entire image. - */ - wxPixelData(Image& image); - - - /** - Create pixel data object representing the area of the image defined by - @a rect. - */ - wxPixelData(Image& i, const wxRect& rect); - - /** - Create pixel data object representing the area of the image defined by - @a pt and @a sz. - */ - wxPixelData(Image& i, const wxPoint& pt, const wxSize& sz) - - /** - Return @true of if we could get access to bitmap data successfully. - */ - operator bool() const: - - /** - Return the iterator pointing to the origin of the image. - */ - Iterator GetPixels() const; - - /** - Returns origin of the rectangular region this wxPixelData represents. - */ - wxPoint GetOrigin() const; - - /** - Return width of the region this wxPixelData represents. - */ - int GetWidth() const; - - /** - Return height of the region this wxPixelData represents. - */ - int GetHeight() const; - - /** - Return the area which this wxPixelData represents in the image. - */ - wxSize GetSize() const; - - /** - Return the distance between two rows. - */ - int GetRowStride() const; - - - /** - The iterator of class wxPixelData. - */ - class Iterator - { - public: - - /** - Reset the iterator to point to (0, 0). - */ - void Reset(const PixelData& data); - - /** - Initializes the iterator to point to the origin of the given pixel - data. - */ - Iterator(PixelData& data); - - /** - Initializes the iterator to point to the origin of the given Bitmap. - */ - Iterator(wxBitmap& bmp, PixelData& data); - - /** - Default constructor. - */ - Iterator(); - - /** - Return @true if this iterator is valid. - */ - bool IsOk() const; - - /** - Advance the iterator to the next pixel, prefix version. - */ - Iterator& operator++(); - - /** - Advance the iterator to the next pixel, postfix (hence less - efficient -- don't use it unless you absolutely must) version. - */ - Iterator operator++(int); - - /** - Move @a x pixels to the right and @a y down. - - @note The rows won't wrap automatically. - */ - void Offset(const PixelData& data, int x, int y); - - /** - Move @a x pixels to the right. - - @note The rows won't wrap automatically. - */ - void OffsetX(const PixelData&data, int x); - - /** - Move @a y rows to the bottom - */ - void OffsetY(const PixelData& data, int y); - - /** - Go to the given position - */ - void MoveTo(const PixelData& data, int x, int y); - - //@{ - /** - Data Access: Access to invidividual colour components. - */ - ChannelType& Red(); - ChannelType& Green(); - ChannelType& Blue(); - ChannelType& Alpha(); - //@} - }; -}; - diff --git a/interface/recguard.h b/interface/recguard.h deleted file mode 100644 index d646798f41..0000000000 --- a/interface/recguard.h +++ /dev/null @@ -1,100 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: recguard.h -// Purpose: interface of wxRecursionGuardFlag -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxRecursionGuardFlag - @wxheader{recguard.h} - - This is a completely opaque class which exists only to be used with - wxRecursionGuard, please see the example in that class' documentation. - - @remarks - - wxRecursionGuardFlag object must be declared @c static or the recursion - would never be detected. - - @library{wxbase} - @category{misc} -*/ -class wxRecursionGuardFlag -{ -public: - -}; - - - -/** - @class wxRecursionGuard - @wxheader{recguard.h} - - wxRecursionGuard is a very simple class which can be used to prevent reentrancy - problems in a function. It is not thread-safe and so should be used only in - single-threaded programs or in combination with some thread synchronization - mechanisms. - - wxRecursionGuard is always used together with the - wxRecursionGuardFlag like in this example: - - @code - void Foo() - { - static wxRecursionGuardFlag s_flag; - wxRecursionGuard guard(s_flag); - if ( guard.IsInside() ) - { - // don't allow reentrancy - return; - } - - ... - } - @endcode - - As you can see, wxRecursionGuard simply tests the flag value and sets it to - @true if it hadn't been already set. - IsInside() allows testing the old flag - value. The advantage of using this class compared to directly manipulating the - flag is that the flag is always reset in the wxRecursionGuard destructor and so - you don't risk to forget to do it even if the function returns in an unexpected - way (for example because an exception has been thrown). - - @library{wxbase} - @category{misc} -*/ -class wxRecursionGuard -{ -public: - /** - A wxRecursionGuard object must always be initialized with a @c static - wxRecursionGuardFlag. The constructor saves the - value of the flag to be able to return the correct value from - IsInside(). - */ - wxRecursionGuard(wxRecursionGuardFlag& flag); - - /** - The destructor resets the flag value so that the function can be entered again - the next time. - - @note This is not virtual, so this class is not meant to be derived - from (besides, there is absolutely no reason to do it anyhow). - */ - ~wxRecursionGuard(); - - /** - Returns @true if we're already inside the code block "protected" by this - wxRecursionGuard (i.e. between this line and the end of current scope). - Usually the function using wxRecursionGuard takes some specific actions - in such case (may be simply returning) to prevent reentrant calls to itself. - - If this method returns @false, it is safe to continue. - */ - bool IsInside() const; -}; - diff --git a/interface/regex.h b/interface/regex.h deleted file mode 100644 index a61eaf28a4..0000000000 --- a/interface/regex.h +++ /dev/null @@ -1,246 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: regex.h -// Purpose: interface of wxRegEx -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @anchor wxRE_FLAGS - - Flags for regex compilation to be used with wxRegEx::Compile(). -*/ -enum -{ - /** Use extended regex syntax. */ - wxRE_EXTENDED = 0, - - /** Use advanced RE syntax (built-in regex only). */ - wxRE_ADVANCED = 1, - - /** Use basic RE syntax. */ - wxRE_BASIC = 2, - - /** Ignore case in match. */ - wxRE_ICASE = 4, - - /** Only check match, don't set back references. */ - wxRE_NOSUB = 8, - - /** - If not set, treat '\n' as an ordinary character, otherwise it is - special: it is not matched by '.' and '^' and '$' always match - after/before it regardless of the setting of wxRE_NOT[BE]OL. - */ - wxRE_NEWLINE = 16, - - /** Default flags.*/ - wxRE_DEFAULT = wxRE_EXTENDED -}; - -/** - @anchor wxRE_NOT_FLAGS - - Flags for regex matching to be used with wxRegEx::Matches(). - These flags are mainly useful when doing several matches in a long string - to prevent erroneous matches for '^' and '$': -*/ -enum -{ - /** '^' doesn't match at the start of line. */ - wxRE_NOTBOL = 32, - - /** '$' doesn't match at the end of line. */ - wxRE_NOTEOL = 64 -}; - -/** - @class wxRegEx - @wxheader{regex.h} - - wxRegEx represents a regular expression. This class provides support - for regular expressions matching and also replacement. - - It is built on top of either the system library (if it has support - for POSIX regular expressions - which is the case of the most modern - Unices) or uses the built in Henry Spencer's library. Henry Spencer - would appreciate being given credit in the documentation of software - which uses his library, but that is not a requirement. - - Regular expressions, as defined by POSIX, come in two flavours: @e extended - and @e basic. The builtin library also adds a third flavour - of expression @ref overview_resyntax "advanced", which is not available - when using the system library. - - Unicode is fully supported only when using the builtin library. - When using the system library in Unicode mode, the expressions and data - are translated to the default 8-bit encoding before being passed to - the library. - - On platforms where a system library is available, the default is to use - the builtin library for Unicode builds, and the system library otherwise. - It is possible to use the other if preferred by selecting it when building - the wxWidgets. - - @library{wxbase} - @category{data} - - Examples: - - A bad example of processing some text containing email addresses (the example - is bad because the real email addresses can have more complicated form than - @c user@host.net): - - @code - wxString text; - ... - wxRegEx reEmail = wxT("([^@]+)@([[:alnum:].-_].)+([[:alnum:]]+)"); - if ( reEmail.Matches(text) ) - { - wxString text = reEmail.GetMatch(email); - wxString username = reEmail.GetMatch(email, 1); - if ( reEmail.GetMatch(email, 3) == wxT("com") ) // .com TLD? - { - ... - } - } - - // or we could do this to hide the email address - size_t count = reEmail.ReplaceAll(text, wxT("HIDDEN@\\2\\3")); - printf("text now contains %u hidden addresses", count); - @endcode -*/ -class wxRegEx -{ -public: - - /** - Default constructor: use Compile() later. - */ - wxRegEx(); - - /** - Create and compile the regular expression, use - IsValid() to test for compilation errors. - - As for the flags, please see @ref wxRE_FLAGS. - */ - wxRegEx(const wxString& expr, int flags = wxRE_DEFAULT); - - - /** - Destructor. It's not virtual, don't derive from this class. - */ - ~wxRegEx(); - - /** - Compile the string into regular expression, return @true if ok or @false - if string has a syntax error. - - As for the flags, please see @ref wxRE_FLAGS. - */ - bool Compile(const wxString& pattern, int flags = wxRE_DEFAULT); - - /** - Get the start index and the length of the match of the expression - (if @a index is 0) or a bracketed subexpression (@a index different from 0). - - May only be called after successful call to Matches() and only if @c wxRE_NOSUB - was @b not used in Compile(). - - Returns @false if no match or if an error occurred. - - */ - bool GetMatch(size_t* start, size_t* len, size_t index = 0) const; - - /** - Returns the part of string corresponding to the match where index is interpreted - as above. Empty string is returned if match failed. - - May only be called after successful call to Matches() and only if @c wxRE_NOSUB - was @b not used in Compile(). - */ - wxString GetMatch(const wxString& text, size_t index = 0) const; - - /** - Returns the size of the array of matches, i.e. the number of bracketed - subexpressions plus one for the expression itself, or 0 on error. - - May only be called after successful call to Compile(). - and only if @c wxRE_NOSUB was @b not used. - */ - size_t GetMatchCount() const; - - /** - Return @true if this is a valid compiled regular expression, @false - otherwise. - */ - bool IsValid() const; - - //@{ - /** - Matches the precompiled regular expression against the string @a text, - returns @true if matches and @false otherwise. - - @e Flags may be combination of @c wxRE_NOTBOL and @c wxRE_NOTEOL, see - @ref wxRE_NOT_FLAGS. - - Some regex libraries assume that the text given is null terminated, while - others require the length be given as a separate parameter. Therefore for - maximum portability assume that @a text cannot contain embedded nulls. - - When the Matches(const wxChar *text, int flags = 0) form is used, - a wxStrlen() will be done internally if the regex library requires the - length. When using Matches() in a loop the Matches(text, flags, len) - form can be used instead, making it possible to avoid a wxStrlen() inside - the loop. - - May only be called after successful call to Compile(). - */ - bool Matches(const wxChar* text, int flags = 0) const; - const bool Matches(const wxChar* text, int flags, size_t len) const; - //@} - - /** - Matches the precompiled regular expression against the string @a text, - returns @true if matches and @false otherwise. - - @e Flags may be combination of @c wxRE_NOTBOL and @c wxRE_NOTEOL, see - @ref wxRE_NOT_FLAGS. - - May only be called after successful call to Compile(). - */ - const bool Matches(const wxString& text, int flags = 0) const; - - /** - Replaces the current regular expression in the string pointed to by - @a text, with the text in @a replacement and return number of matches - replaced (maybe 0 if none found) or -1 on error. - - The replacement text may contain back references @c \\number which will be - replaced with the value of the corresponding subexpression in the - pattern match. @c \\0 corresponds to the entire match and @c \& is a - synonym for it. Backslash may be used to quote itself or @c \& character. - - @a maxMatches may be used to limit the number of replacements made, setting - it to 1, for example, will only replace first occurrence (if any) of the - pattern in the text while default value of 0 means replace all. - */ - int Replace(wxString* text, const wxString& replacement, - size_t maxMatches = 0) const; - - /** - Replace all occurrences: this is actually a synonym for - Replace(). - - @see ReplaceFirst() - */ - int ReplaceAll(wxString* text, const wxString& replacement) const; - - /** - Replace the first occurrence. - */ - int ReplaceFirst(wxString* text, const wxString& replacement) const; -}; - diff --git a/interface/region.h b/interface/region.h deleted file mode 100644 index 6d8d212213..0000000000 --- a/interface/region.h +++ /dev/null @@ -1,438 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: region.h -// Purpose: interface of wxRegionIterator -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - Types of results returned from a call to wxRegion::Contains(). -*/ -enum wxRegionContain -{ - /** The specified value is not contained within this region. */ - wxOutRegion = 0, - - /** - The specified value is partially contained within this region. - - On Windows, this result is not supported. ::wxInRegion will be returned - instead. - */ - wxPartRegion = 1, - - /** - The specified value is fully contained within this region. - - On Windows, this result will be returned even if only part of the specified - value is contained in this region. - */ - wxInRegion = 2 -}; - -/** - @class wxRegionIterator - @wxheader{region.h} - - This class is used to iterate through the rectangles in a region, - typically when examining the damaged regions of a window within an OnPaint call. - - To use it, construct an iterator object on the stack and loop through the - regions, testing the object and incrementing the iterator at the end of the - loop. - - See wxPaintEvent for an example of use. - - @library{wxcore} - @category{gdi} - - @stdobjects - ::wxNullRegion - - @see wxPaintEvent -*/ -class wxRegionIterator : public wxObject -{ -public: - /** - Default constructor. - */ - wxRegionIterator(); - /** - Creates an iterator object given a region. - */ - wxRegionIterator(const wxRegion& region); - - /** - An alias for GetHeight(). - */ - wxCoord GetH() const; - - /** - Returns the height value for the current region. - */ - wxCoord GetHeight() const; - - /** - Returns the current rectangle. - */ - wxRect GetRect() const; - - /** - An alias for GetWidth(). - */ - wxCoord GetW() const; - - /** - Returns the width value for the current region. - */ - wxCoord GetWidth() const; - - /** - Returns the x value for the current region. - */ - wxCoord GetX() const; - - /** - Returns the y value for the current region. - */ - wxCoord GetY() const; - - /** - Returns @true if there are still some rectangles; otherwise returns @false. - */ - bool HaveRects() const; - - /** - Resets the iterator to the beginning of the rectangles. - */ - void Reset(); - - /** - Resets the iterator to the given region. - */ - void Reset(const wxRegion& region); - - /** - Increment operator. Increments the iterator to the next region. - - @beginWxPythonOnly - A wxPython alias for this operator is called Next. - @endWxPythonOnly - */ - void operator ++(); - - /** - Returns @true if there are still some rectangles; otherwise returns @false. - - You can use this to test the iterator object as if it were of type @c bool. - */ - operator bool() const; -}; - - - -/** - @class wxRegion - @wxheader{region.h} - - A wxRegion represents a simple or complex region on a device context or window. - - 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 counting, are not affected. - - @stdobjects - - ::wxNullRegion - - @library{wxcore} - @category{data,gdi} - - @see wxRegionIterator -*/ -class wxRegion : public wxGDIObject -{ -public: - /** - Default constructor. - */ - wxRegion(); - /** - Constructs a rectangular region with the given position and size. - */ - wxRegion(wxCoord x, wxCoord y, wxCoord width, wxCoord height); - /** - Constructs a rectangular region from the top left point and the bottom right - point. - */ - wxRegion(const wxPoint& topLeft, const wxPoint& bottomRight); - /** - Constructs a rectangular region a wxRect object. - */ - wxRegion(const wxRect& rect); - /** - Copy constructor, uses @ref overview_refcount. - */ - wxRegion(const wxRegion& region); - /** - Constructs a region corresponding to the polygon made of @a n points - in the provided array. - @a fillStyle parameter may have values @c wxWINDING_RULE or @c wxODDEVEN_RULE. - */ - wxRegion(size_t n, const wxPoint* points, int fillStyle = wxWINDING_RULE); - /** - Constructs a region using a bitmap. See Union() for more details. - */ - wxRegion(const wxBitmap& bmp); - /** - Constructs a region using the non-transparent pixels of a bitmap. See - Union() for more details. - */ - wxRegion(const wxBitmap& bmp, const wxColour& transColour, - int tolerance = 0); - - /** - Destructor. - See @ref overview_refcount_destruct "reference-counted object destruction" for - more info. - */ - ~wxRegion(); - - /** - Clears the current region. - */ - void Clear(); - - /** - Returns a value indicating whether the given point is contained within the region. - - @return The return value is one of @c wxOutRegion and @c wxInRegion. - */ - wxRegionContain Contains(long& x, long& y) const; - /** - Returns a value indicating whether the given point is contained within the region. - - @return The return value is one of @c wxOutRegion and @c wxInRegion. - */ - wxRegionContain Contains(const wxPoint& pt) const; - /** - Returns a value indicating whether the given rectangle is contained within the - region. - - @return One of ::wxOutRegion, ::wxPartRegion or ::wxInRegion. - - @note On Windows, only ::wxOutRegion and ::wxInRegion are returned; a value - ::wxInRegion then indicates that all or some part of the region is - contained in this region. - */ - wxRegionContain Contains(long& x, long& y, long& width, long& height) const; - /** - Returns a value indicating whether the given rectangle is contained within the - region. - - @return One of ::wxOutRegion, ::wxPartRegion or ::wxInRegion. - - @note On Windows, only ::wxOutRegion and ::wxInRegion are returned; a value - ::wxInRegion then indicates that all or some part of the region is - contained in this region. - */ - wxRegionContain Contains(const wxRect& rect) const; - - /** - Convert the region to a black and white bitmap with the white pixels - being inside the region. - */ - wxBitmap ConvertToBitmap() const; - - //@{ - /** - Returns the outer bounds of the region. - */ - void GetBox(wxCoord& x, wxCoord& y, wxCoord& width, - wxCoord& height) const; - const wxRect GetBox() const; - //@} - - /** - Finds the intersection of this region and another, rectangular region, - specified using position and size. - - @return @true if successful, @false otherwise. - - @remarks Creates the intersection of the two regions, that is, the parts - which are in both regions. The result is stored in this - region. - */ - bool Intersect(wxCoord x, wxCoord y, wxCoord width, - wxCoord height); - /** - Finds the intersection of this region and another, rectangular region. - - @return @true if successful, @false otherwise. - - @remarks Creates the intersection of the two regions, that is, the parts - which are in both regions. The result is stored in this - region. - */ - bool Intersect(const wxRect& rect); - /** - Finds the intersection of this region and another region. - - @return @true if successful, @false otherwise. - - @remarks Creates the intersection of the two regions, that is, the parts - which are in both regions. The result is stored in this - region. - */ - bool Intersect(const wxRegion& region); - - /** - Returns @true if the region is empty, @false otherwise. - */ - bool IsEmpty() const; - - /** - Returns @true if the region is equal to, i.e. covers the same area as, - another one. - - @note If both this region and @a region are invalid, they are - considered to be equal. - */ - bool IsEqual(const wxRegion& region) const; - - //@{ - /** - Moves the region by the specified offsets in horizontal and vertical - directions. - - @return @true if successful, @false otherwise (the region is unchanged - then). - */ - bool Offset(wxCoord x, wxCoord y); - bool Offset(const wxPoint& pt); - //@} - - /** - Subtracts a rectangular region from this region. - - @return @true if successful, @false otherwise. - - @remarks This operation combines the parts of 'this' region that are not - part of the second region. The result is stored in this - region. - */ - bool Subtract(const wxRect& rect); - /** - Subtracts a region from this region. - - @return @true if successful, @false otherwise. - - @remarks This operation combines the parts of 'this' region that are not - part of the second region. The result is stored in this - region. - */ - bool Subtract(const wxRegion& region); - - /** - Finds the union of this region and another, rectangular region, specified using - position and size. - - @return @true if successful, @false otherwise. - - @remarks This operation creates a region that combines all of this region - and the second region. The result is stored in this - region. - */ - bool Union(wxCoord x, wxCoord y, wxCoord width, wxCoord height); - /** - Finds the union of this region and another, rectangular region. - - @return @true if successful, @false otherwise. - - @remarks This operation creates a region that combines all of this region - and the second region. The result is stored in this - region. - */ - bool Union(const wxRect& rect); - /** - Finds the union of this region and another region. - - @return @true if successful, @false otherwise. - - @remarks This operation creates a region that combines all of this region - and the second region. The result is stored in this - region. - */ - bool Union(const wxRegion& region); - /** - Finds the union of this region and the non-transparent pixels of a - bitmap. The bitmap's mask is used to determine transparency. If the - bitmap doesn't have a mask, the bitmap's full dimensions are used. - - @return @true if successful, @false otherwise. - - @remarks This operation creates a region that combines all of this region - and the second region. The result is stored in this - region. - */ - bool Union(const wxBitmap& bmp); - /** - Finds the union of this region and the non-transparent pixels of a - bitmap. Colour to be treated as transparent is specified in the - @a transColour argument, along with an optional colour tolerance value. - - @return @true if successful, @false otherwise. - - @remarks This operation creates a region that combines all of this region - and the second region. The result is stored in this - region. - */ - bool Union(const wxBitmap& bmp, const wxColour& transColour, - int tolerance = 0); - - /** - Finds the Xor of this region and another, rectangular region, specified using - position and size. - - @return @true if successful, @false otherwise. - - @remarks This operation creates a region that combines all of this region - and the second region, except for any overlapping - areas. The result is stored in this region. - */ - bool Xor(wxCoord x, wxCoord y, wxCoord width, wxCoord height); - /** - Finds the Xor of this region and another, rectangular region. - - @return @true if successful, @false otherwise. - - @remarks This operation creates a region that combines all of this region - and the second region, except for any overlapping - areas. The result is stored in this region. - */ - bool Xor(const wxRect& rect); - /** - Finds the Xor of this region and another region. - - @return @true if successful, @false otherwise. - - @remarks This operation creates a region that combines all of this region - and the second region, except for any overlapping - areas. The result is stored in this region. - */ - bool Xor(const wxRegion& region); - - /** - Assignment operator, using @ref overview_refcount. - */ - void operator =(const wxRegion& region); -}; - -/** - An empty region. -*/ -wxRegion wxNullRegion; diff --git a/interface/renderer.h b/interface/renderer.h deleted file mode 100644 index 6c33c39d59..0000000000 --- a/interface/renderer.h +++ /dev/null @@ -1,523 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: renderer.h -// Purpose: interface of wxRendererNative -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @anchor wxCONTROL_FLAGS - - The following rendering flags are defined for wxRendererNative: -*/ -enum -{ - /** Control is disabled. */ - wxCONTROL_DISABLED = 0x00000001, - - /** Currently has keyboard focus. */ - wxCONTROL_FOCUSED = 0x00000002, - - /** (Button) is pressed. */ - wxCONTROL_PRESSED = 0x00000004, - - /** Control-specific bit. */ - wxCONTROL_SPECIAL = 0x00000008, - - /** Only for the buttons. */ - wxCONTROL_ISDEFAULT = wxCONTROL_SPECIAL, - - /** Only for the menu items. */ - wxCONTROL_ISSUBMENU = wxCONTROL_SPECIAL, - - /** Only for the tree items. */ - wxCONTROL_EXPANDED = wxCONTROL_SPECIAL, - - /** Only for the status bar panes. */ - wxCONTROL_SIZEGRIP = wxCONTROL_SPECIAL, - - /** Checkboxes only: flat border. */ - wxCONTROL_FLAT = wxCONTROL_SPECIAL, - - /** Mouse is currently over the control. */ - wxCONTROL_CURRENT = 0x00000010, - - /** Selected item in e.g. listbox. */ - wxCONTROL_SELECTED = 0x00000020, - - /** (Check/radio button) is checked. */ - wxCONTROL_CHECKED = 0x00000040, - - /** (Menu) item can be checked. */ - wxCONTROL_CHECKABLE = 0x00000080, - - /** (Check) undetermined state. */ - wxCONTROL_UNDETERMINED = wxCONTROL_CHECKABLE -}; - -/** - @struct wxSplitterRenderParams - @wxheader{renderer.h} - - This is just a simple @c struct used as a return value of - wxRendererNative::GetSplitterParams(). - - It doesn't have any methods and all of its fields are constant, so they can - only be examined but not modified. - - @library{wxbase} - @category{gdi} -*/ -struct wxSplitterRenderParams -{ - /** - The only way to initialize this struct is by using this ctor. - */ - wxSplitterRenderParams(wxCoord widthSash_, wxCoord border_, bool isSens_); - - /** - The width of the border drawn by the splitter inside it, may be 0. - */ - const wxCoord border; - - /** - @true if the sash changes appearance when the mouse passes over it, @false - otherwise. - */ - const bool isHotSensitive; - - /** - The width of the splitter sash. - */ - const wxCoord widthSash; -}; - -/** - @struct wxHeaderButtonParams - @wxheader{renderer.h} - - This @c struct can optionally be used with - wxRendererNative::DrawHeaderButton() to specify custom values used to draw - the text or bitmap label. - - @library{wxbase} - @category{gdi} -*/ -struct wxHeaderButtonParams -{ - wxHeaderButtonParams(); - - wxColour m_arrowColour; - wxColour m_selectionColour; - wxString m_labelText; - wxFont m_labelFont; - wxColour m_labelColour; - wxBitmap m_labelBitmap; - int m_labelAlignment; -}; - -/** - Used to specify the type of sort arrow used with - wxRendererNative::DrawHeaderButton(). -*/ -enum wxHeaderSortIconType -{ - wxHDR_SORT_ICON_NONE, ///< Don't draw a sort arrow. - wxHDR_SORT_ICON_UP, ///< Draw a sort arrow icon pointing up. - wxHDR_SORT_ICON_DOWN ///< Draw a sort arrow icon pointing down. -}; - - - -/** - @class wxDelegateRendererNative - @wxheader{renderer.h} - - wxDelegateRendererNative allows reuse of renderers code by forwarding all the - wxRendererNative methods to the given object and - thus allowing you to only modify some of its methods -- without having to - reimplement all of them. - - Note that the "normal", inheritance-based approach, doesn't work with the - renderers as it is impossible to derive from a class unknown at compile-time - and the renderer is only chosen at run-time. So suppose that you want to only - add something to the drawing of the tree control buttons but leave all the - other methods unchanged -- the only way to do it, considering that the renderer - class which you want to customize might not even be written yet when you write - your code (it could be written later and loaded from a DLL during run-time), is - by using this class. - - Except for the constructor, it has exactly the same methods as - wxRendererNative and their implementation is - trivial: they are simply forwarded to the real renderer. Note that the "real" - renderer may, in turn, be a wxDelegateRendererNative as well and that there may - be arbitrarily many levels like this -- but at the end of the chain there must - be a real renderer which does the drawing. - - @library{wxcore} - @category{gdi} - - @see wxRendererNative -*/ -class wxDelegateRendererNative : public wxRendererNative -{ -public: - /** - The default constructor does the same thing as the other one except that it - uses the @ref wxRendererNative::GetGeneric() "generic renderer" instead of the - user-specified @a rendererNative. - - In any case, this sets up the delegate renderer object to follow all calls to - the specified real renderer. - */ - wxDelegateRendererNative(); - /** - This constructor uses the user-specified @a rendererNative to set up the delegate - renderer object to follow all calls to the specified real renderer. - - @note - This object does not take ownership of (i.e. won't delete) @a rendererNative. - */ - wxDelegateRendererNative(wxRendererNative& rendererNative); - - // The rest of these functions inherit the documentation from wxRendererNative - - virtual int DrawHeaderButton(wxWindow *win, wxDC& dc, - const wxRect& rect, int flags = 0, - wxHeaderSortIconType sortArrow = wxHDR_SORT_ICON_NONE, - wxHeaderButtonParams* params = NULL); - - virtual int DrawHeaderButtonContents(wxWindow *win, wxDC& dc, - const wxRect& rect, int flags = 0, - wxHeaderSortIconType sortArrow = wxHDR_SORT_ICON_NONE, - wxHeaderButtonParams* params = NULL); - - virtual int GetHeaderButtonHeight(wxWindow *win); - - virtual void DrawTreeItemButton(wxWindow *win, wxDC& dc, - const wxRect& rect, int flags = 0); - - virtual void DrawSplitterBorder(wxWindow *win, wxDC& dc, - const wxRect& rect, int flags = 0); - - virtual void DrawSplitterSash(wxWindow *win, wxDC& dc, - const wxSize& size, wxCoord position, - wxOrientation orient, int flags = 0); - - virtual void DrawComboBoxDropButton(wxWindow *win, wxDC& dc, - const wxRect& rect, int flags = 0); - - virtual void DrawDropArrow(wxWindow *win, wxDC& dc, - const wxRect& rect, int flags = 0); - - virtual void DrawCheckBox(wxWindow *win, wxDC& dc, - const wxRect& rect, int flags = 0 ); - - virtual void DrawPushButton(wxWindow *win, wxDC& dc, - const wxRect& rect, int flags = 0 ); - - virtual void DrawItemSelectionRect(wxWindow *win, wxDC& dc, - const wxRect& rect, int flags = 0 ); - - virtual void DrawFocusRect(wxWindow* win, wxDC& dc, - const wxRect& rect, int flags = 0); - - virtual wxSplitterRenderParams GetSplitterParams(const wxWindow *win); - - virtual wxRendererVersion GetVersion() const; -}; - - - -/** - @class wxRendererNative - @wxheader{renderer.h} - - First, a brief introduction to wxRendererNative and why it is needed. - - Usually wxWidgets uses the underlying low level GUI system to draw all the - controls - this is what we mean when we say that it is a "native" framework. - However not all controls exist under all (or even any) platforms and in this - case wxWidgets provides a default, generic, implementation of them written in - wxWidgets itself. - - These controls don't have the native appearance if only the standard - line drawing and other graphics primitives are used, because the native - appearance is different under different platforms while the lines are always - drawn in the same way. - - This is why we have renderers: wxRendererNative is a class which virtualizes the - drawing, i.e. it abstracts the drawing operations and allows you to draw say, a - button, without caring about exactly how this is done. Of course, as we - can draw the button differently in different renderers, this also allows us to - emulate the native look and feel. - - So the renderers work by exposing a large set of high-level drawing functions - which are used by the generic controls. There is always a default global - renderer but it may be changed or extended by the user, see - @ref page_samples_render. - - All drawing functions take some standard parameters: - - @li @a win - The window being drawn. It is normally not used and when - it is it should only be used as a generic wxWindow - (in order to get its low level handle, for example), but you should - not assume that it is of some given type as the same renderer - function may be reused for drawing different kinds of control. - @li @a dc - The wxDC to draw on. Only this device - context should be used for drawing. It is not necessary to restore - pens and brushes for it on function exit but, on the other hand, you - shouldn't assume that it is in any specific state on function entry: - the rendering functions should always prepare it. - @li @a rect - The bounding rectangle for the element to be drawn. - @li @a flags - The optional flags (none by default) which can be a - combination of the @ref wxCONTROL_FLAGS. - - Note that each drawing function restores the wxDC attributes if - it changes them, so it is safe to assume that the same pen, brush and colours - that were active before the call to this function are still in effect after it. - - @library{wxcore} - @category{gdi} -*/ -class wxRendererNative -{ -public: - /** - Virtual destructor as for any base class. - */ - ~wxRendererNative(); - - /** - Draw a check box (used by wxDataViewCtrl). - - @a flags may have the @c wxCONTROL_CHECKED, @c wxCONTROL_CURRENT or - @c wxCONTROL_UNDETERMINED bit set, see @ref wxCONTROL_FLAGS. - */ - virtual void DrawCheckBox(wxWindow* win, wxDC& dc, - const wxRect& rect, int flags); - - /** - Draw a button like the one used by wxComboBox to show a - drop down window. The usual appearance is a downwards pointing arrow. - - @a flags may have the @c wxCONTROL_PRESSED or @c wxCONTROL_CURRENT bit set, - see @ref wxCONTROL_FLAGS. - */ - virtual void DrawComboBoxDropButton(wxWindow* win, wxDC& dc, - const wxRect& rect, - int flags); - - /** - Draw a drop down arrow that is suitable for use outside a combo box. Arrow will - have transparent background. - - @a rect is not entirely filled by the arrow. Instead, you should use bounding - rectangle of a drop down button which arrow matches the size you need. - - @a flags may have the @c wxCONTROL_PRESSED or @c wxCONTROL_CURRENT bit set, - see @ref wxCONTROL_FLAGS. - */ - virtual void DrawDropArrow(wxWindow* win, wxDC& dc, const wxRect& rect, - int flags); - - /** - Draw a focus rectangle using the specified rectangle. - wxListCtrl. - - The only supported flags is @c wxCONTROL_SELECTED for items which are selected. - see @ref wxCONTROL_FLAGS. - */ - virtual void DrawFocusRect(wxWindow* win, wxDC& dc, const wxRect& rect, - int flags = 0); - - /** - Draw the header control button (used, for example, by wxListCtrl). - - Depending on platforms the @a flags parameter may support the @c wxCONTROL_SELECTED - @c wxCONTROL_DISABLED and @c wxCONTROL_CURRENT bits, see @ref wxCONTROL_FLAGS. - - @return - The optimal width to contain the the unabreviated label text or - bitmap, the sort arrow if present, and internal margins. - */ - virtual int DrawHeaderButton(wxWindow* win, wxDC& dc, - const wxRect& rect, int flags = 0, - wxHeaderSortIconType sortArrow = wxHDR_SORT_ICON_NONE, - wxHeaderButtonParams* params = NULL); - - /** - Draw the contents of a header control button (label, sort arrows, - etc.). This function is normally only called by DrawHeaderButton(). - - Depending on platforms the @a flags parameter may support the @c wxCONTROL_SELECTED - @c wxCONTROL_DISABLED and @c wxCONTROL_CURRENT bits, see @ref wxCONTROL_FLAGS. - - @return - The optimal width to contain the the unabreviated label text or - bitmap, the sort arrow if present, and internal margins. - */ - virtual int DrawHeaderButtonContents(wxWindow *win, wxDC& dc, - const wxRect& rect, int flags = 0, - wxHeaderSortIconType sortArrow = wxHDR_SORT_ICON_NONE, - wxHeaderButtonParams* params = NULL); - - /** - Draw a selection rectangle underneath the text as used e.g. in a - wxListCtrl. - - The supported @a flags are @c wxCONTROL_SELECTED for items - which are selected (e.g. often a blue rectangle) and @c wxCONTROL_CURRENT - for the item that has the focus (often a dotted line around the item's text). - @c wxCONTROL_FOCUSED may be used to indicate if the control has the focus - (othewise the the selection rectangle is e.g. often grey and not blue). - This may be ignored by the renderer or deduced by the code directly from - the @a win. - */ - virtual void DrawItemSelectionRect(wxWindow* win, wxDC& dc, - const wxRect& rect, int flags = 0); - - /** - Draw a blank push button that looks very similar to wxButton. - - @a flags may have the @c wxCONTROL_PRESSED, @c wxCONTROL_CURRENT or - @c wxCONTROL_ISDEFAULT bit set, see @ref wxCONTROL_FLAGS. - */ - virtual void DrawPushButton(wxWindow* win, wxDC& dc, - const wxRect& rect, int flags); - - /** - Draw the border for sash window: this border must be such that the sash - drawn by DrawSplitterSash() blends into it well. - */ - virtual void DrawSplitterBorder(wxWindow* win, wxDC& dc, - const wxRect& rect, int flags = 0); - - /** - Draw a sash. The @a orient parameter defines whether the sash should be - vertical or horizontal and how the @a position should be interpreted. - */ - virtual void DrawSplitterSash(wxWindow* win, wxDC& dc, - const wxSize& size, wxCoord position, - wxOrientation orient, int flags = 0); - - /** - Draw the expanded/collapsed icon for a tree control item. - - To draw an expanded button the @a flags parameter must contain @c wxCONTROL_EXPANDED bit, - see @ref wxCONTROL_FLAGS. - */ - virtual void DrawTreeItemButton(wxWindow* win, wxDC& dc, - const wxRect& rect, int flags = 0); - - /** - Return the currently used renderer. - */ - static wxRendererNative Get(); - - /** - Return the default (native) implementation for this platform -- this is also - the one used by default but this may be changed by calling - Set() in which case the return value of this - method may be different from the return value of Get(). - */ - static wxRendererNative GetDefault(); - - /** - Return the generic implementation of the renderer. Under some platforms, this - is the default renderer implementation, others have platform-specific default - renderer which can be retrieved by calling GetDefault(). - */ - static wxRendererNative GetGeneric(); - - /** - Returns the height of a header button, either a fixed platform height if - available, or a - generic height based on the window's font. - */ - virtual int GetHeaderButtonHeight(wxWindow* win); - - /** - Get the splitter parameters, see - wxSplitterRenderParams. - */ - virtual wxSplitterRenderParams GetSplitterParams(const wxWindow* win); - - /** - This function is used for version checking: Load() - refuses to load any shared libraries implementing an older or incompatible - version. - - @remarks - The implementation of this method is always the same in all renderers (simply - construct wxRendererVersion using the @c wxRendererVersion::Current_XXX values), - but it has to be in the derived, not base, class, to detect mismatches between - the renderers versions and so you have to implement it anew in all renderers. - */ - virtual wxRendererVersion GetVersion() const; - - /** - Load the renderer from the specified DLL, the returned pointer must be - deleted by caller if not @NULL when it is not used any more. - - The @a name should be just the base name of the renderer and not the full - name of the DLL file which is constructed differently (using - wxDynamicLibrary::CanonicalizePluginName()) - on different systems. - */ - static wxRendererNative* Load(const wxString& name); - - /** - Set the renderer to use, passing @NULL reverts to using the default - renderer (the global renderer must always exist). - - Return the previous renderer used with Set() or @NULL if none. - */ - static wxRendererNative* Set(wxRendererNative* renderer); -}; - - - -/** - @struct wxRendererVersion - @wxheader{renderer.h} - - This simple struct represents the wxRendererNative - interface version and is only used as the return value of - wxRendererNative::GetVersion(). - - The version has two components: the version itself and the age. If the main - program and the renderer have different versions they are never compatible with - each other because the version is only changed when an existing virtual - function is modified or removed. The age, on the other hand, is incremented - each time a new virtual method is added and so, at least for the compilers - using a common C++ object model, the calling program is compatible with any - renderer which has the age greater or equal to its age. This verification is - done by IsCompatible() method. - - @library{wxbase} - @category{gdi} -*/ -struct wxRendererVersion -{ - /** - Checks if the main program is compatible with the renderer having the version - @e ver, returns @true if it is and @false otherwise. - - This method is used by wxRendererNative::Load() to determine whether a - renderer can be used. - */ - static bool IsCompatible(const wxRendererVersion& ver); - - /** - The age component. - */ - const int age; - - /** - The version component. - */ - const int version; -}; - diff --git a/interface/richtext/richtextbuffer.h b/interface/richtext/richtextbuffer.h deleted file mode 100644 index 31b30625c5..0000000000 --- a/interface/richtext/richtextbuffer.h +++ /dev/null @@ -1,1035 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: richtext/richtextbuffer.h -// Purpose: interface of wxRichTextBuffer -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxRichTextBuffer - @headerfile richtextbuffer.h wx/richtext/richtextbuffer.h - - This class represents the whole buffer associated with a wxRichTextCtrl. - - @library{wxrichtext} - @category{richtext} - - @see wxTextAttr, wxRichTextCtrl -*/ -class wxRichTextBuffer -{ -public: - //@{ - /** - Default constructors. - */ - wxRichTextBuffer(const wxRichTextBuffer& obj); - wxRichTextBuffer(); - //@} - - /** - Destructor. - */ - ~wxRichTextBuffer(); - - /** - Adds an event handler to the buffer's list of handlers. A buffer associated with - a contol has the control as the only event handler, but the application is free - to add more if further notification is required. All handlers are notified - of an event originating from the buffer, such as the replacement of a style - sheet - during loading. The buffer never deletes any of the event handlers, unless - RemoveEventHandler() is - called with @true as the second argument. - */ - bool AddEventHandler(wxEvtHandler* handler); - - /** - Adds a file handler. - */ - void AddHandler(wxRichTextFileHandler* handler); - - /** - Adds a paragraph of text. - */ - wxRichTextRange AddParagraph(const wxString& text); - - /** - Returns @true if the buffer is currently collapsing commands into a single - notional command. - */ - bool BatchingUndo() const; - - /** - Begins using alignment. - */ - bool BeginAlignment(wxTextAttrAlignment alignment); - - /** - Begins collapsing undo/redo commands. Note that this may not work properly - if combining commands that delete or insert content, changing ranges for - subsequent actions. - @a cmdName should be the name of the combined command that will appear - next to Undo and Redo in the edit menu. - */ - bool BeginBatchUndo(const wxString& cmdName); - - /** - Begin applying bold. - */ - bool BeginBold(); - - /** - Begins applying the named character style. - */ - bool BeginCharacterStyle(const wxString& characterStyle); - - /** - Begins using this font. - */ - bool BeginFont(const wxFont& font); - - /** - Begins using the given point size. - */ - bool BeginFontSize(int pointSize); - - /** - Begins using italic. - */ - bool BeginItalic(); - - /** - Begin using @a leftIndent for the left indent, and optionally @a leftSubIndent - for - the sub-indent. Both are expressed in tenths of a millimetre. - The sub-indent is an offset from the left of the paragraph, and is used for all - but the - first line in a paragraph. A positive value will cause the first line to appear - to the left - of the subsequent lines, and a negative value will cause the first line to be - indented - relative to the subsequent lines. - */ - bool BeginLeftIndent(int leftIndent, int leftSubIndent = 0); - - /** - Begins line spacing using the specified value. @e spacing is a multiple, where - 10 means single-spacing, - 15 means 1.5 spacing, and 20 means double spacing. The following constants are - defined for convenience: - */ - bool BeginLineSpacing(int lineSpacing); - - /** - Begins using a specified list style. Optionally, you can also pass a level and - a number. - */ - bool BeginListStyle(const wxString& listStyle, int level = 1, - int number = 1); - - /** - Begins a numbered bullet. This call will be needed for each item in the list, - and the - application should take care of incrementing the numbering. - @a bulletNumber is a number, usually starting with 1. - @a leftIndent and @a leftSubIndent are values in tenths of a millimetre. - @a bulletStyle is a bitlist of the following values: - - wxRichTextBuffer uses indentation to render a bulleted item. The left indent is - the distance between - the margin and the bullet. The content of the paragraph, including the first - line, starts - at leftMargin + leftSubIndent. So the distance between the left edge of the - bullet and the - left of the actual paragraph is leftSubIndent. - */ - bool BeginNumberedBullet(int bulletNumber, int leftIndent, - int leftSubIndent, - int bulletStyle = wxTEXT_ATTR_BULLET_STYLE_ARABIC|wxTEXT_ATTR_BULLET_STYLE_PERIOD); - - /** - Begins paragraph spacing; pass the before-paragraph and after-paragraph spacing - in tenths of - a millimetre. - */ - bool BeginParagraphSpacing(int before, int after); - - /** - Begins applying the named paragraph style. - */ - bool BeginParagraphStyle(const wxString& paragraphStyle); - - /** - Begins a right indent, specified in tenths of a millimetre. - */ - bool BeginRightIndent(int rightIndent); - - /** - Begins applying a standard bullet, using one of the standard bullet names - (currently @c standard/circle or @c standard/square. - See BeginNumberedBullet() for an explanation of how indentation is used to - render the bulleted paragraph. - */ - bool BeginStandardBullet(const wxString& bulletName, - int leftIndent, - int leftSubIndent, - int bulletStyle = wxTEXT_ATTR_BULLET_STYLE_STANDARD); - - /** - Begins using a specified style. - */ - bool BeginStyle(const wxTextAttr& style); - - /** - Begins suppressing undo/redo commands. The way undo is suppressed may be - implemented - differently by each command. If not dealt with by a command implementation, then - it will be implemented automatically by not storing the command in the undo - history - when the action is submitted to the command processor. - */ - bool BeginSuppressUndo(); - - /** - Begins applying a symbol bullet, using a character from the current font. See - BeginNumberedBullet() for - an explanation of how indentation is used to render the bulleted paragraph. - */ - bool BeginSymbolBullet(wxChar symbol, int leftIndent, - int leftSubIndent, - int bulletStyle = wxTEXT_ATTR_BULLET_STYLE_SYMBOL); - - /** - Begins using the specified text foreground colour. - */ - bool BeginTextColour(const wxColour& colour); - - /** - Begins applying wxTEXT_ATTR_URL to the content. Pass a URL and optionally, a - character style to apply, - since it is common to mark a URL with a familiar style such as blue text with - underlining. - */ - bool BeginURL(const wxString& url, - const wxString& characterStyle = wxEmptyString); - - /** - Begins using underline. - */ - bool BeginUnderline(); - - /** - Returns @true if content can be pasted from the clipboard. - */ - bool CanPasteFromClipboard() const; - - /** - Cleans up the file handlers. - */ - void CleanUpHandlers(); - - /** - Clears the buffer. - */ - void Clear(); - - //@{ - /** - Clears the list style from the given range, clearing list-related attributes - and applying any named paragraph style associated with each paragraph. - @a flags is a bit list of the following: - wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable. - See also SetListStyle(), PromoteList(), NumberList(). - */ - bool ClearListStyle(const wxRichTextRange& range, - int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO); - bool ClearListStyle(const wxRichTextRange& range, - int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO); - //@} - - /** - Clears the style stack. - */ - void ClearStyleStack(); - - /** - Clones the object. - */ - wxRichTextObject* Clone() const; - - /** - Copies the given buffer. - */ - void Copy(const wxRichTextBuffer& obj); - - /** - Copy the given range to the clipboard. - */ - bool CopyToClipboard(const wxRichTextRange& range); - - /** - Submits a command to delete the given range. - */ - bool DeleteRangeWithUndo(const wxRichTextRange& range, - wxRichTextCtrl* ctrl); - - //@{ - /** - Dumps the contents of the buffer for debugging purposes. - */ - void Dump(); - void Dump(wxTextOutputStream& stream); - //@} - - /** - Ends alignment. - */ - bool EndAlignment(); - - /** - Ends all styles that have been started with a Begin... command. - */ - bool EndAllStyles(); - - /** - Ends collapsing undo/redo commands, and submits the combined command. - */ - bool EndBatchUndo(); - - /** - Ends using bold. - */ - bool EndBold(); - - /** - Ends using the named character style. - */ - bool EndCharacterStyle(); - - /** - Ends using a font. - */ - bool EndFont(); - - /** - Ends using a point size. - */ - bool EndFontSize(); - - /** - Ends using italic. - */ - bool EndItalic(); - - /** - Ends using a left indent. - */ - bool EndLeftIndent(); - - /** - Ends using a line spacing. - */ - bool EndLineSpacing(); - - /** - Ends using a specified list style. - */ - bool EndListStyle(); - - /** - Ends a numbered bullet. - */ - bool EndNumberedBullet(); - - /** - Ends paragraph spacing. - */ - bool EndParagraphSpacing(); - - /** - Ends applying a named character style. - */ - bool EndParagraphStyle(); - - /** - Ends using a right indent. - */ - bool EndRightIndent(); - - /** - Ends using a standard bullet. - */ - bool EndStandardBullet(); - - /** - Ends the current style. - */ - bool EndStyle(); - - /** - Ends suppressing undo/redo commands. - */ - bool EndSuppressUndo(); - - /** - Ends using a symbol bullet. - */ - bool EndSymbolBullet(); - - /** - Ends using a text foreground colour. - */ - bool EndTextColour(); - - /** - Ends applying a URL. - */ - bool EndURL(); - - /** - Ends using underline. - */ - bool EndUnderline(); - - //@{ - /** - Finds a handler by name. - */ - wxRichTextFileHandler* FindHandler(int imageType); - wxRichTextFileHandler* FindHandler(const wxString& extension, - int imageType); - wxRichTextFileHandler* FindHandler(const wxString& name); - //@} - - /** - Finds a handler by filename or, if supplied, type. - */ - wxRichTextFileHandler* FindHandlerFilenameOrType(const wxString& filename, - int imageType); - - /** - Gets the basic (overall) style. This is the style of the whole - buffer before further styles are applied, unlike the default style, which - only affects the style currently being applied (for example, setting the default - style to bold will cause subsequently inserted text to be bold). - */ - const wxTextAttr GetBasicStyle() const; - - /** - Gets the collapsed command. - */ - wxRichTextCommand* GetBatchedCommand() const; - - /** - Gets the command processor. A text buffer always creates its own command - processor when it is - initialized. - */ - wxCommandProcessor* GetCommandProcessor() const; - - /** - Returns the current default style, affecting the style currently being applied - (for example, setting the default - style to bold will cause subsequently inserted text to be bold). - */ - const wxTextAttr GetDefaultStyle() const; - - /** - Gets a wildcard incorporating all visible handlers. If @a types is present, - it will be filled with the file type corresponding to each filter. This can be - used to determine the type to pass to @ref getextwildcard() LoadFile given a - selected filter. - */ - wxString GetExtWildcard(bool combine = false, bool save = false, - wxArrayInt* types = NULL); - - /** - Returns the list of file handlers. - */ - wxList GetHandlers(); - - /** - Returns the object to be used to render certain aspects of the content, such as - bullets. - */ - static wxRichTextRenderer* GetRenderer(); - - /** - Gets the attributes at the given position. - This function gets the combined style - that is, the style you see on the - screen as a result - of combining base style, paragraph style and character style attributes. To get - the character - or paragraph style alone, use GetUncombinedStyle(). - */ - bool GetStyle(long position, wxTextAttr& style); - - /** - This function gets a style representing the common, combined attributes in the - given range. - Attributes which have different values within the specified range will not be - included the style - flags. - The function is used to get the attributes to display in the formatting dialog: - the user - can edit the attributes common to the selection, and optionally specify the - values of further - attributes to be applied uniformly. - To apply the edited attributes, you can use SetStyle() specifying - the wxRICHTEXT_SETSTYLE_OPTIMIZE flag, which will only apply attributes that - are different - from the @e combined attributes within the range. So, the user edits the - effective, displayed attributes - for the range, but his choice won't be applied unnecessarily to content. As an - example, - say the style for a paragraph specifies bold, but the paragraph text doesn't - specify a weight. The - combined style is bold, and this is what the user will see on-screen and in the - formatting - dialog. The user now specifies red text, in addition to bold. When applying with - SetStyle, the content font weight attributes won't be changed to bold because - this is already specified - by the paragraph. However the text colour attributes @e will be changed to - show red. - */ - bool GetStyleForRange(const wxRichTextRange& range, - wxTextAttr& style); - - /** - Returns the current style sheet associated with the buffer, if any. - */ - wxRichTextStyleSheet* GetStyleSheet() const; - - /** - Get the size of the style stack, for example to check correct nesting. - */ - size_t GetStyleStackSize() const; - - /** - Gets the attributes at the given position. - This function gets the @e uncombined style - that is, the attributes associated - with the - paragraph or character content, and not necessarily the combined attributes you - see on the - screen. To get the combined attributes, use GetStyle(). - If you specify (any) paragraph attribute in @e style's flags, this function - will fetch - the paragraph attributes. Otherwise, it will return the character attributes. - */ - bool GetUncombinedStyle(long position, wxTextAttr& style); - - /** - Finds the text position for the given position, putting the position in @a - textPosition if - one is found. @a pt is in logical units (a zero y position is - at the beginning of the buffer). - The function returns one of the following values: - */ - int HitTest(wxDC& dc, const wxPoint& pt, long& textPosition); - - /** - Initialisation. - */ - void Init(); - - /** - Initialises the standard handlers. Currently, only the plain text - loading/saving handler - is initialised by default. - */ - void InitStandardHandlers(); - - /** - Inserts a handler at the front of the list. - */ - void InsertHandler(wxRichTextFileHandler* handler); - - /** - Submits a command to insert the given image. - */ - bool InsertImageWithUndo(long pos, - const wxRichTextImageBlock& imageBlock, - wxRichTextCtrl* ctrl); - - /** - Submits a command to insert a newline. - */ - bool InsertNewlineWithUndo(long pos, wxRichTextCtrl* ctrl); - - /** - Submits a command to insert the given text. - */ - bool InsertTextWithUndo(long pos, const wxString& text, - wxRichTextCtrl* ctrl); - - /** - Returns @true if the buffer has been modified. - */ - bool IsModified() const; - - //@{ - /** - Loads content from a file. - */ - bool LoadFile(wxInputStream& stream, - int type = wxRICHTEXT_TYPE_ANY); - bool LoadFile(const wxString& filename, - int type = wxRICHTEXT_TYPE_ANY); - //@} - - /** - Marks the buffer as modified or unmodified. - */ - void Modify(bool modify = true); - - //@{ - /** - Numbers the paragraphs in the given range. Pass flags to determine how the - attributes are set. - Either the style definition or the name of the style definition (in the current - sheet) can be passed. - @a flags is a bit list of the following: - wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable. - wxRICHTEXT_SETSTYLE_RENUMBER: specifies that numbering should start from @e - startFrom, otherwise existing attributes are used. - wxRICHTEXT_SETSTYLE_SPECIFY_LEVEL: specifies that @a listLevel should be used - as the level for all paragraphs, otherwise the current indentation will be used. - See also SetListStyle(), PromoteList(), ClearListStyle(). - */ - bool NumberList(const wxRichTextRange& range, - const wxRichTextListStyleDefinition* style, - int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO, - int startFrom = -1, - int listLevel = -1); - bool Number(const wxRichTextRange& range, - const wxString& styleName, - int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO, - int startFrom = -1, - int listLevel = -1); - //@} - - /** - Pastes the clipboard content to the buffer at the given position. - */ - bool PasteFromClipboard(long position); - - //@{ - /** - Promotes or demotes the paragraphs in the given range. A positive @a promoteBy - produces a smaller indent, and a negative number - produces a larger indent. Pass flags to determine how the attributes are set. - Either the style definition or the name of the style definition (in the current - sheet) can be passed. - @a flags is a bit list of the following: - wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable. - wxRICHTEXT_SETSTYLE_RENUMBER: specifies that numbering should start from @e - startFrom, otherwise existing attributes are used. - wxRICHTEXT_SETSTYLE_SPECIFY_LEVEL: specifies that @a listLevel should be used - as the level for all paragraphs, otherwise the current indentation will be used. - See also SetListStyle(), See also SetListStyle(), ClearListStyle(). - */ - bool PromoteList(int promoteBy, const wxRichTextRange& range, - const wxRichTextListStyleDefinition* style, - int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO, - int listLevel = -1); - bool PromoteList(int promoteBy, const wxRichTextRange& range, - const wxString& styleName, - int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO, - int listLevel = -1); - //@} - - /** - Removes an event handler from the buffer's list of handlers, deleting the - object if @a deleteHandler is @true. - */ - bool RemoveEventHandler(wxEvtHandler* handler, - bool deleteHandler = false); - - /** - Removes a handler. - */ - bool RemoveHandler(const wxString& name); - - /** - Clears the buffer, adds a new blank paragraph, and clears the command history. - */ - void ResetAndClearCommands(); - - //@{ - /** - Saves content to a file. - */ - bool SaveFile(wxOutputStream& stream, - int type = wxRICHTEXT_TYPE_ANY); - bool SaveFile(const wxString& filename, - int type = wxRICHTEXT_TYPE_ANY); - //@} - - /** - Sets the basic (overall) style. This is the style of the whole - buffer before further styles are applied, unlike the default style, which - only affects the style currently being applied (for example, setting the default - style to bold will cause subsequently inserted text to be bold). - */ - void SetBasicStyle(const wxTextAttr& style); - - /** - Sets the default style, affecting the style currently being applied (for - example, setting the default - style to bold will cause subsequently inserted text to be bold). - This is not cumulative - setting the default style will replace the previous - default style. - */ - void SetDefaultStyle(const wxTextAttr& style); - - //@{ - /** - Sets the list attributes for the given range, passing flags to determine how - the attributes are set. - Either the style definition or the name of the style definition (in the current - sheet) can be passed. - @a flags is a bit list of the following: - wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable. - wxRICHTEXT_SETSTYLE_RENUMBER: specifies that numbering should start from @e - startFrom, otherwise existing attributes are used. - wxRICHTEXT_SETSTYLE_SPECIFY_LEVEL: specifies that @a listLevel should be used - as the level for all paragraphs, otherwise the current indentation will be used. - See also NumberList(), PromoteList(), ClearListStyle(). - */ - bool SetListStyle(const wxRichTextRange& range, - const wxRichTextListStyleDefinition* style, - int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO, - int startFrom = -1, - int listLevel = -1); - bool SetListStyle(const wxRichTextRange& range, - const wxString& styleName, - int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO, - int startFrom = -1, - int listLevel = -1); - //@} - - /** - Sets @a renderer as the object to be used to render certain aspects of the - content, such as bullets. - You can override default rendering by deriving a new class from - wxRichTextRenderer or wxRichTextStdRenderer, - overriding one or more virtual functions, and setting an instance of the class - using this function. - */ - static void SetRenderer(wxRichTextRenderer* renderer); - - /** - Sets the attributes for the given range. Pass flags to determine how the - attributes are set. - The end point of range is specified as the last character position of the span - of text. - So, for example, to set the style for a character at position 5, use the range - (5,5). - This differs from the wxRichTextCtrl API, where you would specify (5,6). - @a flags may contain a bit list of the following values: - wxRICHTEXT_SETSTYLE_NONE: no style flag. - wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this operation should be - undoable. - wxRICHTEXT_SETSTYLE_OPTIMIZE: specifies that the style should not be applied - if the - combined style at this point is already the style in question. - wxRICHTEXT_SETSTYLE_PARAGRAPHS_ONLY: specifies that the style should only be - applied to paragraphs, - and not the content. This allows content styling to be preserved independently - from that of e.g. a named paragraph style. - wxRICHTEXT_SETSTYLE_CHARACTERS_ONLY: specifies that the style should only be - applied to characters, - and not the paragraph. This allows content styling to be preserved - independently from that of e.g. a named paragraph style. - wxRICHTEXT_SETSTYLE_RESET: resets (clears) the existing style before applying - the new style. - wxRICHTEXT_SETSTYLE_REMOVE: removes the specified style. Only the style flags - are used in this operation. - */ - bool SetStyle(const wxRichTextRange& range, - const wxTextAttr& style, - int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO); - - /** - Sets the current style sheet, if any. This will allow the application to use - named character and paragraph styles found in the style sheet. - */ - void SetStyleSheet(wxRichTextStyleSheet* styleSheet); - - /** - Submit an action immediately, or delay it according to whether collapsing is on. - */ - bool SubmitAction(wxRichTextAction* action); - - /** - Returns @true if undo suppression is currently on. - */ - bool SuppressingUndo() const; -}; - - - -/** - @class wxRichTextFileHandler - @headerfile richtextbuffer.h wx/richtext/richtextbuffer.h - - This is the base class for file handlers, for loading and/or saving content - associated with a wxRichTextBuffer. - - @library{wxrichtext} - @category{richtext} -*/ -class wxRichTextFileHandler : public wxObject -{ -public: - /** - Constructor. - */ - wxRichTextFileHandler(const wxString& name = wxEmptyString, - const wxString& ext = wxEmptyString, - int type = 0); - - /** - Override this function and return @true if this handler can we handle @e - filename. By default, - this function checks the extension. - */ - bool CanHandle(const wxString& filename) const; - - /** - Override and return @true if this handler can load content. - */ - bool CanLoad() const; - - /** - Override and return @true if this handler can save content. - */ - bool CanSave() const; - - /** - Override to load content from @a stream into @e buffer. - */ - bool DoLoadFile(wxRichTextBuffer* buffer, wxInputStream& stream); - - /** - Override to save content to @a stream from @e buffer. - */ - bool DoSaveFile(wxRichTextBuffer* buffer, wxOutputStream& stream); - - /** - Returns the encoding associated with the handler (if any). - */ - const wxString GetEncoding() const; - - /** - Returns the extension associated with the handler. - */ - wxString GetExtension() const; - - /** - Returns flags that change the behaviour of loading or saving. See the - documentation for each - handler class to see what flags are relevant for each handler. - */ - int GetFlags() const; - - /** - Returns the name of the handler. - */ - wxString GetName() const; - - /** - Returns the type of the handler. - */ - int GetType() const; - - /** - Returns @true if this handler should be visible to the user. - */ - bool IsVisible() const; - - //@{ - /** - Loads content from a stream or file. Not all handlers will implement file - loading. - */ - bool LoadFile(wxRichTextBuffer* buffer, wxInputStream& stream); - bool LoadFile(wxRichTextBuffer* buffer, - const wxString& filename); - //@} - - //@{ - /** - Saves content to a stream or file. Not all handlers will implement file saving. - */ - bool SaveFile(wxRichTextBuffer* buffer, wxOutputStream& stream); - bool SaveFile(wxRichTextBuffer* buffer, - const wxString& filename); - //@} - - /** - Sets the encoding to use when saving a file. If empty, a suitable encoding is - chosen. - */ - void SetEncoding(const wxString& encoding); - - /** - Sets the default extension to recognise. - */ - void SetExtension(const wxString& ext); - - /** - Sets flags that change the behaviour of loading or saving. See the - documentation for each - handler class to see what flags are relevant for each handler. - You call this function directly if you are using a file handler explicitly - (without - going through the text control or buffer LoadFile/SaveFile API). Or, you can - call the control or buffer's SetHandlerFlags function to set the flags that will - be used for subsequent load and save operations. - */ - void SetFlags(int flags); - - /** - Sets the name of the handler. - */ - void SetName(const wxString& name); - - /** - Sets the handler type. - */ - void SetType(int type); - - /** - Sets whether the handler should be visible to the user (via the application's - load and save - dialogs). - */ - void SetVisible(bool visible); -}; - - - -/** - @class wxRichTextRange - @headerfile richtextbuffer.h wx/richtext/richtextbuffer.h - - This class stores beginning and end positions for a range of data. - - @library{wxrichtext} - @category{richtext} -*/ -class wxRichTextRange -{ -public: - //@{ - /** - Constructors. - */ - wxRichTextRange(long start, long end); - wxRichTextRange(const wxRichTextRange& range); - wxRichTextRange(); - //@} - - /** - Destructor. - */ - ~wxRichTextRange(); - - /** - Returns @true if the given position is within this range. Does not - match if the range is empty. - */ - bool Contains(long pos) const; - - /** - Converts the internal range, which uses the first and last character positions - of the range, - to the API-standard range, whose end is one past the last character in the - range. - In other words, one is added to the end position. - */ - wxRichTextRange FromInternal() const; - - /** - Returns the end position. - */ - long GetEnd() const; - - /** - Returns the length of the range. - */ - long GetLength() const; - - /** - Returns the start of the range. - */ - long GetStart() const; - - /** - Returns @true if this range is completely outside @e range. - */ - bool IsOutside(const wxRichTextRange& range) const; - - /** - Returns @true if this range is completely within @e range. - */ - bool IsWithin(const wxRichTextRange& range) const; - - /** - Limits this range to be within @e range. - */ - bool LimitTo(const wxRichTextRange& range); - - /** - Sets the end of the range. - */ - void SetEnd(long end); - - /** - Sets the range. - */ - void SetRange(long start, long end); - - /** - Sets the start of the range. - */ - void SetStart(long start); - - /** - Swaps the start and end. - */ - void Swap(); - - /** - Converts the API-standard range, whose end is one past the last character in - the range, - to the internal form, which uses the first and last character positions of the - range. - In other words, one is subtracted from the end position. - */ - wxRichTextRange ToInternal() const; - - /** - Adds @a range to this range. - */ - wxRichTextRange operator+(const wxRichTextRange& range) const; - - /** - Subtracts @a range from this range. - */ - wxRichTextRange operator-(const wxRichTextRange& range) const; - - /** - Assigns @a range to this range. - */ - void operator=(const wxRichTextRange& range); - - /** - Returns @true if @a range is the same as this range. - */ - bool operator==(const wxRichTextRange& range) const; -}; - diff --git a/interface/richtext/richtextctrl.h b/interface/richtext/richtextctrl.h deleted file mode 100644 index c5c7004ec7..0000000000 --- a/interface/richtext/richtextctrl.h +++ /dev/null @@ -1,1407 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: richtext/richtextctrl.h -// Purpose: interface of wxRichTextEvent -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxRichTextEvent - @headerfile richtextctrl.h wx/richtext/richtextctrl.h - - This is the event class for wxRichTextCtrl notifications. - - @library{wxrichtext} - @category{richtext} -*/ -class wxRichTextEvent : public wxNotifyEvent -{ -public: - //@{ - /** - Constructors. - */ - wxRichTextEvent(const wxRichTextEvent& event); - wxRichTextEvent(wxEventType commandType = wxEVT_NULL, - int winid = 0); - //@} - - /** - Clones the event. - */ - wxEvent* Clone() const; - - /** - Returns the character pressed, within a wxEVT_COMMAND_RICHTEXT_CHARACTER event. - */ - wxChar GetCharacter() const; - - /** - Returns flags indicating modifier keys pressed. Possible values are - wxRICHTEXT_CTRL_DOWN, - wxRICHTEXT_SHIFT_DOWN, and wxRICHTEXT_ALT_DOWN. - */ - int GetFlags() const; - - /** - Returns the new style sheet. Can be used in a - wxEVT_COMMAND_RICHTEXT_STYLESHEET_CHANGING or - wxEVT_COMMAND_RICHTEXT_STYLESHEET_CHANGED event handler. - */ - wxRichTextStyleSheet* GetNewStyleSheet() const; - - /** - Returns the old style sheet. Can be used in a - wxEVT_COMMAND_RICHTEXT_STYLESHEET_CHANGING or - wxEVT_COMMAND_RICHTEXT_STYLESHEET_CHANGED event handler. - */ - wxRichTextStyleSheet* GetOldStyleSheet() const; - - /** - Returns the buffer position at which the event occured. - */ - long GetPosition() const; - - /** - Gets the range for the current operation. - */ - wxRichTextRange GetRange() const; - - /** - Sets the character variable. - */ - void SetCharacter(wxChar ch); - - /** - Sets flags indicating modifier keys pressed. Possible values are - wxRICHTEXT_CTRL_DOWN, - wxRICHTEXT_SHIFT_DOWN, and wxRICHTEXT_ALT_DOWN. - */ - void SetFlags(int flags); - - /** - Sets the new style sheet variable. - */ - void SetNewStyleSheet(wxRichTextStyleSheet* sheet); - - /** - Sets the old style sheet variable. - */ - void SetOldStyleSheet(wxRichTextStyleSheet* sheet); - - /** - Sets the buffer position variable. - */ - void SetPosition(long pos); - - /** - Sets the range variable. - */ - void SetRange(const wxRichTextRange& range); -}; - - - -/** - @class wxRichTextCtrl - @headerfile richtextctrl.h wx/richtext/richtextctrl.h - - wxRichTextCtrl provides a generic, ground-up implementation of a text control - capable of showing multiple styles and images. - - wxRichTextCtrl sends notification events: see wxRichTextEvent. - It also sends the standard wxTextCtrl events wxEVT_COMMAND_TEXT_ENTER and - wxEVT_COMMAND_TEXT_UPDATED, - and wxTextUrlEvent when URL content is clicked. - - For more information, see the @ref overview_wxrichtextctrloverview - "wxRichTextCtrl overview". - - @library{wxrichtext} - @category{richtext} -*/ -class wxRichTextCtrl -{ -public: - //@{ - /** - Constructors. - */ - wxRichTextCtrl(); - wxRichTextCtrl(wxWindow* parent, wxWindowID id = wxID_ANY, - const wxString& value = wxEmptyString, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = wxRE_MULTILINE, - const wxValidator& validator = wxDefaultValidator, - const wxString& name = wxTextCtrlNameStr); - //@} - - /** - Destructor. - */ - ~wxRichTextCtrl(); - - /** - Adds an image to the control's buffer. - */ - wxRichTextRange AddImage(const wxImage& image); - - /** - Adds a new paragraph of text to the end of the buffer. - */ - wxRichTextRange AddParagraph(const wxString& text); - - /** - Sets the insertion point to the end of the buffer and writes the text. - */ - void AppendText(const wxString& text); - - /** - Applies the given alignment to the selection (undoable). - For alignment values, see wxTextAttr. - */ - bool ApplyAlignmentToSelection(wxTextAttrAlignment alignment); - - /** - Apples bold to the selection (undoable). - */ - bool ApplyBoldToSelection(); - - /** - Applies italic to the selection (undoable). - */ - bool ApplyItalicToSelection(); - - /** - Applies the given style to the selection. - */ - bool ApplyStyle(wxRichTextStyleDefinition* def); - - /** - Applies the style sheet to the buffer, matching paragraph styles in the sheet - against named styles - in the buffer. This might be useful if the styles have changed. If @a sheet is - @NULL, the - sheet set with SetStyleSheet is used. - Currently this applies paragraph styles only. - */ - bool ApplyStyleSheet(wxRichTextStyleSheet* sheet = NULL); - - /** - Applies underline to the selection (undoable). - */ - bool ApplyUnderlineToSelection(); - - /** - Returns @true if undo commands are being batched. - */ - bool BatchingUndo() const; - - /** - Begins using alignment - For alignment values, see wxTextAttr. - */ - bool BeginAlignment(wxTextAttrAlignment alignment); - - /** - Starts batching undo history for commands. - */ - bool BeginBatchUndo(const wxString& cmdName); - - /** - Begins using bold. - */ - bool BeginBold(); - - /** - Begins using the named character style. - */ - bool BeginCharacterStyle(const wxString& characterStyle); - - /** - Begins using this font. - */ - bool BeginFont(const wxFont& font); - - /** - Begins using the given point size. - */ - bool BeginFontSize(int pointSize); - - /** - Begins using italic. - */ - bool BeginItalic(); - - /** - Begins applying a left indent and subindent in tenths of a millimetre. - The sub-indent is an offset from the left of the paragraph, and is used for all - but the - first line in a paragraph. A positive value will cause the first line to appear - to the left - of the subsequent lines, and a negative value will cause the first line to be - indented - relative to the subsequent lines. - wxRichTextBuffer uses indentation to render a bulleted item. The left indent is - the distance between - the margin and the bullet. The content of the paragraph, including the first - line, starts - at leftMargin + leftSubIndent. So the distance between the left edge of the - bullet and the - left of the actual paragraph is leftSubIndent. - */ - bool BeginLeftIndent(int leftIndent, int leftSubIndent = 0); - - /** - Begins appling line spacing. @e spacing is a multiple, where 10 means - single-spacing, - 15 means 1.5 spacing, and 20 means double spacing. The following constants are - defined for convenience: - */ - bool BeginLineSpacing(int lineSpacing); - - /** - Begins using a specified list style. Optionally, you can also pass a level and - a number. - */ - bool BeginListStyle(const wxString& listStyle, int level = 1, - int number = 1); - - /** - Begins a numbered bullet. This call will be needed for each item in the list, - and the - application should take care of incrementing the numbering. - @a bulletNumber is a number, usually starting with 1. - @a leftIndent and @a leftSubIndent are values in tenths of a millimetre. - @a bulletStyle is a bitlist of the following values: - - wxRichTextBuffer uses indentation to render a bulleted item. The left indent is - the distance between - the margin and the bullet. The content of the paragraph, including the first - line, starts - at leftMargin + leftSubIndent. So the distance between the left edge of the - bullet and the - left of the actual paragraph is leftSubIndent. - */ - bool BeginNumberedBullet(int bulletNumber, int leftIndent, - int leftSubIndent, - int bulletStyle = wxTEXT_ATTR_BULLET_STYLE_ARABIC|wxTEXT_ATTR_BULLET_STYLE_PERIOD); - - /** - Begins paragraph spacing; pass the before-paragraph and after-paragraph spacing - in tenths of - a millimetre. - */ - bool BeginParagraphSpacing(int before, int after); - - /** - Begins applying the named paragraph style. - */ - bool BeginParagraphStyle(const wxString& paragraphStyle); - - /** - Begins a right indent, specified in tenths of a millimetre. - */ - bool BeginRightIndent(int rightIndent); - - /** - Begins applying a style. - */ - bool BeginStyle(const wxTextAttr& style); - - /** - Starts suppressing undo history for commands. - */ - bool BeginSuppressUndo(); - - /** - Begins applying a symbol bullet, using a character from the current font. See - BeginNumberedBullet() for - an explanation of how indentation is used to render the bulleted paragraph. - */ - bool BeginSymbolBullet(wxChar symbol, int leftIndent, - int leftSubIndent, - int bulletStyle = wxTEXT_ATTR_BULLET_STYLE_SYMBOL); - - /** - Begins using this colour. - */ - bool BeginTextColour(const wxColour& colour); - - /** - Begins applying wxTEXT_ATTR_URL to the content. Pass a URL and optionally, a - character style to apply, - since it is common to mark a URL with a familiar style such as blue text with - underlining. - */ - bool BeginURL(const wxString& url, - const wxString& characterStyle = wxEmptyString); - - /** - Begins using underlining. - */ - bool BeginUnderline(); - - /** - Returns @true if selected content can be copied to the clipboard. - */ - bool CanCopy() const; - - /** - Returns @true if selected content can be copied to the clipboard and deleted. - */ - bool CanCut() const; - - /** - Returns @true if selected content can be deleted. - */ - bool CanDeleteSelection() const; - - /** - Returns @true if the clipboard content can be pasted to the buffer. - */ - bool CanPaste() const; - - /** - Returns @true if there is a command in the command history that can be redone. - */ - bool CanRedo() const; - - /** - Returns @true if there is a command in the command history that can be undone. - */ - bool CanUndo() const; - - /** - Clears the buffer content, leaving a single empty paragraph. Cannot be undone. - */ - void Clear(); - - //@{ - /** - Clears the list style from the given range, clearing list-related attributes - and applying any named paragraph style associated with each paragraph. - @a flags is a bit list of the following: - wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable. - See also SetListStyle(), PromoteList(), NumberList(). - */ - bool ClearListStyle(const wxRichTextRange& range, - int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO); - bool ClearListStyle(const wxRichTextRange& range, - int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO); - //@} - - /** - Sends the event to the control. - */ - void Command(wxCommandEvent& event); - - /** - Copies the selected content (if any) to the clipboard. - */ - void Copy(); - - /** - Creates the underlying window. - */ - bool Create(wxWindow* parent, wxWindowID id = wxID_ANY, - const wxString& value = wxEmptyString, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = wxRE_MULTILINE, - const wxValidator& validator = wxDefaultValidator, - const wxString& name = wxTextCtrlNameStr); - - /** - Copies the selected content (if any) to the clipboard and deletes the selection. - This is undoable. - */ - void Cut(); - - /** - Deletes the content within the given range. - */ - bool Delete(const wxRichTextRange& range); - - /** - Deletes content if there is a selection, e.g. when pressing a key. - Returns the new caret position in @e newPos, or leaves it if there - was no action. This is undoable. - */ - bool DeleteSelectedContent(long* newPos = NULL); - - /** - Deletes the content in the selection, if any. This is undoable. - */ - void DeleteSelection(); - - /** - Sets the buffer's modified status to @false, and clears the buffer's command - history. - */ - void DiscardEdits(); - - /** - Currently this simply returns @c wxSize(10, 10). - */ - wxSize DoGetBestSize() const; - - /** - Ends alignment. - */ - bool EndAlignment(); - - /** - Ends application of all styles in the current style stack. - */ - bool EndAllStyles(); - - /** - Ends batching undo command history. - */ - bool EndBatchUndo(); - - /** - Ends using bold. - */ - bool EndBold(); - - /** - Ends application of a named character style. - */ - bool EndCharacterStyle(); - - /** - Ends using a font. - */ - bool EndFont(); - - /** - Ends using a point size. - */ - bool EndFontSize(); - - /** - Ends using italic. - */ - bool EndItalic(); - - /** - Ends left indent. - */ - bool EndLeftIndent(); - - /** - Ends line spacing. - */ - bool EndLineSpacing(); - - /** - Ends using a specified list style. - */ - bool EndListStyle(); - - /** - Ends application of a numbered bullet. - */ - bool EndNumberedBullet(); - - /** - Ends paragraph spacing. - */ - bool EndParagraphSpacing(); - - /** - Ends application of a named character style. - */ - bool EndParagraphStyle(); - - /** - Ends right indent. - */ - bool EndRightIndent(); - - /** - Ends the current style. - */ - bool EndStyle(); - - /** - Ends suppressing undo command history. - */ - bool EndSuppressUndo(); - - /** - Ends applying a symbol bullet. - */ - bool EndSymbolBullet(); - - /** - Ends applying a text colour. - */ - bool EndTextColour(); - - /** - Ends applying a URL. - */ - bool EndURL(); - - /** - End applying underlining. - */ - bool EndUnderline(); - - /** - Helper function for extending the selection, returning @true if the selection - was - changed. Selections are in caret positions. - */ - bool ExtendSelection(long oldPosition, long newPosition, - int flags); - - /** - Helper function for finding the caret position for the next word. Direction - is 1 (forward) or -1 (backwards). - */ - long FindNextWordPosition(int direction = 1) const; - - /** - Call this function to prevent refresh and allow fast updates, and then Thaw() to - refresh the control. - */ - void Freeze(); - - /** - Gets the basic (overall) style. This is the style of the whole - buffer before further styles are applied, unlike the default style, which - only affects the style currently being applied (for example, setting the default - style to bold will cause subsequently inserted text to be bold). - */ - const wxTextAttr GetBasicStyle() const; - - //@{ - /** - Returns the buffer associated with the control. - */ - const wxRichTextBuffer GetBuffer(); - const wxRichTextBuffer& GetBuffer(); - //@} - - /** - Returns the current caret position. - */ - long GetCaretPosition() const; - - /** - Returns the caret height and position for the given character position - */ - bool GetCaretPositionForIndex(long position, wxRect& rect); - - /** - Gets the command processor associated with the control's buffer. - */ - wxCommandProcessor* GetCommandProcessor() const; - - /** - Returns the current default style, which can be used to change how subsequently - inserted - text is displayed. - */ - const wxTextAttr GetDefaultStyle() const; - - /** - Gets the size of the buffer beyond which layout is delayed during resizing. - This optimizes sizing for large buffers. The default is 20000. - */ - long GetDelayedLayoutThreshold() const; - - /** - Gets the current filename associated with the control. - */ - wxString GetFilename() const; - - /** - Returns the first visible position in the current view. - */ - long GetFirstVisiblePosition() const; - - /** - Returns flags that change the behaviour of loading or saving. See the - documentation for each - handler class to see what flags are relevant for each handler. - */ - int GetHandlerFlags() const; - - /** - Returns the current insertion point. - */ - long GetInsertionPoint() const; - - /** - Returns the last position in the buffer. - */ - wxTextPos GetLastPosition() const; - - /** - Returns the length of the specified line in characters. - */ - int GetLineLength(long lineNo) const; - - /** - Returns the text for the given line. - */ - wxString GetLineText(long lineNo) const; - - /** - Transforms physical window position to logical (unscrolled) position. - */ - wxPoint GetLogicalPoint(const wxPoint& ptPhysical) const; - - /** - Returns the number of lines in the buffer. - */ - int GetNumberOfLines() const; - - /** - Transforms logical (unscrolled) position to physical window position. - */ - wxPoint GetPhysicalPoint(const wxPoint& ptLogical) const; - - /** - Gets the text for the given range. - The end point of range is specified as the last character position of the span - of text, plus one. - */ - wxString GetRange(long from, long to) const; - - /** - Returns the range of the current selection. - The end point of range is specified as the last character position of the span - of text, plus one. - If the return values @a from and @a to are the same, there is no selection. - */ - void GetSelection(long* from, long* to) const; - - /** - Returns the selection range in character positions. -1, -1 means no selection. - */ - const wxRichTextRange GetSelectionRange() const; - - /** - Returns the text within the current selection range, if any. - */ - wxString GetStringSelection() const; - - /** - Gets the attributes at the given position. - This function gets the combined style - that is, the style you see on the - screen as a result - of combining base style, paragraph style and character style attributes. To get - the character - or paragraph style alone, use GetUncombinedStyle(). - */ - bool GetStyle(long position, wxTextAttr& style); - - /** - Gets the attributes common to the specified range. Attributes that differ in - value within the range will - not be included in @e style's flags. - */ - bool GetStyleForRange(const wxRichTextRange& range, - wxTextAttr& style); - - /** - Returns the style sheet associated with the control, if any. A style sheet - allows named - character and paragraph styles to be applied. - */ - wxRichTextStyleSheet* GetStyleSheet() const; - - /** - Gets the attributes at the given position. - This function gets the @e uncombined style - that is, the attributes associated - with the - paragraph or character content, and not necessarily the combined attributes you - see on the - screen. To get the combined attributes, use GetStyle(). - If you specify (any) paragraph attribute in @e style's flags, this function - will fetch - the paragraph attributes. Otherwise, it will return the character attributes. - */ - bool GetUncombinedStyle(long position, wxTextAttr& style); - - /** - Returns the content of the entire control as a string. - */ - wxString GetValue() const; - - /** - Internal helper function returning the line for the visible caret position. If - the caret is - shown at the very end of the line, it means the next character is actually - on the following line. So this function gets the line we're expecting to find - if this is the case. - */ - wxRichTextLine* GetVisibleLineForCaretPosition(long caretPosition) const; - - /** - Test if this whole range has character attributes of the specified kind. If any - of the attributes are different within the range, the test fails. You - can use this to implement, for example, bold button updating. @a style must have - flags indicating which attributes are of interest. - */ - bool HasCharacterAttributes(const wxRichTextRange& range, - const wxTextAttr& style) const; - - /** - Test if this whole range has paragraph attributes of the specified kind. If any - of the attributes are different within the range, the test fails. You - can use this to implement, for example, centering button updating. @a style - must have - flags indicating which attributes are of interest. - */ - bool HasParagraphAttributes(const wxRichTextRange& range, - const wxTextAttr& style) const; - - /** - Returns @true if there is a selection. - */ - bool HasSelection() const; - - //@{ - /** - Finds the character at the given position in pixels. - @a pt is in device coords (not adjusted for the client area origin nor for - scrolling). - */ - wxTextCtrlHitTestResult HitTest(const wxPoint& pt, long* pos) const; - const wxTextCtrlHitTestResult HitTest(const wxPoint& pt, - wxTextCoord* col, - wxTextCoord* row) const; - //@} - - /** - Initialises the members of the control. - */ - void Init(); - - /** - Initialises the command event. - */ - void InitCommandEvent(wxCommandEvent& event) const; - - /** - Returns @true if the user has recently set the default style without moving - the caret, - and therefore the UI needs to reflect the default style and not the style at - the caret. - Below is an example of code that uses this function to determine whether the UI - should show that the current style is bold. - - See also SetAndShowDefaultStyle(). - */ - bool IsDefaultStyleShowing() const; - - /** - Returns @true if the control is editable. - */ - bool IsEditable() const; - - /** - Returns @true if Freeze has been called without a Thaw. - */ - bool IsFrozen() const; - - /** - Returns @true if the buffer has been modified. - */ - bool IsModified() const; - - /** - Returns @true if the control is multiline. - */ - bool IsMultiLine() const; - - /** - Returns @true if the given position is visible on the screen. - */ - bool IsPositionVisible(long pos) const; - - /** - Returns @true if all of the selection is aligned according to the specified - flag. - */ - bool IsSelectionAligned(wxTextAttrAlignment alignment) const; - - /** - Returns @true if all of the selection is bold. - */ - bool IsSelectionBold() const; - - /** - Returns @true if all of the selection is italic. - */ - bool IsSelectionItalics() const; - - /** - Returns @true if all of the selection is underlined. - */ - bool IsSelectionUnderlined() const; - - /** - Returns @true if the control is single-line. Currently wxRichTextCtrl does not - support single-line editing. - */ - bool IsSingleLine() const; - - /** - Helper function implementing keyboard navigation. - */ - bool KeyboardNavigate(int keyCode, int flags); - - /** - Lays out the buffer, which must be done before certain operations, such as - setting the caret position. This function should not normally be required by the - application. - */ - bool LayoutContent(bool onlyVisibleRect = false); - - /** - Inserts a line break at the current insertion point. A line break forces - wrapping within a paragraph, and - can be introduced by using this function, by appending the wxChar value @b - wxRichTextLineBreakChar to text content, - or by typing Shift-Return. - */ - bool LineBreak(); - - /** - Loads content into the control's buffer using the given type. If the specified - type - is wxRICHTEXT_TYPE_ANY, the type is deduced from the filename extension. - This function looks for a suitable wxRichTextFileHandler object. - */ - bool LoadFile(const wxString& file, - int type = wxRICHTEXT_TYPE_ANY); - - /** - Marks the buffer as modified. - */ - void MarkDirty(); - - /** - Move the caret to the given character position. - */ - bool MoveCaret(long pos, bool showAtLineStart = false); - - /** - Move the caret one visual step forward: this may mean setting a flag - and keeping the same position if we're going from the end of one line - to the start of the next, which may be the exact same caret position. - */ - void MoveCaretBack(long oldPosition); - - /** - Move the caret one visual step forward: this may mean setting a flag - and keeping the same position if we're going from the end of one line - to the start of the next, which may be the exact same caret position. - */ - void MoveCaretForward(long oldPosition); - - /** - Moves the caret down. - */ - bool MoveDown(int noLines = 1, int flags = 0); - - /** - Moves to the end of the buffer. - */ - bool MoveEnd(int flags = 0); - - /** - Moves to the start of the buffer. - */ - bool MoveHome(int flags = 0); - - /** - Moves left. - */ - bool MoveLeft(int noPositions = 1, int flags = 0); - - /** - Moves right. - */ - bool MoveRight(int noPositions = 1, int flags = 0); - - /** - Moves to the end of the line. - */ - bool MoveToLineEnd(int flags = 0); - - /** - Moves to the start of the line. - */ - bool MoveToLineStart(int flags = 0); - - /** - Moves to the end of the paragraph. - */ - bool MoveToParagraphEnd(int flags = 0); - - /** - Moves to the start of the paragraph. - */ - bool MoveToParagraphStart(int flags = 0); - - /** - Moves up. - */ - bool MoveUp(int noLines = 1, int flags = 0); - - /** - Inserts a new paragraph at the current insertion point. See also LineBreak(). - */ - bool Newline(); - - //@{ - /** - Numbers the paragraphs in the given range. Pass flags to determine how the - attributes are set. - Either the style definition or the name of the style definition (in the current - sheet) can be passed. - @a flags is a bit list of the following: - wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable. - wxRICHTEXT_SETSTYLE_RENUMBER: specifies that numbering should start from @e - startFrom, otherwise existing attributes are used. - wxRICHTEXT_SETSTYLE_SPECIFY_LEVEL: specifies that @a listLevel should be used - as the level for all paragraphs, otherwise the current indentation will be used. - See also SetListStyle(), PromoteList(), ClearListStyle(). - */ - bool NumberList(const wxRichTextRange& range, - const wxRichTextListStyleDefinition* style, - int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO, - int startFrom = -1, - int listLevel = -1); - bool Number(const wxRichTextRange& range, - const wxString& styleName, - int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO, - int startFrom = -1, - int listLevel = -1); - //@} - - /** - Standard handler for the wxID_CLEAR command. - */ - void OnClear(wxCommandEvent& event); - - /** - Shows a standard context menu with undo, redo, cut, copy, paste, clear, and - select all commands. - */ - void OnContextMenu(wxContextMenuEvent& event); - - /** - Standard handler for the wxID_COPY command. - */ - void OnCopy(wxCommandEvent& event); - - /** - Standard handler for the wxID_CUT command. - */ - void OnCut(wxCommandEvent& event); - - /** - Loads the first dropped file. - */ - void OnDropFiles(wxDropFilesEvent& event); - - /** - Standard handler for the wxID_PASTE command. - */ - void OnPaste(wxCommandEvent& event); - - /** - Standard handler for the wxID_REDO command. - */ - void OnRedo(wxCommandEvent& event); - - /** - Standard handler for the wxID_SELECTALL command. - */ - void OnSelectAll(wxCommandEvent& event); - - /** - Standard handler for the wxID_PASTE command. - */ - void OnUndo(wxCommandEvent& event); - - /** - Standard update handler for the wxID_CLEAR command. - */ - void OnUpdateClear(wxUpdateUIEvent& event); - - /** - Standard update handler for the wxID_COPY command. - */ - void OnUpdateCopy(wxUpdateUIEvent& event); - - /** - Standard update handler for the wxID_CUT command. - */ - void OnUpdateCut(wxUpdateUIEvent& event); - - /** - Standard update handler for the wxID_PASTE command. - */ - void OnUpdatePaste(wxUpdateUIEvent& event); - - /** - Standard update handler for the wxID_REDO command. - */ - void OnUpdateRedo(wxUpdateUIEvent& event); - - /** - Standard update handler for the wxID_SELECTALL command. - */ - void OnUpdateSelectAll(wxUpdateUIEvent& event); - - /** - Standard update handler for the wxID_UNDO command. - */ - void OnUpdateUndo(wxUpdateUIEvent& event); - - /** - Moves one or more pages down. - */ - bool PageDown(int noPages = 1, int flags = 0); - - /** - Moves one or more pages up. - */ - bool PageUp(int noPages = 1, int flags = 0); - - /** - Paints the background. - */ - void PaintBackground(wxDC& dc); - - /** - Pastes content from the clipboard to the buffer. - */ - void Paste(); - - /** - Internal function to position the visible caret according to the current caret - position. - */ - void PositionCaret(); - - /** - Converts a text position to zero-based column and line numbers. - */ - bool PositionToXY(long pos, long* x, long* y) const; - - //@{ - /** - Promotes or demotes the paragraphs in the given range. A positive @a promoteBy - produces a smaller indent, and a negative number - produces a larger indent. Pass flags to determine how the attributes are set. - Either the style definition or the name of the style definition (in the current - sheet) can be passed. - @a flags is a bit list of the following: - wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable. - wxRICHTEXT_SETSTYLE_RENUMBER: specifies that numbering should start from @e - startFrom, otherwise existing attributes are used. - wxRICHTEXT_SETSTYLE_SPECIFY_LEVEL: specifies that @a listLevel should be used - as the level for all paragraphs, otherwise the current indentation will be used. - See also SetListStyle(), See also SetListStyle(), ClearListStyle(). - */ - bool PromoteList(int promoteBy, const wxRichTextRange& range, - const wxRichTextListStyleDefinition* style, - int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO, - int listLevel = -1); - bool PromoteList(int promoteBy, const wxRichTextRange& range, - const wxString& styleName, - int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO, - int listLevel = -1); - //@} - - /** - Redoes the current command. - */ - void Redo(); - - /** - Removes the content in the specified range. - */ - void Remove(long from, long to); - - /** - Replaces the content in the specified range with the string specified by @e - value. - */ - void Replace(long from, long to, const wxString& value); - - /** - Saves the buffer content using the given type. If the specified type - is wxRICHTEXT_TYPE_ANY, the type is deduced from the filename extension. - This function looks for a suitable wxRichTextFileHandler object. - */ - bool SaveFile(const wxString& file = wxEmptyString, - int type = wxRICHTEXT_TYPE_ANY); - - /** - Scrolls @a position into view. This function takes a caret position. - */ - bool ScrollIntoView(long position, int keyCode); - - /** - Selects all the text in the buffer. - */ - void SelectAll(); - - /** - Cancels any selection. - */ - void SelectNone(); - - /** - Sets @a attr as the default style and tells the control that the UI should - reflect - this attribute until the user moves the caret. - See also IsDefaultStyleShowing(). - */ - void SetAndShowDefaultStyle(const wxTextAttr& attr); - - /** - Sets the basic (overall) style. This is the style of the whole - buffer before further styles are applied, unlike the default style, which - only affects the style currently being applied (for example, setting the default - style to bold will cause subsequently inserted text to be bold). - */ - void SetBasicStyle(const wxTextAttr& style); - - /** - The caret position is the character position just before the caret. - A value of -1 means the caret is at the start of the buffer. - */ - void SetCaretPosition(long position, - bool showAtLineStart = false); - - /** - Sets the current default style, which can be used to change how subsequently - inserted - text is displayed. - */ - bool SetDefaultStyle(const wxTextAttr& style); - - /** - Sets the default style to the style under the cursor. - */ - bool SetDefaultStyleToCursorStyle(); - - /** - Sets the size of the buffer beyond which layout is delayed during resizing. - This optimizes sizing for large buffers. The default is 20000. - */ - void SetDelayedLayoutThreshold(long threshold); - - /** - Makes the control editable, or not. - */ - void SetEditable(bool editable); - - /** - Sets the current filename. - */ - void SetFilename(const wxString& filename); - - /** - Sets the font, and also the basic and default attributes (see - wxRichTextCtrl::SetDefaultStyle). - */ - bool SetFont(const wxFont& font); - - /** - Sets flags that change the behaviour of loading or saving. See the - documentation for each - handler class to see what flags are relevant for each handler. - */ - void SetHandlerFlags(int flags); - - /** - Sets the insertion point. - */ - void SetInsertionPoint(long pos); - - /** - Sets the insertion point to the end of the text control. - */ - void SetInsertionPointEnd(); - - //@{ - /** - Sets the list attributes for the given range, passing flags to determine how - the attributes are set. - Either the style definition or the name of the style definition (in the current - sheet) can be passed. - @a flags is a bit list of the following: - wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable. - wxRICHTEXT_SETSTYLE_RENUMBER: specifies that numbering should start from @e - startFrom, otherwise existing attributes are used. - wxRICHTEXT_SETSTYLE_SPECIFY_LEVEL: specifies that @a listLevel should be used - as the level for all paragraphs, otherwise the current indentation will be used. - See also NumberList(), PromoteList(), ClearListStyle(). - */ - bool SetListStyle(const wxRichTextRange& range, - const wxRichTextListStyleDefinition* style, - int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO, - int startFrom = -1, - int listLevel = -1); - bool SetListStyle(const wxRichTextRange& range, - const wxString& styleName, - int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO, - int startFrom = -1, - int listLevel = -1); - //@} - - /** - Sets the selection to the given range. - The end point of range is specified as the last character position of the span - of text, plus one. - So, for example, to set the selection for a character at position 5, use the - range (5,6). - */ - void SetSelection(long from, long to); - - /** - Sets the selection to the given range. - The end point of range is specified as the last character position of the span - of text, plus one. - So, for example, to set the selection for a character at position 5, use the - range (5,6). - */ - void SetSelectionRange(const wxRichTextRange& range); - - //@{ - /** - Sets the attributes for the given range. - The end point of range is specified as the last character position of the span - of text, plus one. - So, for example, to set the style for a character at position 5, use the range - (5,6). - */ - bool SetStyle(const wxRichTextRange& range, - const wxTextAttr& style); - bool SetStyle(long start, long end, const wxTextAttr& style); - //@} - - //@{ - /** - Sets the attributes for the given range, passing flags to determine how the - attributes are set. - The end point of range is specified as the last character position of the span - of text, plus one. - So, for example, to set the style for a character at position 5, use the range - (5,6). - @a flags may contain a bit list of the following values: - wxRICHTEXT_SETSTYLE_NONE: no style flag. - wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this operation should be - undoable. - wxRICHTEXT_SETSTYLE_OPTIMIZE: specifies that the style should not be applied - if the - combined style at this point is already the style in question. - wxRICHTEXT_SETSTYLE_PARAGRAPHS_ONLY: specifies that the style should only be - applied to paragraphs, - and not the content. This allows content styling to be preserved independently - from that of e.g. a named paragraph style. - wxRICHTEXT_SETSTYLE_CHARACTERS_ONLY: specifies that the style should only be - applied to characters, - and not the paragraph. This allows content styling to be preserved - independently from that of e.g. a named paragraph style. - wxRICHTEXT_SETSTYLE_RESET: resets (clears) the existing style before applying - the new style. - wxRICHTEXT_SETSTYLE_REMOVE: removes the specified style. Only the style flags - are used in this operation. - */ - bool SetStyleEx(const wxRichTextRange& range, - const wxTextAttr& style, - int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO); - bool SetStyleEx(long start, long end, - const wxTextAttr& style, - int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO); - //@} - - /** - Sets the style sheet associated with the control. A style sheet allows named - character and paragraph styles to be applied. - */ - void SetStyleSheet(wxRichTextStyleSheet* styleSheet); - - /** - Replaces existing content with the given text. - */ - void SetValue(const wxString& value); - - /** - A helper function setting up scrollbars, for example after a resize. - */ - void SetupScrollbars(bool atTop = false); - - /** - Scrolls the buffer so that the given position is in view. - */ - void ShowPosition(long pos); - - /** - Returns @true if undo history suppression is on. - */ - bool SuppressingUndo() const; - - /** - Call this function to end a Freeze and refresh the display. - */ - void Thaw(); - - /** - Undoes the command at the top of the command history, if there is one. - */ - void Undo(); - - /** - Moves a number of words to the left. - */ - bool WordLeft(int noWords = 1, int flags = 0); - - /** - Move a nuber of words to the right. - */ - bool WordRight(int noWords = 1, int flags = 0); - - //@{ - /** - Write a bitmap or image at the current insertion point. Supply an optional type - to use - for internal and file storage of the raw data. - */ - bool WriteImage(const wxString& filename, int bitmapType); - bool WriteImage(const wxRichTextImageBlock& imageBlock); - bool WriteImage(const wxBitmap& bitmap, - int bitmapType = wxBITMAP_TYPE_PNG); - bool WriteImage(const wxImage& image, - int bitmapType = wxBITMAP_TYPE_PNG); - //@} - - /** - Writes text at the current position. - */ - void WriteText(const wxString& text); - - /** - Translates from column and line number to position. - */ - long XYToPosition(long x, long y) const; -}; - diff --git a/interface/richtext/richtextformatdlg.h b/interface/richtext/richtextformatdlg.h deleted file mode 100644 index c5d00abc7a..0000000000 --- a/interface/richtext/richtextformatdlg.h +++ /dev/null @@ -1,253 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: richtext/richtextformatdlg.h -// Purpose: interface of wxRichTextFormattingDialogFactory -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxRichTextFormattingDialogFactory - @headerfile richtextformatdlg.h wx/richtext/richtextformatdlg.h - - This class provides pages for wxRichTextFormattingDialog, and allows other - customization of the dialog. - A default instance of this class is provided automatically. If you wish to - change the behaviour of the - formatting dialog (for example add or replace a page), you may derive from this - class, - override one or more functions, and call the static function - wxRichTextFormattingDialog::SetFormattingDialogFactory. - - @library{wxrichtext} - @category{FIXME} -*/ -class wxRichTextFormattingDialogFactory : public wxObject -{ -public: - /** - Constructor. - */ - wxRichTextFormattingDialogFactory(); - - /** - Destructor. - */ - ~wxRichTextFormattingDialogFactory(); - - /** - Creates the main dialog buttons. - */ - virtual bool CreateButtons(wxRichTextFormattingDialog* dialog); - - /** - Creates a page, given a page identifier. - */ - virtual wxPanel* CreatePage(int page, wxString& title, - wxRichTextFormattingDialog* dialog); - - /** - Creates all pages under the dialog's book control, also calling AddPage. - */ - virtual bool CreatePages(long pages, - wxRichTextFormattingDialog* dialog); - - /** - Enumerate all available page identifiers. - */ - virtual int GetPageId(int i) const; - - /** - Gets the number of available page identifiers. - */ - virtual int GetPageIdCount() const; - - /** - Gets the image index for the given page identifier. - */ - virtual int GetPageImage(int id) const; - - /** - Set the property sheet style, called at the start of - wxRichTextFormattingDialog::Create. - */ - virtual bool SetSheetStyle(wxRichTextFormattingDialog* dialog); - - /** - Invokes help for the dialog. - */ - virtual bool ShowHelp(int page, - wxRichTextFormattingDialog* dialog); -}; - - - -/** - @class wxRichTextFormattingDialog - @headerfile richtextformatdlg.h wx/richtext/richtextformatdlg.h - - This dialog allows the user to edit a character and/or paragraph style. - - In the constructor, specify the pages that will be created. Use GetStyle - to retrieve the common style for a given range, and then use ApplyStyle - to apply the user-selected formatting to a control. For example: - - @code - wxRichTextRange range; - if (m_richTextCtrl-HasSelection()) - range = m_richTextCtrl-GetSelectionRange(); - else - range = wxRichTextRange(0, m_richTextCtrl-GetLastPosition()+1); - - int pages = - wxRICHTEXT_FORMAT_FONT|wxRICHTEXT_FORMAT_INDENTS_SPACING|wxRICHTEXT_FORMAT_TABS|wxRICHTEXT_FORMAT_BULLETS; - - wxRichTextFormattingDialog formatDlg(pages, this); - formatDlg.GetStyle(m_richTextCtrl, range); - - if (formatDlg.ShowModal() == wxID_OK) - { - formatDlg.ApplyStyle(m_richTextCtrl, range); - } - @endcode - - @library{wxrichtext} - @category{richtext} -*/ -class wxRichTextFormattingDialog : public wxPropertySheetDialog -{ -public: - //@{ - /** - Constructors. - - @param flags - The pages to show. - @param parent - The dialog's parent. - @param id - The dialog's identifier. - @param title - The dialog's caption. - @param pos - The dialog's position. - @param size - The dialog's size. - @param style - The dialog's window style. - */ - wxRichTextFormattingDialog(long flags, wxWindow* parent); - const wxPoint& pos = wxDefaultPosition, const wxSize& sz = wxDefaultSize, long style = wxDEFAULT_DIALOG_STYLE) - wxRichTextFormattingDialog(); - //@} - - /** - Destructor. - */ - ~wxRichTextFormattingDialog(); - - /** - Apply attributes to the given range, only changing attributes that need to be - changed. - */ - bool ApplyStyle(wxRichTextCtrl* ctrl, - const wxRichTextRange& range, - int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO|wxRICHTEXT_SETSTYLE_OPTIMIZE); - - /** - Creation: see @ref overview_wxrichtextformattingdialog "the constructor" for - details about the parameters. - */ - bool Create(long flags, wxWindow* parent, const wxString& title, - wxWindowID id, - const wxPoint& pos = wxDefaultPosition, - const wxSize& sz = wxDefaultSize, - long style = wxDEFAULT_DIALOG_STYLE); - - //@{ - /** - Gets the attributes being edited. - */ - const wxTextAttr GetAttributes(); - const wxTextAttr& GetAttributes(); - //@} - - /** - Helper for pages to get the top-level dialog. - */ - wxRichTextFormattingDialog* GetDialog(wxWindow* win); - - /** - Helper for pages to get the attributes. - */ - wxTextAttr* GetDialogAttributes(wxWindow* win); - - /** - Helper for pages to get the style. - */ - wxRichTextStyleDefinition* GetDialogStyleDefinition(wxWindow* win); - - /** - Returns the object to be used to customize the dialog and provide pages. - */ - wxRichTextFormattingDialogFactory* GetFormattingDialogFactory(); - - /** - Returns the image list associated with the dialog, used for example if showing - the dialog as a toolbook. - */ - wxImageList* GetImageList() const; - - /** - Gets common attributes from the given range and calls SetAttributes. Attributes - that do not have common values in the given range - will be omitted from the style's flags. - */ - bool GetStyle(wxRichTextCtrl* ctrl, const wxRichTextRange& range); - - /** - Gets the associated style definition, if any. - */ - wxRichTextStyleDefinition* GetStyleDefinition() const; - - /** - Gets the associated style sheet, if any. - */ - wxRichTextStyleSheet* GetStyleSheet() const; - - /** - Sets the attributes to be edited. - */ - void SetAttributes(const wxTextAttr& attr); - - /** - Sets the formatting factory object to be used for customization and page - creation. - It deletes the existing factory object. - */ - void SetFormattingDialogFactory(wxRichTextFormattingDialogFactory* factory); - - /** - Sets the image list associated with the dialog's property sheet. - */ - void SetImageList(wxImageList* imageList); - - /** - Sets the attributes and optionally updates the display, if @a update is @true. - */ - bool SetStyle(const wxTextAttr& style, bool update = true); - - /** - Sets the style definition and optionally update the display, if @a update is @c - @true. - */ - bool SetStyleDefinition(const wxRichTextStyleDefinition& styleDef, - wxRichTextStyleSheet* sheet, - bool update = true); - - /** - Updates the display. - */ - bool UpdateDisplay(); -}; - diff --git a/interface/richtext/richtexthtml.h b/interface/richtext/richtexthtml.h deleted file mode 100644 index 99e51abe0f..0000000000 --- a/interface/richtext/richtexthtml.h +++ /dev/null @@ -1,111 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: richtext/richtexthtml.h -// Purpose: interface of wxRichTextHTMLHandler -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxRichTextHTMLHandler - @headerfile richtexthtml.h wx/richtext/richtexthtml.h - - Handles HTML output (only) for wxRichTextCtrl content. - - The most flexible way to use this class is to create a temporary object and call - its functions directly, rather than use wxRichTextBuffer::SaveFile or - wxRichTextCtrl::SaveFile. - - Image handling requires a little extra work from the application, to choose an - appropriate image format for the target HTML viewer and to clean up the - temporary images - later. If you are planning to load the HTML into a standard web browser, you can - specify the handler flag wxRICHTEXT_HANDLER_SAVE_IMAGES_TO_BASE64 (the default) - and no extra work is required: the images will be written with the HTML. - - However, if you want wxHTML compatibility, you will need to use - wxRICHTEXT_HANDLER_SAVE_IMAGES_TO_MEMORY - or wxRICHTEXT_HANDLER_SAVE_IMAGES_TO_FILES. In this case, you must either call - wxRichTextHTMLHandler::DeleteTemporaryImages before - the next load operation, or you must store the image - locations and delete them yourself when appropriate. You can call - wxRichTextHTMLHandler::GetTemporaryImageLocations to - get the array of temporary image names. - - @library{wxrichtext} - @category{richtext} -*/ -class wxRichTextHTMLHandler : public wxRichTextFileHandler -{ -public: - /** - , wxString&@e ext = wxT("html"), @b int@e type = wxRICHTEXT_TYPE_HTML) - Constructor. - */ - wxRichTextHTMLHandler() const; - - /** - Clears the image locations generated by the last operation. - */ - void ClearTemporaryImageLocations(); - - //@{ - /** - Delete the in-memory or temporary files generated by the last operation. This - is a static - function that can be used to delete the saved locations from an earlier - operation, - for example after the user has viewed the HTML file. - */ - bool DeleteTemporaryImages(); - bool DeleteTemporaryImages(int flags, - const wxArrayString& imageLocations); - //@} - - /** - Saves the buffer content to the HTML stream. - */ - bool DoSaveFile(wxRichTextBuffer* buffer, wxOutputStream& stream); - - /** - Returns the mapping for converting point sizes to HTML font sizes. - */ - wxArrayInt GetFontSizeMapping(); - - /** - Returns the directory used to store temporary image files. - */ - const wxString GetTempDir() const; - - /** - Returns the image locations for the last operation. - */ - const wxArrayString GetTemporaryImageLocations() const; - - /** - Reset the file counter, in case, for example, the same names are required each - time - */ - void SetFileCounter(int counter); - - /** - Sets the mapping for converting point sizes to HTML font sizes. - There should be 7 elements, one for each HTML font size, each element - specifying the maximum point size for that - HTML font size. - For example: - */ - void SetFontSizeMapping(const wxArrayInt& fontSizeMapping); - - /** - Sets the directory for storing temporary files. If empty, the system - temporary directory will be used. - */ - void SetTempDir(const wxString& tempDir); - - /** - Sets the list of image locations generated by the last operation. - */ - void SetTemporaryImageLocations(const wxArrayString& locations); -}; - diff --git a/interface/richtext/richtextprint.h b/interface/richtext/richtextprint.h deleted file mode 100644 index 2c70bdbf5d..0000000000 --- a/interface/richtext/richtextprint.h +++ /dev/null @@ -1,397 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: richtext/richtextprint.h -// Purpose: interface of wxRichTextHeaderFooterData -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxRichTextHeaderFooterData - @headerfile richtextprint.h wx/richtext/richtextprint.h - - - This class represents header and footer data to be passed to the - wxRichTextPrinting and - wxRichTextPrintout classes. - - Headers and footers can be specified independently for odd, even or both page - sides. Different text can be specified - for left, centre and right locations on the page, and the font and text colour - can also - be specified. You can specify the following keywords in header and footer text, - which will - be substituted for the actual values during printing and preview. - - @DATE@: the current date. - @PAGESCNT@: the total number of pages. - @PAGENUM@: the current page number. - @TIME@: the current time. - @TITLE@: the title of the document, as passed to the wxRichTextPrinting or - wxRichTextLayout constructor. - - @library{wxrichtext} - @category{richtext} -*/ -class wxRichTextHeaderFooterData : public wxObject -{ -public: - //@{ - /** - Constructors. - */ - wxRichTextHeaderFooterData(); - wxRichTextHeaderFooterData(const wxRichTextHeaderFooterData& data); - //@} - - /** - Clears all text. - */ - void Clear(); - - /** - Copies the data. - */ - void Copy(const wxRichTextHeaderFooterData& data); - - /** - Returns the font specified for printing the header and footer. - */ - const wxFont GetFont() const; - - /** - Returns the margin between the text and the footer. - */ - int GetFooterMargin() const; - - /** - Returns the footer text on odd or even pages, and at a given position on the - page (left, centre or right). - */ - wxString GetFooterText(wxRichTextOddEvenPage page = wxRICHTEXT_PAGE_EVEN, - wxRichTextPageLocation location = wxRICHTEXT_PAGE_CENTRE) const; - - /** - Returns the margin between the text and the header. - */ - int GetHeaderMargin() const; - - /** - Returns the header text on odd or even pages, and at a given position on the - page (left, centre or right). - */ - wxString GetHeaderText(wxRichTextOddEvenPage page = wxRICHTEXT_PAGE_EVEN, - wxRichTextPageLocation location = wxRICHTEXT_PAGE_CENTRE) const; - - /** - Returns @true if the header and footer will be shown on the first page. - */ - bool GetShowOnFirstPage() const; - - /** - Helper function for getting the header or footer text, odd or even pages, and - at a given position on the page (left, centre or right). - */ - wxString GetText(int headerFooter, wxRichTextOddEvenPage page, - wxRichTextPageLocation location) const; - - /** - Returns the text colour for drawing the header and footer. - */ - const wxColour GetTextColour() const; - - /** - Initialises the object. - */ - void Init(); - - /** - Sets the font for drawing the header and footer. - */ - void SetFont(const wxFont& font); - - /** - Sets the footer text on odd or even pages, and at a given position on the page - (left, centre or right). - */ - void SetFooterText(const wxString& text, - wxRichTextOddEvenPage page = wxRICHTEXT_PAGE_ALL, - wxRichTextPageLocation location = wxRICHTEXT_PAGE_CENTRE); - - /** - Sets the header text on odd or even pages, and at a given position on the page - (left, centre or right). - */ - void SetHeaderText(const wxString& text, - wxRichTextOddEvenPage page = wxRICHTEXT_PAGE_ALL, - wxRichTextPageLocation location = wxRICHTEXT_PAGE_CENTRE); - - /** - Sets the margins between text and header or footer, in tenths of a millimeter. - */ - void SetMargins(int headerMargin, int footerMargin); - - /** - Pass @true to show the header or footer on first page (the default). - */ - void SetShowOnFirstPage(bool showOnFirstPage); - - /** - Helper function for setting the header or footer text, odd or even pages, and - at a given position on the page (left, centre or right). - */ - void SetText(const wxString& text, int headerFooter, - wxRichTextOddEvenPage page, - wxRichTextPageLocation location); - - /** - Sets the text colour for drawing the header and footer. - */ - void SetTextColour(const wxColour& col); - - /** - Assignment operator. - */ - void operator operator=(const wxRichTextHeaderFooterData& data); -}; - - - -/** - @class wxRichTextPrintout - @headerfile richtextprint.h wx/richtext/richtextprint.h - - This class implements print layout for wxRichTextBuffer. Instead of using it - directly, you - should normally use the wxRichTextPrinting class. - - @library{wxrichtext} - @category{richtext} -*/ -class wxRichTextPrintout : public wxPrintout -{ -public: - /** - ) - Constructor. - */ - wxRichTextPrintout(); - - /** - Calculates scaling and text, header and footer rectangles. - */ - void CalculateScaling(wxDC* dc, wxRect& textRect, - wxRect& headerRect, - wxRect& footerRect); - - /** - Returns the header and footer data associated with the printout. - */ - const wxRichTextHeaderFooterData GetHeaderFooterData() const; - - /** - Gets the page information. - */ - void GetPageInfo(int* minPage, int* maxPage, int* selPageFrom, - int* selPageTo); - - /** - Returns a pointer to the buffer being rendered. - */ - wxRichTextBuffer* GetRichTextBuffer() const; - - /** - Returns @true if the given page exists in the printout. - */ - bool HasPage(int page); - - /** - Prepares for printing, laying out the buffer and calculating pagination. - */ - void OnPreparePrinting(); - - /** - Does the actual printing for this page. - */ - bool OnPrintPage(int page); - - /** - Sets the header and footer data associated with the printout. - */ - void SetHeaderFooterData(const wxRichTextHeaderFooterData& data); - - /** - Sets margins in 10ths of millimetre. Defaults to 1 inch for margins. - */ - void SetMargins(int top = 252, int bottom = 252, int left = 252, - int right = 252); - - /** - Sets the buffer to print. wxRichTextPrintout does not manage this pointer; it - should - be managed by the calling code, such as wxRichTextPrinting. - */ - void SetRichTextBuffer(wxRichTextBuffer* buffer); -}; - - - -/** - @class wxRichTextPrinting - @headerfile richtextprint.h wx/richtext/richtextprint.h - - This class provides a simple interface for performing wxRichTextBuffer printing - and previewing. It uses wxRichTextPrintout for layout and rendering. - - @library{wxrichtext} - @category{richtext} -*/ -class wxRichTextPrinting : public wxObject -{ -public: - /** - , @b wxWindow*@e parentWindow = @NULL) - Constructor. Optionally pass a title to be used in the preview frame and - printing wait dialog, and - also a parent window for these windows. - */ - wxRichTextPrinting(); - - /** - A convenience function to get the footer text. See wxRichTextHeaderFooterData - for details. - */ - wxString GetFooterText(wxRichTextOddEvenPage page = wxRICHTEXT_PAGE_EVEN, - wxRichTextPageLocation location = wxRICHTEXT_PAGE_CENTRE) const; - - /** - Returns the internal wxRichTextHeaderFooterData object. - */ - const wxRichTextHeaderFooterData GetHeaderFooterData() const; - - /** - A convenience function to get the header text. See wxRichTextHeaderFooterData - for details. - */ - wxString GetHeaderText(wxRichTextOddEvenPage page = wxRICHTEXT_PAGE_EVEN, - wxRichTextPageLocation location = wxRICHTEXT_PAGE_CENTRE) const; - - /** - Returns a pointer to the internal page setup data. - */ - wxPageSetupDialogData* GetPageSetupData(); - - /** - Returns the parent window to be used for the preview window and printing wait - dialog. - */ - wxWindow* GetParentWindow() const; - - /** - Returns the dimensions to be used for the preview window. - */ - const wxRect GetPreviewRect() const; - - /** - Returns a pointer to the internal print data. - */ - wxPrintData* GetPrintData(); - - /** - Returns the title of the preview window or printing wait caption. - */ - const wxString GetTitle() const; - - /** - Shows the page setup dialog. - */ - void PageSetup(); - - /** - Shows a preview window for the given buffer. The function takes its own copy of - @e buffer. - */ - bool PreviewBuffer(const wxRichTextBuffer& buffer); - - /** - Shows a preview window for the given file. @a richTextFile can be a text file - or XML file, or other file - depending on the available file handlers. - */ - bool PreviewFile(const wxString& richTextFile); - - /** - Prints the given buffer. The function takes its own copy of @e buffer. - */ - bool PrintBuffer(const wxRichTextBuffer& buffer); - - /** - Prints the given file. @a richTextFile can be a text file or XML file, or other - file - depending on the available file handlers. - */ - bool PrintFile(const wxString& richTextFile); - - /** - A convenience function to set the footer text. See wxRichTextHeaderFooterData - for details. - */ - void SetFooterText(const wxString& text, - wxRichTextOddEvenPage page = wxRICHTEXT_PAGE_ALL, - wxRichTextPageLocation location = wxRICHTEXT_PAGE_CENTRE); - - /** - Sets the internal wxRichTextHeaderFooterData object. - */ - void SetHeaderFooterData(const wxRichTextHeaderFooterData& data); - - /** - Sets the wxRichTextHeaderFooterData font. - */ - void SetHeaderFooterFont(const wxFont& font); - - /** - Sets the wxRichTextHeaderFooterData text colour. - */ - void SetHeaderFooterTextColour(const wxColour& colour); - - /** - A convenience function to set the header text. See wxRichTextHeaderFooterData - for details. - */ - void SetHeaderText(const wxString& text, - wxRichTextOddEvenPage page = wxRICHTEXT_PAGE_ALL, - wxRichTextPageLocation location = wxRICHTEXT_PAGE_CENTRE); - - /** - Sets the page setup data. - */ - void SetPageSetupData(const wxPageSetupData& pageSetupData); - - /** - Sets the parent window to be used for the preview window and printing wait - dialog. - */ - void SetParentWindow(wxWindow* parent); - - /** - Sets the dimensions to be used for the preview window. - */ - void SetPreviewRect(const wxRect& rect); - - /** - Sets the print data. - */ - void SetPrintData(const wxPrintData& printData); - - /** - Pass @true to show the header and footer on the first page. - */ - void SetShowOnFirstPage(bool show); - - /** - Pass the title of the preview window or printing wait caption. - */ - void SetTitle(const wxString& title); -}; - diff --git a/interface/richtext/richtextstyledlg.h b/interface/richtext/richtextstyledlg.h deleted file mode 100644 index 38ad39121d..0000000000 --- a/interface/richtext/richtextstyledlg.h +++ /dev/null @@ -1,177 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: richtext/richtextstyledlg.h -// Purpose: interface of wxRichTextStyleOrganiserDialog -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxRichTextStyleOrganiserDialog - @headerfile richtextstyledlg.h wx/richtext/richtextstyledlg.h - - This class shows a style sheet and allows the user to edit, add and remove - styles. - It can also be used as a style browser, for example if the application is not - using a permanent wxRichTextStyleComboCtrl or wxRichTextStyleListCtrl to - present styles. - - @library{wxrichtext} - @category{richtext} -*/ -class wxRichTextStyleOrganiserDialog : public wxDialog -{ -public: - //@{ - /** - Constructors. - To create a dialog, pass a bitlist of @a flags (see below), a style sheet, a - text control to apply a selected style to (or @NULL), followed by the usual window parameters. - To specify the operations available to the user, pass a combination of these - values to @e flags: - - @b wxRICHTEXT_ORGANISER_DELETE_STYLES - - Provides a button for deleting styles. - - @b wxRICHTEXT_ORGANISER_CREATE_STYLES - - Provides buttons for creating styles. - - @b wxRICHTEXT_ORGANISER_APPLY_STYLES - - Provides a button for applying the currently selected style to the selection. - - @b wxRICHTEXT_ORGANISER_EDIT_STYLES - - Provides a button for editing styles. - - @b wxRICHTEXT_ORGANISER_RENAME_STYLES - - Provides a button for renaming styles. - - @b wxRICHTEXT_ORGANISER_OK_CANCEL - - Provides OK and Cancel buttons. - - @b wxRICHTEXT_ORGANISER_RENUMBER - - Provides a checkbox for specifying that the selection should be renumbered. - - The following flags determine what will be displayed in the style list: - - @b wxRICHTEXT_ORGANISER_SHOW_CHARACTER - - Displays character styles only. - - @b wxRICHTEXT_ORGANISER_SHOW_PARAGRAPH - - Displays paragraph styles only. - - @b wxRICHTEXT_ORGANISER_SHOW_LIST - - Displays list styles only. - - @b wxRICHTEXT_ORGANISER_SHOW_ALL - - Displays all styles. - - The following symbols define commonly-used combinations of flags: - - @b wxRICHTEXT_ORGANISER_ORGANISE - - Enable all style editing operations so the dialog behaves as a style organiser. - - @b wxRICHTEXT_ORGANISER_BROWSE - - Show a list of all styles and their previews, but only allow application of a - style or - cancellation of the dialog. This makes the dialog behave as a style browser. - - @b wxRICHTEXT_ORGANISER_BROWSE_NUMBERING - - Enables only list style browsing, plus a control to specify renumbering. This - allows the dialog to be used for applying list styles to the selection. - */ - wxRichTextStyleOrganiserDialog(int flags, - wxRichTextStyleSheet* sheet, - wxRichTextCtrl* ctrl, - wxWindow* parent, - wxWindowID id = wxID_ANY); - const wxSize& size = wxDefaultSize, long style = wxDEFAULT_DIALOG_STYLE|wxRESIZE_BORDER|wxSYSTEM_MENU|wxCLOSE_BOX) - wxRichTextStyleOrganiserDialog(); - //@} - - /** - Applies the selected style to selection in the given control or the control - passed to the constructor. - */ - bool ApplyStyle(wxRichTextCtrl* ctrl = NULL); - - /** - , wxPoint&@e pos = wxDefaultPosition, wxSize&@e size = wxDefaultSize, @b - long@e style = wxDEFAULT_DIALOG_STYLE|wxRESIZE_BORDER|wxSYSTEM_MENU|wxCLOSE_BOX) - Creates the dialog. See - */ - bool Create(int flags, wxRichTextStyleSheet* sheet, - wxRichTextCtrl* ctrl, - wxWindow* parent, - wxWindowID id = wxID_ANY) const; - - /** - Returns @true if the user has opted to restart numbering. - */ - bool GetRestartNumbering() const; - - /** - Returns the associated rich text control (if any). - */ - wxRichTextCtrl* GetRichTextCtrl() const; - - /** - Returns selected style name. - */ - wxString GetSelectedStyle() const; - - /** - Returns selected style definition. - */ - wxRichTextStyleDefinition* GetSelectedStyleDefinition() const; - - /** - Returns the associated style sheet. - */ - wxRichTextStyleSheet* GetStyleSheet() const; - - /** - Sets the flags used to control the interface presented to the user. - */ - void SetFlags(int flags); - - /** - Checks or unchecks the restart numbering checkbox. - */ - void SetRestartNumbering(bool restartNumbering); - - /** - Sets the control to be associated with the dialog, for the purposes of applying - a style to the selection. - */ - void SetRichTextCtrl(wxRichTextCtrl* ctrl); - - /** - Determines whether tooltips will be shown. - */ - void SetShowToolTips(bool show); - - /** - Sets the associated style sheet. - */ - void SetStyleSheet(wxRichTextStyleSheet* sheet); - - /** - Returns the flags used to control the interface presented to the user. - */ - int GetFlags() const; -}; - diff --git a/interface/richtext/richtextstyles.h b/interface/richtext/richtextstyles.h deleted file mode 100644 index a054d938cc..0000000000 --- a/interface/richtext/richtextstyles.h +++ /dev/null @@ -1,677 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: richtext/richtextstyles.h -// Purpose: interface of wxRichTextStyleListCtrl -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxRichTextStyleListCtrl - @headerfile richtextstyles.h wx/richtext/richtextstyles.h - - This class incorporates a wxRichTextStyleListBox and - a choice control that allows the user to select the category of style to view. - It is demonstrated in the wxRichTextCtrl sample in @c samples/richtext. - - To use wxRichTextStyleListCtrl, add the control to your window hierarchy and - call wxRichTextStyleListCtrl::SetStyleType with - one of wxRichTextStyleListBox::wxRICHTEXT_STYLE_ALL, - wxRichTextStyleListBox::wxRICHTEXT_STYLE_PARAGRAPH, - wxRichTextStyleListBox::wxRICHTEXT_STYLE_CHARACTER and - wxRichTextStyleListBox::wxRICHTEXT_STYLE_LIST to set the current view. - Associate the control with a style sheet and rich text control with - SetStyleSheet and SetRichTextCtrl, - so that when a style is double-clicked, it is applied to the selection. - - @beginStyleTable - @style{wxRICHTEXTSTYLELIST_HIDE_TYPE_SELECTOR} - This style hides the category selection control. - @endStyleTable - - @library{wxrichtext} - @category{FIXME} -*/ -class wxRichTextStyleListCtrl : public wxControl -{ -public: - //@{ - /** - Constructors. - */ - wxRichTextStyleListCtrl(wxWindow* parent, - wxWindowID id = wxID_ANY, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = 0); - wxRichTextStyleListCtrl(); - //@} - - /** - Creates the windows. - */ - bool Create(wxWindow* parent, wxWindowID id = wxID_ANY, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = 0); - - /** - Returns the associated rich text control, if any. - */ - wxRichTextCtrl* GetRichTextCtrl() const; - - /** - Returns the wxChoice control used for selecting the style category. - */ - wxChoice* GetStyleChoice() const; - - /** - Returns the wxListBox control used to view the style list. - */ - wxRichTextStyleListBox* GetStyleListBox() const; - - /** - Returns the associated style sheet, if any. - */ - wxRichTextStyleSheet* GetStyleSheet() const; - - /** - Returns the type of style to show in the list box. - */ - wxRichTextStyleListBox::wxRichTextStyleType GetStyleType() const; - - /** - Associates the control with a wxRichTextCtrl. - */ - void SetRichTextCtrl(wxRichTextCtrl* ctrl); - - /** - Associates the control with a style sheet. - */ - void SetStyleSheet(wxRichTextStyleSheet* styleSheet); - - /** - Sets the style type to display. One of - wxRichTextStyleListBox::wxRICHTEXT_STYLE_ALL, wxRichTextStyleListBox::wxRICHTEXT_STYLE_PARAGRAPH, - wxRichTextStyleListBox::wxRICHTEXT_STYLE_CHARACTER and - wxRichTextStyleListBox::wxRICHTEXT_STYLE_LIST. - */ - void SetStyleType(wxRichTextStyleListBox::wxRichTextStyleType styleType); - - /** - Updates the style list box. - */ - void UpdateStyles(); -}; - - - -/** - @class wxRichTextStyleDefinition - @headerfile richtextstyles.h wx/richtext/richtextstyles.h - - This is a base class for paragraph and character styles. - - @library{wxrichtext} - @category{FIXME} -*/ -class wxRichTextStyleDefinition : public wxObject -{ -public: - /** - Constructor. - */ - wxRichTextStyleDefinition(const wxString& name = wxEmptyString); - - /** - Destructor. - */ - ~wxRichTextStyleDefinition(); - - /** - Returns the style on which this style is based. - */ - const wxString GetBaseStyle() const; - - /** - Returns the style's description. - */ - const wxString GetDescription() const; - - /** - Returns the style name. - */ - const wxString GetName() const; - - //@{ - /** - Returns the attributes associated with this style. - */ - wxTextAttr GetStyle() const; - const wxTextAttr GetStyle() const; - //@} - - /** - Returns the style attributes combined with the attributes of the specified base - style, if any. This function works recursively. - */ - wxTextAttr GetStyleMergedWithBase(wxRichTextStyleSheet* sheet) const; - - /** - Sets the name of the style that this style is based on. - */ - void SetBaseStyle(const wxString& name); - - /** - Sets the style description. - */ - void SetDescription(const wxString& descr); - - /** - Sets the name of the style. - */ - void SetName(const wxString& name); - - /** - Sets the attributes for this style. - */ - void SetStyle(const wxTextAttr& style); -}; - - - -/** - @class wxRichTextParagraphStyleDefinition - @headerfile richtextstyles.h wx/richtext/richtextstyles.h - - This class represents a paragraph style definition, usually added to a - wxRichTextStyleSheet. - - @library{wxrichtext} - @category{richtext} -*/ -class wxRichTextParagraphStyleDefinition : public wxRichTextStyleDefinition -{ -public: - /** - Constructor. - */ - wxRichTextParagraphStyleDefinition(const wxString& name = wxEmptyString); - - /** - Destructor. - */ - ~wxRichTextParagraphStyleDefinition(); - - /** - Returns the style that should normally follow this style. - */ - const wxString GetNextStyle() const; - - /** - Sets the style that should normally follow this style. - */ - void SetNextStyle(const wxString& name); -}; - - - -/** - @class wxRichTextStyleListBox - @headerfile richtextstyles.h wx/richtext/richtextstyles.h - - This is a listbox that can display the styles in a wxRichTextStyleSheet, - and apply the selection to an associated wxRichTextCtrl. - - See @c samples/richtext for an example of how to use it. - - @library{wxrichtext} - @category{richtext} - - @see wxRichTextStyleComboCtrl, @ref overview_wxrichtextctrloverview - "wxRichTextCtrl overview" -*/ -class wxRichTextStyleListBox : public wxHtmlListBox -{ -public: - /** - Constructor. - */ - wxRichTextStyleListBox(wxWindow* parent, - wxWindowID id = wxID_ANY, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = 0); - - /** - Destructor. - */ - ~wxRichTextStyleListBox(); - - /** - Applies the @e ith style to the associated rich text control. - */ - void ApplyStyle(int i); - - /** - Converts units in tenths of a millimetre to device units. - */ - int ConvertTenthsMMToPixels(wxDC& dc, int units) const; - - /** - Creates a suitable HTML fragment for a definition. - */ - wxString CreateHTML(wxRichTextStyleDefinition* def) const; - - /** - If the return value is @true, clicking on a style name in the list will - immediately - apply the style to the associated rich text control. - */ - bool GetApplyOnSelection() const; - - /** - Returns the wxRichTextCtrl associated with this listbox. - */ - wxRichTextCtrl* GetRichTextCtrl() const; - - /** - Gets a style for a listbox index. - */ - wxRichTextStyleDefinition* GetStyle(size_t i) const; - - /** - Returns the style sheet associated with this listbox. - */ - wxRichTextStyleSheet* GetStyleSheet() const; - - /** - Returns the type of style to show in the list box. - */ - wxRichTextStyleListBox::wxRichTextStyleType GetStyleType() const; - - /** - Returns the HTML for this item. - */ - wxString OnGetItem(size_t n) const; - - /** - Implements left click behaviour, applying the clicked style to the - wxRichTextCtrl. - */ - void OnLeftDown(wxMouseEvent& event); - - /** - Reacts to selection. - */ - void OnSelect(wxCommandEvent& event); - - /** - If @a applyOnSelection is @true, clicking on a style name in the list will - immediately - apply the style to the associated rich text control. - */ - void SetApplyOnSelection(bool applyOnSelection); - - /** - Associates the listbox with a wxRichTextCtrl. - */ - void SetRichTextCtrl(wxRichTextCtrl* ctrl); - - /** - Associates the control with a style sheet. - */ - void SetStyleSheet(wxRichTextStyleSheet* styleSheet); - - /** - Sets the style type to display. One of - wxRichTextStyleListBox::wxRICHTEXT_STYLE_ALL, wxRichTextStyleListBox::wxRICHTEXT_STYLE_PARAGRAPH, - wxRichTextStyleListBox::wxRICHTEXT_STYLE_CHARACTER and - wxRichTextStyleListBox::wxRICHTEXT_STYLE_LIST. - */ - void SetStyleType(wxRichTextStyleListBox::wxRichTextStyleType styleType); - - /** - Updates the list from the associated style sheet. - */ - void UpdateStyles(); -}; - - - -/** - @class wxRichTextStyleComboCtrl - @headerfile richtextstyles.h wx/richtext/richtextstyles.h - - This is a combo control that can display the styles in a wxRichTextStyleSheet, - and apply the selection to an associated wxRichTextCtrl. - - See @c samples/richtext for an example of how to use it. - - @library{wxrichtext} - @category{richtext} - - @see wxRichTextStyleListBox, @ref overview_wxrichtextctrloverview - "wxRichTextCtrl overview" -*/ -class wxRichTextStyleComboCtrl : public wxComboCtrl -{ -public: - /** - Constructor. - */ - wxRichTextStyleComboCtrl(wxWindow* parent, - wxWindowID id = wxID_ANY, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = 0); - - /** - Destructor. - */ - ~wxRichTextStyleComboCtrl(); - - /** - Returns the wxRichTextCtrl associated with this control. - */ - wxRichTextCtrl* GetRichTextCtrl() const; - - /** - Returns the style sheet associated with this control. - */ - wxRichTextStyleSheet* GetStyleSheet() const; - - /** - Associates the control with a wxRichTextCtrl. - */ - void SetRichTextCtrl(wxRichTextCtrl* ctrl); - - /** - Associates the control with a style sheet. - */ - void SetStyleSheet(wxRichTextStyleSheet* styleSheet); - - /** - Updates the combo control from the associated style sheet. - */ - void UpdateStyles(); -}; - - - -/** - @class wxRichTextCharacterStyleDefinition - @headerfile richtextstyles.h wx/richtext/richtextstyles.h - - This class represents a character style definition, usually added to a - wxRichTextStyleSheet. - - @library{wxrichtext} - @category{richtext} -*/ -class wxRichTextCharacterStyleDefinition : public wxRichTextStyleDefinition -{ -public: - /** - Constructor. - */ - wxRichTextCharacterStyleDefinition(const wxString& name = wxEmptyString); - - /** - Destructor. - */ - ~wxRichTextCharacterStyleDefinition(); -}; - - - -/** - @class wxRichTextListStyleDefinition - @headerfile richtextstyles.h wx/richtext/richtextstyles.h - - This class represents a list style definition, usually added to a - wxRichTextStyleSheet. - - The class inherits paragraph attributes from - wxRichTextStyleParagraphDefinition, and adds 10 further attribute objects, one for each level of a list. - When applying a list style to a paragraph, the list style's base and - appropriate level attributes are merged with the - paragraph's existing attributes. - - You can apply a list style to one or more paragraphs using - wxRichTextCtrl::SetListStyle. You - can also use the functions wxRichTextCtrl::NumberList, - wxRichTextCtrl::PromoteList and - wxRichTextCtrl::ClearListStyle. As usual, there are wxRichTextBuffer versions - of these functions - so that you can apply them directly to a buffer without requiring a control. - - @library{wxrichtext} - @category{richtext} -*/ -class wxRichTextListStyleDefinition : public wxRichTextParagraphStyleDefinition -{ -public: - /** - Constructor. - */ - wxRichTextListStyleDefinition(const wxString& name = wxEmptyString); - - /** - Destructor. - */ - ~wxRichTextListStyleDefinition(); - - /** - This function combines the given paragraph style with the list style's base - attributes and level style matching the given indent, returning the combined attributes. - If @a styleSheet is specified, the base style for this definition will also be - included in the result. - */ - wxTextAttr CombineWithParagraphStyle(int indent, - const wxTextAttr& paraStyle, - wxRichTextStyleSheet* styleSheet = NULL); - - /** - This function finds the level (from 0 to 9) whose indentation attribute mostly - closely matches @a indent (expressed in tenths of a millimetre). - */ - int FindLevelForIndent(int indent) const; - - /** - This function combines the list style's base attributes and the level style - matching the given indent, returning the combined attributes. - If @a styleSheet is specified, the base style for this definition will also be - included in the result. - */ - wxTextAttr GetCombinedStyle(int indent, - wxRichTextStyleSheet* styleSheet = NULL) const; - - /** - This function combines the list style's base attributes and the style for the - specified level, returning the combined attributes. - If @a styleSheet is specified, the base style for this definition will also be - included in the result. - */ - wxTextAttr GetCombinedStyleLevel(int level, - wxRichTextStyleSheet* styleSheet = NULL) const; - - /** - Returns the style for the given level. @a level is a number between 0 and 9. - */ - const wxTextAttr* GetLevelAttributes(int level) const; - - /** - Returns the number of levels. This is hard-wired to 10. - Returns the style for the given level. @e level is a number between 0 and 9. - */ - int GetLevelCount() const; - - /** - Returns @true if the given level has numbered list attributes. - */ - int IsNumbered(int level) const; - - //@{ - /** - Sets the style for the given level. @a level is a number between 0 and 9. - The first and most flexible form uses a wxTextAttr object, while the second - form is for convenient setting of the most commonly-used attributes. - */ - void SetLevelAttributes(int level, const wxTextAttr& attr); - void SetLevelAttributes(int level, int leftIndent, - int leftSubIndent, - int bulletStyle, - const wxString& bulletSymbol = wxEmptyString); - //@} -}; - - - -/** - @class wxRichTextStyleSheet - @headerfile richtextstyles.h wx/richtext/richtextstyles.h - - A style sheet contains named paragraph and character styles that make it - easy for a user to apply combinations of attributes to a wxRichTextCtrl. - - You can use a wxRichTextStyleListBox in your - user interface to show available styles to the user, and allow application - of styles to the control. - - @library{wxrichtext} - @category{richtext} -*/ -class wxRichTextStyleSheet : public wxObject -{ -public: - /** - Constructor. - */ - wxRichTextStyleSheet(); - - /** - Destructor. - */ - ~wxRichTextStyleSheet(); - - /** - Adds a definition to the character style list. - */ - bool AddCharacterStyle(wxRichTextCharacterStyleDefinition* def); - - /** - Adds a definition to the list style list. - */ - bool AddListStyle(wxRichTextListStyleDefinition* def); - - /** - Adds a definition to the paragraph style list. - */ - bool AddParagraphStyle(wxRichTextParagraphStyleDefinition* def); - - /** - Adds a definition to the appropriate style list. - */ - bool AddStyle(wxRichTextStyleDefinition* def); - - /** - Deletes all styles. - */ - void DeleteStyles(); - - /** - Finds a character definition by name. - */ - wxRichTextCharacterStyleDefinition* FindCharacterStyle(const wxString& name) const; - - /** - Finds a list definition by name. - */ - wxRichTextListStyleDefinition* FindListStyle(const wxString& name) const; - - /** - Finds a paragraph definition by name. - */ - wxRichTextParagraphStyleDefinition* FindParagraphStyle(const wxString& name) const; - - /** - Finds a style definition by name. - */ - wxRichTextStyleDefinition* FindStyle(const wxString& name) const; - - /** - Returns the @e nth character style. - */ - wxRichTextCharacterStyleDefinition* GetCharacterStyle(size_t n) const; - - /** - Returns the number of character styles. - */ - size_t GetCharacterStyleCount() const; - - /** - Returns the style sheet's description. - */ - const wxString GetDescription() const; - - /** - Returns the @e nth list style. - */ - wxRichTextListStyleDefinition* GetListStyle(size_t n) const; - - /** - Returns the number of list styles. - */ - size_t GetListStyleCount() const; - - /** - Returns the style sheet's name. - */ - const wxString GetName() const; - - /** - Returns the @e nth paragraph style. - */ - wxRichTextParagraphStyleDefinition* GetParagraphStyle(size_t n) const; - - /** - Returns the number of paragraph styles. - */ - size_t GetParagraphStyleCount() const; - - /** - Removes a character style. - */ - bool RemoveCharacterStyle(wxRichTextStyleDefinition* def, - bool deleteStyle = false); - - /** - Removes a list style. - */ - bool RemoveListStyle(wxRichTextStyleDefinition* def, - bool deleteStyle = false); - - /** - Removes a paragraph style. - */ - bool RemoveParagraphStyle(wxRichTextStyleDefinition* def, - bool deleteStyle = false); - - /** - Removes a style. - */ - bool RemoveStyle(wxRichTextStyleDefinition* def, - bool deleteStyle = false); - - /** - Sets the style sheet's description. - */ - void SetDescription(const wxString& descr); - - /** - Sets the style sheet's name. - */ - void SetName(const wxString& name); -}; - diff --git a/interface/richtext/richtextsymboldlg.h b/interface/richtext/richtextsymboldlg.h deleted file mode 100644 index f862372780..0000000000 --- a/interface/richtext/richtextsymboldlg.h +++ /dev/null @@ -1,190 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: richtext/richtextsymboldlg.h -// Purpose: interface of wxSymbolPickerDialog -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxSymbolPickerDialog - @headerfile richtextsymboldlg.h wx/richtext/richtextsymboldlg.h - - wxSymbolPickerDialog presents the user with a choice of fonts and a grid - of available characters. This modal dialog provides the application with - a selected symbol and optional font selection. - - Although this dialog is contained in the rich text library, the dialog - is generic and can be used in other contexts. - - To use the dialog, pass a default symbol specified as a string, an initial font - name, - and a current font name. The difference between the initial font and - current font is that the initial font determines what the font control will be - set to when the dialog shows - an empty string will show the selection @e - normal text. - The current font, on the other hand, is used by the dialog to determine what - font - to display the characters in, even when no initial font is selected. - This allows the user (and application) to distinguish between inserting a - symbol in the current font, and inserting it with a specified font. - - When the dialog is dismissed, the application can get the selected symbol - with GetSymbol and test whether a font was specified with UseNormalFont, - fetching the specified font with GetFontName. - - Here's a realistic example, inserting the supplied symbol into a - rich text control in either the current font or specified font. - - @code - wxRichTextCtrl* ctrl = (wxRichTextCtrl*) FindWindow(ID_RICHTEXT_CTRL); - - wxTextAttr attr; - attr.SetFlags(wxTEXT_ATTR_FONT); - ctrl-GetStyle(ctrl-GetInsertionPoint(), attr); - - wxString currentFontName; - if (attr.HasFont() && attr.GetFont().Ok()) - currentFontName = attr.GetFont().GetFaceName(); - - // Don't set the initial font in the dialog (so the user is choosing - // 'normal text', i.e. the current font) but do tell the dialog - // what 'normal text' is. - - wxSymbolPickerDialog dlg(wxT("*"), wxEmptyString, currentFontName, this); - - if (dlg.ShowModal() == wxID_OK) - { - if (dlg.HasSelection()) - { - long insertionPoint = ctrl-GetInsertionPoint(); - - ctrl-WriteText(dlg.GetSymbol()); - - if (!dlg.UseNormalFont()) - { - wxFont font(attr.GetFont()); - font.SetFaceName(dlg.GetFontName()); - attr.SetFont(font); - ctrl-SetStyle(insertionPoint, insertionPoint+1, attr); - } - } - } - @endcode - - @library{wxrichtext} - @category{cmndlg} -*/ -class wxSymbolPickerDialog : public wxDialog -{ -public: - //@{ - /** - Constructors. - - @param symbol - The initial symbol to show. Specify a single character in a string, or an - empty string. - @param initialFont - The initial font to be displayed in the font list. If empty, the item - normal text will be selected. - @param normalTextFont - The font the dialog will use to display the symbols if the initial font is - empty. - @param parent - The dialog's parent. - @param id - The dialog's identifier. - @param title - The dialog's caption. - @param pos - The dialog's position. - @param size - The dialog's size. - @param style - The dialog's window style. - */ - wxSymbolPickerDialog(const wxString& symbol, - const wxString& initialFont, - const wxString& normalTextFont, - wxWindow* parent, - wxWindowID id = wxID_ANY); - const wxSize& size = wxDefaultSize, long style = wxDEFAULT_DIALOG_STYLE|wxRESIZE_BORDER|wxCLOSE_BOX) - wxSymbolPickerDialog(); - //@} - - /** - , wxPoint&@e pos = wxDefaultPosition, wxSize&@e size = wxDefaultSize, @b - long@e style = wxDEFAULT_DIALOG_STYLE|wxRESIZE_BORDER|wxCLOSE_BOX) - Creation: see @ref wxsymbolpickerdialog() "the constructor" for details about - the parameters. - */ - bool Create(const wxString& symbol, const wxString& initialFont, - const wxString& normalTextFont, - wxWindow* parent, - wxWindowID id = wxID_ANY) const; - - /** - Returns the font name (the font reflected in the font list). - */ - wxString GetFontName() const; - - /** - Returns @true if the dialog is showing the full range of Unicode characters. - */ - bool GetFromUnicode() const; - - /** - Gets the font name used for displaying symbols in the absence of a selected - font. - */ - wxString GetNormalTextFontName() const; - - /** - Gets the current or initial symbol as a string. - */ - wxString GetSymbol() const; - - /** - Gets the selected symbol character as an integer. - */ - int GetSymbolChar() const; - - /** - Returns @true if a symbol is selected. - */ - bool HasSelection() const; - - /** - Sets the initial/selected font name. - */ - void SetFontName(const wxString& value); - - /** - Sets the internal flag indicating that the full Unicode range should be - displayed. - */ - void SetFromUnicode(bool value); - - /** - Sets the name of the font to be used in the absence of a selected font. - */ - void SetNormalTextFontName(const wxString& value); - - /** - Sets the symbol as a one or zero character string. - */ - void SetSymbol(const wxString& value); - - /** - Sets Unicode display mode. - */ - void SetUnicodeMode(bool unicodeMode); - - /** - Returns @true if the has specified normal text - that is, there is no selected - font. - */ - bool UseNormalFont() const; -}; - diff --git a/interface/richtext/richtextxml.h b/interface/richtext/richtextxml.h deleted file mode 100644 index f469e5401a..0000000000 --- a/interface/richtext/richtextxml.h +++ /dev/null @@ -1,102 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: richtext/richtextxml.h -// Purpose: interface of wxRichTextXMLHandler -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxRichTextXMLHandler - @headerfile richtextxml.h wx/richtext/richtextxml.h - - A handler for loading and saving content in an XML format specific - to wxRichTextBuffer. You can either add the handler to the buffer - and load and save through the buffer or control API, or you can - create an instance of the handler on the stack and call its - functions directly. - - @library{wxrichtext} - @category{richtext} -*/ -class wxRichTextXMLHandler : public wxRichTextFileHandler -{ -public: - /** - , wxString&@e ext = wxT("xml"), @b int@e type = wxRICHTEXT_TYPE_XML) - Constructor. - */ - wxRichTextXMLHandler() const; - - /** - Returns @true. - */ - bool CanLoad() const; - - /** - Returns @true. - */ - bool CanSave() const; - - /** - Creates XML code for a given character or paragraph style. - */ - wxString CreateStyle(const wxTextAttr& attr, bool isPara = false); - - /** - Loads buffer context from the given stream. - */ - bool DoLoadFile(wxRichTextBuffer* buffer, wxInputStream& stream); - - /** - Saves buffer context to the given stream. - */ - bool DoSaveFile(wxRichTextBuffer* buffer, wxOutputStream& stream); - - /** - Recursively exports an object to the stream. - */ - bool ExportXML(wxOutputStream& stream, wxMBConv* convMem, - wxMBConv* convFile, - wxRichTextObject& obj, - int level); - - /** - Helper function: gets node context. - */ - wxString GetNodeContent(wxXmlNode* node); - - /** - Helper function: gets a named parameter from the XML node. - */ - wxXmlNode* GetParamNode(wxXmlNode* node, const wxString& param); - - /** - Helper function: gets a named parameter from the XML node. - */ - wxString GetParamValue(wxXmlNode* node, const wxString& param); - - /** - Helper function: gets style parameters from the given XML node. - */ - bool GetStyle(wxTextAttr& attr, wxXmlNode* node, - bool isPara = false); - - /** - Helper function: gets text from the node. - */ - wxString GetText(wxXmlNode* node, - const wxString& param = wxEmptyString, - bool translate = false); - - /** - Helper function: returns @true if the node has the given parameter. - */ - bool HasParam(wxXmlNode* node, const wxString& param); - - /** - Recursively imports an object. - */ - bool ImportXML(wxRichTextBuffer* buffer, wxXmlNode* node); -}; - diff --git a/interface/sashwin.h b/interface/sashwin.h deleted file mode 100644 index a8fdb75076..0000000000 --- a/interface/sashwin.h +++ /dev/null @@ -1,213 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: sashwin.h -// Purpose: interface of wxSashWindow -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxSashWindow - @wxheader{sashwin.h} - - wxSashWindow allows any of its edges to have a sash which can be dragged - to resize the window. The actual content window will be created by the - application - as a child of wxSashWindow. The window (or an ancestor) will be notified of a - drag - via a wxSashEvent notification. - - @beginStyleTable - @style{wxSW_3D} - Draws a 3D effect sash and border. - @style{wxSW_3DSASH} - Draws a 3D effect sash. - @style{wxSW_3DBORDER} - Draws a 3D effect border. - @style{wxSW_BORDER} - Draws a thin black border. - @endStyleTable - - @beginEventTable{wxSashEvent} - @event{EVT_SASH_DRAGGED(id, func)} - Process a wxEVT_SASH_DRAGGED event, when the user has finished - dragging a sash. - @event{EVT_SASH_DRAGGED_RANGE(id1, id2, func)} - Process a wxEVT_SASH_DRAGGED_RANGE event, when the user has - finished dragging a sash. The event handler is called when windows - with ids in the given range have their sashes dragged. - @endEventTable - - @library{wxadv} - @category{miscwnd} - - @see wxSashEvent, wxSashLayoutWindow, @ref overview_eventhandling -*/ -class wxSashWindow : public wxWindow -{ -public: - //@{ - /** - Constructs a sash window, which can be a child of a frame, dialog or any other - non-control window. - - @param parent - Pointer to a parent window. - @param id - Window identifier. If -1, will automatically create an identifier. - @param pos - Window position. wxDefaultPosition is (-1, -1) which indicates that - wxSashWindows - should generate a default position for the window. If using the - wxSashWindow class directly, supply - an actual position. - @param size - Window size. wxDefaultSize is (-1, -1) which indicates that wxSashWindows - should generate a default size for the window. - @param style - Window style. For window styles, please see wxSashWindow. - @param name - Window name. - */ - wxSashWindow(); - wxSashWindow(wxWindow* parent, wxWindowID id, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = wxCLIP_CHILDREN | wxSW_3D, - const wxString& name = "sashWindow"); - //@} - - /** - Destructor. - */ - ~wxSashWindow(); - - /** - Gets the maximum window size in the x direction. - */ - int GetMaximumSizeX() const; - - /** - Gets the maximum window size in the y direction. - */ - int GetMaximumSizeY() const; - - /** - Gets the minimum window size in the x direction. - */ - int GetMinimumSizeX(); - - /** - Gets the minimum window size in the y direction. - */ - int GetMinimumSizeY() const; - - /** - Returns @true if a sash is visible on the given edge, @false otherwise. - - @param edge - Edge. One of wxSASH_TOP, wxSASH_RIGHT, wxSASH_BOTTOM, wxSASH_LEFT. - - @see SetSashVisible() - */ - bool GetSashVisible(wxSashEdgePosition edge) const; - - /** - Returns @true if the sash has a border, @false otherwise. - This function is obsolete since the sash border property is unused. - - @param edge - Edge. One of wxSASH_TOP, wxSASH_RIGHT, wxSASH_BOTTOM, wxSASH_LEFT. - - @see SetSashBorder() - */ - bool HasBorder(wxSashEdgePosition edge) const; - - /** - Sets the maximum window size in the x direction. - */ - void SetMaximumSizeX(int min); - - /** - Sets the maximum window size in the y direction. - */ - void SetMaximumSizeY(int min); - - /** - Sets the minimum window size in the x direction. - */ - void SetMinimumSizeX(int min); - - /** - Sets the minimum window size in the y direction. - */ - void SetMinimumSizeY(int min); - - /** - Call this function to give the sash a border, or remove the border. - This function is obsolete since the sash border property is unused. - - @param edge - Edge to change. One of wxSASH_TOP, wxSASH_RIGHT, wxSASH_BOTTOM, wxSASH_LEFT. - @param hasBorder - @true to give the sash a border visible, @false to remove it. - */ - void SetSashBorder(wxSashEdgePosition edge, bool hasBorder); - - /** - Call this function to make a sash visible or invisible on a particular edge. - - @param edge - Edge to change. One of wxSASH_TOP, wxSASH_RIGHT, wxSASH_BOTTOM, wxSASH_LEFT. - @param visible - @true to make the sash visible, @false to make it invisible. - - @see GetSashVisible() - */ - void SetSashVisible(wxSashEdgePosition edge, bool visible); -}; - - - -/** - @class wxSashEvent - @wxheader{sashwin.h} - - A sash event is sent when the sash of a wxSashWindow has been - dragged by the user. - - @library{wxadv} - @category{FIXME} - - @see wxSashWindow, @ref overview_eventhandlingoverview -*/ -class wxSashEvent : public wxCommandEvent -{ -public: - /** - Constructor. - */ - wxSashEvent(int id = 0, wxSashEdgePosition edge = wxSASH_NONE); - - /** - Returns the rectangle representing the new size the window would be if the - resize was applied. It is - up to the application to set the window size if required. - */ - wxRect GetDragRect() const; - - /** - Returns the status of the sash: one of wxSASH_STATUS_OK, - wxSASH_STATUS_OUT_OF_RANGE. - If the drag caused the notional bounding box of the window to flip over, for - example, the drag will be out of rage. - */ - wxSashDragStatus GetDragStatus() const; - - /** - Returns the dragged edge. The return value is one of wxSASH_TOP, wxSASH_RIGHT, - wxSASH_BOTTOM, wxSASH_LEFT. - */ - wxSashEdgePosition GetEdge() const; -}; - diff --git a/interface/sckipc.h b/interface/sckipc.h deleted file mode 100644 index 0ec3ce061e..0000000000 --- a/interface/sckipc.h +++ /dev/null @@ -1,306 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: sckipc.h -// Purpose: interface of wxTCPServer -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxTCPServer - @wxheader{sckipc.h} - - A wxTCPServer object represents the server part of a client-server conversation. - It emulates a DDE-style protocol, but uses TCP/IP which is available on most - platforms. - - A DDE-based implementation for Windows is available using wxDDEServer. - - @library{wxnet} - @category{FIXME} - - @see wxTCPClient, wxTCPConnection, @ref overview_ipcoverview "IPC overview" -*/ -class wxTCPServer : public wxObject -{ -public: - /** - Constructs a server object. - */ - wxTCPServer(); - - /** - Registers the server using the given service name. Under Unix, the - string must contain an integer id which is used as an Internet port - number. @false is returned if the call failed (for example, the port - number is already in use). - */ - bool Create(const wxString& service); - - /** - When a client calls @b MakeConnection, the server receives the - message and this member is called. The application should derive a - member to intercept this message and return a connection object of - either the standard wxTCPConnection type, or of a user-derived type. If the - topic is "STDIO", the application may wish to refuse the connection. - Under Unix, when a server is created the OnAcceptConnection message is - always sent for standard input and output. - */ - virtual wxConnectionBase* OnAcceptConnection(const wxString& topic); -}; - - - -/** - @class wxTCPClient - @wxheader{sckipc.h} - - A wxTCPClient object represents the client part of a client-server conversation. - It emulates a DDE-style protocol, but uses TCP/IP which is available on most - platforms. - - A DDE-based implementation for Windows is available using wxDDEClient. - - To create a client which can communicate with a suitable server, - you need to derive a class from wxTCPConnection and another from wxTCPClient. - The custom wxTCPConnection class will intercept communications in - a 'conversation' with a server, and the custom wxTCPServer is required - so that a user-overridden wxTCPClient::OnMakeConnection member can return - a wxTCPConnection of the required class, when a connection is made. - - @library{wxnet} - @category{FIXME} - - @see wxTCPServer, wxTCPConnection, @ref overview_ipcoverview "Interprocess - communications overview" -*/ -class wxTCPClient : public wxObject -{ -public: - /** - Constructs a client object. - */ - wxTCPClient(); - - /** - Tries to make a connection with a server specified by the host - (a machine name under Unix), service name (must - contain an integer port number under Unix), and a topic string. If the - server allows a connection, a wxTCPConnection object will be returned. - The type of wxTCPConnection returned can be altered by overriding - the OnMakeConnection() member to return your own - derived connection object. - */ - wxConnectionBase* MakeConnection(const wxString& host, - const wxString& service, - const wxString& topic); - - /** - The type of wxTCPConnection returned from a MakeConnection() call can - be altered by deriving the @b OnMakeConnection member to return your - own derived connection object. By default, a wxTCPConnection - object is returned. - The advantage of deriving your own connection class is that it will - enable you to intercept messages initiated by the server, such - as wxTCPConnection::OnAdvise. You may also want to - store application-specific data in instances of the new class. - */ - wxConnectionBase* OnMakeConnection(); - - /** - Returns @true if this is a valid host name, @false otherwise. - */ - bool ValidHost(const wxString& host); -}; - - - -/** - @class wxTCPConnection - @wxheader{sckipc.h} - - A wxTCPClient object represents the connection between a client and a server. - It emulates a DDE-style protocol, but uses TCP/IP which is available on most - platforms. - - A DDE-based implementation for Windows is available using wxDDEConnection. - - A wxTCPConnection object can be created by making a connection using a - wxTCPClient object, or by the acceptance of a connection by a - wxTCPServer object. The bulk of a conversation is controlled by - calling members in a @b wxTCPConnection object or by overriding its - members. - - An application should normally derive a new connection class from - wxTCPConnection, in order to override the communication event handlers - to do something interesting. - - @library{wxnet} - @category{FIXME} - - @see wxTCPClient, wxTCPServer, @ref overview_ipcoverview "Interprocess - communications overview" -*/ -class wxTCPConnection : public wxObject -{ -public: - //@{ - /** - Constructs a connection object. If no user-defined connection object is - to be derived from wxTCPConnection, then the constructor should not be - called directly, since the default connection object will be provided on - requesting (or accepting) a connection. However, if the user defines his - or her own derived connection object, the wxTCPServer::OnAcceptConnection - and/or wxTCPClient::OnMakeConnection members should be replaced by - functions which construct the new connection object. If the arguments of - the wxTCPConnection constructor are void, then a default buffer is - associated with the connection. Otherwise, the programmer must provide a - a buffer and size of the buffer for the connection object to use in - transactions. - */ - wxTCPConnection(); - wxTCPConnection(void* buffer, size_t size); - //@} - - //@{ - /** - Called by the server application to advise the client of a change in - the data associated with the given item. Causes the client - connection's OnAdvise() - member to be called. Returns @true if successful. - */ - bool Advise(const wxString& item, const void* data, size_t size, - wxIPCFormat format = wxIPC_PRIVATE); - bool Advise(const wxString& item, const char* data); - bool Advise(const wxString& item, const wchar_t* data); - bool Advise(const wxString& item, const wxString data); - //@} - - /** - Called by the client or server application to disconnect from the other - program; it causes the OnDisconnect() message - to be sent to the corresponding connection object in the other - program. The default behaviour of @b OnDisconnect is to delete the - connection, but the calling application must explicitly delete its - side of the connection having called @b Disconnect. Returns @true if - successful. - */ - bool Disconnect(); - - //@{ - /** - Called by the client application to execute a command on the server. Can - also be used to transfer arbitrary data to the server (similar - to Poke() in that respect). Causes the - server connection's OnExecute() member to be - called. Returns @true if successful. - */ - bool Execute(const void* data, size_t size, - wxIPCFormat format = wxIPC_PRIVATE); - bool Execute(const char* data); - bool Execute(const wchar_t* data); - bool Execute(const wxString data); - //@} - - /** - Message sent to the client application when the server notifies it of a - change in the data associated with the given item. - */ - virtual bool OnAdvise(const wxString& topic, - const wxString& item, - const void* data, - size_t size, - wxIPCFormat format); - - /** - Message sent to the client or server application when the other - application notifies it to delete the connection. Default behaviour is - to delete the connection object. - */ - virtual bool OnDisconnect(); - - /** - Message sent to the server application when the client notifies it to - execute the given data. Note that there is no item associated with - this message. - */ - virtual bool OnExecute(const wxString& topic, const void* data, - size_t size, - wxIPCFormat format); - - /** - Message sent to the server application when the client notifies it to - accept the given data. - */ - virtual bool OnPoke(const wxString& topic, const wxString& item, - const void* data, - size_t size, - wxIPCFormat format); - - /** - Message sent to the server application when the client - calls Request(). The server - should respond by returning a character string from @b OnRequest, - or @NULL to indicate no data. - */ - virtual const void* OnRequest(const wxString& topic, - const wxString& item, - size_t* size, - wxIPCFormat format); - - /** - Message sent to the server application by the client, when the client - wishes to start an 'advise loop' for the given topic and item. The - server can refuse to participate by returning @false. - */ - virtual bool OnStartAdvise(const wxString& topic, - const wxString& item); - - /** - Message sent to the server application by the client, when the client - wishes to stop an 'advise loop' for the given topic and item. The - server can refuse to stop the advise loop by returning @false, although - this doesn't have much meaning in practice. - */ - virtual bool OnStopAdvise(const wxString& topic, - const wxString& item); - - //@{ - /** - Called by the client application to poke data into the server. Can be - used to transfer arbitrary data to the server. Causes the server - connection's OnPoke() member - to be called. Returns @true if successful. - */ - bool Poke(const wxString& item, const void* data, size_t size, - wxIPCFormat format = wxIPC_PRIVATE); - bool Poke(const wxString& item, const char* data); - bool Poke(const wxString& item, const wchar_t* data); - bool Poke(const wxString& item, const wxString data); - //@} - - /** - Called by the client application to request data from the server. Causes - the server connection's OnRequest() member to be called. Returns a - character string (actually a pointer to the connection's buffer) if - successful, @NULL otherwise. - */ - const void* Request(const wxString& item, size_t* size, - wxIPCFormat format = wxIPC_TEXT); - - /** - Called by the client application to ask if an advise loop can be started - with the server. Causes the server connection's OnStartAdvise() - member to be called. Returns @true if the server okays it, @false - otherwise. - */ - bool StartAdvise(const wxString& item); - - /** - Called by the client application to ask if an advise loop can be - stopped. Causes the server connection's OnStopAdvise() member - to be called. Returns @true if the server okays it, @false otherwise. - */ - bool StopAdvise(const wxString& item); -}; - diff --git a/interface/sckstrm.h b/interface/sckstrm.h deleted file mode 100644 index a29d0ef6f8..0000000000 --- a/interface/sckstrm.h +++ /dev/null @@ -1,56 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: sckstrm.h -// Purpose: interface of wxSocketOutputStream -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxSocketOutputStream - @wxheader{sckstrm.h} - - This class implements an output stream which writes data from - a connected socket. Note that this stream is purely sequential - and it does not support seeking. - - @library{wxnet} - @category{streams} - - @see wxSocketBase -*/ -class wxSocketOutputStream : public wxOutputStream -{ -public: - /** - Creates a new write-only socket stream using the specified initialized - socket connection. - */ - wxSocketOutputStream(wxSocketBase& s); -}; - - - -/** - @class wxSocketInputStream - @wxheader{sckstrm.h} - - This class implements an input stream which reads data from - a connected socket. Note that this stream is purely sequential - and it does not support seeking. - - @library{wxnet} - @category{streams} - - @see wxSocketBase -*/ -class wxSocketInputStream : public wxInputStream -{ -public: - /** - Creates a new read-only socket stream using the specified initialized - socket connection. - */ - wxSocketInputStream(wxSocketBase& s); -}; - diff --git a/interface/scopeguard.h b/interface/scopeguard.h deleted file mode 100644 index e8c88a7989..0000000000 --- a/interface/scopeguard.h +++ /dev/null @@ -1,95 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: scopeguard.h -// Purpose: interface of global functions -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** @ingroup group_funcmacro_misc */ -//@{ -/** - This macro ensures that the global @a function with 0, 1, 2 or more - parameters (up to some implementation-defined limit) is executed on scope - exit, whether due to a normal function return or because an exception has - been thrown. A typical example of its usage: - - @code - void *buf = malloc(size); - wxON_BLOCK_EXIT1(free, buf); - @endcode - - Please see the original article by Andrei Alexandrescu and Petru Marginean - published in December 2000 issue of C/C++ Users Journal for more details. - - @see wxON_BLOCK_EXIT_OBJ0() - - @header{wx/scopeguard.h} -*/ -#define wxON_BLOCK_EXIT0(function) -#define wxON_BLOCK_EXIT1(function, p1) -#define wxON_BLOCK_EXIT2(function, p1, p2) -//@} - -/** @ingroup group_funcmacro_misc */ -//@{ -/** - This family of macros is similar to wxON_BLOCK_EXIT0(), but calls a method - of the given object instead of a free function. - - @header{wx/scopeguard.h} -*/ -#define wxON_BLOCK_EXIT_OBJ0(object, method) -#define wxON_BLOCK_EXIT_OBJ1(object, method, p1) -#define wxON_BLOCK_EXIT_OBJ2(object, method, p1, p2) -//@} - -/** @ingroup group_funcmacro_misc */ -//@{ -/** - This family of macros is similar to wxON_BLOCK_OBJ0(), but calls a method - of @c this object instead of a method of the specified object. - - @header{wx/scopeguard.h} -*/ -#define wxON_BLOCK_EXIT_THIS0(method) -#define wxON_BLOCK_EXIT_THIS1(method, p1) -#define wxON_BLOCK_EXIT_THIS2(method, p1, p2) -//@} - -/** @ingroup group_funcmacro_misc */ -//@{ -/** - This macro sets a variable to the specified value on scope exit. - - Example of usage: - @code - void foo() - { - bool isDoingSomething = true; - { - wxON_BLOCK_EXIT_SET(isDoingSomething, false); - ... do something ... - } - ... isDoingSomething is false now ... - } - @endcode - - @see wxON_BLOCK_EXIT_OBJ0(), wxON_BLOCK_EXIT_NULL() - - @header{wx/scopeguard.h} -*/ -#define wxON_BLOCK_EXIT_SET(var, value) - -/** - This macro sets the pointer passed to it as argument to NULL on scope exit. - - It must be used instead of wxON_BLOCK_EXIT_SET() when the value being set - is @c NULL. - - @header{wx/scopeguard.h} - */ -#define wxON_BLOCK_EXIT_NULL(ptr) - -//@} - diff --git a/interface/scrolbar.h b/interface/scrolbar.h deleted file mode 100644 index d6574c6b06..0000000000 --- a/interface/scrolbar.h +++ /dev/null @@ -1,149 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: scrolbar.h -// Purpose: interface of wxScrollBar -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxScrollBar - @wxheader{scrolbar.h} - - A wxScrollBar is a control that represents a horizontal or - vertical scrollbar. It is distinct from the two scrollbars that some windows - provide automatically, but the two types of scrollbar share the way - events are received. - - @beginStyleTable - @style{wxSB_HORIZONTAL} - Specifies a horizontal scrollbar. - @style{wxSB_VERTICAL} - Specifies a vertical scrollbar. - @endStyleTable - - @library{wxcore} - @category{ctrl} - - - @see @ref overview_scrolling, @ref overview_eventhandling, wxScrolled -*/ -class wxScrollBar : public wxControl -{ -public: - /** - Default constructor - */ - wxScrollBar(); - - /** - Constructor, creating and showing a scrollbar. - - @param parent - Parent window. Must be non-@NULL. - @param id - Window identifier. The value wxID_ANY indicates a default value. - @param pos - Window position. If wxDefaultPosition is specified then a default - position is chosen. - @param size - Window size. If wxDefaultSize is specified then a default size - is chosen. - @param style - Window style. See wxScrollBar. - @param validator - Window validator. - @param name - Window name. - - @see Create(), wxValidator - */ - wxScrollBar(wxWindow* parent, wxWindowID id, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = wxSB_HORIZONTAL, - const wxValidator& validator = wxDefaultValidator, - const wxString& name = "scrollBar"); - - /** - Destructor, destroying the scrollbar. - */ - ~wxScrollBar(); - - /** - Scrollbar creation function called by the scrollbar constructor. - See wxScrollBar() for details. - */ - bool Create(wxWindow* parent, wxWindowID id, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = wxSB_HORIZONTAL, - const wxValidator& validator = wxDefaultValidator, - const wxString& name = "scrollBar"); - - /** - Returns the page size of the scrollbar. This is the number of scroll units - that will be scrolled when the user pages up or down. Often it is the - same as the thumb size. - - @see SetScrollbar() - */ - int GetPageSize() const; - - /** - Returns the length of the scrollbar. - - @see SetScrollbar() - */ - int GetRange() const; - - /** - Returns the current position of the scrollbar thumb. - - @see SetThumbPosition() - */ - int GetThumbPosition() const; - - /** - Returns the thumb or 'view' size. - - @see SetScrollbar() - */ - int GetThumbSize() const; - - /** - Sets the scrollbar properties. - - @param position - The position of the scrollbar in scroll units. - @param thumbSize - The size of the thumb, or visible portion of the scrollbar, in scroll units. - @param range - The maximum position of the scrollbar. - @param pageSize - The size of the page size in scroll units. This is the number of units - the scrollbar will scroll when it is paged up or down. Often it is the same - as - the thumb size. - @param refresh - @true to redraw the scrollbar, @false otherwise. - - @remarks Let's say you wish to display 50 lines of text, using the same - font. The window is sized so that you can only see 16 - lines at a time. - */ - virtual void SetScrollbar(int position, int thumbSize, int range, - int pageSize, - bool refresh = true); - - /** - Sets the position of the scrollbar. - - @param viewStart - The position of the scrollbar thumb. - - @see GetThumbPosition() - */ - void SetThumbPosition(int viewStart); -}; - diff --git a/interface/scrolwin.h b/interface/scrolwin.h deleted file mode 100644 index b05bc233fc..0000000000 --- a/interface/scrolwin.h +++ /dev/null @@ -1,423 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: scrolwin.h -// Purpose: interface of wxScrolled template -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @wxheader{scrolwin.h} - - The wxScrolled class manages scrolling for its client area, transforming - the coordinates according to the scrollbar positions, and setting the - scroll positions, thumb sizes and ranges according to the area in view. - - There are two commonly used (but not the only possible!) specializations of - this class: - - - ::wxScrolledWindow, aka wxScrolled, is equivalent to - ::wxScrolledWindow from earlier versions. Derived from wxPanel, it shares - wxPanel's behaviour with regard to TAB traversal and focus handling. Use - this if the scrolled window will have child controls. - - - ::wxScrolledCanvas, aka wxScrolled, derives from wxWindow and - so doesn't handle children specially. This is suitable e.g. for - implementating scrollable controls such as tree or list controls. - - Starting from version 2.4 of wxWidgets, there are several ways to use a - ::wxScrolledWindow (and now wxScrolled). In particular, there are - three ways to set the size of the scrolling area: - - One way is to set the scrollbars directly using a call to SetScrollbars(). - This is the way it used to be in any previous version of wxWidgets and it - will be kept for backwards compatibility. - - An additional method of manual control, which requires a little less - computation of your own, is to set the total size of the scrolling area by - calling either wxWindow::SetVirtualSize(), or wxWindow::FitInside(), and - setting the scrolling increments for it by calling SetScrollRate(). - Scrolling in some orientation is enabled by setting a non-zero increment - for it. - - The most automatic and newest way is to simply let sizers determine the - scrolling area. This is now the default when you set an interior sizer into - a wxScrolled with wxWindow::SetSizer(). The scrolling area will be - set to the size requested by the sizer and the scrollbars will be assigned - for each orientation according to the need for them and the scrolling - increment set by SetScrollRate(). As above, scrolling is only enabled in - orientations with a non-zero increment. You can influence the minimum size - of the scrolled area controlled by a sizer by calling - wxWindow::SetVirtualSizeHints(). (Calling SetScrollbars() has analogous - effects in wxWidgets 2.4 -- in later versions it may not continue to - override the sizer.) - - Note that if maximum size hints are still supported by - wxWindow::SetVirtualSizeHints(), use them at your own dire risk. They may - or may not have been removed for 2.4, but it really only makes sense to set - minimum size hints here. We should probably replace - wxWindow::SetVirtualSizeHints() with wxWindow::SetMinVirtualSize() or - similar and remove it entirely in future. - - As with all windows, an application can draw onto a wxScrolled using a - @ref overview_dc "device context". - - You have the option of handling the OnPaint handler or overriding the - wxScrolled::OnDraw() function, which is passed a pre-scrolled device - context (prepared by wxScrolled::DoPrepareDC()). - - If you don't wish to calculate your own scrolling, you must call - DoPrepareDC() when not drawing from within OnDraw(), to set the device - origin for the device context according to the current scroll position. - - A wxScrolled will normally scroll itself and therefore its child windows - as well. It might however be desired to scroll a different window than - itself: e.g. when designing a spreadsheet, you will normally only have to - scroll the (usually white) cell area, whereas the (usually grey) label area - will scroll very differently. For this special purpose, you can call - SetTargetWindow() which means that pressing the scrollbars will scroll a - different window. - - Note that the underlying system knows nothing about scrolling coordinates, - so that all system functions (mouse events, expose events, refresh calls - etc) as well as the position of subwindows are relative to the "physical" - origin of the scrolled window. If the user insert a child window at - position (10,10) and scrolls the window down 100 pixels (moving the child - window out of the visible area), the child window will report a position - of (10,-90). - - @beginStyleTable - @style{wxRETAINED} - Uses a backing pixmap to speed refreshes. Motif only. - @endStyleTable - - @remarks - Use wxScrolled for applications where the user scrolls by a fixed amount, - and where a 'page' can be interpreted to be the current visible portion of - the window. For more sophisticated applications, use the wxScrolled - implementation as a guide to build your own scroll behaviour or use - wxVScrolledWindow or its variants. - - @since The wxScrolled template exists since version 2.9.0. In older versions, - only ::wxScrolledWindow (equivalent of wxScrolled) was - available. - - @library{wxcore} - @category{miscwnd} - - @see wxScrollBar, wxClientDC, wxPaintDC, - wxVScrolledWindow, wxHScrolledWindow, wxHVScrolledWindow, -*/ -template -class wxScrolled : public T -{ -public: - /// Default constructor. - wxScrolled(); - - /** - Constructor. - - @param parent - Parent window. - @param id - Window identifier. The value @c wxID_ANY indicates a default value. - @param pos - Window position. If a position of @c wxDefaultPosition is specified - then a default position is chosen. - @param size - Window size. If a size of @c wxDefaultSize is specified then the - window is sized appropriately. - @param style - Window style. See wxScrolled. - @param name - Window name. - - @remarks The window is initially created without visible scrollbars. - Call SetScrollbars() to specify how big the virtual window - size should be. - */ - wxScrolled(wxWindow* parent, wxWindowID id = -1, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = wxHSCROLL | wxVSCROLL, - const wxString& name = "scrolledWindow"); - - - /** - Translates the logical coordinates to the device ones. For example, if - a window is scrolled 10 pixels to the bottom, the device coordinates of - the origin are (0, 0) (as always), but the logical coordinates are (0, - 10) and so the call to CalcScrolledPosition(0, 10, xx, yy) will return - 0 in yy. - - @see CalcUnscrolledPosition() - */ - void CalcScrolledPosition(int x, int y, int* xx, int* yy) const; - - /** - Translates the device coordinates to the logical ones. For example, if - a window is scrolled 10 pixels to the bottom, the device coordinates of - the origin are (0, 0) (as always), but the logical coordinates are (0, - 10) and so the call to CalcUnscrolledPosition(0, 0, xx, yy) will return - 10 in yy. - - @see CalcScrolledPosition() - */ - void CalcUnscrolledPosition(int x, int y, int* xx, int* yy) const; - - /** - Creates the window for two-step construction. Derived classes - should call or replace this function. See wxScrolled::wxScrolled() - for details. - */ - bool Create(wxWindow* parent, wxWindowID id = -1, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = wxHSCROLL | wxVSCROLL, - const wxString& name = "scrolledWindow"); - - /** - Call this function to prepare the device context for drawing a scrolled - image. - - It sets the device origin according to the current scroll position. - DoPrepareDC() is called automatically within the default OnPaint() - event handler, so your OnDraw() override will be passed a - 'pre-scrolled' device context. However, if you wish to draw from - outside of OnDraw() (via OnPaint()), or you wish to implement OnPaint() - yourself, you must call this function yourself. - - For example: - @code - void MyWindow::OnEvent(wxMouseEvent& event) - { - wxClientDC dc(this); - DoPrepareDC(dc); - - dc.SetPen(*wxBLACK_PEN); - float x, y; - event.Position(&x, &y); - if (xpos > -1 && ypos > -1 && event.Dragging()) - { - dc.DrawLine(xpos, ypos, x, y); - } - xpos = x; - ypos = y; - } - @endcode - - */ - void DoPrepareDC(wxDC& dc); - - /** - Enable or disable physical scrolling in the given direction. Physical - scrolling is the physical transfer of bits up or down the - screen when a scroll event occurs. If the application scrolls by a - variable amount (e.g. if there are different font sizes) then physical - scrolling will not work, and you should switch it off. Note that you - will have to reposition child windows yourself, if physical scrolling - is disabled. - - @param xScrolling - If @true, enables physical scrolling in the x direction. - @param yScrolling - If @true, enables physical scrolling in the y direction. - - @remarks Physical scrolling may not be available on all platforms. Where - it is available, it is enabled by default. - */ - void EnableScrolling(bool xScrolling, bool yScrolling); - - /** - Get the number of pixels per scroll unit (line), in each direction, as - set by SetScrollbars(). A value of zero indicates no scrolling in that - direction. - - @param xUnit - Receives the number of pixels per horizontal unit. - @param yUnit - Receives the number of pixels per vertical unit. - - @see SetScrollbars(), GetVirtualSize() - */ - void GetScrollPixelsPerUnit(int* xUnit, int* yUnit) const; - - /** - Get the position at which the visible portion of the window starts. - - @param x - Receives the first visible x position in scroll units. - @param y - Receives the first visible y position in scroll units. - - @remarks If either of the scrollbars is not at the home position, x - and/or y will be greater than zero. Combined with - wxWindow::GetClientSize(), the application can use this - function to efficiently redraw only the visible portion - of the window. The positions are in logical scroll - units, not pixels, so to convert to pixels you will - have to multiply by the number of pixels per scroll - increment. - - @see SetScrollbars() - */ - void GetViewStart(int* x, int* y) const; - - /** - Gets the size in device units of the scrollable window area (as - opposed to the client size, which is the area of the window currently - visible). - - @param x - Receives the length of the scrollable window, in pixels. - @param y - Receives the height of the scrollable window, in pixels. - - @remarks Use wxDC::DeviceToLogicalX() and wxDC::DeviceToLogicalY() to - translate these units to logical units. - - @see SetScrollbars(), GetScrollPixelsPerUnit() - */ - void GetVirtualSize(int* x, int* y) const; - - /** - Motif only: @true if the window has a backing bitmap. - */ - bool IsRetained() const; - - /** - Called by the default paint event handler to allow the application to - define painting behaviour without having to worry about calling - DoPrepareDC(). - - Instead of overriding this function you may also just process the paint - event in the derived class as usual, but then you will have to call - DoPrepareDC() yourself. - */ - virtual void OnDraw(wxDC& dc); - - /** - This function is for backwards compatibility only and simply calls - DoPrepareDC() now. Notice that it is not called by the default paint - event handle (DoPrepareDC() is), so overriding this method in your - derived class is useless. - */ - void PrepareDC(wxDC& dc); - - /** - Scrolls a window so the view start is at the given point. - - @param x - The x position to scroll to, in scroll units. - @param y - The y position to scroll to, in scroll units. - - @remarks The positions are in scroll units, not pixels, so to convert to - pixels you will have to multiply by the number of - pixels per scroll increment. If either parameter is -1, - that position will be ignored (no change in that - direction). - - @see SetScrollbars(), GetScrollPixelsPerUnit() - */ - void Scroll(int x, int y); - - /** - Set the horizontal and vertical scrolling increment only. See the - pixelsPerUnit parameter in SetScrollbars(). - */ - void SetScrollRate(int xstep, int ystep); - - /** - Sets up vertical and/or horizontal scrollbars. - - The first pair of parameters give the number of pixels per 'scroll - step', i.e. amount moved when the up or down scroll arrows are pressed. - The second pair gives the length of scrollbar in scroll steps, which - sets the size of the virtual window. - - @a xPos and @a yPos optionally specify a position to scroll to - immediately. - - For example, the following gives a window horizontal and vertical - scrollbars with 20 pixels per scroll step, and a size of 50 steps (1000 - pixels) in each direction: - @code - window->SetScrollbars(20, 20, 50, 50); - @endcode - - wxScrolled manages the page size itself, using the current client - window size as the page size. - - Note that for more sophisticated scrolling applications, for example - where scroll steps may be variable according to the position in the - document, it will be necessary to derive a new class from wxWindow, - overriding OnSize() and adjusting the scrollbars appropriately. - - @param pixelsPerUnitX - Pixels per scroll unit in the horizontal direction. - @param pixelsPerUnitY - Pixels per scroll unit in the vertical direction. - @param noUnitsX - Number of units in the horizontal direction. - @param noUnitsY - Number of units in the vertical direction. - @param xPos - Position to initialize the scrollbars in the horizontal direction, - in scroll units. - @param yPos - Position to initialize the scrollbars in the vertical direction, in - scroll units. - @param noRefresh - Will not refresh window if @true. - - @see wxWindow::SetVirtualSize() - */ - void SetScrollbars(int pixelsPerUnitX, int pixelsPerUnitY, - int noUnitsX, - int noUnitsY, - int xPos = 0, - int yPos = 0, - bool noRefresh = false); - - /** - Call this function to tell wxScrolled to perform the actual - scrolling on a different window (and not on itself). - */ - void SetTargetWindow(wxWindow* window); -}; - - -/** - Scrolled window derived from wxPanel. - - See wxScrolled for detailed description. - - @note Note that because this class derives from wxPanel, it shares its - behavior with regard to TAB traversal and focus handling (in - particular, it forwards focus to its children). If you don't want - this behaviour, use ::wxScrolledCanvas instead. - - @note ::wxScrolledWindow is an alias for wxScrolled since version - 2.9.0. In older versions, it was a standalone class. - - @library{wxcore} - @category{miscwnd} - - @see wxScrolled, ::wxScrolledCanvas -*/ -typedef wxScrolled wxScrolledWindow; - -/** - Alias for wxScrolled. Scrolled window that doesn't have children - and so doesn't need or want special handling of TAB traversal. - - @since 2.9.0 - - @library{wxcore} - @category{miscwnd} - - @see wxScrolled, ::wxScrolledWindow -*/ -typedef wxScrolled wxScrolledCanvas; diff --git a/interface/settings.h b/interface/settings.h deleted file mode 100644 index 83fff83f18..0000000000 --- a/interface/settings.h +++ /dev/null @@ -1,406 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: settings.h -// Purpose: interface of wxSystemSettings -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxSystemSettings - @wxheader{settings.h} - - wxSystemSettings allows the application to ask for details about - the system. This can include settings such as standard colours, fonts, - and user interface element sizes. - - @library{wxcore} - @category{misc} - - @see wxFont, wxColour -*/ -class wxSystemSettings : public wxObject -{ -public: - /** - Default constructor. You don't need to create an instance of wxSystemSettings - since all of its functions are static. - */ - wxSystemSettings(); - - /** - Returns a system colour. - @a index can be one of: - - @b wxSYS_COLOUR_SCROLLBAR - - The scrollbar grey area. - - @b wxSYS_COLOUR_BACKGROUND - - The desktop colour. - - @b wxSYS_COLOUR_ACTIVECAPTION - - Active window caption. - - @b wxSYS_COLOUR_INACTIVECAPTION - - Inactive window caption. - - @b wxSYS_COLOUR_MENU - - Menu background. - - @b wxSYS_COLOUR_WINDOW - - Window background. - - @b wxSYS_COLOUR_WINDOWFRAME - - Window frame. - - @b wxSYS_COLOUR_MENUTEXT - - Menu text. - - @b wxSYS_COLOUR_WINDOWTEXT - - Text in windows. - - @b wxSYS_COLOUR_CAPTIONTEXT - - Text in caption, size box and scrollbar arrow box. - - @b wxSYS_COLOUR_ACTIVEBORDER - - Active window border. - - @b wxSYS_COLOUR_INACTIVEBORDER - - Inactive window border. - - @b wxSYS_COLOUR_APPWORKSPACE - - Background colour MDI applications. - - @b wxSYS_COLOUR_HIGHLIGHT - - Item(s) selected in a control. - - @b wxSYS_COLOUR_HIGHLIGHTTEXT - - Text of item(s) selected in a control. - - @b wxSYS_COLOUR_BTNFACE - - Face shading on push buttons. - - @b wxSYS_COLOUR_BTNSHADOW - - Edge shading on push buttons. - - @b wxSYS_COLOUR_GRAYTEXT - - Greyed (disabled) text. - - @b wxSYS_COLOUR_BTNTEXT - - Text on push buttons. - - @b wxSYS_COLOUR_INACTIVECAPTIONTEXT - - Colour of text in active captions. - - @b wxSYS_COLOUR_BTNHIGHLIGHT - - Highlight colour for buttons (same as wxSYS_COLOUR_3DHILIGHT). - - @b wxSYS_COLOUR_3DDKSHADOW - - Dark shadow for three-dimensional display elements. - - @b wxSYS_COLOUR_3DLIGHT - - Light colour for three-dimensional display elements. - - @b wxSYS_COLOUR_INFOTEXT - - Text colour for tooltip controls. - - @b wxSYS_COLOUR_INFOBK - - Background colour for tooltip controls. - - @b wxSYS_COLOUR_DESKTOP - - Same as wxSYS_COLOUR_BACKGROUND. - - @b wxSYS_COLOUR_3DFACE - - Same as wxSYS_COLOUR_BTNFACE. - - @b wxSYS_COLOUR_3DSHADOW - - Same as wxSYS_COLOUR_BTNSHADOW. - - @b wxSYS_COLOUR_3DHIGHLIGHT - - Same as wxSYS_COLOUR_BTNHIGHLIGHT. - - @b wxSYS_COLOUR_3DHILIGHT - - Same as wxSYS_COLOUR_BTNHIGHLIGHT. - - @b wxSYS_COLOUR_BTNHILIGHT - - Same as wxSYS_COLOUR_BTNHIGHLIGHT. - */ - static wxColour GetColour(wxSystemColour index); - - /** - Returns a system font. - @a index can be one of: - - @b wxSYS_OEM_FIXED_FONT - - Original equipment manufacturer dependent fixed-pitch font. - - @b wxSYS_ANSI_FIXED_FONT - - Windows fixed-pitch font. - - @b wxSYS_ANSI_VAR_FONT - - Windows variable-pitch (proportional) font. - - @b wxSYS_SYSTEM_FONT - - System font. - - @b wxSYS_DEVICE_DEFAULT_FONT - - Device-dependent font (Windows NT only). - - @b wxSYS_DEFAULT_GUI_FONT - - Default font for user interface - objects such as menus and dialog boxes. Note that with modern GUIs nothing - guarantees that the same font is used for all GUI elements, so some controls - might use a different font by default. - */ - static wxFont GetFont(wxSystemFont index); - - /** - Returns the value of a system metric, or -1 if the metric is not supported on - the current system. - The value of @a win determines if the metric returned is a global value or - a wxWindow based value, in which case it might determine the widget, the - display the window is on, or something similar. The window given should be as - close to the - metric as possible (e.g a wxTopLevelWindow in case of the wxSYS_CAPTION_Y - metric). - @a index can be one of: - - @b wxSYS_MOUSE_BUTTONS - - Number of buttons on mouse, or zero if no mouse was installed. - - @b wxSYS_BORDER_X - - Width of single border. - - @b wxSYS_BORDER_Y - - Height of single border. - - @b wxSYS_CURSOR_X - - Width of cursor. - - @b wxSYS_CURSOR_Y - - Height of cursor. - - @b wxSYS_DCLICK_X - - Width in pixels of rectangle within which two successive mouse - clicks must fall to generate a double-click. - - @b wxSYS_DCLICK_Y - - Height in pixels of rectangle within which two successive mouse - clicks must fall to generate a double-click. - - @b wxSYS_DCLICK_MSEC - - Maximal time, in milliseconds, which may - pass between subsequent clicks for a double click to be generated. - - @b wxSYS_DRAG_X - - Width in pixels of a rectangle centered on a drag point - to allow for limited movement of the mouse pointer before a drag operation - begins. - - @b wxSYS_DRAG_Y - - Height in pixels of a rectangle centered on a drag point - to allow for limited movement of the mouse pointer before a drag operation - begins. - - @b wxSYS_EDGE_X - - Width of a 3D border, in pixels. - - @b wxSYS_EDGE_Y - - Height of a 3D border, in pixels. - - @b wxSYS_HSCROLL_ARROW_X - - Width of arrow bitmap on horizontal scrollbar. - - @b wxSYS_HSCROLL_ARROW_Y - - Height of arrow bitmap on horizontal scrollbar. - - @b wxSYS_HTHUMB_X - - Width of horizontal scrollbar thumb. - - @b wxSYS_ICON_X - - The default width of an icon. - - @b wxSYS_ICON_Y - - The default height of an icon. - - @b wxSYS_ICONSPACING_X - - Width of a grid cell for items in large icon view, - in pixels. Each item fits into a rectangle of this size when arranged. - - @b wxSYS_ICONSPACING_Y - - Height of a grid cell for items in large icon view, - in pixels. Each item fits into a rectangle of this size when arranged. - - @b wxSYS_WINDOWMIN_X - - Minimum width of a window. - - @b wxSYS_WINDOWMIN_Y - - Minimum height of a window. - - @b wxSYS_SCREEN_X - - Width of the screen in pixels. - - @b wxSYS_SCREEN_Y - - Height of the screen in pixels. - - @b wxSYS_FRAMESIZE_X - - Width of the window frame for a wxTHICK_FRAME window. - - @b wxSYS_FRAMESIZE_Y - - Height of the window frame for a wxTHICK_FRAME window. - - @b wxSYS_SMALLICON_X - - Recommended width of a small icon (in window captions, and small icon view). - - @b wxSYS_SMALLICON_Y - - Recommended height of a small icon (in window captions, and small icon view). - - @b wxSYS_HSCROLL_Y - - Height of horizontal scrollbar in pixels. - - @b wxSYS_VSCROLL_X - - Width of vertical scrollbar in pixels. - - @b wxSYS_VSCROLL_ARROW_X - - Width of arrow bitmap on a vertical scrollbar. - - @b wxSYS_VSCROLL_ARROW_Y - - Height of arrow bitmap on a vertical scrollbar. - - @b wxSYS_VTHUMB_Y - - Height of vertical scrollbar thumb. - - @b wxSYS_CAPTION_Y - - Height of normal caption area. - - @b wxSYS_MENU_Y - - Height of single-line menu bar. - - @b wxSYS_NETWORK_PRESENT - - 1 if there is a network present, 0 otherwise. - - @b wxSYS_PENWINDOWS_PRESENT - - 1 if PenWindows is installed, 0 otherwise. - - @b wxSYS_SHOW_SOUNDS - - Non-zero if the user requires an application to present information visually in - situations - where it would otherwise present the information only in audible form; zero - otherwise. - - @b wxSYS_SWAP_BUTTONS - - Non-zero if the meanings of the left and right mouse buttons are swapped; zero - otherwise. - - @a win is a pointer to the window for which the metric is requested. - Specifying the @a win parameter is encouraged, because some metrics on some - ports are not supported without one, - or they might be capable of reporting better values if given one. If a window - does not make sense for a metric, - one should still be given, as for example it might determine which displays - cursor width is requested with - wxSYS_CURSOR_X. - */ - static int GetMetric(wxSystemMetric index, wxWindow* win = NULL); - - /** - Returns the screen type. The return value is one of: - - @b wxSYS_SCREEN_NONE - - Undefined screen type - - @b wxSYS_SCREEN_TINY - - Tiny screen, less than 320x240 - - @b wxSYS_SCREEN_PDA - - PDA screen, 320x240 or more but less than 640x480 - - @b wxSYS_SCREEN_SMALL - - Small screen, 640x480 or more but less than 800x600 - - @b wxSYS_SCREEN_DESKTOP - - Desktop screen, 800x600 or more - */ - static wxSystemScreenType GetScreenType(); -}; - diff --git a/interface/sizer.h b/interface/sizer.h deleted file mode 100644 index bba558dd4d..0000000000 --- a/interface/sizer.h +++ /dev/null @@ -1,1683 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: sizer.h -// Purpose: interface of wxStdDialogButtonSizer -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxStdDialogButtonSizer - @wxheader{sizer.h} - - This class creates button layouts which conform to the standard button spacing - and ordering defined by the platform - or toolkit's user interface guidelines (if such things exist). By using this - class, you can ensure that all your - standard dialogs look correct on all major platforms. Currently it conforms to - the Windows, GTK+ and Mac OS X - human interface guidelines. - - When there aren't interface guidelines defined for a particular platform or - toolkit, wxStdDialogButtonSizer reverts - to the Windows implementation. - - To use this class, first add buttons to the sizer by calling AddButton (or - SetAffirmativeButton, SetNegativeButton, - or SetCancelButton) and then call Realize in order to create the actual button - layout used. Other than these special - operations, this sizer works like any other sizer. - - If you add a button with wxID_SAVE, on Mac OS X the button will be renamed to - "Save" and - the wxID_NO button will be renamed to "Don't Save" in accordance with the Mac - OS X Human Interface Guidelines. - - @library{wxcore} - @category{winlayout} - - @see wxSizer, @ref overview_sizer "Sizer Overview", - wxDialog::CreateButtonSizer -*/ -class wxStdDialogButtonSizer : public wxBoxSizer -{ -public: - /** - Constructor for a wxStdDialogButtonSizer. - */ - wxStdDialogButtonSizer(); - - /** - Adds a button to the wxStdDialogButtonSizer. The @a button must have - one of the following identifiers: - wxID_OK - wxID_YES - wxID_SAVE - wxID_APPLY - wxID_CLOSE - wxID_NO - wxID_CANCEL - wxID_HELP - wxID_CONTEXT_HELP - */ - void AddButton(wxButton* button); - - /** - Rearranges the buttons and applies proper spacing between buttons to make them - match the platform or toolkit's interface guidelines. - */ - void Realize(); - - /** - Sets the affirmative button for the sizer. This allows you to use identifiers - other than the standard identifiers outlined above. - */ - void SetAffirmativeButton(wxButton* button); - - /** - Sets the cancel button for the sizer. This allows you to use identifiers other - than the standard identifiers outlined above. - */ - void SetCancelButton(wxButton* button); - - /** - Sets the negative button for the sizer. This allows you to use identifiers - other than the standard identifiers outlined above. - */ - void SetNegativeButton(wxButton* button); -}; - - - -/** - @class wxSizerItem - @wxheader{sizer.h} - - The wxSizerItem class is used to track the position, size and other - attributes of each item managed by a wxSizer. It is not usually necessary - to use this class because the sizer elements can also be identified by - their positions or window or sizer pointers but sometimes it may be more - convenient to use it directly. - - @library{wxcore} - @category{winlayout} -*/ -class wxSizerItem : public wxObject -{ -public: - //@{ - /** - Construct a sizer item for tracking a subsizer. - */ - wxSizerItem(int width, int height, int proportion, int flag, - int border, wxObject* userData); - wxSizerItem(wxWindow* window, const wxSizerFlags& flags); - wxSizerItem(wxWindow* window, int proportion, int flag, - int border, - wxObject* userData); - wxSizerItem(wxSizer* window, const wxSizerFlags& flags); - wxSizerItem(wxSizer* sizer, int proportion, int flag, - int border, - wxObject* userData); - //@} - - /** - Deletes the user data and subsizer, if any. - */ - ~wxSizerItem(); - - /** - Calculates the minimum desired size for the item, including any space - needed by borders. - */ - wxSize CalcMin(); - - /** - Destroy the window or the windows in a subsizer, depending on the type - of item. - */ - void DeleteWindows(); - - /** - Enable deleting the SizerItem without destroying the contained sizer. - */ - void DetachSizer(); - - /** - Return the border attribute. - */ - int GetBorder() const; - - /** - Return the flags attribute. - - See @ref wxsizer_flags "wxSizer flags list" for details. - */ - int GetFlag() const; - - /** - Return the numeric id of wxSizerItem, or @c wxID_NONE if the id has - not been set. - */ - int GetId() const; - - /** - Get the minimum size needed for the item. - */ - wxSize GetMinSize() const; - - /** - Sets the minimum size to be allocated for this item. - - If this item is a window, the @a size is also passed to - wxWindow::SetMinSize(). - */ - void SetMinSize(const wxSize& size); - - /** - @overload - */ - void SetMinSize(int x, int y); - - /** - What is the current position of the item, as set in the last Layout. - */ - wxPoint GetPosition() const; - - /** - Get the proportion item attribute. - */ - int GetProportion() const; - - /** - Get the ration item attribute. - */ - float GetRatio() const; - - /** - Get the rectangle of the item on the parent window, excluding borders. - */ - wxRect GetRect(); - - /** - Get the current size of the item, as set in the last Layout. - */ - wxSize GetSize() const; - - /** - If this item is tracking a sizer, return it. @NULL otherwise. - */ - wxSizer* GetSizer() const; - - /** - If this item is tracking a spacer, return its size. - */ - const wxSize GetSpacer() const; - - /** - Get the userData item attribute. - */ - wxObject* GetUserData() const; - - /** - If this item is tracking a window then return it. @NULL otherwise. - */ - wxWindow* GetWindow() const; - - /** - Returns @true if this item is a window or a spacer and it is shown or - if this item is a sizer and not all of its elements are hidden. - - In other words, for sizer items, all of the child elements must be - hidden for the sizer itself to be considered hidden. - - As an exception, if the @c wxRESERVE_SPACE_EVEN_IF_HIDDEN flag was - used for this sizer item, then IsShown() always returns @true for it - (see wxSizerFlags::ReserveSpaceEvenIfHidden()). - */ - bool IsShown() const; - - /** - Is this item a sizer? - */ - bool IsSizer() const; - - /** - Is this item a spacer? - */ - bool IsSpacer() const; - - /** - Is this item a window? - */ - bool IsWindow() const; - - /** - Set the border item attribute. - */ - void SetBorder(int border); - - /** - Set the position and size of the space allocated to the sizer, and - adjust the position and size of the item to be within that space - taking alignment and borders into account. - */ - void SetDimension(const wxPoint& pos, const wxSize& size); - - /** - Set the flag item attribute. - */ - void SetFlag(int flag); - - /** - Sets the numeric id of the wxSizerItem to @e id. - */ - void SetId(int id); - - /** - - */ - void SetInitSize(int x, int y); - - /** - Set the proportion item attribute. - */ - void SetProportion(int proportion); - - //@{ - /** - Set the ratio item attribute. - */ - void SetRatio(int width, int height); - void SetRatio(wxSize size); - void SetRatio(float ratio); - //@} - - /** - Set the sizer tracked by this item. - */ - void SetSizer(wxSizer* sizer); - - /** - Set the size of the spacer tracked by this item. - */ - void SetSpacer(const wxSize& size); - - /** - Set the window to be tracked by thsi item. - */ - void SetWindow(wxWindow* window); - - /** - Set the show item attribute, which sizers use to determine if the item - is to be made part of the layout or not. If the item is tracking a - window then it is shown or hidden as needed. - */ - void Show(bool show); -}; - - - -/** - @class wxSizerFlags - @wxheader{sizer.h} - - Container for sizer items flags providing readable names for them. - - Normally, when you add an item to a sizer via wxSizer::Add, you have to - specify a lot of flags and parameters which can be unwieldy. This is where - wxSizerFlags comes in: it allows you to specify all parameters using the - named methods instead. For example, instead of - - @code - sizer->Add(ctrl, 0, wxEXPAND | wxALL, 10); - @endcode - - you can now write - - @code - sizer->Add(ctrl, wxSizerFlags().Expand().Border(10)); - @endcode - - This is more readable and also allows you to create wxSizerFlags objects which - can be reused for several sizer items. - - @code - wxSizerFlags flagsExpand(1); - flagsExpand.Expand().Border(10); - - sizer->Add(ctrl1, flagsExpand); - sizer->Add(ctrl2, flagsExpand); - @endcode - - Note that by specification, all methods of wxSizerFlags return the wxSizerFlags - object itself to allowing chaining multiple methods calls like in the examples - above. - - @library{wxcore} - @category{winlayout} - - @see wxSizer -*/ -class wxSizerFlags -{ -public: - /** - Creates the wxSizer with the proportion specified by @e proportion. - */ - wxSizerFlags(int proportion = 0); - - /** - Sets the alignment of this wxSizerFlags to @e align. - - This method replaces the previously set alignment with the specified - one. - - @see Top(), Left(), Right(), Bottom(), Centre() - - @param align Combination of @c wxALIGN_XXX bit masks. - */ - wxSizerFlags& Align(int align = 0); - - /** - Sets the wxSizerFlags to have a border of a number of pixels specified - by @a borderinpixels with the directions specified by @e direction. - */ - wxSizerFlags& Border(int direction, int borderinpixels); - - /** - Sets the wxSizerFlags to have a border with size as returned by - GetDefaultBorder(). - - @param direction Direction(s) to apply the border in. - */ - wxSizerFlags& Border(int direction = wxALL); - - /** - Aligns the object to the bottom, similar for @c Align(wxALIGN_BOTTOM). - - Unlike Align(), this method doesn't change the horizontal alignment of - the item. - */ - wxSizerFlags& Bottom(); - - /** - Sets the object of the wxSizerFlags to center itself in the area it is - given. - */ - wxSizerFlags& Center(); - - /** - Center() for people with the other dialect of English. - */ - wxSizerFlags& Centre(); - - /** - Sets the border in the given @a direction having twice the default - border size. - */ - wxSizerFlags& DoubleBorder(int direction = wxALL); - - /** - Sets the border in left and right directions having twice the default - border size. - */ - wxSizerFlags& DoubleHorzBorder(); - - /** - Sets the object of the wxSizerFlags to expand to fill as much area as - it can. - */ - wxSizerFlags& Expand(); - - /** - Set the @c wxFIXED_MINSIZE flag which indicates that the initial size - of the window should be also set as its minimal size. - */ - wxSizerFlags& FixedMinSize(); - - /** - Set the @c wxRESERVE_SPACE_EVEN_IF_HIDDEN flag. Normally wxSizers - don't allocate space for hidden windows or other items. This flag - overrides this behavior so that sufficient space is allocated for the - window even if it isn't visible. This makes it possible to dynamically - show and hide controls without resizing parent dialog, for example. - - @since 2.8.8 - */ - wxSizerFlags& ReserveSpaceEvenIfHidden(); - - /** - Returns the border used by default in Border() method. - */ - static int GetDefaultBorder(); - - /** - Aligns the object to the left, similar for @c Align(wxALIGN_LEFT). - - Unlike Align(), this method doesn't change the vertical alignment of - the item. - */ - wxSizerFlags& Left(); - - /** - Sets the proportion of this wxSizerFlags to @e proportion - */ - wxSizerFlags& Proportion(int proportion = 0); - - /** - Aligns the object to the right, similar for @c Align(wxALIGN_RIGHT). - - Unlike Align(), this method doesn't change the vertical alignment of - the item. - */ - wxSizerFlags& Right(); - - /** - Set the @c wx_SHAPED flag which indicates that the elements should - always keep the fixed width to height ratio equal to its original value. - */ - wxSizerFlags& Shaped(); - - /** - Aligns the object to the top, similar for @c Align(wxALIGN_TOP). - - Unlike Align(), this method doesn't change the horizontal alignment of - the item. - */ - wxSizerFlags& Top(); - - /** - Sets the border in the given @a direction having thrice the default - border size. - */ - wxSizerFlags& TripleBorder(int direction = wxALL); -}; - - - -/** - @class wxNotebookSizer - @wxheader{sizer.h} - - @deprecated - This class is deprecated and should not be used in new code! It is no - longer needed, wxNotebook control can be inserted - into any sizer class and its minimal size will be determined correctly. - - wxNotebookSizer is a specialized sizer to make sizers work in connection - with using notebooks. This sizer is different from any other sizer as you - must not add any children to it - instead, it queries the notebook class - itself. The only thing this sizer does is to determine the size of the - biggest page of the notebook and report an adjusted minimal size to a more - toplevel sizer. - - @library{wxbase} - @category{winlayout} - - @see wxSizer, wxNotebook, - @ref overview_sizer "Sizers overview" -*/ -class wxNotebookSizer : public wxSizer -{ -public: - /** - Constructor. It takes an associated notebook as its only parameter. - */ - wxNotebookSizer(wxNotebook* notebook); - - /** - Returns the notebook associated with the sizer. - */ - wxNotebook* GetNotebook(); -}; - - - -/** - @class wxFlexGridSizer - @wxheader{sizer.h} - - A flex grid sizer is a sizer which lays out its children in a two-dimensional - table with all table fields in one row having the same - height and all fields in one column having the same width, but all - rows or all columns are not necessarily the same height or width as in - the wxGridSizer. - - Since wxWidgets 2.5.0, wxFlexGridSizer can also size items equally in one - direction but unequally ("flexibly") in the other. If the sizer is only - flexible in one direction (this can be changed using - wxFlexGridSizer::SetFlexibleDirection), - it needs to be decided how the sizer should grow in the other ("non-flexible") - direction in order to fill the available space. The - wxFlexGridSizer::SetNonFlexibleGrowMode method - serves this purpose. - - @library{wxcore} - @category{winlayout} - - @see wxSizer, @ref overview_sizer "Sizer Overview" -*/ -class wxFlexGridSizer : public wxGridSizer -{ -public: - //@{ - /** - Constructor for a wxGridSizer. @a rows and @a cols determine the number of - columns and rows in the sizer - if either of the parameters is zero, it will be - calculated to form the total number of children in the sizer, thus making the - sizer grow dynamically. @a vgap and @a hgap define extra space between - all children. - */ - wxFlexGridSizer(int rows, int cols, int vgap, int hgap); - wxFlexGridSizer(int cols, int vgap = 0, int hgap = 0); - //@} - - /** - Specifies that column @a idx (starting from zero) should be grown if - there is extra space available to the sizer. - The @a proportion parameter has the same meaning as the stretch factor for - the sizers() except that if all proportions are 0, - then all columns are resized equally (instead of not being resized at all). - */ - void AddGrowableCol(size_t idx, int proportion = 0); - - /** - Specifies that row idx (starting from zero) should be grown if there - is extra space available to the sizer. - See AddGrowableCol() for the description - of @a proportion parameter. - */ - void AddGrowableRow(size_t idx, int proportion = 0); - - /** - Returns a wxOrientation value that specifies whether the sizer flexibly - resizes its columns, rows, or both (default). - - @return One of the following values: - - @see SetFlexibleDirection() - */ - int GetFlexibleDirection() const; - - /** - Returns the value that specifies how the sizer grows in the "non-flexible" - direction if there is one. - - @return One of the following values: - - @see SetFlexibleDirection(), - SetNonFlexibleGrowMode() - */ - int GetNonFlexibleGrowMode() const; - - /** - Specifies that column idx is no longer growable. - */ - void RemoveGrowableCol(size_t idx); - - /** - Specifies that row idx is no longer growable. - */ - void RemoveGrowableRow(size_t idx); - - /** - Specifies whether the sizer should flexibly resize its columns, rows, or - both. Argument @c direction can be @c wxVERTICAL, @c wxHORIZONTAL - or @c wxBOTH (which is the default value). Any other value is ignored. See - @ref GetFlexibleDirection() GetFlexibleDirection for the - explanation of these values. - Note that this method does not trigger relayout. - */ - void SetFlexibleDirection(int direction); - - /** - Specifies how the sizer should grow in the non-flexible direction if - there is one (so - SetFlexibleDirection() must have - been called previously). Argument @a mode can be one of those documented in - GetNonFlexibleGrowMode(), please - see there for their explanation. - Note that this method does not trigger relayout. - */ - void SetNonFlexibleGrowMode(wxFlexSizerGrowMode mode); -}; - - - -/** - @class wxSizer - @wxheader{sizer.h} - - wxSizer is the abstract base class used for laying out subwindows in a window. - You - cannot use wxSizer directly; instead, you will have to use one of the sizer - classes derived from it. Currently there are wxBoxSizer, - wxStaticBoxSizer, - wxGridSizer, - wxFlexGridSizer, - wxWrapSizer - and wxGridBagSizer. - - The layout algorithm used by sizers in wxWidgets is closely related to layout - in other GUI toolkits, such as Java's AWT, the GTK toolkit or the Qt toolkit. - It is - based upon the idea of the individual subwindows reporting their minimal - required - size and their ability to get stretched if the size of the parent window has - changed. - This will most often mean that the programmer does not set the original size of - a dialog in the beginning, rather the dialog will be assigned a sizer and this - sizer - will be queried about the recommended size. The sizer in turn will query its - children, which can be normal windows, empty space or other sizers, so that - a hierarchy of sizers can be constructed. Note that wxSizer does not derive - from wxWindow - and thus does not interfere with tab ordering and requires very little - resources compared - to a real window on screen. - - What makes sizers so well fitted for use in wxWidgets is the fact that every - control - reports its own minimal size and the algorithm can handle differences in font - sizes - or different window (dialog item) sizes on different platforms without - problems. If e.g. - the standard font as well as the overall design of Motif widgets requires more - space than - on Windows, the initial dialog size will automatically be bigger on Motif than - on Windows. - - Sizers may also be used to control the layout of custom drawn items on the - window. The Add(), Insert(), and Prepend() functions return a pointer to - the newly added wxSizerItem. Just add empty space of the desired size and - attributes, and then use the wxSizerItem::GetRect() method to determine - where the drawing operations should take place. - - Please notice that sizers, like child windows, are owned by the library and - will be deleted by it which implies that they must be allocated on the - heap. However if you create a sizer and do not add it to another sizer or - window, the library wouldn't be able to delete such an orphan sizer and in - this, and only this, case it should be deleted explicitly. - - @b wxPython note: If you wish to create a sizer class in wxPython you should - derive the class from @c wxPySizer in order to get Python-aware - capabilities for the various virtual methods. - - @anchor wxsizer_flags - @par wxSizer flags - The "flag" argument accepted by wxSizeItem constructors and other - functions, e.g. wxSizer::Add(), is OR-combination of the following flags. - Two main behaviours are defined using these flags. One is the border around - a window: the border parameter determines the border width whereas the - flags given here determine which side(s) of the item that the border will - be added. The other flags determine how the sizer item behaves when the - space allotted to the sizer changes, and is somewhat dependent on the - specific kind of sizer used. - @beginDefList - @itemdef{wxTOP
- wxBOTTOM
- wxLEFT
- wxRIGHT
- wxALL, - These flags are used to specify which side(s) of the sizer item - the border width will apply to.} - @itemdef{wxEXPAND, - The item will be expanded to fill the space assigned to the item.} - @itemdef{wxSHAPED, - The item will be expanded as much as possible while also - maintaining its aspect ratio.} - @itemdef{wxFIXED_MINSIZE, - Normally wxSizers will use GetAdjustedBestSize() to determine what - the minimal size of window items should be, and will use that size - to calculate the layout. This allows layouts to adjust when an - item changes and its best size becomes different. If you would - rather have a window item stay the size it started with then use - wxFIXED_MINSIZE.} - @itemdef{wxRESERVE_SPACE_EVEN_IF_HIDDEN, - Normally wxSizers don't allocate space for hidden windows or other - items. This flag overrides this behavior so that sufficient space - is allocated for the window even if it isn't visible. This makes - it possible to dynamically show and hide controls without resizing - parent dialog, for example. (Available since 2.8.8.) - } - @itemdef{wxALIGN_CENTER
- wxALIGN_CENTRE
- wxALIGN_LEFT
- wxALIGN_RIGHT
- wxALIGN_TOP
- wxALIGN_BOTTOM
- wxALIGN_CENTER_VERTICAL
- wxALIGN_CENTRE_VERTICAL
- wxALIGN_CENTER_HORIZONTAL
- wxALIGN_CENTRE_HORIZONTAL, - The wxALIGN flags allow you to specify the alignment of the item - within the space allotted to it by the sizer, adjusted for the - border if any.} - @endDefList - - - @library{wxcore} - @category{winlayout} - - @see @ref overview_sizer "Sizer Overview" -*/ -class wxSizer : public wxObject -{ -public: - /** - The constructor. Note that wxSizer is an abstract base class and may not - be instantiated. - */ - wxSizer(); - - /** - The destructor. - */ - ~wxSizer(); - - /** - Appends a child to the sizer. - - wxSizer itself is an abstract class, but the parameters are equivalent - in the derived classes that you will instantiate to use it so they are - described here: - - @param window - The window to be added to the sizer. Its initial size (either set - explicitly by the user or calculated internally when using - wxDefaultSize) is interpreted as the minimal and in many cases also - the initial size. - @param flags - A wxSizerFlags object that enables you to specify most of the above - parameters more conveniently. - */ - wxSizerItem* Add(wxWindow* window, const wxSizerFlags& flags); - - /** - Appends a child to the sizer. - - wxSizer itself is an abstract class, but the parameters are equivalent - in the derived classes that you will instantiate to use it so they are - described here: - - @param window - The window to be added to the sizer. Its initial size (either set - explicitly by the user or calculated internally when using - wxDefaultSize) is interpreted as the minimal and in many cases also - the initial size. - @param proportion - Although the meaning of this parameter is undefined in wxSizer, it - is used in wxBoxSizer to indicate if a child of a sizer can change - its size in the main orientation of the wxBoxSizer - where 0 stands - for not changeable and a value of more than zero is interpreted - relative to the value of other children of the same wxBoxSizer. For - example, you might have a horizontal wxBoxSizer with three - children, two of which are supposed to change their size with the - sizer. Then the two stretchable windows would get a value of 1 each - to make them grow and shrink equally with the sizer's horizontal - dimension. - @param flag - OR-combination of flags affecting sizer's behavior. See - @ref wxsizer_flags "wxSizer flags list" for details. - @param border - Determines the border width, if the flag parameter is set to - include any border flag. - @param userData - Allows an extra object to be attached to the sizer item, for use in - derived classes when sizing information is more complex than the - proportion and flag will allow for. - */ - wxSizerItem* Add(wxWindow* window, int proportion = 0, - int flag = 0, - int border = 0, - wxObject* userData = NULL); - - /** - Appends a child to the sizer. - - wxSizer itself is an abstract class, but the parameters are equivalent - in the derived classes that you will instantiate to use it so they are - described here: - - @param sizer - The (child-)sizer to be added to the sizer. This allows placing a - child sizer in a sizer and thus to create hierarchies of sizers - (typically a vertical box as the top sizer and several horizontal - boxes on the level beneath). - @param flags - A wxSizerFlags object that enables you to specify most of the above - parameters more conveniently. - */ - wxSizerItem* Add(wxSizer* sizer, const wxSizerFlags& flags); - - /** - Appends a child to the sizer. - - wxSizer itself is an abstract class, but the parameters are equivalent - in the derived classes that you will instantiate to use it so they are - described here: - - @param sizer - The (child-)sizer to be added to the sizer. This allows placing a - child sizer in a sizer and thus to create hierarchies of sizers - (typically a vertical box as the top sizer and several horizontal - boxes on the level beneath). - @param proportion - Although the meaning of this parameter is undefined in wxSizer, it - is used in wxBoxSizer to indicate if a child of a sizer can change - its size in the main orientation of the wxBoxSizer - where 0 stands - for not changeable and a value of more than zero is interpreted - relative to the value of other children of the same wxBoxSizer. For - example, you might have a horizontal wxBoxSizer with three - children, two of which are supposed to change their size with the - sizer. Then the two stretchable windows would get a value of 1 each - to make them grow and shrink equally with the sizer's horizontal - dimension. - @param flag - OR-combination of flags affecting sizer's behavior. See - @ref wxsizer_flags "wxSizer flags list" for details. - @param border - Determines the border width, if the flag parameter is set to - include any border flag. - @param userData - Allows an extra object to be attached to the sizer item, for use in - derived classes when sizing information is more complex than the - proportion and flag will allow for. - */ - wxSizerItem* Add(wxSizer* sizer, int proportion = 0, - int flag = 0, - int border = 0, - wxObject* userData = NULL); - - /** - Appends a spacer child to the sizer. - - wxSizer itself is an abstract class, but the parameters are equivalent - in the derived classes that you will instantiate to use it so they are - described here. - - @a width and @a height specify the dimension of a spacer to be added to - the sizer. Adding spacers to sizers gives more flexibility in the - design of dialogs; imagine for example a horizontal box with two - buttons at the bottom of a dialog: you might want to insert a space - between the two buttons and make that space stretchable using the - proportion flag and the result will be that the left button will be - aligned with the left side of the dialog and the right button with the - right side - the space in between will shrink and grow with the dialog. - - @param width - Width of the spacer. - @param height - Height of the spacer. - @param proportion - Although the meaning of this parameter is undefined in wxSizer, it - is used in wxBoxSizer to indicate if a child of a sizer can change - its size in the main orientation of the wxBoxSizer - where 0 stands - for not changeable and a value of more than zero is interpreted - relative to the value of other children of the same wxBoxSizer. For - example, you might have a horizontal wxBoxSizer with three - children, two of which are supposed to change their size with the - sizer. Then the two stretchable windows would get a value of 1 each - to make them grow and shrink equally with the sizer's horizontal - dimension. - @param flag - OR-combination of flags affecting sizer's behavior. See - @ref wxsizer_flags "wxSizer flags list" for details. - @param border - Determines the border width, if the flag parameter is set to - include any border flag. - @param userData - Allows an extra object to be attached to the sizer item, for use in - derived classes when sizing information is more complex than the - proportion and flag will allow for. - */ - wxSizerItem* Add(int width, int height, int proportion = 0, - int flag = 0, - int border = 0, - wxObject* userData = NULL); - - /** - Adds non-stretchable space to the sizer. More readable way of calling - wxSizer::Add(size, size, 0). - */ - wxSizerItem* AddSpacer(int size); - - /** - Adds stretchable space to the sizer. More readable way of calling - wxSizer::Add(0, 0, prop). - */ - wxSizerItem* AddStretchSpacer(int prop = 1); - - /** - This method is abstract and has to be overwritten by any derived class. - Here, the sizer will do the actual calculation of its children's minimal sizes. - */ - wxSize CalcMin(); - - /** - Detaches all children from the sizer. If @a delete_windows is @true then - child windows will also be deleted. - */ - void Clear(bool delete_windows = false); - - /** - Computes client area size for @a window so that it matches the sizer's - minimal size. Unlike GetMinSize(), this method accounts for other - constraints imposed on @e window, namely display's size (returned size - will never be too large for the display) and maximum window size if - previously set by wxWindow::SetMaxSize(). The returned value is - suitable for passing to wxWindow::SetClientSize() or - wxWindow::SetMinClientSize(). - - @since 2.8.8 - - @see ComputeFittingWindowSize(), Fit() - */ - wxSize ComputeFittingClientSize(wxWindow* window); - - /** - Like ComputeFittingClientSize(), but converts the result into window - size. The returned value is suitable for passing to wxWindow::SetSize() - or wxWindow::SetMinSize(). - - @since 2.8.8 - - @see ComputeFittingClientSize(), Fit() - */ - wxSize ComputeFittingWindowSize(wxWindow* window); - - /** - Detach the child @a window from the sizer without destroying it. - - This method does not cause any layout or resizing to take place, call Layout() - to update the layout "on screen" after detaching a child from the sizer. - - Returns @true if the child item was found and detached, @false otherwise. - - @see Remove() - */ - bool Detach(wxWindow* window); - - /** - Detach the child @a sizer from the sizer without destroying it. - - This method does not cause any layout or resizing to take place, call Layout() - to update the layout "on screen" after detaching a child from the sizer. - - Returns @true if the child item was found and detached, @false otherwise. - - @see Remove() - */ - bool Detach(wxSizer* sizer); - - /** - Detach a item at position @a index from the sizer without destroying it. - - This method does not cause any layout or resizing to take place, call Layout() - to update the layout "on screen" after detaching a child from the sizer. - Returns @true if the child item was found and detached, @false otherwise. - - @see Remove() - */ - bool Detach(size_t index); - - /** - Tell the sizer to resize the @a window so that its client area matches the - sizer's minimal size - (ComputeFittingClientSize() is called - to determine it). - This is commonly done in the constructor of the window - itself, see sample in the description - of wxBoxSizer. Returns the new window size. - - @see ComputeFittingClientSize(), ComputeFittingWindowSize() - */ - wxSize Fit(wxWindow* window); - - /** - Tell the sizer to resize the virtual size of the @a window to match the sizer's - minimal size. This will not alter the on screen size of the window, but may - cause the addition/removal/alteration of scrollbars required to view the virtual - area in windows which manage it. - - @see wxScrolled::SetScrollbars(), SetVirtualSizeHints() - */ - void FitInside(wxWindow* window); - - /** - Returns the list of the items in this sizer. The elements of type-safe - wxList @a wxSizerItemList are pointers to objects of type - @ref wxSizerItem "wxSizerItem". - */ - wxSizerItemList& GetChildren(); - - /** - Returns the list of the items in this sizer. The elements of type-safe - wxList @a wxSizerItemList are pointers to objects of type - @ref wxSizerItem "wxSizerItem". - */ - const wxSizerItemList& GetChildren() const; - - /** - Returns the window this sizer is used in or @NULL if none. - */ - wxWindow* GetContainingWindow() const; - - /** - Finds wxSizerItem which holds the given @a window - Use parameter @a recursive to search in subsizers too. - Returns pointer to item or @NULL. - */ - wxSizerItem* GetItem(wxWindow* window, bool recursive = false); - - /** - Finds wxSizerItem which holds the given @a sizer - Use parameter @a recursive to search in subsizers too. - Returns pointer to item or @NULL. - */ - - wxSizerItem* GetItem(wxSizer* sizer, bool recursive = false); - /** - Finds wxSizerItem which is located in the sizer at position - @a index. - Use parameter @a recursive to search in subsizers too. - Returns pointer to item or @NULL. - */ - wxSizerItem* GetItem(size_t index); - - /** - Finds item of the sizer which has the given @e id. This @a id is not the - window id but the id of the wxSizerItem itself. This is mainly useful for - retrieving the sizers created from XRC resources. - Use parameter @a recursive to search in subsizers too. - Returns pointer to item or @NULL. - */ - wxSizerItem* GetItemById(int id, bool recursive = false); - - /** - Returns the minimal size of the sizer. This is either the combined minimal - size of all the children and their borders or the minimal size set by - SetMinSize(), depending on which is bigger. - Note that the returned value is client size, not window size. - In particular, if you use the value to set toplevel window's minimal or - actual size, use wxWindow::SetMinClientSize - or wxWindow::SetClientSize, not - wxWindow::SetMinSize - or wxWindow::SetSize. - */ - wxSize GetMinSize(); - - /** - Returns the current position of the sizer. - */ - wxPoint GetPosition(); - - /** - Returns the current size of the sizer. - */ - wxSize GetSize(); - - /** - Hides the child @a window. - - To make a sizer item disappear, use Hide() followed by Layout(). - - Use parameter @a recursive to hide elements found in subsizers. - Returns @true if the child item was found, @false otherwise. - - @see IsShown(), Show() - */ - bool Hide(wxWindow* window, bool recursive = false); - - /** - Hides the child @a sizer. - - To make a sizer item disappear, use Hide() followed by Layout(). - - Use parameter @a recursive to hide elements found in subsizers. - Returns @true if the child item was found, @false otherwise. - - @see IsShown(), Show() - */ - bool Hide(wxSizer* sizer, bool recursive = false); - - /** - Hides the item at position @a index. - - To make a sizer item disappear, use Hide() followed by Layout(). - - Use parameter @a recursive to hide elements found in subsizers. - Returns @true if the child item was found, @false otherwise. - - @see IsShown(), Show() - */ - bool Hide(size_t index); - - /** - Insert a child into the sizer before any existing item at - - See Add() for the meaning of the other parameters. - */ - wxSizerItem* Insert(size_t index, wxWindow* window, - const wxSizerFlags& flags); - - /** - Insert a child into the sizer before any existing item at - - See Add() for the meaning of the other parameters. - */ - wxSizerItem* Insert(size_t index, wxWindow* window, - int proportion = 0, - int flag = 0, - int border = 0, - wxObject* userData = NULL); - - /** - Insert a child into the sizer before any existing item at - - See Add() for the meaning of the other parameters. - */ - wxSizerItem* Insert(size_t index, wxSizer* sizer, - const wxSizerFlags& flags); - - /** - Insert a child into the sizer before any existing item at - - See Add() for the meaning of the other parameters. - */ - wxSizerItem* Insert(size_t index, wxSizer* sizer, - int proportion = 0, - int flag = 0, - int border = 0, - wxObject* userData = NULL); - - /** - Insert a child into the sizer before any existing item at - - See Add() for the meaning of the other parameters. - */ - wxSizerItem* Insert(size_t index, int width, int height, - int proportion = 0, - int flag = 0, - int border = 0, - wxObject* userData = NULL); - - /** - Inserts non-stretchable space to the sizer. More readable way of calling - wxSizer::Insert(size, size, 0). - */ - wxSizerItem* InsertSpacer(size_t index, int size); - - /** - Inserts stretchable space to the sizer. More readable way of calling - wxSizer::Insert(0, 0, prop). - */ - wxSizerItem* InsertStretchSpacer(size_t index, int prop = 1); - - /** - Returns @true if the @e window is shown. - - @see Hide(), Show(), wxSizerItem::IsShown() - */ - bool IsShown(wxWindow* window) const; - - /** - Returns @true if the @e sizer is shown. - - @see Hide(), Show(), wxSizerItem::IsShown() - */ - bool IsShown(wxSizer* sizer) const; - - /** - Returns @true if the item at @a index is shown. - - @see Hide(), Show(), wxSizerItem::IsShown() - */ - bool IsShown(size_t index) const; - - /** - Call this to force layout of the children anew, e.g. after having added a child - to or removed a child (window, other sizer or space) from the sizer while - keeping - the current dimension. - */ - void Layout(); - - /** - Same as Add(), but prepends the items to the beginning of the - list of items (windows, subsizers or spaces) owned by this sizer. - */ - wxSizerItem* Prepend(wxWindow* window, const wxSizerFlags& flags); - - /** - Same as Add(), but prepends the items to the beginning of the - list of items (windows, subsizers or spaces) owned by this sizer. - */ - wxSizerItem* Prepend(wxWindow* window, int proportion = 0, - int flag = 0, - int border = 0, - wxObject* userData = NULL); - - /** - Same as Add(), but prepends the items to the beginning of the - list of items (windows, subsizers or spaces) owned by this sizer. - */ - wxSizerItem* Prepend(wxSizer* sizer, - const wxSizerFlags& flags); - - /** - Same as Add(), but prepends the items to the beginning of the - list of items (windows, subsizers or spaces) owned by this sizer. - */ - wxSizerItem* Prepend(wxSizer* sizer, int proportion = 0, - int flag = 0, - int border = 0, - wxObject* userData = NULL); - - /** - Same as Add(), but prepends the items to the beginning of the - list of items (windows, subsizers or spaces) owned by this sizer. - */ - wxSizerItem* Prepend(int width, int height, - int proportion = 0, - int flag = 0, - int border = 0, - wxObject* userData = NULL); - - /** - Prepends non-stretchable space to the sizer. More readable way of - calling wxSizer::Prepend(size, size, 0). - */ - wxSizerItem* PrependSpacer(int size); - - /** - Prepends stretchable space to the sizer. More readable way of calling - wxSizer::Prepend(0, 0, prop). - */ - wxSizerItem* PrependStretchSpacer(int prop = 1); - - /** - This method is abstract and has to be overwritten by any derived class. - Here, the sizer will do the actual calculation of its children's - positions and sizes. - */ - void RecalcSizes(); - - /** - Removes a child window from the sizer, but does @b not destroy it - (because windows are owned by their parent window, not the sizer). - - @deprecated - The overload of this method taking a wxWindow* parameter - is deprecated as it does not destroy the window as would usually be - expected from Remove(). You should use Detach() in new code instead. - There is currently no wxSizer method that will both detach and destroy - a wxWindow item. - - @note This method does not cause any layout or resizing to take - place, call Layout() to update the layout "on screen" after - removing a child from the sizer. - - @return @true if the child item was found and removed, @false otherwise. - */ - bool Remove(wxWindow* window); - - /** - Removes a sizer child from the sizer and destroys it. - - @note This method does not cause any layout or resizing to take - place, call Layout() to update the layout "on screen" after - removing a child from the sizer. - - @param sizer The wxSizer to be removed. - - @return @true if the child item was found and removed, @false otherwise. - */ - bool Remove(wxSizer* sizer); - - /** - Removes a child from the sizer and destroys it if it is a sizer or a - spacer, but not if it is a window (because windows are owned by their - parent window, not the sizer). - - @note This method does not cause any layout or resizing to take - place, call Layout() to update the layout "on screen" after - removing a child from the sizer. - - @param index The position of the child in the sizer, e.g. 0 for the - first item. - - @return @true if the child item was found and removed, @false otherwise. - */ - bool Remove(size_t index); - - /** - Detaches the given @a oldwin from the sizer and - replaces it with the given @a newwin. The detached - child window is @b not deleted (because windows are - owned by their parent window, not the sizer). - - Use parameter @a recursive to search the given element recursively in subsizers. - - This method does not cause any layout or resizing to take place, - call Layout() to update the layout "on screen" after replacing a - child from the sizer. - - Returns @true if the child item was found and removed, @false otherwise. - */ - bool Replace(wxWindow* oldwin, wxWindow* newwin, - bool recursive = false); - - /** - Detaches the given @a oldsz from the sizer and - replaces it with the given @a newsz. The detached - child sizer is deleted. - - Use parameter @a recursive to search the given element recursively in subsizers. - - This method does not cause any layout or resizing to take place, - call Layout() to update the layout "on screen" after replacing a - child from the sizer. - - Returns @true if the child item was found and removed, @false otherwise. - */ - bool Replace(wxSizer* oldsz, wxSizer* newsz, - bool recursive = false); - - /** - Detaches the given item at position @a index from the sizer and - replaces it with the given wxSizerItem @a newitem. - - The detached child is deleted @b only if it is a sizer or a spacer - (but not if it is a wxWindow because windows are owned by their - parent window, not the sizer). - - This method does not cause any layout or resizing to take place, - call Layout() to update the layout "on screen" after replacing a - child from the sizer. - - Returns @true if the child item was found and removed, @false otherwise. - */ - bool Replace(size_t index, wxSizerItem* newitem); - - /** - Call this to force the sizer to take the given dimension and thus force - the items owned by the sizer to resize themselves according to the - rules defined by the parameter in the Add() and Prepend() methods. - */ - void SetDimension(int x, int y, int width, int height); - - /** - @overload - */ - void SetDimension(const wxPoint& pos, const wxSize& size); - - /** - Set an item's minimum size by window, sizer, or position. - - The item will be found recursively in the sizer's descendants. This - function enables an application to set the size of an item after - initial creation. - - @see wxSizerItem::SetMinSize() - */ - void SetItemMinSize(wxWindow* window, int width, int height); - - /** - Set an item's minimum size by window, sizer, or position. - - The item will be found recursively in the sizer's descendants. This - function enables an application to set the size of an item after - initial creation. - - @see wxSizerItem::SetMinSize() - */ - void SetItemMinSize(wxSizer* sizer, int width, int height); - - /** - Set an item's minimum size by window, sizer, or position. - - The item will be found recursively in the sizer's descendants. This - function enables an application to set the size of an item after - initial creation. - - @see wxSizerItem::SetMinSize() - */ - void SetItemMinSize(size_t index, int width, int height); - - /** - Call this to give the sizer a minimal size. Normally, the sizer will - calculate its minimal size based purely on how much space its children - need. After calling this method GetMinSize() will return either the - minimal size as requested by its children or the minimal size set here, - depending on which is bigger. - */ - void SetMinSize(const wxSize& size); - - /** - @overload - */ - void SetMinSize(int width, int height); - - /** - This method first calls Fit() and then - wxTopLevelWindow::SetSizeHints on the @e window - passed to it. This only makes sense when @a window is actually a - wxTopLevelWindow such as a wxFrame or a - wxDialog, since SetSizeHints only has any effect in these classes. - It does nothing in normal windows or controls. - This method is implicitly used by wxWindow::SetSizerAndFit - which is commonly invoked in the constructor of a toplevel window itself (see - the sample in the description of wxBoxSizer) if the - toplevel window is resizable. - */ - void SetSizeHints(wxWindow* window); - - /** - Tell the sizer to set the minimal size of the @a window virtual area to match - the sizer's - minimal size. For windows with managed scrollbars this will set them - appropriately. - - @see wxScrolled::SetScrollbars() - */ - void SetVirtualSizeHints(wxWindow* window); - - /** - Shows or hides the @a window. - To make a sizer item disappear or reappear, use Show() followed by Layout(). - - Use parameter @a recursive to show or hide elements found in subsizers. - - Returns @true if the child item was found, @false otherwise. - - @see Hide(), IsShown() - */ - bool Show(wxWindow* window, bool show = true, - bool recursive = false); - - /** - Shows or hides @a sizer. - To make a sizer item disappear or reappear, use Show() followed by Layout(). - - Use parameter @a recursive to show or hide elements found in subsizers. - - Returns @true if the child item was found, @false otherwise. - - @see Hide(), IsShown() - */ - bool Show(wxSizer* sizer, bool show = true, - bool recursive = false); - - /** - Shows the item at @a index. - To make a sizer item disappear or reappear, use Show() followed by Layout(). - - Returns @true if the child item was found, @false otherwise. - - @see Hide(), IsShown() - */ - bool Show(size_t index, bool show = true); -}; - - - -/** - @class wxGridSizer - @wxheader{sizer.h} - - A grid sizer is a sizer which lays out its children in a two-dimensional - table with all table fields having the same size, - i.e. the width of each field is the width of the widest child, - the height of each field is the height of the tallest child. - - @library{wxcore} - @category{winlayout} - - @see wxSizer, @ref overview_sizer "Sizer Overview" -*/ -class wxGridSizer : public wxSizer -{ -public: - //@{ - /** - Constructor for a wxGridSizer. @a rows and @a cols determine the number of - columns and rows in the sizer - if either of the parameters is zero, it will be - calculated to form the total number of children in the sizer, thus making the - sizer grow dynamically. @a vgap and @a hgap define extra space between - all children. - */ - wxGridSizer(int rows, int cols, int vgap, int hgap); - wxGridSizer(int cols, int vgap = 0, int hgap = 0); - //@} - - /** - Returns the number of columns in the sizer. - */ - int GetCols(); - - /** - Returns the horizontal gap (in pixels) between cells in the sizer. - */ - int GetHGap(); - - /** - Returns the number of rows in the sizer. - */ - int GetRows(); - - /** - Returns the vertical gap (in pixels) between the cells in the sizer. - */ - int GetVGap(); - - /** - Sets the number of columns in the sizer. - */ - void SetCols(int cols); - - /** - Sets the horizontal gap (in pixels) between cells in the sizer. - */ - void SetHGap(int gap); - - /** - Sets the number of rows in the sizer. - */ - void SetRows(int rows); - - /** - Sets the vertical gap (in pixels) between the cells in the sizer. - */ - void SetVGap(int gap); -}; - - - -/** - @class wxStaticBoxSizer - @wxheader{sizer.h} - - wxStaticBoxSizer is a sizer derived from wxBoxSizer but adds a static - box around the sizer. This static box may be either created independently or - the sizer may create it itself as a convenience. In any case, the sizer owns - the wxStaticBox control and will delete it if it is - deleted. - - @library{wxcore} - @category{winlayout} - - @see wxSizer, wxStaticBox, wxBoxSizer, @ref overview_sizer - "Sizer Overview" -*/ -class wxStaticBoxSizer : public wxBoxSizer -{ -public: - //@{ - /** - The first constructor uses an already existing static box. It takes the - associated static box and the orientation @e orient, which can be either - @c wxVERTICAL or @c wxHORIZONTAL as parameters. - The second one creates a new static box with the given label and parent window. - */ - wxStaticBoxSizer(wxStaticBox* box, int orient); - wxStaticBoxSizer(int orient, wxWindow parent, - const wxString& label = wxEmptyString); - //@} - - /** - Returns the static box associated with the sizer. - */ - wxStaticBox* GetStaticBox(); -}; - - - -/** - @class wxBoxSizer - @wxheader{sizer.h} - - The basic idea behind a box sizer is that windows will most often be laid out - in rather - simple basic geometry, typically in a row or a column or several hierarchies of - either. - - For more information, please see @ref overview_sizer_box - "Programming with wxBoxSizer". - - @library{wxcore} - @category{winlayout} - - @see wxSizer, @ref overview_sizer "Sizers Overview" -*/ -class wxBoxSizer : public wxSizer -{ -public: - /** - Constructor for a wxBoxSizer. @a orient may be either of wxVERTICAL - or wxHORIZONTAL for creating either a column sizer or a row sizer. - */ - wxBoxSizer(int orient); - - /** - Implements the calculation of a box sizer's minimal. It is used internally - only and must not be called by the user. Documented for information. - */ - wxSize CalcMin(); - - /** - Returns the orientation of the box sizer, either wxVERTICAL - or wxHORIZONTAL. - */ - int GetOrientation(); - - /** - Implements the calculation of a box sizer's dimensions and then sets - the size of its children (calling wxWindow::SetSize - if the child is a window). It is used internally only and must not be called - by the user (call Layout() if you want to resize). Documented for information. - */ - void RecalcSizes(); -}; - diff --git a/interface/slider.h b/interface/slider.h deleted file mode 100644 index 5d20acb9fc..0000000000 --- a/interface/slider.h +++ /dev/null @@ -1,283 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: slider.h -// Purpose: interface of wxSlider -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxSlider - @wxheader{slider.h} - - A slider is a control with a handle which can be pulled - back and forth to change the value. - - On Windows, the track bar control is used. - - Slider events are handled in the same way as a scrollbar. - - @beginStyleTable - @style{wxSL_HORIZONTAL} - Displays the slider horizontally (this is the default). - @style{wxSL_VERTICAL} - Displays the slider vertically. - @style{wxSL_AUTOTICKS} - Displays tick marks. - @style{wxSL_LABELS} - Displays minimum, maximum and value labels. - @style{wxSL_LEFT} - Displays ticks on the left and forces the slider to be vertical. - @style{wxSL_RIGHT} - Displays ticks on the right and forces the slider to be vertical. - @style{wxSL_TOP} - Displays ticks on the top. - @style{wxSL_BOTTOM} - Displays ticks on the bottom (this is the default). - @style{wxSL_SELRANGE} - Allows the user to select a range on the slider. Windows only. - @style{wxSL_INVERSE} - Inverses the mininum and maximum endpoints on the slider. Not - compatible with wxSL_SELRANGE. - @endStyleTable - - @library{wxcore} - @category{ctrl} - - - @see @ref overview_eventhandlingoverview, wxScrollBar -*/ -class wxSlider : public wxControl -{ -public: - /** - Default constructor - */ - wxSlider(); - - /** - Constructor, creating and showing a slider. - - @param parent - Parent window. Must not be @NULL. - @param id - Window identifier. The value wxID_ANY indicates a default value. - @param value - Initial position for the slider. - @param minValue - Minimum slider position. - @param maxValue - Maximum slider position. - @param size - Window size. If wxDefaultSize is specified then a default size - is chosen. - @param style - Window style. See wxSlider. - @param validator - Window validator. - @param name - Window name. - - @see Create(), wxValidator - */ - wxSlider(wxWindow* parent, wxWindowID id, int value, - int minValue, int maxValue, - const wxPoint& point = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = wxSL_HORIZONTAL, - const wxValidator& validator = wxDefaultValidator, - const wxString& name = "slider"); - - /** - Destructor, destroying the slider. - */ - ~wxSlider(); - - /** - Clears the selection, for a slider with the @b wxSL_SELRANGE style. - - @remarks Windows 95 only. - */ - void ClearSel(); - - /** - Clears the ticks. - - @remarks Windows 95 only. - */ - void ClearTicks(); - - /** - Used for two-step slider construction. See wxSlider() - for further details. - */ - bool Create(wxWindow* parent, wxWindowID id, int value, - int minValue, int maxValue, - const wxPoint& point = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = wxSL_HORIZONTAL, - const wxValidator& validator = wxDefaultValidator, - const wxString& name = "slider"); - - /** - Returns the line size. - - @see SetLineSize() - */ - int GetLineSize() const; - - /** - Gets the maximum slider value. - - @see GetMin(), SetRange() - */ - int GetMax() const; - - /** - Gets the minimum slider value. - - @see GetMin(), SetRange() - */ - int GetMin() const; - - /** - Returns the page size. - - @see SetPageSize() - */ - int GetPageSize() const; - - /** - Returns the selection end point. - - @remarks Windows 95 only. - - @see GetSelStart(), SetSelection() - */ - int GetSelEnd() const; - - /** - Returns the selection start point. - - @remarks Windows 95 only. - - @see GetSelEnd(), SetSelection() - */ - int GetSelStart() const; - - /** - Returns the thumb length. - - @remarks Windows 95 only. - - @see SetThumbLength() - */ - int GetThumbLength() const; - - /** - Returns the tick frequency. - - @remarks Windows 95 only. - - @see SetTickFreq() - */ - int GetTickFreq() const; - - /** - Gets the current slider value. - - @see GetMin(), GetMax(), SetValue() - */ - int GetValue() const; - - /** - Sets the line size for the slider. - - @param lineSize - The number of steps the slider moves when the user moves it up or down a - line. - - @see GetLineSize() - */ - void SetLineSize(int lineSize); - - /** - Sets the page size for the slider. - - @param pageSize - The number of steps the slider moves when the user pages up or down. - - @see GetPageSize() - */ - void SetPageSize(int pageSize); - - /** - Sets the minimum and maximum slider values. - - @see GetMin(), GetMax() - */ - void SetRange(int minValue, int maxValue); - - /** - Sets the selection. - - @param startPos - The selection start position. - @param endPos - The selection end position. - - @remarks Windows 95 only. - - @see GetSelStart(), GetSelEnd() - */ - void SetSelection(int startPos, int endPos); - - /** - Sets the slider thumb length. - - @param len - The thumb length. - - @remarks Windows 95 only. - - @see GetThumbLength() - */ - void SetThumbLength(int len); - - /** - Sets a tick position. - - @param tickPos - The tick position. - - @remarks Windows 95 only. - - @see SetTickFreq() - */ - void SetTick(int tickPos); - - /** - Sets the tick mark frequency and position. - - @param n - Frequency. For example, if the frequency is set to two, a tick mark is - displayed for - every other increment in the slider's range. - @param pos - Position. Must be greater than zero. TODO: what is this for? - - @remarks Windows 95 only. - - @see GetTickFreq() - */ - void SetTickFreq(int n, int pos); - - /** - Sets the slider position. - - @param value - The slider position. - */ - void SetValue(int value); -}; - diff --git a/interface/snglinst.h b/interface/snglinst.h deleted file mode 100644 index b24130c399..0000000000 --- a/interface/snglinst.h +++ /dev/null @@ -1,107 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: snglinst.h -// Purpose: interface of wxSingleInstanceChecker -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxSingleInstanceChecker - @wxheader{snglinst.h} - - wxSingleInstanceChecker class allows to check that only a single instance of a - program is running. To do it, you should create an object of this class. As - long as this object is alive, calls to - wxSingleInstanceChecker::IsAnotherRunning from - other processes will return @true. - - As the object should have the life span as big as possible, it makes sense to - create it either as a global or in wxApp::OnInit. For - example: - - @code - bool MyApp::OnInit() - { - const wxString name = wxString::Format("MyApp-%s", wxGetUserId().c_str()); - m_checker = new wxSingleInstanceChecker(name); - if ( m_checker-IsAnotherRunning() ) - { - wxLogError(_("Another program instance is already running, aborting.")); - - delete m_checker; // OnExit() won't be called if we return @false - m_checker = @NULL; - - return @false; - } - - ... more initializations ... - - return @true; - } - - int MyApp::OnExit() - { - delete m_checker; - - return 0; - } - @endcode - - Note using wxGetUserId() to construct the name: this - allows different user to run the application concurrently which is usually the - intended goal. If you don't use the user name in the wxSingleInstanceChecker - name, only one user would be able to run the application at a time. - - This class is implemented for Win32 and Unix platforms (supporting @c fcntl() - system call, but almost all of modern Unix systems do) only. - - @library{wxbase} - @category{misc} -*/ -class wxSingleInstanceChecker -{ -public: - /** - Like Create() but without - error checking. - */ - wxSingleInstanceChecker(const wxString& name, - const wxString& path = wxEmptyString); - - /** - Destructor frees the associated resources. - Note that it is not virtual, this class is not meant to be used polymorphically - */ - ~wxSingleInstanceChecker(); - - /** - Initialize the object if it had been created using the default constructor. - Note that you can't call Create() more than once, so calling it if the - @ref wxsingleinstancechecker() "non default ctor" - had been used is an error. - - @param name - must be given and be as unique as possible. It is used as the - mutex name under Win32 and the lock file name under Unix. - GetAppName() and wxGetUserId() - are commonly used to construct this parameter. - @param path - is optional and is ignored under Win32 and used as the directory to - create the lock file in under Unix (default is - wxGetHomeDir()) - - @return Returns @false if initialization failed, it doesn't mean that - another instance is running - use IsAnotherRunning() - to check for it. - */ - bool Create(const wxString& name, - const wxString& path = wxEmptyString); - - /** - Returns @true if another copy of this program is already running, @false - otherwise. - */ - bool IsAnotherRunning() const; -}; - diff --git a/interface/socket.h b/interface/socket.h deleted file mode 100644 index 2312cf26e0..0000000000 --- a/interface/socket.h +++ /dev/null @@ -1,1096 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: socket.h -// Purpose: interface of wxIPV4address -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxIPV4address - @wxheader{socket.h} - - - @library{wxbase} - @category{net} -*/ -class wxIPV4address : public wxIPaddress -{ -public: - /** - Set address to any of the addresses of the current machine. Whenever - possible, use this function instead of LocalHost(), - as this correctly handles multi-homed hosts and avoids other small - problems. Internally, this is the same as setting the IP address - to @b INADDR_ANY. - - @return Returns @true on success, @false if something went wrong. - */ - bool AnyAddress(); - - //@{ - /** - Returns the hostname which matches the IP address. - */ - bool Hostname(const wxString& hostname); - Return value wxString Hostname(); - //@} - - /** - Returns a wxString containing the IP address in dot quad (127.0.0.1) format. - */ - wxString IPAddress(); - - /** - Set address to localhost (127.0.0.1). Whenever possible, use the - AnyAddress(), - function instead of this one, as this will correctly handle multi-homed - hosts and avoid other small problems. - */ - bool LocalHost(); - - //@{ - /** - Returns the current service. - */ - bool Service(const wxString& service); - Return value bool Service(unsigned short service); - Return value unsigned short Service(); - //@} -}; - - - -/** - @class wxSocketServer - @wxheader{socket.h} - - - @library{wxnet} - @category{net} - - @see wxSocketServer::WaitForAccept, wxSocketBase::SetNotify, - wxSocketBase::Notify, wxSocketServer::AcceptWith -*/ -class wxSocketServer : public wxSocketBase -{ -public: - /** - Constructs a new server and tries to bind to the specified @e address. - Before trying to accept new connections, test whether it succeeded with - @ref wxSocketBase::isok wxSocketBase:IsOk. - - @param address - Specifies the local address for the server (e.g. port number). - @param flags - Socket flags (See wxSocketBase::SetFlags) - */ - wxSocketServer(const wxSockAddress& address, - wxSocketFlags flags = wxSOCKET_NONE); - - /** - Destructor (it doesn't close the accepted connections). - */ - ~wxSocketServer(); - - /** - Accepts an incoming connection request, and creates a new - wxSocketBase object which represents - the server-side of the connection. - If @a wait is @true and there are no pending connections to be - accepted, it will wait for the next incoming connection to - arrive. @b Warning: This will block the GUI. - If @a wait is @false, it will try to accept a pending connection - if there is one, but it will always return immediately without blocking - the GUI. If you want to use Accept in this way, you can either check for - incoming connections with WaitForAccept() - or catch @b wxSOCKET_CONNECTION events, then call Accept once you know - that there is an incoming connection waiting to be accepted. - - @return Returns an opened socket connection, or @NULL if an error - occurred or if the wait parameter was @false and there - were no pending connections. - - @see WaitForAccept(), wxSocketBase::SetNotify, - wxSocketBase::Notify, AcceptWith() - */ - wxSocketBase* Accept(bool wait = true); - - /** - Accept an incoming connection using the specified socket object. - - @param socket - Socket to be initialized - - @return Returns @true on success, or @false if an error occurred or if the - wait parameter was @false and there were no pending - connections. - */ - bool AcceptWith(wxSocketBase& socket, bool wait = true); - - /** - This function waits for an incoming connection. Use it if you want to call - Accept() or AcceptWith() - with @e wait set to @false, to detect when an incoming connection is waiting - to be accepted. - - @param seconds - Number of seconds to wait. - If -1, it will wait for the default timeout, - as set with SetTimeout. - @param millisecond - Number of milliseconds to wait. - - @return Returns @true if an incoming connection arrived, @false if the - timeout elapsed. - */ - bool WaitForAccept(long seconds = -1, long millisecond = 0); -}; - - - -/** - @class wxIPaddress - @wxheader{socket.h} - - wxIPaddress is an abstract base class for all internet protocol address - objects. Currently, only wxIPV4address - is implemented. An experimental implementation for IPV6, wxIPV6address, - is being developed. - - @library{wxbase} - @category{net} -*/ -class wxIPaddress : public wxSockAddress -{ -public: - /** - Internally, this is the same as setting the IP address - to @b INADDR_ANY. - On IPV4 implementations, 0.0.0.0 - On IPV6 implementations, :: - - @return Returns @true on success, @false if something went wrong. - */ - virtual bool AnyAddress(); - - /** - Internally, this is the same as setting the IP address - to @b INADDR_BROADCAST. - On IPV4 implementations, 255.255.255.255 - - @return Returns @true on success, @false if something went wrong. - */ - virtual bool BroadcastAddress(); - - //@{ - /** - Returns the hostname which matches the IP address. - */ - virtual bool Hostname(const wxString& hostname); - Return value virtual wxString Hostname(); - //@} - - /** - Returns a wxString containing the IP address. - */ - virtual wxString IPAddress(); - - /** - Determines if current address is set to localhost. - */ - virtual bool IsLocalHost(); - - /** - Set address to localhost. - On IPV4 implementations, 127.0.0.1 - On IPV6 implementations, ::1 - - @return Returns @true on success, @false if something went wrong. - */ - virtual bool LocalHost(); - - //@{ - /** - Returns the current service. - */ - virtual bool Service(const wxString& service); - Return value virtual bool Service(unsigned short service); - Return value virtual unsigned short Service(); - //@} -}; - - - -/** - @class wxSocketClient - @wxheader{socket.h} - - - @library{wxnet} - @category{net} - - @see wxSocketClient::WaitOnConnect, wxSocketBase::SetNotify, - wxSocketBase::Notify -*/ -class wxSocketClient : public wxSocketBase -{ -public: - /** - Constructor. - - @param flags - Socket flags (See wxSocketBase::SetFlags) - */ - wxSocketClient(wxSocketFlags flags = wxSOCKET_NONE); - - /** - Destructor. Please see wxSocketBase::Destroy. - */ - ~wxSocketClient(); - - //@{ - /** - Connects to a server using the specified address. - If @a wait is @true, Connect will wait until the connection - completes. @b Warning: This will block the GUI. - If @a wait is @false, Connect will try to establish the connection and - return immediately, without blocking the GUI. When used this way, even if - Connect returns @false, the connection request can be completed later. - To detect this, use WaitOnConnect(), - or catch @b wxSOCKET_CONNECTION events (for successful establishment) - and @b wxSOCKET_LOST events (for connection failure). - - @param address - Address of the server. - @param local - Bind to the specified local address and port before connecting. - The local address and port can also be set using SetLocal, - and then using the 2-parameter Connect method. - @param wait - If @true, waits for the connection to complete. - - @return Returns @true if the connection is established and no error - occurs. - - @see WaitOnConnect(), wxSocketBase::SetNotify, - wxSocketBase::Notify - */ - bool Connect(wxSockAddress& address, bool wait = true); - bool Connect(wxSockAddress& address, wxSockAddress& local, - bool wait = true); - //@} - - /** - Wait until a connection request completes, or until the specified timeout - elapses. Use this function after issuing a call - to Connect() with @e wait set to @false. - - @param seconds - Number of seconds to wait. - If -1, it will wait for the default timeout, - as set with SetTimeout. - @param millisecond - Number of milliseconds to wait. - - @return WaitOnConnect returns @true if the connection request completes. - This does not necessarily mean that the connection was - successfully established; it might also happen that the - connection was refused by the peer. Use IsConnected to - distinguish between these two situations. - */ - bool WaitOnConnect(long seconds = -1, long milliseconds = 0); -}; - - - -/** - @class wxSockAddress - @wxheader{socket.h} - - You are unlikely to need to use this class: only wxSocketBase uses it. - - @library{wxbase} - @category{FIXME} - - @see wxSocketBase, wxIPaddress, wxIPV4address -*/ -class wxSockAddress : public wxObject -{ -public: - /** - Default constructor. - */ - wxSockAddress(); - - /** - Default destructor. - */ - ~wxSockAddress(); - - /** - Delete all informations about the address. - */ - void Clear(); - - /** - Returns the length of the socket address. - */ - int SockAddrLen(); -}; - - - -/** - @class wxSocketEvent - @wxheader{socket.h} - - This event class contains information about socket events. - - @library{wxnet} - @category{net} - - @see wxSocketBase, wxSocketClient, wxSocketServer -*/ -class wxSocketEvent : public wxEvent -{ -public: - /** - Constructor. - */ - wxSocketEvent(int id = 0); - - /** - Gets the client data of the socket which generated this event, as - set with wxSocketBase::SetClientData. - */ - void* GetClientData(); - - /** - Returns the socket object to which this event refers to. This makes - it possible to use the same event handler for different sockets. - */ - wxSocketBase* GetSocket() const; - - /** - Returns the socket event type. - */ - wxSocketNotify GetSocketEvent() const; -}; - - - -/** - @class wxSocketBase - @wxheader{socket.h} - - wxSocketBase is the base class for all socket-related objects, and it - defines all basic IO functionality. - - Note: (Workaround for implementation limitation for wxWidgets up to 2.5.x) - If you want to use sockets or derived classes such as wxFTP in a secondary - thread, - call wxSocketBase::Initialize() (undocumented) from the main thread before - creating - any sockets - in wxApp::OnInit for example. - See http://wiki.wxwidgets.org/wiki.pl?WxSocket or - http://www.litwindow.com/knowhow/knowhow.html for more details. - - @library{wxnet} - @category{net} - - @see wxSocketEvent, wxSocketClient, wxSocketServer, @ref overview_samplesockets - "Sockets sample" -*/ -class wxSocketBase : public wxObject -{ -public: - /** - Default constructor. Don't use it directly; instead, use - wxSocketClient to construct a socket client, or - wxSocketServer to construct a socket server. - */ - wxSocketBase(); - - /** - Destructor. Do not destroy a socket using the delete operator directly; - use Destroy() instead. Also, do not create - socket objects in the stack. - */ - ~wxSocketBase(); - - /** - Functions that perform basic IO functionality. - Close() - - Discard() - - Peek() - - Read() - - ReadMsg() - - Unread() - - Write() - - WriteMsg() - Functions that perform a timed wait on a certain IO condition. - InterruptWait() - - Wait() - - WaitForLost() - - WaitForRead() - - WaitForWrite() - - and also: - wxSocketServer::WaitForAccept - - wxSocketClient::WaitOnConnect - Functions that allow applications to customize socket IO as needed. - GetFlags() - - SetFlags() - - SetTimeout() - - SetLocal() - */ - - - /** - This function shuts down the socket, disabling further transmission and - reception of data; it also disables events for the socket and frees the - associated system resources. Upon socket destruction, Close is automatically - called, so in most cases you won't need to do it yourself, unless you - explicitly want to shut down the socket, typically to notify the peer - that you are closing the connection. - */ - void Close(); - - /** - @ref construct() wxSocketBase - - @ref destruct() ~wxSocketBase - - Destroy() - */ - - - /** - Destroys the socket safely. Use this function instead of the delete operator, - since otherwise socket events could reach the application even after the - socket has been destroyed. To prevent this problem, this function appends - the wxSocket to a list of object to be deleted on idle time, after all - events have been processed. For the same reason, you should avoid creating - socket objects in the stack. - Destroy calls Close() automatically. - - @return Always @true. - */ - bool Destroy(); - - /** - This function simply deletes all bytes in the incoming queue. This function - always returns immediately and its operation is not affected by IO flags. - Use LastCount() to verify the number of bytes actually discarded. - If you use Error(), it will always return @false. - */ - wxSocketBase Discard(); - - /** - Returns @true if an error occurred in the last IO operation. - Use this function to check for an error condition after one of the - following calls: Discard, Peek, Read, ReadMsg, Unread, Write, WriteMsg. - */ - bool Error() const; - - /** - Returns a pointer of the client data for this socket, as set with - SetClientData() - */ - void* GetClientData() const; - - /** - Returns current IO flags, as set with SetFlags() - */ - wxSocketFlags GetFlags() const; - - /** - This function returns the local address field of the socket. The local - address field contains the complete local address of the socket (local - address, local port, ...). - - @return @true if no error happened, @false otherwise. - */ - bool GetLocal(wxSockAddress& addr) const; - - /** - This function returns the peer address field of the socket. The peer - address field contains the complete peer host address of the socket - (address, port, ...). - - @return @true if no error happened, @false otherwise. - */ - bool GetPeer(wxSockAddress& addr) const; - - /** - Functions that allow applications to receive socket events. - Notify() - - SetNotify() - - GetClientData() - - SetClientData() - - SetEventHandler() - */ - - - /** - Use this function to interrupt any wait operation currently in progress. - Note that this is not intended as a regular way to interrupt a Wait call, - but only as an escape mechanism for exceptional situations where it is - absolutely necessary to use it, for example to abort an operation due to - some exception or abnormal problem. InterruptWait is automatically called - when you Close() a socket (and thus also upon - socket destruction), so you don't need to use it in these cases. - Wait(), - wxSocketServer::WaitForAccept, - WaitForLost(), - WaitForRead(), - WaitForWrite(), - wxSocketClient::WaitOnConnect - */ - void InterruptWait(); - - /** - Returns @true if the socket is connected. - */ - bool IsConnected() const; - - /** - This function waits until the socket is readable. This might mean that - queued data is available for reading or, for streamed sockets, that - the connection has been closed, so that a read operation will complete - immediately without blocking (unless the @b wxSOCKET_WAITALL flag - is set, in which case the operation might still block). - */ - bool IsData() const; - - /** - Returns @true if the socket is not connected. - */ - bool IsDisconnected() const; - - /** - Returns @true if the socket is initialized and ready and @false in other - cases. - */ - bool IsOk() const; - - /** - Returns the number of bytes read or written by the last IO call. - Use this function to get the number of bytes actually transferred - after using one of the following IO calls: Discard, Peek, Read, - ReadMsg, Unread, Write, WriteMsg. - */ - wxUint32 LastCount() const; - - /** - Returns the last wxSocket error. See @ref overview_wxsocketbase "wxSocket - errors". - Please note that this function merely returns the last error code, - but it should not be used to determine if an error has occurred (this - is because successful operations do not change the LastError value). - Use Error() first, in order to determine - if the last IO call failed. If this returns @true, use LastError - to discover the cause of the error. - */ - wxSocketError LastError() const; - - /** - According to the @a notify value, this function enables - or disables socket events. If @a notify is @true, the events - configured with SetNotify() will - be sent to the application. If @a notify is @false; no events - will be sent. - */ - void Notify(bool notify); - - /** - This function peeks a buffer of @a nbytes bytes from the socket. - Peeking a buffer doesn't delete it from the socket input queue. - Use LastCount() to verify the number of bytes actually peeked. - Use Error() to determine if the operation succeeded. - - @param buffer - Buffer where to put peeked data. - @param nbytes - Number of bytes. - - @return Returns a reference to the current object. - - @see Error(), LastError(), LastCount(), - SetFlags() - */ - wxSocketBase Peek(void* buffer, wxUint32 nbytes); - - /** - This function reads a buffer of @a nbytes bytes from the socket. - Use LastCount() to verify the number of bytes actually read. - Use Error() to determine if the operation succeeded. - - @param buffer - Buffer where to put read data. - @param nbytes - Number of bytes. - - @return Returns a reference to the current object. - - @see Error(), LastError(), LastCount(), - SetFlags() - */ - wxSocketBase Read(void* buffer, wxUint32 nbytes); - - /** - This function reads a buffer sent by WriteMsg() - on a socket. If the buffer passed to the function isn't big enough, the - remaining bytes will be discarded. This function always waits for the - buffer to be entirely filled, unless an error occurs. - Use LastCount() to verify the number of bytes actually read. - Use Error() to determine if the operation succeeded. - - @param buffer - Buffer where to put read data. - @param nbytes - Size of the buffer. - - @return Returns a reference to the current object. - - @see Error(), LastError(), LastCount(), - SetFlags(), WriteMsg() - */ - wxSocketBase ReadMsg(void* buffer, wxUint32 nbytes); - - /** - This function restores the previous state of the socket, as saved - with SaveState() - Calls to SaveState and RestoreState can be nested. - - @see SaveState() - */ - void RestoreState(); - - /** - This function saves the current state of the socket in a stack. Socket - state includes flags, as set with SetFlags(), - event mask, as set with SetNotify() and - Notify(), user data, as set with - SetClientData(). - Calls to SaveState and RestoreState can be nested. - - @see RestoreState() - */ - void SaveState(); - - /** - Sets user-supplied client data for this socket. All socket events will - contain a pointer to this data, which can be retrieved with - the wxSocketEvent::GetClientData function. - */ - void SetClientData(void* data); - - /** - Sets an event handler to be called when a socket event occurs. The - handler will be called for those events for which notification is - enabled with SetNotify() and - Notify(). - - @param handler - Specifies the event handler you want to use. - @param id - The id of socket event. - - @see SetNotify(), Notify(), wxSocketEvent, wxEvtHandler - */ - void SetEventHandler(wxEvtHandler& handler, int id = -1); - - /** - Use SetFlags to customize IO operation for this socket. - The @a flags parameter may be a combination of flags ORed together. - The following flags can be used: - - @b wxSOCKET_NONE - - Normal functionality. - - @b wxSOCKET_NOWAIT - - Read/write as much data as possible and return immediately. - - @b wxSOCKET_WAITALL - - Wait for all required data to be read/written unless an error occurs. - - @b wxSOCKET_BLOCK - - Block the GUI (do not yield) while reading/writing data. - - @b wxSOCKET_REUSEADDR - - Allows the use of an in-use port (wxServerSocket only) - - @b wxSOCKET_BROADCAST - - Switches the socket to broadcast mode - - @b wxSOCKET_NOBIND - - Stops the socket from being bound to a specific adapter (normally used in - conjunction with @b wxSOCKET_BROADCAST) - - A brief overview on how to use these flags follows. - If no flag is specified (this is the same as @b wxSOCKET_NONE), - IO calls will return after some data has been read or written, even - when the transfer might not be complete. This is the same as issuing - exactly one blocking low-level call to recv() or send(). Note - that @e blocking here refers to when the function returns, not - to whether the GUI blocks during this time. - If @b wxSOCKET_NOWAIT is specified, IO calls will return immediately. - Read operations will retrieve only available data. Write operations will - write as much data as possible, depending on how much space is available - in the output buffer. This is the same as issuing exactly one nonblocking - low-level call to recv() or send(). Note that @e nonblocking here - refers to when the function returns, not to whether the GUI blocks during - this time. - If @b wxSOCKET_WAITALL is specified, IO calls won't return until ALL - the data has been read or written (or until an error occurs), blocking if - necessary, and issuing several low level calls if necessary. This is the - same as having a loop which makes as many blocking low-level calls to - recv() or send() as needed so as to transfer all the data. Note - that @e blocking here refers to when the function returns, not - to whether the GUI blocks during this time. - The @b wxSOCKET_BLOCK flag controls whether the GUI blocks during - IO operations. If this flag is specified, the socket will not yield - during IO calls, so the GUI will remain blocked until the operation - completes. If it is not used, then the application must take extra - care to avoid unwanted reentrance. - The @b wxSOCKET_REUSEADDR flag controls the use of the SO_REUSEADDR standard - setsockopt() flag. This flag allows the socket to bind to a port that is - already in use. - This is mostly used on UNIX-based systems to allow rapid starting and stopping - of a server - - otherwise you may have to wait several minutes for the port to become available. - wxSOCKET_REUSEADDR can also be used with socket clients to (re)bind to a - particular local port - for an outgoing connection. - This option can have surprising platform dependent behavior, so check the - documentation for - your platform's implementation of setsockopt(). Note that on BSD-based systems - (e.g. Mac OS X), - use of wxSOCKET_REUSEADDR implies SO_REUSEPORT in addition to SO_REUSEADDR to - be consistent - with Windows. - The @b wxSOCKET_BROADCAST flag controls the use of the SO_BROADCAST standard - setsockopt() flag. This flag allows the socket to use the broadcast address, - and is generally - used in conjunction with @b wxSOCKET_NOBIND and wxIPaddress::BroadcastAddress. - So: - @b wxSOCKET_NONE will try to read at least SOME data, no matter how much. - @b wxSOCKET_NOWAIT will always return immediately, even if it cannot - read or write ANY data. - @b wxSOCKET_WAITALL will only return when it has read or written ALL - the data. - @b wxSOCKET_BLOCK has nothing to do with the previous flags and - it controls whether the GUI blocks. - @b wxSOCKET_REUSEADDR controls special platform-specific behavior for - reusing local addresses/ports. - */ - void SetFlags(wxSocketFlags flags); - - /** - This function allows you to set the local address and port, - useful when an application needs to reuse a particular port. When - a local port is set for a wxSocketClient, - @b bind will be called before @b connect. - */ - bool SetLocal(wxIPV4address& local); - - /** - SetNotify specifies which socket events are to be sent to the event handler. - The @a flags parameter may be combination of flags ORed together. The - following flags can be used: - - @b wxSOCKET_INPUT_FLAG - - to receive wxSOCKET_INPUT - - @b wxSOCKET_OUTPUT_FLAG - - to receive wxSOCKET_OUTPUT - - @b wxSOCKET_CONNECTION_FLAG - - to receive wxSOCKET_CONNECTION - - @b wxSOCKET_LOST_FLAG - - to receive wxSOCKET_LOST - - For example: - - In this example, the user will be notified about incoming socket data and - whenever the connection is closed. - For more information on socket events see @ref overview_wxsocketbase "wxSocket - events". - */ - void SetNotify(wxSocketEventFlags flags); - - /** - This function sets the default socket timeout in seconds. This timeout - applies to all IO calls, and also to the Wait() family - of functions if you don't specify a wait interval. Initially, the default - timeout is 10 minutes. - */ - void SetTimeout(int seconds); - - /** - Functions to retrieve current state and miscellaneous info. - Error() - - GetLocal() - - GetPeer() - IsConnected() - - IsData() - - IsDisconnected() - - LastCount() - - LastError() - - IsOk() - - SaveState() - - RestoreState() - */ - - - /** - This function unreads a buffer. That is, the data in the buffer is put back - in the incoming queue. This function is not affected by wxSocket flags. - If you use LastCount(), it will always return @e nbytes. - If you use Error(), it will always return @false. - - @param buffer - Buffer to be unread. - @param nbytes - Number of bytes. - - @return Returns a reference to the current object. - - @see Error(), LastCount(), LastError() - */ - wxSocketBase Unread(const void* buffer, wxUint32 nbytes); - - /** - This function waits until any of the following conditions is @true: - - The socket becomes readable. - The socket becomes writable. - An ongoing connection request has completed (wxSocketClient only) - An incoming connection request has arrived (wxSocketServer only) - The connection has been closed. - Note that it is recommended to use the individual Wait functions - to wait for the required condition, instead of this one. - - @param seconds - Number of seconds to wait. - If -1, it will wait for the default timeout, - as set with SetTimeout. - @param millisecond - Number of milliseconds to wait. - - @return Returns @true when any of the above conditions is satisfied, - @false if the timeout was reached. - - @see InterruptWait(), wxSocketServer::WaitForAccept, - WaitForLost(), WaitForRead(), - WaitForWrite(), wxSocketClient::WaitOnConnect - */ - bool Wait(long seconds = -1, long millisecond = 0); - - /** - This function waits until the connection is lost. This may happen if - the peer gracefully closes the connection or if the connection breaks. - - @param seconds - Number of seconds to wait. - If -1, it will wait for the default timeout, - as set with SetTimeout. - @param millisecond - Number of milliseconds to wait. - - @return Returns @true if the connection was lost, @false if the timeout - was reached. - - @see InterruptWait(), Wait() - */ - bool WaitForLost(long seconds = -1, long millisecond = 0); - - /** - This function waits until the socket is readable. This might mean that - queued data is available for reading or, for streamed sockets, that - the connection has been closed, so that a read operation will complete - immediately without blocking (unless the @b wxSOCKET_WAITALL flag - is set, in which case the operation might still block). - - @param seconds - Number of seconds to wait. - If -1, it will wait for the default timeout, - as set with SetTimeout. - @param millisecond - Number of milliseconds to wait. - - @return Returns @true if the socket becomes readable, @false on timeout. - - @see InterruptWait(), Wait() - */ - bool WaitForRead(long seconds = -1, long millisecond = 0); - - /** - This function waits until the socket becomes writable. This might mean that - the socket is ready to send new data, or for streamed sockets, that the - connection has been closed, so that a write operation is guaranteed to - complete immediately (unless the @b wxSOCKET_WAITALL flag is set, - in which case the operation might still block). - - @param seconds - Number of seconds to wait. - If -1, it will wait for the default timeout, - as set with SetTimeout. - @param millisecond - Number of milliseconds to wait. - - @return Returns @true if the socket becomes writable, @false on timeout. - - @see InterruptWait(), Wait() - */ - bool WaitForWrite(long seconds = -1, long millisecond = 0); - - /** - This function writes a buffer of @a nbytes bytes to the socket. - Use LastCount() to verify the number of bytes actually written. - Use Error() to determine if the operation succeeded. - - @param buffer - Buffer with the data to be sent. - @param nbytes - Number of bytes. - - @return Returns a reference to the current object. - - @see Error(), LastError(), LastCount(), - SetFlags() - */ - wxSocketBase Write(const void* buffer, wxUint32 nbytes); - - /** - This function writes a buffer of @a nbytes bytes from the socket, but it - writes a short header before so that ReadMsg() - knows how much data should it actually read. So, a buffer sent with WriteMsg - @b must be read with ReadMsg. This function always waits for the entire - buffer to be sent, unless an error occurs. - Use LastCount() to verify the number of bytes actually written. - Use Error() to determine if the operation succeeded. - - @param buffer - Buffer with the data to be sent. - @param nbytes - Number of bytes to send. - - @return Returns a reference to the current object. - */ - wxSocketBase WriteMsg(const void* buffer, wxUint32 nbytes); -}; - - - -/** - @class wxDatagramSocket - @wxheader{socket.h} - - - @library{wxnet} - @category{FIXME} - - @see wxSocketBase::Error, wxSocketBase::LastError, wxSocketBase::LastCount, - wxSocketBase::SetFlags, -*/ -class wxDatagramSocket : public wxSocketBase -{ -public: - /** - Constructor. - - @param flags - Socket flags (See wxSocketBase::SetFlags) - */ - wxDatagramSocket(wxSocketFlags flags = wxSOCKET_NONE); - - /** - Destructor. Please see wxSocketBase::Destroy. - */ - ~wxDatagramSocket(); - - /** - This function reads a buffer of @a nbytes bytes from the socket. - Use wxSocketBase::LastCount to verify the number of bytes actually read. - Use wxSocketBase::Error to determine if the operation succeeded. - - @param address - Any address - will be overwritten with the address of the peer that sent - that data. - @param buffer - Buffer where to put read data. - @param nbytes - Number of bytes. - - @return Returns a reference to the current object, and the address of - the peer that sent the data on address param. - - @see wxSocketBase::Error, wxSocketBase::LastError, wxSocketBase::LastCount, - wxSocketBase::SetFlags, - */ - wxDatagramSocket ReceiveFrom(wxSockAddress& address, - void* buffer, - wxUint32 nbytes); - - /** - This function writes a buffer of @a nbytes bytes to the socket. - Use wxSocketBase::LastCount to verify the number of bytes actually wrote. - Use wxSocketBase::Error to determine if the operation succeeded. - - @param address - The address of the destination peer for this data. - @param buffer - Buffer where read data is. - @param nbytes - Number of bytes. - - @return Returns a reference to the current object. - */ - wxDatagramSocket SendTo(const wxSockAddress& address, - const void* buffer, - wxUint32 nbytes); -}; - diff --git a/interface/sound.h b/interface/sound.h deleted file mode 100644 index 2d22a5b76c..0000000000 --- a/interface/sound.h +++ /dev/null @@ -1,107 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: sound.h -// Purpose: interface of wxSound -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxSound - @wxheader{sound.h} - - This class represents a short sound (loaded from Windows WAV file), that - can be stored in memory and played. Currently this class is implemented - on Windows and Unix (and uses either - Open Sound System or - Simple DirectMedia Layer). - - @library{wxadv} - @category{FIXME} -*/ -class wxSound : public wxObject -{ -public: - //@{ - /** - Constructs a wave object from a file or, under Windows, from a Windows - resource. Call IsOk() to determine whether this - succeeded. - - @param fileName - The filename or Windows resource. - @param isResource - @true if fileName is a resource, @false if it is a filename. - */ - wxSound(); - wxSound(const wxString& fileName, bool isResource = false); - //@} - - /** - Destroys the wxSound object. - */ - ~wxSound(); - - /** - Constructs a wave object from a file or resource. - - @param fileName - The filename or Windows resource. - @param isResource - @true if fileName is a resource, @false if it is a filename. - - @return @true if the call was successful, @false otherwise. - */ - bool Create(const wxString& fileName, bool isResource = false); - - /** - Returns @true if the object contains a successfully loaded file or resource, - @false otherwise. - */ - bool IsOk() const; - - /** - Returns @true if a sound is played at the moment. - This method is currently not implemented under Windows. - */ - static bool IsPlaying() const; - - //@{ - /** - Plays the sound file. If another sound is playing, it will be interrupted. - Returns @true on success, @false otherwise. Note that in general it is - possible - to delete the object which is being asynchronously played any time after - calling this function and the sound would continue playing, however this - currently doesn't work under Windows for sound objects loaded from memory data. - The possible values for @a flags are: - - wxSOUND_SYNC - - @c Play will block and wait until the sound is - replayed. - - wxSOUND_ASYNC - - Sound is played asynchronously, - @c Play returns immediately - - wxSOUND_ASYNC | wxSOUND_LOOP - - Sound is played asynchronously - and loops until another sound is played, - Stop() is called or the program terminates. - - The static form is shorthand for this code: - */ - bool Play(unsigned flags = wxSOUND_ASYNC); - const static bool Play(const wxString& filename, - unsigned flags = wxSOUND_ASYNC); - //@} - - /** - If a sound is played, this function stops it. - */ - static void Stop(); -}; - diff --git a/interface/spinbutt.h b/interface/spinbutt.h deleted file mode 100644 index 054bce9150..0000000000 --- a/interface/spinbutt.h +++ /dev/null @@ -1,165 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: spinbutt.h -// Purpose: interface of wxSpinEvent -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxSpinEvent - @wxheader{spinbutt.h} - - This event class is used for the events generated by - wxSpinButton and wxSpinCtrl. - - @library{wxcore} - @category{events} - - @see wxSpinButton and wxSpinCtrl -*/ -class wxSpinEvent : public wxNotifyEvent -{ -public: - /** - The constructor is not normally used by the user code. - */ - wxSpinEvent(wxEventType commandType = wxEVT_NULL, int id = 0); - - /** - Retrieve the current spin button or control value. - */ - int GetPosition() const; - - /** - Set the value associated with the event. - */ - void SetPosition(int pos); -}; - - - -/** - @class wxSpinButton - @wxheader{spinbutt.h} - - A wxSpinButton has two small up and down (or left and right) arrow buttons. It - is often used next to a text control for increment and decrementing a value. - Portable programs should try to use wxSpinCtrl instead - as wxSpinButton is not implemented for all platforms but wxSpinCtrl is as it - degenerates to a simple wxTextCtrl on such platforms. - - @note the range supported by this control (and wxSpinCtrl) depends on the - platform but is at least @c -0x8000 to @c 0x7fff. Under GTK and - Win32 with sufficiently new version of @c comctrl32.dll (at least 4.71 is - required, 5.80 is recommended) the full 32 bit range is supported. - - @beginStyleTable - @style{wxSP_HORIZONTAL} - Specifies a horizontal spin button (note that this style is not - supported in wxGTK). - @style{wxSP_VERTICAL} - Specifies a vertical spin button. - @style{wxSP_ARROW_KEYS} - The user can use arrow keys to change the value. - @style{wxSP_WRAP} - The value wraps at the minimum and maximum. - @endStyleTable - - @library{wxcore} - @category{ctrl} - - - @see wxSpinCtrl -*/ -class wxSpinButton : public wxControl -{ -public: - /** - Default constructor. - */ - wxSpinButton(); - - /** - Constructor, creating and showing a spin button. - - @param parent - Parent window. Must not be @NULL. - @param id - Window identifier. The value wxID_ANY indicates a default value. - @param pos - Window position. If wxDefaultPosition is specified then a default - position is chosen. - @param size - Window size. If wxDefaultSize is specified then a default size - is chosen. - @param style - Window style. See wxSpinButton. - @param name - Window name. - - @see Create() - */ - wxSpinButton(wxWindow* parent, wxWindowID id, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = wxSP_HORIZONTAL, - const wxString& name = "spinButton"); - - /** - Destructor, destroys the spin button control. - */ - ~wxSpinButton(); - - /** - Scrollbar creation function called by the spin button constructor. - See wxSpinButton() for details. - */ - bool Create(wxWindow* parent, wxWindowID id, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = wxSP_HORIZONTAL, - const wxString& name = "spinButton"); - - /** - Returns the maximum permissible value. - - @see SetRange() - */ - int GetMax() const; - - /** - Returns the minimum permissible value. - - @see SetRange() - */ - int GetMin() const; - - /** - Returns the current spin button value. - - @see SetValue() - */ - int GetValue() const; - - /** - Sets the range of the spin button. - - @param min - The minimum value for the spin button. - @param max - The maximum value for the spin button. - - @see GetMin(), GetMax() - */ - void SetRange(int min, int max); - - /** - Sets the value of the spin button. - - @param value - The value for the spin button. - */ - void SetValue(int value); -}; - diff --git a/interface/spinctrl.h b/interface/spinctrl.h deleted file mode 100644 index 06d29a3647..0000000000 --- a/interface/spinctrl.h +++ /dev/null @@ -1,124 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: spinctrl.h -// Purpose: interface of wxSpinCtrl -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxSpinCtrl - @wxheader{spinctrl.h} - - wxSpinCtrl combines wxTextCtrl and - wxSpinButton in one control. - - @beginStyleTable - @style{wxSP_ARROW_KEYS} - The user can use arrow keys to change the value. - @style{wxSP_WRAP} - The value wraps at the minimum and maximum. - @endStyleTable - - @library{wxcore} - @category{ctrl} - - - @see wxSpinButton, wxControl -*/ -class wxSpinCtrl : public wxControl -{ -public: - /** - Default constructor. - */ - wxSpinCtrl(); - - /** - Constructor, creating and showing a spin control. - - @param parent - Parent window. Must not be @NULL. - @param value - Default value (as text). - @param id - Window identifier. The value wxID_ANY indicates a default value. - @param pos - Window position. If wxDefaultPosition is specified then a default - position is chosen. - @param size - Window size. If wxDefaultSize is specified then a default size - is chosen. - @param style - Window style. See wxSpinButton. - @param min - Minimal value. - @param max - Maximal value. - @param initial - Initial value. - @param name - Window name. - - @see Create() - */ - wxSpinCtrl(wxWindow* parent, wxWindowID id = -1, - const wxString& value = wxEmptyString, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = wxSP_ARROW_KEYS, - int min = 0, int max = 100, - int initial = 0); - - /** - Creation function called by the spin control constructor. - See wxSpinCtrl() for details. - */ - bool Create(wxWindow* parent, wxWindowID id = -1, - const wxString& value = wxEmptyString, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = wxSP_ARROW_KEYS, - int min = 0, int max = 100, - int initial = 0); - - /** - Gets maximal allowable value. - */ - int GetMax() const; - - /** - Gets minimal allowable value. - */ - int GetMin() const; - - /** - Gets the value of the spin control. - */ - int GetValue() const; - - /** - Sets range of allowable values. - */ - void SetRange(int minVal, int maxVal); - - /** - Select the text in the text part of the control between positions - @a from (inclusive) and @a to (exclusive). This is similar to - wxTextCtrl::SetSelection. - @note this is currently only implemented for Windows and generic versions - of the control. - */ - void SetSelection(long from, long to); - - /** - Sets the value of the spin control. Use the variant using int instead. - */ - void SetValue(const wxString& text); - - /** - Sets the value of the spin control. - */ - void SetValue(int value); -}; - diff --git a/interface/splash.h b/interface/splash.h deleted file mode 100644 index ae408f6bb0..0000000000 --- a/interface/splash.h +++ /dev/null @@ -1,86 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: splash.h -// Purpose: interface of wxSplashScreen -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxSplashScreen - @wxheader{splash.h} - - wxSplashScreen shows a window with a thin border, displaying a bitmap - describing your - application. Show it in application initialisation, and then either explicitly - destroy - it or let it time-out. - - Example usage: - - @code - wxBitmap bitmap; - if (bitmap.LoadFile("splash16.png", wxBITMAP_TYPE_PNG)) - { - wxSplashScreen* splash = new wxSplashScreen(bitmap, - wxSPLASH_CENTRE_ON_SCREEN|wxSPLASH_TIMEOUT, - 6000, @NULL, -1, wxDefaultPosition, wxDefaultSize, - wxBORDER_SIMPLE|wxSTAY_ON_TOP); - } - wxYield(); - @endcode - - @library{wxadv} - @category{managedwnd} -*/ -class wxSplashScreen : public wxFrame -{ -public: - /** - Construct the splash screen passing a bitmap, a style, a timeout, a window id, - optional position - and size, and a window style. - @a splashStyle is a bitlist of some of the following: - wxSPLASH_CENTRE_ON_PARENT - wxSPLASH_CENTRE_ON_SCREEN - wxSPLASH_NO_CENTRE - wxSPLASH_TIMEOUT - wxSPLASH_NO_TIMEOUT - @a milliseconds is the timeout in milliseconds. - */ - wxSplashScreen(const wxBitmap& bitmap, long splashStyle, - int milliseconds, - wxWindow* parent, - wxWindowID id, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = wxBORDER_SIMPLE|wxFRAME_NO_TASKBAR|wxSTAY_ON_TOP); - - /** - Destroys the splash screen. - */ - ~wxSplashScreen(); - - /** - Returns the splash style (see wxSplashScreen() for - details). - */ - long GetSplashStyle() const; - - /** - Returns the window used to display the bitmap. - */ - wxSplashScreenWindow* GetSplashWindow() const; - - /** - Returns the timeout in milliseconds. - */ - int GetTimeout() const; - - /** - Reimplement this event handler if you want to set an application variable on - window destruction, for example. - */ - void OnCloseWindow(wxCloseEvent& event); -}; - diff --git a/interface/splitter.h b/interface/splitter.h deleted file mode 100644 index 71478582a3..0000000000 --- a/interface/splitter.h +++ /dev/null @@ -1,441 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: splitter.h -// Purpose: interface of wxSplitterWindow -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxSplitterWindow - @wxheader{splitter.h} - - @ref overview_wxsplitterwindowoverview "wxSplitterWindow overview" - - This class manages up to two subwindows. The current view can be - split into two programmatically (perhaps from a menu command), and unsplit - either programmatically or via the wxSplitterWindow user interface. - - @beginStyleTable - @style{wxSP_3D} - Draws a 3D effect border and sash. - @style{wxSP_3DSASH} - Draws a 3D effect sash. - @style{wxSP_3DBORDER} - Synonym for wxSP_BORDER. - @style{wxSP_BORDER} - Draws a standard border. - @style{wxSP_NOBORDER} - No border (default). - @style{wxSP_NO_XP_THEME} - Under Windows XP, switches off the attempt to draw the splitter - using Windows XP theming, so the borders and sash will take on the - pre-XP look. - @style{wxSP_PERMIT_UNSPLIT} - Always allow to unsplit, even with the minimum pane size other than - zero. - @style{wxSP_LIVE_UPDATE} - Don't draw XOR line but resize the child windows immediately. - @endStyleTable - - @library{wxcore} - @category{miscwnd} - - @see wxSplitterEvent -*/ -class wxSplitterWindow : public wxWindow -{ -public: - /** - Default constructor - */ - wxSplitterWindow(); - - /** - Constructor for creating the window. - - @param parent - The parent of the splitter window. - @param id - The window identifier. - @param pos - The window position. - @param size - The window size. - @param style - The window style. See wxSplitterWindow. - @param name - The window name. - - @remarks After using this constructor, you must create either one or two - subwindows with the splitter window as parent, and then - call one of Initialize(), - SplitVertically() and - SplitHorizontally() in order to set the - pane(s). - - @see Initialize(), SplitVertically(), - SplitHorizontally(), Create() - */ - wxSplitterWindow(wxWindow* parent, wxWindowID id, - const wxPoint& point = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = wxSP_3D, - const wxString& name = "splitterWindow"); - - /** - Destroys the wxSplitterWindow and its children. - */ - ~wxSplitterWindow(); - - /** - Creation function, for two-step construction. See wxSplitterWindow() for - details. - */ - bool Create(wxWindow* parent, wxWindowID id, - const wxPoint& point = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = wxSP_3D, - const wxString& name = "splitterWindow"); - - /** - Returns the current minimum pane size (defaults to zero). - - @see SetMinimumPaneSize() - */ - int GetMinimumPaneSize() const; - - /** - Returns the current sash gravity. - - @see SetSashGravity() - */ - double GetSashGravity(); - - /** - Returns the current sash position. - - @see SetSashPosition() - */ - int GetSashPosition(); - - /** - Gets the split mode. - - @see SetSplitMode(), SplitVertically(), - SplitHorizontally(). - */ - int GetSplitMode() const; - - /** - Returns the left/top or only pane. - */ - wxWindow* GetWindow1() const; - - /** - Returns the right/bottom pane. - */ - wxWindow* GetWindow2() const; - - /** - Initializes the splitter window to have one pane. The child window is - shown if it is currently hidden. - - @param window - The pane for the unsplit window. - - @remarks This should be called if you wish to initially view only a - single pane in the splitter window. - - @see SplitVertically(), SplitHorizontally() - */ - void Initialize(wxWindow* window); - - /** - Returns @true if the window is split, @false otherwise. - */ - bool IsSplit() const; - - /** - Application-overridable function called when the sash is double-clicked with - the left mouse button. - - @param x - The x position of the mouse cursor. - @param y - The y position of the mouse cursor. - - @remarks The default implementation of this function calls Unsplit if the - minimum pane size is zero. - - @see Unsplit() - */ - virtual void OnDoubleClickSash(int x, int y); - - /** - Application-overridable function called when the sash position is changed by - user. It may return @false to prevent the change or @true to allow it. - - @param newSashPosition - The new sash position (always positive or zero) - - @remarks The default implementation of this function verifies that the - sizes of both panes of the splitter are greater than - minimum pane size. - */ - virtual bool OnSashPositionChange(int newSashPosition); - - /** - Application-overridable function called when the window is unsplit, either - programmatically or using the wxSplitterWindow user interface. - - @param removed - The window being removed. - - @remarks The default implementation of this function simply hides - removed. You may wish to delete the window. - */ - virtual void OnUnsplit(wxWindow* removed); - - /** - This function replaces one of the windows managed by the wxSplitterWindow with - another one. It is in general better to use it instead of calling Unsplit() - and then resplitting the window back because it will provoke much less flicker - (if any). It is valid to call this function whether the splitter has two - windows or only one. - Both parameters should be non-@NULL and @a winOld must specify one of the - windows managed by the splitter. If the parameters are incorrect or the window - couldn't be replaced, @false is returned. Otherwise the function will return - @true, but please notice that it will not delete the replaced window and you - may wish to do it yourself. - - @see GetMinimumPaneSize() - */ - bool ReplaceWindow(wxWindow* winOld, wxWindow* winNew); - - /** - Sets the minimum pane size. - - @param paneSize - Minimum pane size in pixels. - - @remarks The default minimum pane size is zero, which means that either - pane can be reduced to zero by dragging the sash, thus - removing one of the panes. To prevent this behaviour - (and veto out-of-range sash dragging), set a minimum - size, for example 20 pixels. If the wxSP_PERMIT_UNSPLIT - style is used when a splitter window is created, the - window may be unsplit even if minimum size is non-zero. - - @see GetMinimumPaneSize() - */ - void SetMinimumPaneSize(int paneSize); - - /** - Sets the sash gravity. - - @param gravity - The sash gravity. Value between 0.0 and 1.0. - - @see GetSashGravity() - */ - void SetSashGravity(double gravity); - - /** - Sets the sash position. - - @param position - The sash position in pixels. - @param redraw - If @true, resizes the panes and redraws the sash and border. - - @remarks Does not currently check for an out-of-range value. - - @see GetSashPosition() - */ - void SetSashPosition(int position, const bool redraw = true); - - /** - Sets the sash size. Normally, the sash size is determined according to the - metrics - of each platform, but the application can override this, for example to show - a thin sash that the user is not expected to drag. If @a size is more -1, - the custom sash size will be used. - */ - void SetSashSize(int size); - - /** - Sets the split mode. - - @param mode - Can be wxSPLIT_VERTICAL or wxSPLIT_HORIZONTAL. - - @remarks Only sets the internal variable; does not update the display. - - @see GetSplitMode(), SplitVertically(), - SplitHorizontally(). - */ - void SetSplitMode(int mode); - - /** - Initializes the top and bottom panes of the splitter window. The - child windows are shown if they are currently hidden. - - @param window1 - The top pane. - @param window2 - The bottom pane. - @param sashPosition - The initial position of the sash. If this value is - positive, it specifies the size of the upper pane. If it is negative, its - absolute value gives the size of the lower pane. Finally, specify 0 - (default) - to choose the default position (half of the total window height). - - @return @true if successful, @false otherwise (the window was already - split). - - @remarks This should be called if you wish to initially view two panes. - It can also be called at any subsequent time, but the - application should check that the window is not - currently split using IsSplit. - - @see SplitVertically(), IsSplit(), - Unsplit() - */ - bool SplitHorizontally(wxWindow* window1, wxWindow* window2, - int sashPosition = 0); - - /** - Initializes the left and right panes of the splitter window. The - child windows are shown if they are currently hidden. - - @param window1 - The left pane. - @param window2 - The right pane. - @param sashPosition - The initial position of the sash. If this value is - positive, it specifies the size of the left pane. If it is negative, it is - absolute value gives the size of the right pane. Finally, specify 0 - (default) - to choose the default position (half of the total window width). - - @return @true if successful, @false otherwise (the window was already - split). - - @remarks This should be called if you wish to initially view two panes. - It can also be called at any subsequent time, but the - application should check that the window is not - currently split using IsSplit. - - @see SplitHorizontally(), IsSplit(), - Unsplit(). - */ - bool SplitVertically(wxWindow* window1, wxWindow* window2, - int sashPosition = 0); - - /** - Unsplits the window. - - @param toRemove - The pane to remove, or @NULL to remove the right or bottom pane. - - @return @true if successful, @false otherwise (the window was not split). - - @remarks This call will not actually delete the pane being removed; it - calls OnUnsplit which can be overridden for the desired - behaviour. By default, the pane being removed is hidden. - - @see SplitHorizontally(), SplitVertically(), - IsSplit(), OnUnsplit() - */ - bool Unsplit(wxWindow* toRemove = NULL); - - /** - Causes any pending sizing of the sash and child panes to take place - immediately. - Such resizing normally takes place in idle time, in order - to wait for layout to be completed. However, this can cause - unacceptable flicker as the panes are resized after the window has been - shown. To work around this, you can perform window layout (for - example by sending a size event to the parent window), and then - call this function, before showing the top-level window. - */ - void UpdateSize(); -}; - - - -/** - @class wxSplitterEvent - @wxheader{splitter.h} - - This class represents the events generated by a splitter control. Also there is - only one event class, the data associated to the different events is not the - same and so not all accessor functions may be called for each event. The - documentation mentions the kind of event(s) for which the given accessor - function makes sense: calling it for other types of events will result - in assert failure (in debug mode) and will return meaningless results. - - @library{wxcore} - @category{events} - - @see wxSplitterWindow, @ref overview_eventhandlingoverview -*/ -class wxSplitterEvent : public wxNotifyEvent -{ -public: - /** - Constructor. Used internally by wxWidgets only. - */ - wxSplitterEvent(wxEventType eventType = wxEVT_NULL, - wxSplitterWindow* splitter = NULL); - - /** - Returns the new sash position. - May only be called while processing - wxEVT_COMMAND_SPLITTER_SASH_POS_CHANGING and - wxEVT_COMMAND_SPLITTER_SASH_POS_CHANGED events. - */ - int GetSashPosition() const; - - /** - Returns a pointer to the window being removed when a splitter window - is unsplit. - May only be called while processing - wxEVT_COMMAND_SPLITTER_UNSPLIT events. - */ - wxWindow* GetWindowBeingRemoved() const; - - /** - Returns the x coordinate of the double-click point. - May only be called while processing - wxEVT_COMMAND_SPLITTER_DOUBLECLICKED events. - */ - int GetX() const; - - /** - Returns the y coordinate of the double-click point. - May only be called while processing - wxEVT_COMMAND_SPLITTER_DOUBLECLICKED events. - */ - int GetY() const; - - /** - In the case of wxEVT_COMMAND_SPLITTER_SASH_POS_CHANGED events, - sets the new sash position. In the case of - wxEVT_COMMAND_SPLITTER_SASH_POS_CHANGING events, sets the new - tracking bar position so visual feedback during dragging will - represent that change that will actually take place. Set to -1 from - the event handler code to prevent repositioning. - May only be called while processing - wxEVT_COMMAND_SPLITTER_SASH_POS_CHANGING and - wxEVT_COMMAND_SPLITTER_SASH_POS_CHANGED events. - - @param pos - New sash position. - */ - void SetSashPosition(int pos); -}; - diff --git a/interface/srchctrl.h b/interface/srchctrl.h deleted file mode 100644 index 348632ae3f..0000000000 --- a/interface/srchctrl.h +++ /dev/null @@ -1,130 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: srchctrl.h -// Purpose: interface of wxSearchCtrl -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxSearchCtrl - @wxheader{srchctrl.h} - - A search control is a composite control with a search button, a text - control, and a cancel button. - - @beginStyleTable - @style{wxTE_PROCESS_ENTER} - The control will generate the event wxEVT_COMMAND_TEXT_ENTER - (otherwise pressing Enter key is either processed internally by the - control or used for navigation between dialog controls). - @style{wxTE_PROCESS_TAB} - The control will receive wxEVT_CHAR events for TAB pressed - - normally, TAB is used for passing to the next control in a dialog - instead. For the control created with this style, you can still use - Ctrl-Enter to pass to the next control from the keyboard. - @style{wxTE_NOHIDESEL} - By default, the Windows text control doesn't show the selection - when it doesn't have focus - use this style to force it to always - show it. It doesn't do anything under other platforms. - @style{wxTE_LEFT} - The text in the control will be left-justified (default). - @style{wxTE_CENTRE} - The text in the control will be centered (currently wxMSW and - wxGTK2 only). - @style{wxTE_RIGHT} - The text in the control will be right-justified (currently wxMSW - and wxGTK2 only). - @style{wxTE_CAPITALIZE} - On PocketPC and Smartphone, causes the first letter to be - capitalized. - @endStyleTable - - @library{wxcore} - @category{FIXME} - - @see wxTextCtrl::Create, wxValidator -*/ -class wxSearchCtrl : public wxTextCtrl -{ -public: - /** - Default constructor - */ - wxSearchCtrl(); - - /** - Constructor, creating and showing a text control. - - @param parent - Parent window. Should not be @NULL. - @param id - Control identifier. A value of -1 denotes a default value. - @param value - Default text value. - @param pos - Text control position. - @param size - Text control size. - @param style - Window style. See wxSearchCtrl. - @param validator - Window validator. - @param name - Window name. - - @see wxTextCtrl::Create, wxValidator - */ - wxSearchCtrl(wxWindow* parent, wxWindowID id, - const wxString& value = "", - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = 0, - const wxValidator& validator = wxDefaultValidator, - const wxString& name = wxSearchCtrlNameStr); - - /** - Destructor, destroying the search control. - */ - ~wxSearchCtrl(); - - /** - Returns a pointer to the search control's menu object or @NULL if there is no - menu attached. - */ - virtual wxMenu* GetMenu(); - - /** - Returns the search button visibility value. - If there is a menu attached, the search button will be visible regardless of - the search - button visibility value. - This always returns @false in Mac OS X v10.3 - */ - virtual bool IsSearchButtonVisible(); - - /** - Sets the search control's menu object. If there is already a menu associated - with - the search control it is deleted. - - @param menu - Menu to attach to the search control. - */ - virtual void SetMenu(wxMenu* menu); - - /** - Shows or hides the cancel button. - */ - virtual void ShowCancelButton(bool show); - - /** - Sets the search button visibility value on the search control. - If there is a menu attached, the search button will be visible regardless of - the search - button visibility value. - This has no effect in Mac OS X v10.3 - */ - virtual void ShowSearchButton(bool show); -}; - diff --git a/interface/sstream.h b/interface/sstream.h deleted file mode 100644 index 9fb340b705..0000000000 --- a/interface/sstream.h +++ /dev/null @@ -1,72 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: sstream.h -// Purpose: interface of wxStringInputStream -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxStringInputStream - @wxheader{sstream.h} - - This class implements an input stream which reads data from a string. It - supports seeking. - - @library{wxbase} - @category{streams} -*/ -class wxStringInputStream : public wxInputStream -{ -public: - /** - Creates a new read-only stream using the specified string. Note that the string - is copied by the stream so if the original string is modified after using this - constructor, changes to it are not reflected when reading from stream. - */ - wxStringInputStream(const wxString& s); -}; - - - -/** - @class wxStringOutputStream - @wxheader{sstream.h} - - This class implements an output stream which writes data either to a - user-provided or internally allocated string. Note that currently this stream - does not support seeking but can tell its current position. - - @library{wxbase} - @category{streams} -*/ -class wxStringOutputStream : public wxOutputStream -{ -public: - /** - Construct a new stream object writing the data to a string. - - If the provided pointer is non-@NULL, data will be written to it. - Otherwise, an internal string is used for the data written to this - stream, use GetString() to get access to it. - - If @a str is used, data written to the stream is appended to the current - contents of it, i.e. the string is not cleared here. However if it is not - empty, the positions returned by wxOutputStream::TellO will be - offset by the initial string length, i.e. initial stream position will be the - initial length of the string and not 0. - - Notice that the life time of @a conv must be greater than the life time - of this object itself as it stores a reference to it. Also notice that - with default value of this argument the data written to the stream must - be valid UTF-8, pass @c wxConvISO8859_1 to deal with arbitrary 8 bit - data. - */ - wxStringOutputStream(wxString str = NULL, wxMBConv& conv = wxConvUTF8); - - /** - Returns the string containing all the data written to the stream so far. - */ - const wxString& GetString() const; -}; - diff --git a/interface/stackwalk.h b/interface/stackwalk.h deleted file mode 100644 index 782b5268e5..0000000000 --- a/interface/stackwalk.h +++ /dev/null @@ -1,169 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: stackwalk.h -// Purpose: interface of wxStackWalker -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxStackWalker - @wxheader{stackwalk.h} - - wxStackWalker allows an application to enumerate, or walk, the stack frames - (the function callstack). - It is mostly useful in only two situations: - inside wxApp::OnFatalException function to - programmatically get the location of the crash and, in debug builds, in - wxApp::OnAssertFailure to report the caller of the failed - assert. - - wxStackWalker works by repeatedly calling - the wxStackWalker::OnStackFrame method for each frame in the - stack, so to use it you must derive your own class from it and override this - method. - - This class will not return anything except raw stack frame addresses if the - debug information is not available. Under Win32 this means that the PDB file - matching the program being executed should be present. Note that if you use - Microsoft Visual C++ compiler, you can create PDB files even for the programs - built in release mode and it doesn't affect the program size (at least if you - don't forget to add @c /opt:ref option which is suppressed by using - @c /debug linker option by default but should be always enabled for - release builds). Under Unix, you need to compile your program with debugging - information (usually using @c -g compiler and linker options) to get the - file and line numbers information, however function names should be available - even without it. Of course, all this is only @true if you build using a recent - enough version of GNU libc which provides the @c backtrace() function - needed to walk the stack. - - @ref overview_debuggingoverview "debugging overview" for how to make it - available. - - @library{wxbase} - @category{FIXME} - - @see wxStackFrame -*/ -class wxStackWalker -{ -public: - /** - Constructor does nothing, use Walk() to walk the - stack. - */ - wxStackWalker(); - - /** - Destructor does nothing neither but should be virtual as this class is used as - a base one. - */ - ~wxStackWalker(); - - /** - This function must be overrided to process the given frame. - */ - void OnStackFrame(const wxStackFrame& frame); - - /** - Enumerate stack frames from the current location, skipping the initial - number of them (this can be useful when Walk() is called from some known - location and you don't want to see the first few frames anyhow; also - notice that Walk() frame itself is not included if skip = 1). - Up to @a maxDepth frames are walked from the innermost to the outermost one. - */ - void Walk(size_t skip = 1, size_t maxDepth = 200); - - /** - Enumerate stack frames from the location of uncaught exception. - This method can only be called from - wxApp::OnFatalException. - Up to @a maxDepth frames are walked from the innermost to the outermost one. - */ - void WalkFromException(size_t maxDepth = 200); -}; - - - -/** - @class wxStackFrame - @wxheader{stackwalk.h} - - wxStackFrame represents a single stack frame, or a single function in the call - stack, and is used exclusively together with - wxStackWalker, see there for a more detailed - discussion. - - @library{wxbase} - @category{FIXME} - - @see wxStackWalker -*/ -class wxStackFrame -{ -public: - /** - Return the address of this frame. - */ - void* GetAddress() const; - - /** - Return the name of the file containing this frame, empty if - unavailable (typically because debug info is missing). - Use HasSourceLocation() to check whether - the file name is available. - */ - wxString GetFileName() const; - - /** - Get the level of this frame (deepest/innermost one is 0). - */ - size_t GetLevel() const; - - /** - Return the line number of this frame, 0 if unavailable. - - @see GetFileName() - */ - size_t GetLine() const; - - /** - Get the module this function belongs to (empty if not available). - */ - wxString GetModule() const; - - /** - Return the unmangled (if possible) name of the function containing this - frame. - */ - wxString GetName() const; - - /** - Return the return address of this frame. - */ - size_t GetOffset() const; - - /** - Get the name, type and value (in text form) of the given parameter. - Any pointer may be @NULL if you're not interested in the corresponding - value. - Return @true if at least some values could be retrieved. - This function currently is only implemented under Win32 and requires a PDB - file. - */ - bool GetParam(size_t n, wxString* type, wxString* name, - wxString* value) const; - - /** - Return the number of parameters of this function (may return 0 if we - can't retrieve the parameters info even although the function does have - parameters). - */ - size_t GetParamCount() const; - - /** - Return @true if we have the file name and line number for this frame. - */ - bool HasSourceLocation() const; -}; - diff --git a/interface/statbmp.h b/interface/statbmp.h deleted file mode 100644 index d18ff1fe39..0000000000 --- a/interface/statbmp.h +++ /dev/null @@ -1,107 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: statbmp.h -// Purpose: interface of wxStaticBitmap -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxStaticBitmap - @wxheader{statbmp.h} - - A static bitmap control displays a bitmap. Native implementations on some - platforms are only meant for display of the small icons in the dialog - boxes. In particular, under Windows 9x the size of bitmap is limited - to 64*64 pixels. - If you want to display larger images portably, you may use generic - implementation wxGenericStaticBitmap declared in . - - @library{wxcore} - @category{ctrl} - - - @see wxStaticBitmap, wxStaticBox -*/ -class wxStaticBitmap : public wxControl -{ -public: - /** - Default constructor - */ - wxStaticBitmap(); - - /** - Constructor, creating and showing a static bitmap control. - - @param parent - Parent window. Should not be @NULL. - @param id - Control identifier. A value of -1 denotes a default value. - @param label - Bitmap label. - @param pos - Window position. - @param size - Window size. - @param style - Window style. See wxStaticBitmap. - @param name - Window name. - - @see Create() - */ - wxStaticBitmap(wxWindow* parent, wxWindowID id, - const wxBitmap& label, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = 0, - const wxString& name = "staticBitmap"); - - /** - Creation function, for two-step construction. For details see wxStaticBitmap(). - */ - bool Create(wxWindow* parent, wxWindowID id, - const wxBitmap& label, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = 0, - const wxString& name = "staticBitmap"); - - /** - Returns the bitmap currently used in the control. Notice that this method can - be called even if SetIcon() had been used. - - @see SetBitmap() - */ - wxBitmap GetBitmap() const; - - /** - Returns the icon currently used in the control. Notice that this method can - only be called if SetIcon() had been used: an icon - can't be retrieved from the control if a bitmap had been set (using - wxStaticBitmap::SetBitmap). - - @see SetIcon() - */ - wxIcon GetIcon() const; - - /** - Sets the bitmap label. - - @param label - The new bitmap. - - @see GetBitmap() - */ - virtual void SetBitmap(const wxBitmap& label); - - /** - Sets the label to the given icon. - - @param label - The new icon. - */ - virtual void SetIcon(const wxIcon& label); -}; - diff --git a/interface/statbox.h b/interface/statbox.h deleted file mode 100644 index b6719749cb..0000000000 --- a/interface/statbox.h +++ /dev/null @@ -1,85 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: statbox.h -// Purpose: interface of wxStaticBox -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxStaticBox - @wxheader{statbox.h} - - A static box is a rectangle drawn around other panel items to denote - a logical grouping of items. - - Please note that a static box should @b not be used as the parent for the - controls it contains, instead they should be siblings of each other. Although - using a static box as a parent might work in some versions of wxWidgets, it - results in a crash under, for example, wxGTK. - - Also, please note that because of this, the order in which you create new - controls is important. Create your wxStaticBox control @b before any - siblings that are to appear inside the wxStaticBox in order to preserve the - correct Z-Order of controls. - - @library{wxcore} - @category{ctrl} - - - @see wxStaticText -*/ -class wxStaticBox : public wxControl -{ -public: - /** - Default constructor - */ - wxStaticBox(); - - /** - Constructor, creating and showing a static box. - - @param parent - Parent window. Must not be @NULL. - @param id - Window identifier. The value wxID_ANY indicates a default value. - @param label - Text to be displayed in the static box, the empty string for no label. - @param pos - Window position. If wxDefaultPosition is specified then a default - position is chosen. - @param size - Checkbox size. If the size (-1, -1) is specified then a default size is - chosen. - @param style - Window style. See wxStaticBox. - @param name - Window name. - - @see Create() - */ - wxStaticBox(wxWindow* parent, wxWindowID id, - const wxString& label, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = 0, - const wxString& name = "staticBox"); - - /** - Destructor, destroying the group box. - */ - ~wxStaticBox(); - - /** - Creates the static box for two-step construction. See wxStaticBox() - for further details. - */ - bool Create(wxWindow* parent, wxWindowID id, - const wxString& label, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = 0, - const wxString& name = "staticBox"); -}; - diff --git a/interface/statline.h b/interface/statline.h deleted file mode 100644 index 226f28a70a..0000000000 --- a/interface/statline.h +++ /dev/null @@ -1,84 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: statline.h -// Purpose: interface of wxStaticLine -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxStaticLine - @wxheader{statline.h} - - A static line is just a line which may be used in a dialog to separate the - groups of controls. The line may be only vertical or horizontal. - - @beginStyleTable - @style{wxLI_HORIZONTAL} - Creates a horizontal line. - @style{wxLI_VERTICAL} - Creates a vertical line. - @endStyleTable - - @library{wxcore} - @category{FIXME} - - @see wxStaticBox -*/ -class wxStaticLine : public wxControl -{ -public: - /** - Default constructor - */ - wxStaticLine(); - - /** - Constructor, creating and showing a static line. - - @param parent - Parent window. Must not be @NULL. - @param id - Window identifier. The value wxID_ANY indicates a default value. - @param pos - Window position. If wxDefaultPosition is specified then a default - position is chosen. - @param size - Size. Note that either the height or the width (depending on - whether the line if horizontal or vertical) is ignored. - @param style - Window style (either wxLI_HORIZONTAL or wxLI_VERTICAL). - @param name - Window name. - - @see Create() - */ - wxStaticLine(wxWindow* parent, wxWindowID id = wxID_ANY, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = wxLI_HORIZONTAL, - const wxString& name = "staticLine"); - - /** - Creates the static line for two-step construction. See wxStaticLine() - for further details. - */ - bool Create(wxWindow* parent, wxWindowID id = wxID_ANY, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = 0, - const wxString& name = "staticLine"); - - /** - This static function returns the size which will be given to the smaller - dimension of the static line, i.e. its height for a horizontal line or its - width for a vertical one. - */ - int GetDefaultSize(); - - /** - Returns @true if the line is vertical, @false if horizontal. - */ - bool IsVertical() const; -}; - diff --git a/interface/stattext.h b/interface/stattext.h deleted file mode 100644 index ee65c9cdc6..0000000000 --- a/interface/stattext.h +++ /dev/null @@ -1,214 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: stattext.h -// Purpose: interface of wxStaticText -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxStaticText - @wxheader{stattext.h} - - A static text control displays one or more lines of read-only text. - - @beginStyleTable - @style{wxALIGN_LEFT} - Align the text to the left - @style{wxALIGN_RIGHT} - Align the text to the right - @style{wxALIGN_CENTRE} - Center the text (horizontally) - @style{wxST_NO_AUTORESIZE} - By default, the control will adjust its size to exactly fit to the - size of the text when SetLabel is called. If this style flag is - given, the control will not change its size (this style is - especially useful with controls which also have wxALIGN_RIGHT or - CENTER style because otherwise they won't make sense any longer - after a call to SetLabel) - @style{wxST_ELLIPSIZE_START} - If the text width exceeds the control width, replace the beginning - of the text with an ellipsis - @style{wxST_ELLIPSIZE_MIDDLE} - Same as above, but replace the text in the middle of the control - with an ellipsis - @style{wxST_ELLIPSIZE_END} - Same as above, but replace the end of the text with an ellipsis - @style{wxST_MARKUP} - Support markup in the label; see SetLabel for more information - @endStyleTable - - @library{wxcore} - @category{ctrl} - - - @see wxStaticBitmap, wxStaticBox -*/ -class wxStaticText : public wxControl -{ -public: - /** - Default constructor. - */ - wxStaticText(); - - /** - Constructor, creating and showing a text control. - - @param parent - Parent window. Should not be @NULL. - @param id - Control identifier. A value of -1 denotes a default value. - @param label - Text label. - @param pos - Window position. - @param size - Window size. - @param style - Window style. See wxStaticText. - @param name - Window name. - - @see Create() - */ - wxStaticText(wxWindow* parent, wxWindowID id, - const wxString& label, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = 0, - const wxString& name = "staticText"); - - /** - Creation function, for two-step construction. For details see wxStaticText(). - */ - bool Create(wxWindow* parent, wxWindowID id, - const wxString& label, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = 0, - const wxString& name = "staticText"); - - /** - Returns the contents of the control. - Note that the returned string contains both the mnemonics (@c characters), - if any, and markup tags, if any. - Use GetLabelText() if only the - label text is needed. - */ - wxString GetLabel() const; - - //@{ - /** - The first form returns the control's label without the mnemonics characters (if - any) - and without the markup (if the control has @c wxST_MARKUP style). - The second (static) version returns the given @a label string without the - mnemonics - characters (if any) and without the markup. - */ - wxString GetLabelText(); - const static wxString GetLabelText(const wxString& label); - //@} - - /** - Sets the static text label and updates the controls size to exactly fit the - label unless the control has wxST_NO_AUTORESIZE flag. - This function allows to set decorated static label text on platforms which - support it (currently only GTK+ 2). For the other platforms, the markup is - ignored. - The supported tags are: - - b - - bold text - - big - - bigger text - - i - - italic text - - s - - strike-through text - - sub - - subscript text - - sup - - superscript text - - small - - smaller text - - tt - - monospaced text - - u - - underlined text - - span - - generic formatter tag; see Pango Markup for more information. - - Note that the string must be well-formed (e.g. all tags must be correctly - closed) - otherwise it can be not shown correctly or at all. - Also note that you need to escape the following special characters: - - @b Special character - - @b Escape as - - @c - - @c amp; or as @c - - @c ' - - @c apos; - - @c " - - @c quot; - - @c - - @c lt; - - @c - - @c gt; - - The non-escaped ampersand @c characters are interpreted as - mnemonics; see wxControl::SetLabel. - - Example: - - @param label - The new label to set. It may contain newline characters and the markup tags - described above. - */ - virtual void SetLabel(const wxString& label); - - /** - This functions wraps the controls label so that each of its lines becomes at - most @a width pixels wide if possible (the lines are broken at words - boundaries so it might not be the case if words are too long). If @e width - is negative, no wrapping is done. Note that this width is not - necessarily the total width of the control, since a few pixels for the - border (depending on the controls border style) may be added. - - @since 2.6.2 - */ - void Wrap(int width); -}; - diff --git a/interface/statusbr.h b/interface/statusbr.h deleted file mode 100644 index 2d4ca10da5..0000000000 --- a/interface/statusbr.h +++ /dev/null @@ -1,233 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: statusbr.h -// Purpose: interface of wxStatusBar -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxStatusBar - @wxheader{statusbr.h} - - A status bar is a narrow window that can be placed along the bottom of a frame - to give - small amounts of status information. It can contain one or more fields, one or - more of which can - be variable length according to the size of the window. - - wxWindow - - wxEvtHandler - - wxObject - - @beginStyleTable - @style{wxST_SIZEGRIP} - On Windows 95, displays a gripper at right-hand side of the status - bar. - @endStyleTable - - @library{wxcore} - @category{miscwnd} - - @see wxFrame, @ref overview_samplestatbar "Status bar sample" -*/ -class wxStatusBar : public wxWindow -{ -public: - //@{ - /** - Constructor, creating the window. - - @param parent - The window parent, usually a frame. - @param id - The window identifier. It may take a value of -1 to indicate a default - value. - @param style - The window style. See wxStatusBar. - @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 - individual windows. - - @see Create() - */ - wxStatusBar(); - wxStatusBar(wxWindow* parent, wxWindowID id = wxID_ANY, - long style = wxST_SIZEGRIP, - const wxString& name = "statusBar"); - //@} - - /** - Destructor. - */ - ~wxStatusBar(); - - /** - Creates the window, for two-step construction. - See wxStatusBar() for details. - */ - bool Create(wxWindow* parent, wxWindowID id = wxID_ANY, - long style = wxST_SIZEGRIP, - const wxString& name = "statusBar"); - - /** - Returns the size and position of a field's internal bounding rectangle. - - @param i - The field in question. - @param rect - The rectangle values are placed in this variable. - - @return @true if the field index is valid, @false otherwise. - - @see wxRect - */ - virtual bool GetFieldRect(int i, wxRect& rect) const; - - /** - Returns the number of fields in the status bar. - */ - int GetFieldsCount() const; - - /** - Returns the string associated with a status bar field. - - @param i - The number of the status field to retrieve, starting from zero. - - @return The status field string if the field is valid, otherwise the - empty string. - - @see SetStatusText() - */ - virtual wxString GetStatusText(int i = 0) const; - - /** - Sets the field text to the top of the stack, and pops the stack of saved - strings. - - @see PushStatusText() - */ - void PopStatusText(int field = 0); - - /** - Saves the current field text in a per field stack, and sets the field text - to the string passed as argument. - */ - void PushStatusText(const wxString& string, int field = 0); - - /** - Sets the number of fields, and optionally the field widths. - - @param number - The number of fields. - @param widths - An array of n integers interpreted in the same way as - in SetStatusWidths - */ - virtual void SetFieldsCount(int number = 1, int* widths = NULL); - - /** - Sets the minimal possible height for the status bar. The real height may be - bigger than the height specified here depending on the size of the font used by - the status bar. - */ - void SetMinHeight(int height); - - /** - Sets the styles of the fields in the status line which can make fields appear - flat - or raised instead of the standard sunken 3D border. - - @param n - The number of fields in the status bar. Must be equal to the - number passed to SetFieldsCount the last - time it was called. - @param styles - Contains an array of n integers with the styles for each field. There - are three possible styles: - - - - - - - - wxSB_NORMAL - - - - - (default) The field appears sunken with a standard 3D border. - - - - - - wxSB_FLAT - - - - - No border is painted around the field so that it appears flat. - - - - - - wxSB_RAISED - - - - - A raised 3D border is painted around the field. - */ - virtual void SetStatusStyles(int n, int* styles); - - /** - Sets the text for one field. - - @param text - The text to be set. Use an empty string ("") to clear the field. - @param i - The field to set, starting from zero. - - @see GetStatusText(), wxFrame::SetStatusText - */ - virtual void SetStatusText(const wxString& text, int i = 0); - - /** - Sets the widths of the fields in the status line. There are two types of - fields: fixed widths one and variable width fields. For the fixed width fields - you should specify their (constant) width in pixels. For the variable width - fields, specify a negative number which indicates how the field should expand: - the space left for all variable width fields is divided between them according - to the absolute value of this number. A variable width field with width of -2 - gets twice as much of it as a field with width -1 and so on. - For example, to create one fixed width field of width 100 in the right part of - the status bar and two more fields which get 66% and 33% of the remaining - space correspondingly, you should use an array containing -2, -1 and 100. - - @param n - The number of fields in the status bar. Must be equal to the - number passed to SetFieldsCount the last - time it was called. - @param widths - Contains an array of n integers, each of which is - either an absolute status field width in pixels if positive or indicates a - variable width field if negative. - - @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. - - @see SetFieldsCount(), wxFrame::SetStatusWidths - */ - virtual void SetStatusWidths(int n, int* widths); -}; - diff --git a/interface/stc/stc.h b/interface/stc/stc.h deleted file mode 100644 index 53f286e8f4..0000000000 --- a/interface/stc/stc.h +++ /dev/null @@ -1,2746 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: stc/stc.h -// Purpose: interface of wxStyledTextEvent -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxStyledTextEvent - @headerfile stc.h wx/stc/stc.h - - The type of events sent from wxStyledTextCtrl. - - TODO - - @library{wxbase} - @category{FIXME} -*/ -class wxStyledTextEvent : public wxCommandEvent -{ -public: - //@{ - /** - - */ - wxStyledTextEvent(wxEventType commandType = 0, int id = 0); - wxStyledTextEvent(const wxStyledTextEvent& event); - //@} - - /** - - */ - wxEvent* Clone() const; - - /** - - */ - bool GetAlt() const; - - /** - - */ - bool GetControl() const; - - /** - - */ - bool GetDragAllowMove(); - - /** - - */ - wxDragResult GetDragResult(); - - /** - - */ - wxString GetDragText(); - - /** - - */ - int GetFoldLevelNow() const; - - /** - - */ - int GetFoldLevelPrev() const; - - /** - - */ - int GetKey() const; - - /** - - */ - int GetLParam() const; - - /** - - */ - int GetLength() const; - - /** - - */ - int GetLine() const; - - /** - - */ - int GetLinesAdded() const; - - /** - - */ - int GetListType() const; - - /** - - */ - int GetMargin() const; - - /** - - */ - int GetMessage() const; - - /** - - */ - int GetModificationType() const; - - /** - - */ - int GetModifiers() const; - - /** - - */ - int GetPosition() const; - - /** - - */ - bool GetShift() const; - - /** - - */ - wxString GetText() const; - - /** - - */ - int GetWParam() const; - - /** - - */ - int GetX() const; - - /** - - */ - int GetY() const; - - /** - - */ - void SetDragAllowMove(bool val); - - /** - - */ - void SetDragResult(wxDragResult val); - - /** - - */ - void SetDragText(const wxString& val); - - /** - - */ - void SetFoldLevelNow(int val); - - /** - - */ - void SetFoldLevelPrev(int val); - - /** - - */ - void SetKey(int k); - - /** - - */ - void SetLParam(int val); - - /** - - */ - void SetLength(int len); - - /** - - */ - void SetLine(int val); - - /** - - */ - void SetLinesAdded(int num); - - /** - - */ - void SetListType(int val); - - /** - - */ - void SetMargin(int val); - - /** - - */ - void SetMessage(int val); - - /** - - */ - void SetModificationType(int t); - - /** - - */ - void SetModifiers(int m); - - /** - - */ - void SetPosition(int pos); - - /** - - */ - void SetText(const wxString& t); - - /** - - */ - void SetWParam(int val); - - /** - - */ - void SetX(int val); - - /** - - */ - void SetY(int val); -}; - - - -/** - @class wxStyledTextCtrl - @headerfile stc.h wx/stc/stc.h - - A wxWidgets implementation of the Scintilla source code editing component. - - As well as features found in standard text editing components, Scintilla - includes - features especially useful when editing and debugging source code. These - include - support for syntax styling, error indicators, code completion and call tips. - The - selection margin can contain markers like those used in debuggers to indicate - breakpoints and the current line. Styling choices are more open than with many - editors, allowing the use of proportional fonts, bold and italics, multiple - foreground and background colours and multiple fonts. - - wxStyledTextCtrl is a 1 to 1 mapping of "raw" scintilla interface, whose - documentation - can be found in the Scintilla website. - - @library{wxbase} - @category{stc} - - @see wxStyledTextEvent -*/ -class wxStyledTextCtrl : public wxControl -{ -public: - /** - Ctor. - */ - wxStyledTextCtrl::wxStyledTextCtrl(wxWindow* parent, - wxWindowID id = wxID_ANY, - const wxPoint pos = wxDefaultPosition, - const wxSize size = wxDefaultSize, - long style = 0, - const wxString name = "stcwindow"); - - /** - Extend life of document. - */ - void AddRefDocument(void* docPointer); - - /** - Add array of cells to document. - */ - void AddStyledText(const wxMemoryBuffer& data); - - /** - BEGIN generated section. The following code is automatically generated - by gen_iface.py. Do not edit this file. Edit stc.h.in instead - and regenerate - Add text to the document at current position. - */ - void AddText(const wxString& text); - - /** - The following methods are nearly equivallent to their similarly named - cousins above. The difference is that these methods bypass wxString - and always use a char* even if used in a unicode build of wxWidgets. - In that case the character data will be utf-8 encoded since that is - what is used internally by Scintilla in unicode builds. - Add text to the document at current position. - */ - void AddTextRaw(const char* text); - - /** - Enlarge the document to a particular size of text bytes. - */ - void Allocate(int bytes); - - /** - Append a string to the end of the document without changing the selection. - */ - void AppendText(const wxString& text); - - /** - Append a string to the end of the document without changing the selection. - */ - void AppendTextRaw(const char* text); - - /** - Is there an auto-completion list visible? - */ - bool AutoCompActive(); - - /** - Remove the auto-completion list from the screen. - */ - void AutoCompCancel(); - - /** - User has selected an item so remove the list and insert the selection. - */ - void AutoCompComplete(); - - /** - Retrieve whether or not autocompletion is hidden automatically when nothing - matches. - */ - bool AutoCompGetAutoHide(); - - /** - Retrieve whether auto-completion cancelled by backspacing before start. - */ - bool AutoCompGetCancelAtStart(); - - /** - Retrieve whether a single item auto-completion list automatically choose the - item. - */ - bool AutoCompGetChooseSingle(); - - /** - Get currently selected item position in the auto-completion list - */ - int AutoCompGetCurrent(); - - /** - Retrieve whether or not autocompletion deletes any word characters - after the inserted text upon completion. - */ - bool AutoCompGetDropRestOfWord(); - - /** - Retrieve state of ignore case flag. - */ - bool AutoCompGetIgnoreCase(); - - /** - Set the maximum height, in rows, of auto-completion and user lists. - */ - int AutoCompGetMaxHeight(); - - /** - Get the maximum width, in characters, of auto-completion and user lists. - */ - int AutoCompGetMaxWidth(); - - /** - Retrieve the auto-completion list separator character. - */ - int AutoCompGetSeparator(); - - /** - Retrieve the auto-completion list type-separator character. - */ - int AutoCompGetTypeSeparator(); - - /** - Retrieve the position of the caret when the auto-completion list was displayed. - */ - int AutoCompPosStart(); - - /** - Select the item in the auto-completion list that starts with a string. - */ - void AutoCompSelect(const wxString& text); - - /** - Set whether or not autocompletion is hidden automatically when nothing matches. - */ - void AutoCompSetAutoHide(bool autoHide); - - /** - Should the auto-completion list be cancelled if the user backspaces to a - position before where the box was created. - */ - void AutoCompSetCancelAtStart(bool cancel); - - /** - Should a single item auto-completion list automatically choose the item. - */ - void AutoCompSetChooseSingle(bool chooseSingle); - - /** - Set whether or not autocompletion deletes any word characters - after the inserted text upon completion. - */ - void AutoCompSetDropRestOfWord(bool dropRestOfWord); - - /** - Define a set of characters that when typed will cause the autocompletion to - choose the selected item. - */ - void AutoCompSetFillUps(const wxString& characterSet); - - /** - Set whether case is significant when performing auto-completion searches. - */ - void AutoCompSetIgnoreCase(bool ignoreCase); - - /** - Set the maximum height, in rows, of auto-completion and user lists. - The default is 5 rows. - */ - void AutoCompSetMaxHeight(int rowCount); - - /** - Set the maximum width, in characters, of auto-completion and user lists. - Set to 0 to autosize to fit longest item, which is the default. - */ - void AutoCompSetMaxWidth(int characterCount); - - /** - Change the separator character in the string setting up an auto-completion list. - Default is space but can be changed if items contain space. - */ - void AutoCompSetSeparator(int separatorCharacter); - - /** - Change the type-separator character in the string setting up an auto-completion - list. - Default is '?' but can be changed if items contain '?'. - */ - void AutoCompSetTypeSeparator(int separatorCharacter); - - /** - Display a auto-completion list. - The lenEntered parameter indicates how many characters before - the caret should be used to provide context. - */ - void AutoCompShow(int lenEntered, const wxString& itemList); - - /** - Define a set of character that when typed cancel the auto-completion list. - */ - void AutoCompStops(const wxString& characterSet); - - /** - Dedent the selected lines. - */ - void BackTab(); - - /** - Start a sequence of actions that is undone and redone as a unit. - May be nested. - */ - void BeginUndoAction(); - - /** - Highlight the character at a position indicating there is no matching brace. - */ - void BraceBadLight(int pos); - - /** - Highlight the characters at two positions. - */ - void BraceHighlight(int pos1, int pos2); - - /** - Find the position of a matching brace or INVALID_POSITION if no match. - */ - int BraceMatch(int pos); - - /** - Is there an active call tip? - */ - bool CallTipActive(); - - /** - Remove the call tip from the screen. - */ - void CallTipCancel(); - - /** - Retrieve the position where the caret was before displaying the call tip. - */ - int CallTipPosAtStart(); - - /** - Set the background colour for the call tip. - */ - void CallTipSetBackground(const wxColour& back); - - /** - Set the foreground colour for the call tip. - */ - void CallTipSetForeground(const wxColour& fore); - - /** - Set the foreground colour for the highlighted part of the call tip. - */ - void CallTipSetForegroundHighlight(const wxColour& fore); - - /** - Highlight a segment of the definition. - */ - void CallTipSetHighlight(int start, int end); - - /** - Show a call tip containing a definition near position pos. - */ - void CallTipShow(int pos, const wxString& definition); - - /** - Enable use of STYLE_CALLTIP and set call tip tab size in pixels. - */ - void CallTipUseStyle(int tabSize); - - /** - Will a paste succeed? - */ - bool CanPaste(); - - /** - Are there any redoable actions in the undo history? - */ - bool CanRedo(); - - /** - Are there any undoable actions in the undo history? - */ - bool CanUndo(); - - /** - Cancel any modes such as call tip or auto-completion list display. - */ - void Cancel(); - - /** - Move caret left one character. - */ - void CharLeft(); - - /** - Move caret left one character extending selection to new caret position. - */ - void CharLeftExtend(); - - /** - Move caret left one character, extending rectangular selection to new caret - position. - */ - void CharLeftRectExtend(); - - /** - Move caret right one character. - */ - void CharRight(); - - /** - Move caret right one character extending selection to new caret position. - */ - void CharRightExtend(); - - /** - Move caret right one character, extending rectangular selection to new caret - position. - */ - void CharRightRectExtend(); - - /** - Set the last x chosen value to be the caret x position. - */ - void ChooseCaretX(); - - /** - Clear the selection. - */ - void Clear(); - - /** - Delete all text in the document. - */ - void ClearAll(); - - /** - Set all style bytes to 0, remove all folding information. - */ - void ClearDocumentStyle(); - - /** - Clear all the registered images. - */ - void ClearRegisteredImages(); - - /** - When key+modifier combination km is pressed perform msg. - */ - void CmdKeyAssign(int key, int modifiers, int cmd); - - /** - When key+modifier combination km is pressed do nothing. - */ - void CmdKeyClear(int key, int modifiers); - - /** - Drop all key mappings. - */ - void CmdKeyClearAll(); - - /** - Perform one of the operations defined by the wxSTC_CMD_* constants. - */ - void CmdKeyExecute(int cmd); - - /** - Colourise a segment of the document using the current lexing language. - */ - void Colourise(int start, int end); - - /** - Convert all line endings in the document to one mode. - */ - void ConvertEOLs(int eolMode); - - /** - Copy the selection to the clipboard. - */ - void Copy(); - - /** - Copy a range of text to the clipboard. Positions are clipped into the document. - */ - void CopyRange(int start, int end); - - /** - Copy argument text to the clipboard. - */ - void CopyText(int length, const wxString& text); - - /** - - */ - bool Create(wxWindow* parent, wxWindowID id = wxID_ANY, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = 0, - const wxString& name = wxSTCNameStr); - - /** - Create a new document object. - Starts with reference count of 1 and not selected into editor. - */ - void* CreateDocument(); - - /** - Cut the selection to the clipboard. - */ - void Cut(); - - /** - Delete back from the current position to the start of the line. - */ - void DelLineLeft(); - - /** - Delete forwards from the current position to the end of the line. - */ - void DelLineRight(); - - /** - Delete the word to the left of the caret. - */ - void DelWordLeft(); - - /** - Delete the word to the right of the caret. - */ - void DelWordRight(); - - /** - Delete the selection or if no selection, the character before the caret. - */ - void DeleteBack(); - - /** - Delete the selection or if no selection, the character before the caret. - Will not delete the character before at the start of a line. - */ - void DeleteBackNotLine(); - - /** - Allow for simulating a DnD DragOver - */ - wxDragResult DoDragOver(wxCoord x, wxCoord y, wxDragResult def); - - /** - Allow for simulating a DnD DropText - */ - bool DoDropText(long x, long y, const wxString& data); - - /** - Find the document line of a display line taking hidden lines into account. - */ - int DocLineFromVisible(int lineDisplay); - - /** - Move caret to last position in document. - */ - void DocumentEnd(); - - /** - Move caret to last position in document extending selection to new caret - position. - */ - void DocumentEndExtend(); - - /** - Move caret to first position in document. - */ - void DocumentStart(); - - /** - Move caret to first position in document extending selection to new caret - position. - */ - void DocumentStartExtend(); - - /** - Switch from insert to overtype mode or the reverse. - */ - void EditToggleOvertype(); - - /** - Delete the undo history. - */ - void EmptyUndoBuffer(); - - /** - End a sequence of actions that is undone and redone as a unit. - */ - void EndUndoAction(); - - /** - Ensure the caret is visible. - */ - void EnsureCaretVisible(); - - /** - Ensure a particular line is visible by expanding any header line hiding it. - */ - void EnsureVisible(int line); - - /** - Ensure a particular line is visible by expanding any header line hiding it. - Use the currently set visibility policy to determine which range to display. - */ - void EnsureVisibleEnforcePolicy(int line); - - /** - Find the position of a column on a line taking into account tabs and - multi-byte characters. If beyond end of line, return line end position. - */ - int FindColumn(int line, int column); - - /** - Find some text in the document. - */ - int FindText(int minPos, int maxPos, const wxString& text, - int flags = 0); - - /** - Insert a Form Feed character. - */ - void FormFeed(); - - /** - On Windows, will draw the document into a display context such as a printer. - */ - int FormatRange(bool doDraw, int startPos, int endPos, - wxDC* draw, wxDC* target, - wxRect renderRect, - wxRect pageRect); - - /** - Returns the position of the opposite end of the selection to the caret. - */ - int GetAnchor(); - - /** - Does a backspace pressed when caret is within indentation unindent? - */ - bool GetBackSpaceUnIndents(); - - /** - Is drawing done first into a buffer or direct to the screen? - */ - bool GetBufferedDraw(); - - /** - Get the foreground colour of the caret. - */ - wxColour GetCaretForeground(); - - /** - Get the background alpha of the caret line. - */ - int GetCaretLineBackAlpha(); - - /** - Get the colour of the background of the line containing the caret. - */ - wxColour GetCaretLineBackground(); - - /** - Is the background of the line containing the caret in a different colour? - */ - bool GetCaretLineVisible(); - - /** - Get the time in milliseconds that the caret is on and off. - */ - int GetCaretPeriod(); - - /** - Can the caret preferred x position only be changed by explicit movement - commands? - */ - bool GetCaretSticky(); - - /** - Returns the width of the insert mode caret. - */ - int GetCaretWidth(); - - /** - Returns the character byte at the position. - */ - int GetCharAt(int pos); - - /** - Get the code page used to interpret the bytes of the document as characters. - */ - int GetCodePage(); - - /** - Retrieve the column number of a position, taking tab width into account. - */ - int GetColumn(int pos); - - /** - Get the way control characters are displayed. - */ - int GetControlCharSymbol(); - - /** - - */ - wxString GetCurLine(int* OUTPUT); - - /** - - */ - wxCharBuffer GetCurLineRaw(int* OUTPUT); - - /** - END of generated section - Others... - Returns the line number of the line with the caret. - */ - int GetCurrentLine(); - - /** - Returns the position of the caret. - */ - int GetCurrentPos(); - - /** - Retrieve a pointer to the document object. - */ - void* GetDocPointer(); - - /** - Retrieve the current end of line mode - one of CRLF, CR, or LF. - */ - int GetEOLMode(); - - /** - Retrieve the colour used in edge indication. - */ - wxColour GetEdgeColour(); - - /** - Retrieve the column number which text should be kept within. - */ - int GetEdgeColumn(); - - /** - Retrieve the edge highlight mode. - */ - int GetEdgeMode(); - - /** - Retrieve whether the maximum scroll position has the last - line at the bottom of the view. - */ - bool GetEndAtLastLine(); - - /** - Retrieve the position of the last correctly styled character. - */ - int GetEndStyled(); - - /** - Retrieve the display line at the top of the display. - */ - int GetFirstVisibleLine(); - - /** - Is a header line expanded? - */ - bool GetFoldExpanded(int line); - - /** - Retrieve the fold level of a line. - */ - int GetFoldLevel(int line); - - /** - Find the parent line of a child line. - */ - int GetFoldParent(int line); - - /** - Get the highlighted indentation guide column. - */ - int GetHighlightGuide(); - - /** - Retrieve indentation size. - */ - int GetIndent(); - - /** - Are the indentation guides visible? - */ - bool GetIndentationGuides(); - - /** - Find the last child line of a header line. - */ - int GetLastChild(int line, int level); - - /** - Can be used to prevent the EVT_CHAR handler from adding the char - */ - bool GetLastKeydownProcessed(); - - /** - Retrieve the degree of caching of layout information. - */ - int GetLayoutCache(); - - /** - Returns the number of characters in the document. - */ - int GetLength(); - - /** - Retrieve the lexing language of the document. - */ - int GetLexer(); - - /** - Retrieve the contents of a line. - */ - wxString GetLine(int line); - - /** - Returns the number of lines in the document. There is always at least one. - */ - int GetLineCount(); - - /** - Get the position after the last visible characters on a line. - */ - int GetLineEndPosition(int line); - - /** - Retrieve the position before the first non indentation character on a line. - */ - int GetLineIndentPosition(int line); - - /** - Retrieve the number of columns that a line is indented. - */ - int GetLineIndentation(int line); - - /** - Retrieve the contents of a line. - */ - wxCharBuffer GetLineRaw(int line); - - /** - Retrieve the position of the end of the selection at the given line - (INVALID_POSITION if no selection on this line). - */ - int GetLineSelEndPosition(int line); - - /** - Retrieve the position of the start of the selection at the given line - (INVALID_POSITION if no selection on this line). - */ - int GetLineSelStartPosition(int line); - - /** - Retrieve the extra styling information for a line. - */ - int GetLineState(int line); - - /** - Is a line visible? - */ - bool GetLineVisible(int line); - - /** - Returns the size in pixels of the left margin. - */ - int GetMarginLeft(); - - /** - Retrieve the marker mask of a margin. - */ - int GetMarginMask(int margin); - - /** - Returns the size in pixels of the right margin. - */ - int GetMarginRight(); - - /** - Retrieve the mouse click sensitivity of a margin. - */ - bool GetMarginSensitive(int margin); - - /** - Retrieve the type of a margin. - */ - int GetMarginType(int margin); - - /** - Retrieve the width of a margin in pixels. - */ - int GetMarginWidth(int margin); - - /** - Retrieve the last line number that has line state. - */ - int GetMaxLineState(); - - /** - Get which document modification events are sent to the container. - */ - int GetModEventMask(); - - /** - Is the document different from when it was last saved? - */ - bool GetModify(); - - /** - Get whether mouse gets captured. - */ - bool GetMouseDownCaptures(); - - /** - Retrieve the time the mouse must sit still to generate a mouse dwell event. - */ - int GetMouseDwellTime(); - - /** - Returns @true if overtype mode is active otherwise @false is returned. - */ - bool GetOvertype(); - - /** - Get convert-on-paste setting - */ - bool GetPasteConvertEndings(); - - /** - Returns the print colour mode. - */ - int GetPrintColourMode(); - - /** - Returns the print magnification. - */ - int GetPrintMagnification(); - - /** - Is printing line wrapped? - */ - int GetPrintWrapMode(); - - /** - Retrieve a 'property' value previously set with SetProperty. - */ - wxString GetProperty(const wxString& key); - - /** - Retrieve a 'property' value previously set with SetProperty, - with '$()' variable replacement on returned buffer. - */ - wxString GetPropertyExpanded(const wxString& key); - - /** - Retrieve a 'property' value previously set with SetProperty, - interpreted as an int AFTER any '$()' variable replacement. - */ - int GetPropertyInt(const wxString& key); - - /** - In read-only mode? - */ - bool GetReadOnly(); - - /** - Get cursor type. - */ - int GetSTCCursor(); - - /** - Get internal focus flag. - */ - bool GetSTCFocus(); - - /** - Retrieve the document width assumed for scrolling. - */ - int GetScrollWidth(); - - /** - Get the search flags used by SearchInTarget. - */ - int GetSearchFlags(); - - /** - Get the alpha of the selection. - */ - int GetSelAlpha(); - - /** - Retrieve the selected text. - */ - wxString GetSelectedText(); - - /** - Retrieve the selected text. - */ - wxCharBuffer GetSelectedTextRaw(); - - /** - - */ - void GetSelection(int* OUTPUT, int* OUTPUT); - - /** - Returns the position at the end of the selection. - */ - int GetSelectionEnd(); - - /** - Get the mode of the current selection. - */ - int GetSelectionMode(); - - /** - Returns the position at the start of the selection. - */ - int GetSelectionStart(); - - /** - Get error status. - */ - int GetStatus(); - - /** - Returns the style byte at the position. - */ - int GetStyleAt(int pos); - - /** - Retrieve number of bits in style bytes used to hold the lexical state. - */ - int GetStyleBits(); - - /** - Retrieve the number of bits the current lexer needs for styling. - */ - int GetStyleBitsNeeded(); - - /** - Retrieve a buffer of cells. - */ - wxMemoryBuffer GetStyledText(int startPos, int endPos); - - /** - Does a tab pressed when caret is within indentation indent? - */ - bool GetTabIndents(); - - /** - Retrieve the visible size of a tab. - */ - int GetTabWidth(); - - /** - Get the position that ends the target. - */ - int GetTargetEnd(); - - /** - Get the position that starts the target. - */ - int GetTargetStart(); - - /** - Retrieve all the text in the document. - */ - wxString GetText(); - - /** - Retrieve the number of characters in the document. - */ - int GetTextLength(); - - /** - Retrieve a range of text. - */ - wxString GetTextRange(int startPos, int endPos); - - /** - Retrieve a range of text. - */ - wxCharBuffer GetTextRangeRaw(int startPos, int endPos); - - /** - Retrieve all the text in the document. - */ - wxCharBuffer GetTextRaw(); - - /** - Is drawing done in two phases with backgrounds drawn before foregrounds? - */ - bool GetTwoPhaseDraw(); - - /** - Is undo history being collected? - */ - bool GetUndoCollection(); - - /** - Returns the current UseAntiAliasing setting. - */ - bool GetUseAntiAliasing(); - - /** - Is the horizontal scroll bar visible? - */ - bool GetUseHorizontalScrollBar(); - - /** - Retrieve whether tabs will be used in indentation. - */ - bool GetUseTabs(); - - /** - Is the vertical scroll bar visible? - */ - bool GetUseVerticalScrollBar(); - - /** - Are the end of line characters visible? - */ - bool GetViewEOL(); - - /** - Are white space characters currently visible? - Returns one of SCWS_* constants. - */ - int GetViewWhiteSpace(); - - /** - Retrieve whether text is word wrapped. - */ - int GetWrapMode(); - - /** - Retrive the start indent for wrapped lines. - */ - int GetWrapStartIndent(); - - /** - Retrive the display mode of visual flags for wrapped lines. - */ - int GetWrapVisualFlags(); - - /** - Retrive the location of visual flags for wrapped lines. - */ - int GetWrapVisualFlagsLocation(); - - /** - - */ - int GetXOffset(); - - /** - Retrieve the zoom level. - */ - int GetZoom(); - - /** - Set caret to start of a line and ensure it is visible. - */ - void GotoLine(int line); - - /** - Set caret to a position and ensure it is visible. - */ - void GotoPos(int pos); - - /** - Make a range of lines invisible. - */ - void HideLines(int lineStart, int lineEnd); - - /** - Draw the selection in normal style or with selection highlighted. - */ - void HideSelection(bool normal); - - /** - Move caret to first position on line. - */ - void Home(); - - /** - Move caret to first position on display line. - */ - void HomeDisplay(); - - /** - Move caret to first position on display line extending selection to - new caret position. - */ - void HomeDisplayExtend(); - - /** - Move caret to first position on line extending selection to new caret position. - */ - void HomeExtend(); - - /** - Move caret to first position on line, extending rectangular selection to new - caret position. - */ - void HomeRectExtend(); - - /** - These are like their namesakes Home(Extend)?, LineEnd(Extend)?, VCHome(Extend)? - except they behave differently when word-wrap is enabled: - They go first to the start / end of the display line, like (Home|LineEnd)Display - The difference is that, the cursor is already at the point, it goes on to the - start - or end of the document line, as appropriate for (Home|LineEnd|VCHome)(Extend)?. - */ - void HomeWrap(); - - /** - - */ - void HomeWrapExtend(); - - /** - Retrieve the foreground colour of an indicator. - */ - wxColour IndicatorGetForeground(int indic); - - /** - Retrieve the style of an indicator. - */ - int IndicatorGetStyle(int indic); - - /** - Set the foreground colour of an indicator. - */ - void IndicatorSetForeground(int indic, const wxColour& fore); - - /** - Set an indicator to plain, squiggle or TT. - */ - void IndicatorSetStyle(int indic, int style); - - /** - Insert string at a position. - */ - void InsertText(int pos, const wxString& text); - - /** - Insert string at a position. - */ - void InsertTextRaw(int pos, const char* text); - - /** - Copy the line containing the caret. - */ - void LineCopy(); - - /** - Cut the line containing the caret. - */ - void LineCut(); - - /** - Delete the line containing the caret. - */ - void LineDelete(); - - /** - Move caret down one line. - */ - void LineDown(); - - /** - Move caret down one line extending selection to new caret position. - */ - void LineDownExtend(); - - /** - Move caret down one line, extending rectangular selection to new caret position. - */ - void LineDownRectExtend(); - - /** - Duplicate the current line. - */ - void LineDuplicate(); - - /** - Move caret to last position on line. - */ - void LineEnd(); - - /** - Move caret to last position on display line. - */ - void LineEndDisplay(); - - /** - Move caret to last position on display line extending selection to new - caret position. - */ - void LineEndDisplayExtend(); - - /** - Move caret to last position on line extending selection to new caret position. - */ - void LineEndExtend(); - - /** - Move caret to last position on line, extending rectangular selection to new - caret position. - */ - void LineEndRectExtend(); - - /** - - */ - void LineEndWrap(); - - /** - - */ - void LineEndWrapExtend(); - - /** - Retrieve the line containing a position. - */ - int LineFromPosition(int pos); - - /** - How many characters are on a line, not including end of line characters? - */ - int LineLength(int line); - - /** - Scroll horizontally and vertically. - */ - void LineScroll(int columns, int lines); - - /** - Scroll the document down, keeping the caret visible. - */ - void LineScrollDown(); - - /** - Scroll the document up, keeping the caret visible. - */ - void LineScrollUp(); - - /** - Switch the current line with the previous. - */ - void LineTranspose(); - - /** - Move caret up one line. - */ - void LineUp(); - - /** - Move caret up one line extending selection to new caret position. - */ - void LineUpExtend(); - - /** - Move caret up one line, extending rectangular selection to new caret position. - */ - void LineUpRectExtend(); - - /** - Join the lines in the target. - */ - void LinesJoin(); - - /** - Retrieves the number of lines completely visible. - */ - int LinesOnScreen(); - - /** - Split the lines in the target into lines that are less wide than pixelWidth - where possible. - */ - void LinesSplit(int pixelWidth); - - /** - Load the contents of filename into the editor - */ - bool LoadFile(const wxString& filename); - - /** - Transform the selection to lower case. - */ - void LowerCase(); - - /** - Add a marker to a line, returning an ID which can be used to find or delete the - marker. - */ - int MarkerAdd(int line, int markerNumber); - - /** - Add a set of markers to a line. - */ - void MarkerAddSet(int line, int set); - - /** - Set the symbol used for a particular marker number, - and optionally the fore and background colours. - */ - void MarkerDefine(int markerNumber, int markerSymbol, - const wxColour& foreground = wxNullColour, - const wxColour& background = wxNullColour); - - /** - Define a marker from a bitmap - */ - void MarkerDefineBitmap(int markerNumber, const wxBitmap& bmp); - - /** - Delete a marker from a line. - */ - void MarkerDelete(int line, int markerNumber); - - /** - Delete all markers with a particular number from all lines. - */ - void MarkerDeleteAll(int markerNumber); - - /** - Delete a marker. - */ - void MarkerDeleteHandle(int handle); - - /** - Get a bit mask of all the markers set on a line. - */ - int MarkerGet(int line); - - /** - Retrieve the line number at which a particular marker is located. - */ - int MarkerLineFromHandle(int handle); - - /** - Find the next line after lineStart that includes a marker in mask. - */ - int MarkerNext(int lineStart, int markerMask); - - /** - Find the previous line before lineStart that includes a marker in mask. - */ - int MarkerPrevious(int lineStart, int markerMask); - - /** - Set the alpha used for a marker that is drawn in the text area, not the margin. - */ - void MarkerSetAlpha(int markerNumber, int alpha); - - /** - Set the background colour used for a particular marker number. - */ - void MarkerSetBackground(int markerNumber, const wxColour& back); - - /** - Set the foreground colour used for a particular marker number. - */ - void MarkerSetForeground(int markerNumber, const wxColour& fore); - - /** - Move the caret inside current view if it's not there already. - */ - void MoveCaretInsideView(); - - /** - Insert a new line, may use a CRLF, CR or LF depending on EOL mode. - */ - void NewLine(); - - /** - Move caret one page down. - */ - void PageDown(); - - /** - Move caret one page down extending selection to new caret position. - */ - void PageDownExtend(); - - /** - Move caret one page down, extending rectangular selection to new caret position. - */ - void PageDownRectExtend(); - - /** - Move caret one page up. - */ - void PageUp(); - - /** - Move caret one page up extending selection to new caret position. - */ - void PageUpExtend(); - - /** - Move caret one page up, extending rectangular selection to new caret position. - */ - void PageUpRectExtend(); - - /** - Move caret between paragraphs (delimited by empty lines). - */ - void ParaDown(); - - /** - - */ - void ParaDownExtend(); - - /** - - */ - void ParaUp(); - - /** - - */ - void ParaUpExtend(); - - /** - Paste the contents of the clipboard into the document replacing the selection. - */ - void Paste(); - - /** - Retrieve the point in the window where a position is displayed. - */ - wxPoint PointFromPosition(int pos); - - /** - Given a valid document position, return the next position taking code - page into account. Maximum value returned is the last position in the document. - */ - int PositionAfter(int pos); - - /** - Given a valid document position, return the previous position taking code - page into account. Returns 0 if passed 0. - */ - int PositionBefore(int pos); - - /** - Retrieve the position at the start of a line. - */ - int PositionFromLine(int line); - - /** - Find the position from a point within the window. - */ - int PositionFromPoint(wxPoint pt); - - /** - Find the position from a point within the window but return - INVALID_POSITION if not close to text. - */ - int PositionFromPointClose(int x, int y); - - /** - Redoes the next action on the undo history. - */ - void Redo(); - - /** - Register an image for use in autocompletion lists. - */ - void RegisterImage(int type, const wxBitmap& bmp); - - /** - Release a reference to the document, deleting document if it fades to black. - */ - void ReleaseDocument(void* docPointer); - - /** - Replace the selected text with the argument text. - */ - void ReplaceSelection(const wxString& text); - - /** - Replace the target text with the argument text. - Text is counted so it can contain NULs. - Returns the length of the replacement text. - */ - int ReplaceTarget(const wxString& text); - - /** - Replace the target text with the argument text after - d processing. - Text is counted so it can contain NULs. - Looks for - d where d is between 1 and 9 and replaces these with the strings - matched in the last search operation which were surrounded by - ( and - ). - Returns the length of the replacement text including any change - caused by processing the - d patterns. - */ - int ReplaceTargetRE(const wxString& text); - - /** - Write the contents of the editor to filename - */ - bool SaveFile(const wxString& filename); - - /** - Scroll enough to make the given column visible - */ - void ScrollToColumn(int column); - - /** - Scroll enough to make the given line visible - */ - void ScrollToLine(int line); - - /** - Sets the current caret position to be the search anchor. - */ - void SearchAnchor(); - - /** - Search for a counted string in the target and set the target to the found - range. Text is counted so it can contain NULs. - Returns length of range or -1 for failure in which case target is not moved. - */ - int SearchInTarget(const wxString& text); - - /** - Find some text starting at the search anchor. - Does not ensure the selection is visible. - */ - int SearchNext(int flags, const wxString& text); - - /** - Find some text starting at the search anchor and moving backwards. - Does not ensure the selection is visible. - */ - int SearchPrev(int flags, const wxString& text); - - /** - Select all the text in the document. - */ - void SelectAll(); - - /** - Duplicate the selection. If selection empty duplicate the line containing the - caret. - */ - void SelectionDuplicate(); - - /** - Is the selection rectangular? The alternative is the more common stream - selection. - */ - bool SelectionIsRectangle(); - - /** - Send a message to Scintilla - */ - long SendMsg(int msg, long wp = 0, long lp = 0); - - /** - Set the selection anchor to a position. The anchor is the opposite - end of the selection from the caret. - */ - void SetAnchor(int posAnchor); - - /** - Sets whether a backspace pressed when caret is within indentation unindents. - */ - void SetBackSpaceUnIndents(bool bsUnIndents); - - /** - If drawing is buffered then each line of text is drawn into a bitmap buffer - before drawing it to the screen to avoid flicker. - */ - void SetBufferedDraw(bool buffered); - - /** - Set the foreground colour of the caret. - */ - void SetCaretForeground(const wxColour& fore); - - /** - Set background alpha of the caret line. - */ - void SetCaretLineBackAlpha(int alpha); - - /** - Set the colour of the background of the line containing the caret. - */ - void SetCaretLineBackground(const wxColour& back); - - /** - Display the background of the line containing the caret in a different colour. - */ - void SetCaretLineVisible(bool show); - - /** - Get the time in milliseconds that the caret is on and off. 0 = steady on. - */ - void SetCaretPeriod(int periodMilliseconds); - - /** - Stop the caret preferred x position changing when the user types. - */ - void SetCaretSticky(bool useCaretStickyBehaviour); - - /** - Set the width of the insert mode caret. - */ - void SetCaretWidth(int pixelWidth); - - /** - Reset the set of characters for whitespace and word characters to the defaults. - */ - void SetCharsDefault(); - - /** - Set the code page used to interpret the bytes of the document as characters. - */ - void SetCodePage(int codePage); - - /** - Change the way control characters are displayed: - If symbol is 32, keep the drawn way, else, use the given character. - */ - void SetControlCharSymbol(int symbol); - - /** - Sets the position of the caret. - */ - void SetCurrentPos(int pos); - - /** - Change the document object used. - */ - void SetDocPointer(void* docPointer); - - /** - Set the current end of line mode. - */ - void SetEOLMode(int eolMode); - - /** - Change the colour used in edge indication. - */ - void SetEdgeColour(const wxColour& edgeColour); - - /** - Set the column number of the edge. - If text goes past the edge then it is highlighted. - */ - void SetEdgeColumn(int column); - - /** - The edge may be displayed by a line (EDGE_LINE) or by highlighting text that - goes beyond it (EDGE_BACKGROUND) or not displayed at all (EDGE_NONE). - */ - void SetEdgeMode(int mode); - - /** - Sets the scroll range so that maximum scroll position has - the last line at the bottom of the view (default). - Setting this to @false allows scrolling one page below the last line. - */ - void SetEndAtLastLine(bool endAtLastLine); - - /** - Show the children of a header line. - */ - void SetFoldExpanded(int line, bool expanded); - - /** - Set some style options for folding. - */ - void SetFoldFlags(int flags); - - /** - Set the fold level of a line. - This encodes an integer level along with flags indicating whether the - line is a header and whether it is effectively white space. - */ - void SetFoldLevel(int line, int level); - - /** - Set the colours used as a chequerboard pattern in the fold margin - */ - void SetFoldMarginColour(bool useSetting, const wxColour& back); - - /** - - */ - void SetFoldMarginHiColour(bool useSetting, const wxColour& fore); - - /** - Set the horizontal scrollbar to use instead of the ont that's built-in. - */ - void SetHScrollBar(wxScrollBar* bar); - - /** - Set the highlighted indentation guide column. - 0 = no highlighted guide. - */ - void SetHighlightGuide(int column); - - /** - Set a back colour for active hotspots. - */ - void SetHotspotActiveBackground(bool useSetting, - const wxColour& back); - - /** - Set a fore colour for active hotspots. - */ - void SetHotspotActiveForeground(bool useSetting, - const wxColour& fore); - - /** - Enable / Disable underlining active hotspots. - */ - void SetHotspotActiveUnderline(bool underline); - - /** - Limit hotspots to single line so hotspots on two lines don't merge. - */ - void SetHotspotSingleLine(bool singleLine); - - /** - Set the number of spaces used for one level of indentation. - */ - void SetIndent(int indentSize); - - /** - Show or hide indentation guides. - */ - void SetIndentationGuides(bool show); - - /** - Set up the key words used by the lexer. - */ - void SetKeyWords(int keywordSet, const wxString& keyWords); - - /** - - */ - void SetLastKeydownProcessed(bool val); - - /** - Sets the degree of caching of layout information. - */ - void SetLayoutCache(int mode); - - /** - Set the lexing language of the document. - */ - void SetLexer(int lexer); - - /** - Set the lexing language of the document based on string name. - */ - void SetLexerLanguage(const wxString& language); - - /** - Change the indentation of a line to a number of columns. - */ - void SetLineIndentation(int line, int indentSize); - - /** - Used to hold extra styling information for each line. - */ - void SetLineState(int line, int state); - - /** - Sets the size in pixels of the left margin. - */ - void SetMarginLeft(int pixelWidth); - - /** - Set a mask that determines which markers are displayed in a margin. - */ - void SetMarginMask(int margin, int mask); - - /** - Sets the size in pixels of the right margin. - */ - void SetMarginRight(int pixelWidth); - - /** - Make a margin sensitive or insensitive to mouse clicks. - */ - void SetMarginSensitive(int margin, bool sensitive); - - /** - Set a margin to be either numeric or symbolic. - */ - void SetMarginType(int margin, int marginType); - - /** - Set the width of a margin to a width expressed in pixels. - */ - void SetMarginWidth(int margin, int pixelWidth); - - /** - Set the left and right margin in the edit area, measured in pixels. - */ - void SetMargins(int left, int right); - - /** - Set which document modification events are sent to the container. - */ - void SetModEventMask(int mask); - - /** - Set whether the mouse is captured when its button is pressed. - */ - void SetMouseDownCaptures(bool captures); - - /** - Sets the time the mouse must sit still to generate a mouse dwell event. - */ - void SetMouseDwellTime(int periodMilliseconds); - - /** - Set to overtype (@true) or insert mode. - */ - void SetOvertype(bool overtype); - - /** - Enable/Disable convert-on-paste for line endings - */ - void SetPasteConvertEndings(bool convert); - - /** - Modify colours when printing for clearer printed text. - */ - void SetPrintColourMode(int mode); - - /** - Sets the print magnification added to the point size of each style for printing. - */ - void SetPrintMagnification(int magnification); - - /** - Set printing to line wrapped (SC_WRAP_WORD) or not line wrapped (SC_WRAP_NONE). - */ - void SetPrintWrapMode(int mode); - - /** - Set up a value that may be used by a lexer for some optional feature. - */ - void SetProperty(const wxString& key, const wxString& value); - - /** - Set to read only or read write. - */ - void SetReadOnly(bool readOnly); - - /** - Sets the cursor to one of the SC_CURSOR* values. - */ - void SetSTCCursor(int cursorType); - - /** - Change internal focus flag. - */ - void SetSTCFocus(bool focus); - - /** - Remember the current position in the undo history as the position - at which the document was saved. - */ - void SetSavePoint(); - - /** - Sets the document width assumed for scrolling. - */ - void SetScrollWidth(int pixelWidth); - - /** - Set the search flags used by SearchInTarget. - */ - void SetSearchFlags(int flags); - - /** - Set the alpha of the selection. - */ - void SetSelAlpha(int alpha); - - /** - Set the background colour of the selection and whether to use this setting. - */ - void SetSelBackground(bool useSetting, const wxColour& back); - - /** - Set the foreground colour of the selection and whether to use this setting. - */ - void SetSelForeground(bool useSetting, const wxColour& fore); - - /** - Select a range of text. - */ - void SetSelection(int start, int end); - - /** - Sets the position that ends the selection - this becomes the currentPosition. - */ - void SetSelectionEnd(int pos); - - /** - Set the selection mode to stream (SC_SEL_STREAM) or rectangular - (SC_SEL_RECTANGLE) or - by lines (SC_SEL_LINES). - */ - void SetSelectionMode(int mode); - - /** - Sets the position that starts the selection - this becomes the anchor. - */ - void SetSelectionStart(int pos); - - /** - Change error status - 0 = OK. - */ - void SetStatus(int statusCode); - - /** - Divide each styling byte into lexical class bits (default: 5) and indicator - bits (default: 3). If a lexer requires more than 32 lexical states, then this - is used to expand the possible states. - */ - void SetStyleBits(int bits); - - /** - Set the styles for a segment of the document. - */ - void SetStyleBytes(int length, char* styleBytes); - - /** - Change style from current styling position for length characters to a style - and move the current styling position to after this newly styled segment. - */ - void SetStyling(int length, int style); - - /** - Sets whether a tab pressed when caret is within indentation indents. - */ - void SetTabIndents(bool tabIndents); - - /** - Change the visible size of a tab to be a multiple of the width of a space - character. - */ - void SetTabWidth(int tabWidth); - - /** - Sets the position that ends the target which is used for updating the - document without affecting the scroll position. - */ - void SetTargetEnd(int pos); - - /** - Sets the position that starts the target which is used for updating the - document without affecting the scroll position. - */ - void SetTargetStart(int pos); - - /** - Replace the contents of the document with the argument text. - */ - void SetText(const wxString& text); - - /** - Replace the contents of the document with the argument text. - */ - void SetTextRaw(const char* text); - - /** - In twoPhaseDraw mode, drawing is performed in two phases, first the background - and then the foreground. This avoids chopping off characters that overlap the - next run. - */ - void SetTwoPhaseDraw(bool twoPhase); - - /** - Choose between collecting actions into the undo - history and discarding them. - */ - void SetUndoCollection(bool collectUndo); - - /** - Specify whether anti-aliased fonts should be used. Will have no effect - on some platforms, but on some (wxMac for example) can greatly improve - performance. - */ - void SetUseAntiAliasing(bool useAA); - - /** - Show or hide the horizontal scroll bar. - */ - void SetUseHorizontalScrollBar(bool show); - - /** - Indentation will only use space characters if useTabs is @false, otherwise - it will use a combination of tabs and spaces. - */ - void SetUseTabs(bool useTabs); - - /** - Show or hide the vertical scroll bar. - */ - void SetUseVerticalScrollBar(bool show); - - /** - Set the vertical scrollbar to use instead of the ont that's built-in. - */ - void SetVScrollBar(wxScrollBar* bar); - - /** - Make the end of line characters visible or invisible. - */ - void SetViewEOL(bool visible); - - /** - Make white space characters invisible, always visible or visible outside - indentation. - */ - void SetViewWhiteSpace(int viewWS); - - /** - Set the way the display area is determined when a particular line - is to be moved to by Find, FindNext, GotoLine, etc. - */ - void SetVisiblePolicy(int visiblePolicy, int visibleSlop); - - /** - Set the background colour of all whitespace and whether to use this setting. - */ - void SetWhitespaceBackground(bool useSetting, - const wxColour& back); - - /** - Set the set of characters making up whitespace for when moving or selecting by - word. - Should be called after SetWordChars. - */ - void SetWhitespaceChars(const wxString& characters); - - /** - Set the foreground colour of all whitespace and whether to use this setting. - */ - void SetWhitespaceForeground(bool useSetting, - const wxColour& fore); - - /** - Set the set of characters making up words for when moving or selecting by word. - First sets deaults like SetCharsDefault. - */ - void SetWordChars(const wxString& characters); - - /** - Sets whether text is word wrapped. - */ - void SetWrapMode(int mode); - - /** - Set the start indent for wrapped lines. - */ - void SetWrapStartIndent(int indent); - - /** - Set the display mode of visual flags for wrapped lines. - */ - void SetWrapVisualFlags(int wrapVisualFlags); - - /** - Set the location of visual flags for wrapped lines. - */ - void SetWrapVisualFlagsLocation(int wrapVisualFlagsLocation); - - /** - Set the way the caret is kept visible when going sideway. - The exclusion zone is given in pixels. - */ - void SetXCaretPolicy(int caretPolicy, int caretSlop); - - /** - Get and Set the xOffset (ie, horizonal scroll position). - */ - void SetXOffset(int newOffset); - - /** - Set the way the line the caret is on is kept visible. - The exclusion zone is given in lines. - */ - void SetYCaretPolicy(int caretPolicy, int caretSlop); - - /** - Set the zoom level. This number of points is added to the size of all fonts. - It may be positive to magnify or negative to reduce. - */ - void SetZoom(int zoom); - - /** - Make a range of lines visible. - */ - void ShowLines(int lineStart, int lineEnd); - - /** - Start notifying the container of all key presses and commands. - */ - void StartRecord(); - - /** - Set the current styling position to pos and the styling mask to mask. - The styling mask can be used to protect some bits in each styling byte from - modification. - */ - void StartStyling(int pos, int mask); - - /** - Stop notifying the container of all key presses and commands. - */ - void StopRecord(); - - /** - Move caret to bottom of page, or one page down if already at bottom of page. - */ - void StutteredPageDown(); - - /** - Move caret to bottom of page, or one page down if already at bottom of page, - extending selection to new caret position. - */ - void StutteredPageDownExtend(); - - /** - Move caret to top of page, or one page up if already at top of page. - */ - void StutteredPageUp(); - - /** - Move caret to top of page, or one page up if already at top of page, extending - selection to new caret position. - */ - void StutteredPageUpExtend(); - - /** - Clear all the styles and make equivalent to the global default style. - */ - void StyleClearAll(); - - /** - Reset the default style to its state at startup - */ - void StyleResetDefault(); - - /** - Set the background colour of a style. - */ - void StyleSetBackground(int style, const wxColour& back); - - /** - Set a style to be bold or not. - */ - void StyleSetBold(int style, bool bold); - - /** - Set a style to be mixed case, or to force upper or lower case. - */ - void StyleSetCase(int style, int caseForce); - - /** - Set a style to be changeable or not (read only). - Experimental feature, currently buggy. - */ - void StyleSetChangeable(int style, bool changeable); - - /** - Set the character set of the font in a style. Converts the Scintilla - character set values to a wxFontEncoding. - */ - void StyleSetCharacterSet(int style, int characterSet); - - /** - Set a style to have its end of line filled or not. - */ - void StyleSetEOLFilled(int style, bool filled); - - /** - Set the font of a style. - */ - void StyleSetFaceName(int style, const wxString& fontName); - - /** - Set style size, face, bold, italic, and underline attributes from - a wxFont's attributes. - */ - void StyleSetFont(int styleNum, wxFont& font); - - /** - Set all font style attributes at once. - */ - void StyleSetFontAttr(int styleNum, int size, - const wxString& faceName, - bool bold, - bool italic, - bool underline, - wxFontEncoding encoding = wxFONTENCODING_DEFAULT); - - /** - Set the font encoding to be used by a style. - */ - void StyleSetFontEncoding(int style, wxFontEncoding encoding); - - /** - Set the foreground colour of a style. - */ - void StyleSetForeground(int style, const wxColour& fore); - - /** - Set a style to be a hotspot or not. - */ - void StyleSetHotSpot(int style, bool hotspot); - - /** - Set a style to be italic or not. - */ - void StyleSetItalic(int style, bool italic); - - /** - Set the size of characters of a style. - */ - void StyleSetSize(int style, int sizePoints); - - /** - Extract style settings from a spec-string which is composed of one or - more of the following comma separated elements: - bold turns on bold - italic turns on italics - fore:[name or #RRGGBB] sets the foreground colour - back:[name or #RRGGBB] sets the background colour - face:[facename] sets the font face name to use - size:[num] sets the font size in points - eol turns on eol filling - underline turns on underlining - */ - void StyleSetSpec(int styleNum, const wxString& spec); - - /** - Set a style to be underlined or not. - */ - void StyleSetUnderline(int style, bool underline); - - /** - Set a style to be visible or not. - */ - void StyleSetVisible(int style, bool visible); - - /** - If selection is empty or all on one line replace the selection with a tab - character. - If more than one line selected, indent the lines. - */ - void Tab(); - - /** - Make the target range start and end be the same as the selection range start - and end. - */ - void TargetFromSelection(); - - /** - Retrieve the height of a particular line of text in pixels. - */ - int TextHeight(int line); - - /** - Measure the pixel width of some text in a particular style. - NUL terminated text argument. - Does not handle tab or control characters. - */ - int TextWidth(int style, const wxString& text); - - /** - Switch between sticky and non-sticky: meant to be bound to a key. - */ - void ToggleCaretSticky(); - - /** - Switch a header line between expanded and contracted. - */ - void ToggleFold(int line); - - /** - Undo one action in the undo history. - */ - void Undo(); - - /** - Transform the selection to upper case. - */ - void UpperCase(); - - /** - Set whether a pop up menu is displayed automatically when the user presses - the wrong mouse button. - */ - void UsePopUp(bool allowPopUp); - - /** - Display a list of strings and send notification when user chooses one. - */ - void UserListShow(int listType, const wxString& itemList); - - /** - Move caret to before first visible character on line. - If already there move to first character on line. - */ - void VCHome(); - - /** - Like VCHome but extending selection to new caret position. - */ - void VCHomeExtend(); - - /** - Move caret to before first visible character on line. - If already there move to first character on line. - In either case, extend rectangular selection to new caret position. - */ - void VCHomeRectExtend(); - - /** - - */ - void VCHomeWrap(); - - /** - - */ - void VCHomeWrapExtend(); - - /** - Find the display line of a document line taking hidden lines into account. - */ - int VisibleFromDocLine(int line); - - /** - Get position of end of word. - */ - int WordEndPosition(int pos, bool onlyWordCharacters); - - /** - Move caret left one word. - */ - void WordLeft(); - - /** - Move caret left one word, position cursor at end of word. - */ - void WordLeftEnd(); - - /** - Move caret left one word, position cursor at end of word, extending selection - to new caret position. - */ - void WordLeftEndExtend(); - - /** - Move caret left one word extending selection to new caret position. - */ - void WordLeftExtend(); - - /** - Move to the previous change in capitalisation. - */ - void WordPartLeft(); - - /** - Move to the previous change in capitalisation extending selection - to new caret position. - */ - void WordPartLeftExtend(); - - /** - Move to the change next in capitalisation. - */ - void WordPartRight(); - - /** - Move to the next change in capitalisation extending selection - to new caret position. - */ - void WordPartRightExtend(); - - /** - Move caret right one word. - */ - void WordRight(); - - /** - Move caret right one word, position cursor at end of word. - */ - void WordRightEnd(); - - /** - Move caret right one word, position cursor at end of word, extending selection - to new caret position. - */ - void WordRightEndExtend(); - - /** - Move caret right one word extending selection to new caret position. - */ - void WordRightExtend(); - - /** - Get position of start of word. - */ - int WordStartPosition(int pos, bool onlyWordCharacters); - - /** - The number of display lines needed to wrap a document line - */ - int WrapCount(int line); - - /** - Magnify the displayed text by increasing the sizes by 1 point. - */ - void ZoomIn(); - - /** - Make the displayed text smaller by decreasing the sizes by 1 point. - */ - void ZoomOut(); -}; - diff --git a/interface/stdpaths.h b/interface/stdpaths.h deleted file mode 100644 index 8c2769b3c3..0000000000 --- a/interface/stdpaths.h +++ /dev/null @@ -1,218 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: stdpaths.h -// Purpose: interface of wxStandardPaths -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxStandardPaths - @wxheader{stdpaths.h} - - wxStandardPaths returns the standard locations in the file system and should be - used by applications to find their data files in a portable way. - - In the description of the methods below, the example return values are given - for the Unix, Windows and Mac OS X systems, however please note that these are - just the examples and the actual values may differ. For example, under Windows: - the system administrator may change the standard directories locations, i.e. - the Windows directory may be named @c W:\\Win2003 instead of - the default @c C:\\Windows. - - The strings @c appname and @c username should be - replaced with the value returned by wxApp::GetAppName - and the name of the currently logged in user, respectively. The string - @c prefix is only used under Unix and is @c /usr/local by - default but may be changed using wxStandardPaths::SetInstallPrefix. - - The directories returned by the methods of this class may or may not exist. If - they don't exist, it's up to the caller to create them, wxStandardPaths doesn't - do it. - - Finally note that these functions only work with standardly packaged - applications. I.e. under Unix you should follow the standard installation - conventions and under Mac you should create your application bundle according - to the Apple guidelines. Again, this class doesn't help you to do it. - - This class is MT-safe: its methods may be called concurrently from different - threads without additional locking. - - @library{wxbase} - @category{file} - - @see wxFileConfig - */ -class wxStandardPaths -{ -public: - /** - Returns reference to the unique global standard paths object. - */ - static wxStandardPathsBase Get(); - - /** - Return the directory containing the system config files. - Example return values: - - Unix: @c /etc - - Windows: @c C:\\Documents @c and @c Settings\\All @c Users\\Application Data - - Mac: @c /Library/Preferences - - @see wxFileConfig - */ - wxString GetConfigDir() const; - - /** - Return the location of the applications global, i.e. not user-specific, - data files. - Example return values: - - Unix: @c prefix/share/appname - - Windows: the directory where the executable file is located - - Mac: @c appname.app/Contents/SharedSupport bundle subdirectory - - @see GetLocalDataDir() - */ - wxString GetDataDir() const; - - /** - Return the directory containing the current user's documents. - Example return values: - - Unix: @c ~ (the home directory) - - Windows: @c C:\\Documents @c and @c Settings\\username\\Documents - - Mac: @c ~/Documents - - @since 2.7.0 - */ - wxString GetDocumentsDir() const; - - /** - Return the directory and the filename for the current executable. - Example return values: - - Unix: @c /usr/local/bin/exename - - Windows: @c C:\\Programs\\AppFolder\\exename.exe - - Mac: @c /Programs/exename - */ - wxString GetExecutablePath() const; - - /** - @note This function is only available under Unix. - Return the program installation prefix, e.g. @c /usr, @c /opt or - @c /home/zeitlin. - If the prefix had been previously by SetInstallPrefix(), returns that - value, otherwise tries to determine it automatically (Linux only right - now) and finally returns the default @c /usr/local value if it failed. - */ - wxString GetInstallPrefix() const; - - /** - Return the location for application data files which are host-specific and - can't, or shouldn't, be shared with the other machines. - This is the same as GetDataDir() except - under Unix where it returns @c /etc/appname. - */ - wxString GetLocalDataDir() const; - - /** - Return the localized resources directory containing the resource files of the - specified category for the given language. - In general this is just the same as @a lang subdirectory of - GetResourcesDir() (or @c lang.lproj under Mac OS X) but is something quite - different for message catalog category under Unix where it returns the standard - @c prefix/share/locale/lang/LC_MESSAGES directory. - - @since 2.7.0 - */ - wxString GetLocalizedResourcesDir(const wxString& lang, - ResourceCat category = ResourceCat_None) const; - - /** - Return the directory where the loadable modules (plugins) live. - Example return values: - - Unix: @c prefix/lib/appname - - Windows: the directory of the executable file - - Mac: @c appname.app/Contents/PlugIns bundle subdirectory - - @see wxDynamicLibrary - */ - wxString GetPluginsDir() const; - - /** - Return the directory where the application resource files are located. The - resources are the auxiliary data files needed for the application to run and - include, for example, image and sound files it might use. - This function is the same as GetDataDir() for - all platforms except Mac OS X. - Example return values: - - Unix: @c prefix/share/@e appname - - Windows: the directory where the executable file is located - - Mac: @c appname.app/Contents/Resources bundle subdirectory - - @since 2.7.0 - - @see GetLocalizedResourcesDir() - */ - wxString GetResourcesDir() const; - - /** - Return the directory for storing temporary files. To create unique temporary - files, - it is best to use wxFileName::CreateTempFileName for correct behaviour when - multiple processes are attempting to create temporary files. - - @since 2.7.2 - */ - wxString GetTempDir() const; - - /** - Return the directory for the user config files: - - Unix: @c ~ (the home directory) - - Windows: @c C:\\Documents @c and @c Settings\\username\\Application Data - - Mac: @c ~/Library/Preferences - Only use this method if you have a single configuration file to put in this - directory, otherwise GetUserDataDir() is - more appropriate. - */ - wxString GetUserConfigDir() const; - - /** - Return the directory for the user-dependent application data files: - - Unix: @c ~/.appname - - Windows: @c C:\\Documents @c and @c Settings\\username\Application @c Data\appname - - Mac: @c ~/Library/Application @c Support/appname - */ - wxString GetUserDataDir() const; - - /** - Return the directory for user data files which shouldn't be shared with - the other machines. - This is the same as GetUserDataDir() for all platforms except Windows where it returns - @c C:\\Documents @c and @c Settings\\username\\Local @c Settings\\Application @c Data\appname - */ - wxString GetUserLocalDataDir() const; - - /** - @note This function is only available under Unix. - Lets wxStandardPaths know about the real program installation prefix on a Unix - system. By default, the value returned by - GetInstallPrefix() is used. - Although under Linux systems the program prefix may usually be determined - automatically, portable programs should call this function. Usually the prefix - is set during program configuration if using GNU autotools and so it is enough - to pass its value defined in @c config.h to this function. - */ - void SetInstallPrefix(const wxString& prefix); - - /** - Controls what application information is used when constructing paths that - should be unique to this program, such as the application data directory, the - plugins directory on Unix, etc. - Valid values for @a info are @c AppInfo_None and either one or - combination of @c AppInfo_AppName and @c AppInfo_VendorName. The - first one tells this class to not use neither application nor vendor name in - the paths. - By default, only the application name is used under Unix systems but both - application and vendor names are used under Windows and Mac. - */ - void UseAppInfo(int info); -}; - diff --git a/interface/stockitem.h b/interface/stockitem.h deleted file mode 100644 index 61f958d3ee..0000000000 --- a/interface/stockitem.h +++ /dev/null @@ -1,31 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: stockitem.h -// Purpose: interface of global functions -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** @ingroup group_funcmacro_misc */ -//@{ - -/** - Returns label that should be used for given @a id element. - - @param id - Given id of the wxMenuItem, wxButton, wxToolBar tool, etc. - @param withCodes - If @false then strip accelerator code from the label; useful for - getting labels without accelerator char code like for toolbar tooltip - or on platforms without traditional keyboard like smartphones. - @param accelerator - Optional accelerator string automatically added to label; useful for - building labels for wxMenuItem. - - @header{wx/stockitem.h} -*/ -wxString wxGetStockLabel(wxWindowID id, bool withCodes = true, - const wxString& accelerator = wxEmptyString); - -//@} - diff --git a/interface/stopwatch.h b/interface/stopwatch.h deleted file mode 100644 index 3dfba4a146..0000000000 --- a/interface/stopwatch.h +++ /dev/null @@ -1,106 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: stopwatch.h -// Purpose: interface of wxStopWatch -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxStopWatch - @wxheader{stopwatch.h} - - The wxStopWatch class allow you to measure time intervals. For example, you may - use it to measure the time elapsed by some function: - - @code - wxStopWatch sw; - CallLongRunningFunction(); - wxLogMessage("The long running function took %ldms to execute", - sw.Time()); - sw.Pause(); - ... stopwatch is stopped now ... - sw.Resume(); - CallLongRunningFunction(); - wxLogMessage("And calling it twice took $ldms in all", sw.Time()); - @endcode - - @library{wxbase} - @category{misc} - - @see wxTimer -*/ -class wxStopWatch -{ -public: - /** - Constructor. This starts the stop watch. - */ - wxStopWatch(); - - /** - Pauses the stop watch. Call Resume() to resume - time measuring again. - If this method is called several times, @c Resume() must be called the same - number of times to really resume the stop watch. You may, however, call - Start() to resume it unconditionally. - */ - void Pause(); - - /** - Resumes the stop watch which had been paused with - Pause(). - */ - void Resume(); - - /** - (Re)starts the stop watch with a given initial value. - */ - void Start(long milliseconds = 0); - - /** - Returns the time in milliseconds since the start (or restart) or the last call - of - Pause(). - */ - long Time() const; -}; - - - -// ============================================================================ -// Global functions/macros -// ============================================================================ - -/** @ingroup group_funcmacro_time */ -//@{ - -/** - Returns the number of seconds since local time 00:00:00 Jan 1st 1970. - - @see wxDateTime::Now() - - @header{wx/stopwatch.h} -*/ -long wxGetLocalTime(); - -/** - Returns the number of milliseconds since local time 00:00:00 Jan 1st 1970. - - @see wxDateTime::Now(), wxLongLong - - @header{wx/stopwatch.h} -*/ -wxLongLong wxGetLocalTimeMillis(); - -/** - Returns the number of seconds since GMT 00:00:00 Jan 1st 1970. - - @see wxDateTime::Now() - - @header{wx/stopwatch.h} -*/ -long wxGetUTCTime(); - -//@} - diff --git a/interface/strconv.h b/interface/strconv.h deleted file mode 100644 index 1843a27e13..0000000000 --- a/interface/strconv.h +++ /dev/null @@ -1,483 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: strconv.h -// Purpose: interface of wxMBConvUTF7 -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxMBConv - @wxheader{strconv.h} - - This class is the base class of a hierarchy of classes capable of - converting text strings between multibyte (SBCS or DBCS) encodings and - Unicode. - - This is an abstract base class which defines the operations implemented by - all different conversion classes. The derived classes don't add any new - operations of their own (except, possibly, some non-default constructors) - and so you should simply use this class ToWChar() and FromWChar() (or - cMB2WC() and cWC2MB()) methods with the objects of the derived class. - - In the documentation for this and related classes please notice that - length of the string refers to the number of characters in the string - not counting the terminating @c NUL, if any. While the size of the string - is the total number of bytes in the string, including any trailing @c NUL. - Thus, length of wide character string @c L"foo" is 3 while its size can - be either 8 or 16 depending on whether @c wchar_t is 2 bytes (as - under Windows) or 4 (Unix). - - @library{wxbase} - @category{conv} - - @see wxCSConv, wxEncodingConverter, @ref overview_mbconv "wxMBConv classes overview" -*/ -class wxMBConv -{ -public: - /** - Trivial default constructor. - */ - wxMBConv(); - - /** - This pure virtual function is overridden in each of the derived classes - to return a new copy of the object it is called on. - - It is used for copying the conversion objects while preserving their - dynamic type. - */ - virtual wxMBConv* Clone() const = 0; - - /** - This function returns 1 for most of the multibyte encodings in which the - string is terminated by a single @c NUL, 2 for UTF-16 and 4 for UTF-32 for - which the string is terminated with 2 and 4 @c NUL characters respectively. - The other cases are not currently supported and @c wxCONV_FAILED - (defined as -1) is returned for them. - */ - size_t GetMBNulLen() const; - - /** - Returns the maximal value which can be returned by GetMBNulLen() for - any conversion object. - - Currently this value is 4. - - This method can be used to allocate the buffer with enough space for the - trailing @c NUL characters for any encoding. - */ - const size_t GetMaxMBNulLen(); - - /** - Convert multibyte string to a wide character one. - - This is the most general function for converting a multibyte string to - a wide string, cMB2WC() may be often more convenient, however this - function is the most efficient one as it allows to avoid any - unnecessary copying. - - The main case is when @a dst is not @NULL and @a srcLen is not - @c wxNO_LEN (which is defined as @c (size_t)-1): then the function - converts exactly @a srcLen bytes starting at @a src into wide string - which it output to @e dst. If the length of the resulting wide - string is greater than @e dstLen, an error is returned. Note that if - @a srcLen bytes don't include @c NUL characters, the resulting wide - string is not @c NUL-terminated neither. - - If @a srcLen is @c wxNO_LEN, the function supposes that the string is - properly (i.e. as necessary for the encoding handled by this - conversion) @c NUL-terminated and converts the entire string, including - any trailing @c NUL bytes. In this case the wide string is also @c - NUL-terminated. - - Finally, if @a dst is @NULL, the function returns the length of the - needed buffer. - - Example of use of this function: - @code - size_t dstLen = conv.ToWChar(NULL, 0, src); - if ( dstLen == wxCONV_FAILED ) - ... handle error ... - wchar_t *dst = new wchar_t[dstLen]; - if ( conv.ToWChar(dst, dstLen, src) == wxCONV_FAILED ) - ... handle error ... - @endcode - - Notice that when passing the explicit source length the output will - @e not be @c NUL terminated if you pass @c strlen(str) as parameter. - Either leave @a srcLen as default @c wxNO_LEN or add one to @c strlen - result if you want the output to be @c NUL terminated. - - @param dst - Pointer to output buffer of the size of at least @a dstLen or @NULL. - @param dstLen - Maximal number of characters to be written to the output buffer if - @dst is non-@NULL, unused otherwise. - @param src - Point to the source string, must not be @NULL. - @param - The number of characters of the source string to convert or @c - wxNO_LEN (default parameter) to convert everything up to and - including the terminating @c NUL character(s). - @return - The number of character written (or which would have been written - if it were non-@NULL) to @a dst or @c wxCONV_FAILED on error. - */ - virtual size_t ToWChar(wchar_t* dst, size_t dstLen, - const char* src, - size_t srcLen = wxNO_LEN) const; - - /** - Converts wide character string to multibyte. - - This function has the same semantics as ToWChar() except that it - converts a wide string to multibyte one. As with ToWChar(), it may be - more convenient to use cWC2MB() when working with @c NUL terminated - strings. - - @param dst - Pointer to output buffer of the size of at least @a dstLen or @NULL. - @param dstLen - Maximal number of characters to be written to the output buffer if - @dst is non-@NULL, unused otherwise. - @param src - Point to the source string, must not be @NULL. - @param - The number of characters of the source string to convert or @c - wxNO_LEN (default parameter) to convert everything up to and - including the terminating @c NUL character. - @return - The number of character written (or which would have been written - if it were non-@NULL) to @a dst or @c wxCONV_FAILED on error. - */ - virtual size_t FromWChar(char* dst, size_t dstLen, - const wchar_t* src, - size_t srcLen = wxNO_LEN) const; - - //@{ - /** - Converts from multibyte encoding to Unicode by calling MB2WC() and - allocating a temporary wxWCharBuffer to hold the result. - - The first overload takes a @c NUL-terminated input string. The second - one takes a string of exactly the specified length and the string may - include or not the trailing @c NUL character(s). If the string is not - @c NUL-terminated, a temporary @c NUL-terminated copy of it suitable - for passing to wxMBConv::MB2WC is made, so it is more efficient to - ensure that the string is does have the appropriate number of @c NUL - bytes (which is usually 1 but may be 2 or 4 for UTF-16 or UTF-32, see - wxMBConv::GetMBNulLen), especially for long strings. - - If @a outLen is not-@NULL, it receives the length of the converted - string. - */ - const wxWCharBuffer cMB2WC(const char* in) const; - const wxWCharBuffer cMB2WC(const char* in, size_t inLen, size_t *outLen) const; - //@} - - //@{ - /** - Converts from multibyte encoding to the current wxChar type (which - depends on whether wxUSE_UNICODE is set to 1). - - If wxChar is char, it returns the parameter unaltered. If wxChar is - wchar_t, it returns the result in a wxWCharBuffer. The macro wxMB2WXbuf - is defined as the correct return type (without const). - */ - const char* cMB2WX(const char* psz) const; - const wxWCharBuffer cMB2WX(const char* psz) const; - //@} - - //@{ - /** - Converts from Unicode to multibyte encoding by calling WC2MB and - allocating a temporary wxCharBuffer to hold the result. - - The second overload of this function allows to convert a string of the - given length @e inLen, whether it is @c NUL-terminated or not (for wide - character strings, unlike for the multibyte ones, a single @c NUL is - always enough). But notice that just as with @ref wxMBConv::mb2wc - cMB2WC, it is more efficient to pass an already terminated string to - this function as otherwise a copy is made internally. If @a outLen is - not-@NULL, it receives the length of the converted string. - */ - const wxCharBuffer cWC2MB(const wchar_t* in) const; - const wxCharBuffer cWC2MB(const wchar_t* in, size_t inLen, size_t *outLen) const; - //@} - - //@{ - /** - Converts from Unicode to the current wxChar type. - - If wxChar is wchar_t, it returns the parameter unaltered. If wxChar is - char, it returns the result in a wxCharBuffer. The macro wxWC2WXbuf is - defined as the correct return type (without const). - */ - const wchar_t* cWC2WX(const wchar_t* psz) const; - const wxCharBuffer cWC2WX(const wchar_t* psz) const; - //@} - - //@{ - /** - Converts from the current wxChar type to multibyte encoding. - - If wxChar is char, it returns the parameter unaltered. If wxChar is - wchar_t, it returns the result in a wxCharBuffer. The macro wxWX2MBbuf - is defined as the correct return type (without const). - */ - const char* cWX2MB(const wxChar* psz) const; - const wxCharBuffer cWX2MB(const wxChar* psz) const; - //@} - - //@{ - /** - Converts from the current wxChar type to Unicode. - - If wxChar is wchar_t, it returns the parameter unaltered. If wxChar is - char, it returns the result in a wxWCharBuffer. The macro wxWX2WCbuf is - defined as the correct return type (without const). - */ - const wchar_t* cWX2WC(const wxChar* psz) const; - const wxWCharBuffer cWX2WC(const wxChar* psz) const; - //@} - - /** - @deprecated This function is deprecated, please use ToWChar() instead. - - Converts from a string @a in in multibyte encoding to Unicode putting up to - @a outLen characters into the buffer @e out. - - If @a out is @NULL, only the length of the string which would result - from the conversion is calculated and returned. Note that this is the - length and not size, i.e. the returned value does not include the - trailing @c NUL. But when the function is called with a non-@NULL @a - out buffer, the @a outLen parameter should be one more to allow to - properly @c NUL-terminate the string. - - @param out - The output buffer, may be @NULL if the caller is only - interested in the length of the resulting string - @param in - The NUL-terminated input string, cannot be @NULL - @param outLen - The length of the output buffer but including - NUL, ignored if out is @NULL - - @return The length of the converted string excluding the trailing NUL. - */ - virtual size_t MB2WC(wchar_t* out, const char* in, size_t outLen) const; - - /** - @deprecated This function is deprecated, please use FromWChar() instead. - - Converts from Unicode to multibyte encoding. - The semantics of this function (including the return value meaning) is - the same as for wxMBConv::MB2WC. Notice that when the function is - called with a non-@NULL buffer, the @a n parameter should be the size - of the buffer and so it should take into account the trailing @c NUL, - which might take two or four bytes for some encodings (UTF-16 and - UTF-32) and not one. - */ - virtual size_t WC2MB(char* buf, const wchar_t* psz, size_t n) const; -}; - - -/** - @class wxMBConvUTF7 - @wxheader{strconv.h} - - This class converts between the UTF-7 encoding and Unicode. - It has one predefined instance, @b wxConvUTF7. - - Notice that, unlike all the other conversion objects, this converter is - stateful, i.e. it remembers its state from the last call to its ToWChar() - or FromWChar() and assumes it is called on the continuation of the same - string when the same method is called again. This assumption is only made - if an explicit length is specified as parameter to these functions as if an - entire @c NUL terminated string is processed the state doesn't need to be - remembered. - - This also means that, unlike the other predefined conversion objects, - @b wxConvUTF7 is @em not thread-safe. - - @library{wxbase} - @category{conv} - - @see wxMBConvUTF8, @ref overview_mbconv "wxMBConv classes overview" -*/ -class wxMBConvUTF7 : public wxMBConv -{ -}; - - - -/** - @class wxMBConvUTF8 - @wxheader{strconv.h} - - This class converts between the UTF-8 encoding and Unicode. - It has one predefined instance, @b wxConvUTF8. - - @library{wxbase} - @category{conv} - - @see wxMBConvUTF7, @ref overview_mbconv "wxMBConv classes overview" -*/ -class wxMBConvUTF8 : public wxMBConv -{ -}; - - - -/** - @class wxMBConvUTF16 - @wxheader{strconv.h} - - This class is used to convert between multibyte encodings and UTF-16 Unicode - encoding (also known as UCS-2). - - Unlike UTF-8 encoding, UTF-16 uses words and not bytes and hence depends - on the byte ordering: big or little endian. Hence this class is provided in - two versions: wxMBConvUTF16LE and wxMBConvUTF16BE and wxMBConvUTF16 itself - is just a typedef for one of them (native for the given platform, e.g. LE - under Windows and BE under Mac). - - @library{wxbase} - @category{conv} - - @see wxMBConvUTF8, wxMBConvUTF32, @ref overview_mbconv "wxMBConv classes overview" -*/ -class wxMBConvUTF16 : public wxMBConv -{ -}; - - -/** - @class wxMBConvUTF32 - @wxheader{strconv.h} - - This class is used to convert between multibyte encodings and UTF-32 - Unicode encoding (also known as UCS-4). - Unlike UTF-8 encoding, UTF-32 uses (double) words and not bytes and hence - depends on the byte ordering: big or little endian. Hence this class is - provided in two versions: wxMBConvUTF32LE and wxMBConvUTF32BE and - wxMBConvUTF32 itself is just a typedef for one of them (native for the - given platform, e.g. LE under Windows and BE under Mac). - - @library{wxbase} - @category{conv} - - @see wxMBConvUTF8, wxMBConvUTF16, @ref overview_mbconv "wxMBConv classes overview" -*/ -class wxMBConvUTF32 : public wxMBConv -{ -}; - - - - -/** - @class wxCSConv - @wxheader{strconv.h} - - This class converts between any character set supported by the system and - Unicode. - - Please notice that this class uses system-provided conversion functions, - e.g. @c MultiByteToWideChar() and @c WideCharToMultiByte() under MSW and @c - iconv(3) under Unix systems and as such may support different encodings and - different encoding names on different platforms (although all relatively - common encodings are supported should be supported everywhere). - - It has one predefined instance, @b wxConvLocal, for the default user - character set. - - @library{wxbase} - @category{conv} - - @see wxMBConv, wxEncodingConverter, @ref overview_mbconv "wxMBConv classes overview" -*/ -class wxCSConv : public wxMBConv -{ -public: - /** - Constructor. - - You can specify the name of the character set you want to convert - from/to. If the character set name is not recognized, ISO 8859-1 is - used as fall back, use IsOk() to test for this. - - @param charset The name of the encoding, shouldn't be empty. - */ - wxCSConv(const wxString& charset); - - /** - Constructor. - - You can specify an encoding constant for the character set you want to - convert from/to. Use IsOk() after construction to check whether the - encoding is supported by the current system. - - @param encoding Any valid (i.e. not wxFONTENCODING_MAX) font encoding. - */ - wxCSConv(wxFontEncoding encoding); - - /** - Returns @true if the charset (or the encoding) given at constructor is - really available to use. - - Returns @false if ISO 8859-1 will be used instead. - - Note this does not mean that a given string will be correctly - converted. A malformed string may still make conversion functions - return @c wxCONV_FAILED. - - @since 2.8.2 - */ - bool IsOk() const; -}; - - - -/** - @class wxMBConvFile - @wxheader{strconv.h} - - This class used to define the class instance @b wxConvFileName, but - nowadays @b wxConvFileName is either of type wxConvLibc (on most platforms) - or wxConvUTF8 (on MacOS X). - - @b wxConvFileName converts filenames between filesystem multibyte encoding - and Unicode. @b wxConvFileName can also be set to a something else at - run-time which is used e.g. by wxGTK to use a class which checks the - environment variable @b G_FILESYSTEM_ENCODING indicating that filenames - should not be interpreted as UTF8 and also for converting invalid UTF8 - characters (e.g. if there is a filename in iso8859_1) to strings with octal - values. - - Since some platforms (such as Win32) use Unicode in the filenames, - and others (such as Unix) use multibyte encodings, this class should only - be used directly if wxMBFILES is defined to 1. A convenience macro, - @c wxFNCONV, is defined to @c wxConvFileName->cWX2MB in this case. You - could use it like this: - - @code - wxChar *name = wxT("rawfile.doc"); - FILE *fil = fopen(wxFNCONV(name), "r"); - @endcode - - (although it would be better to just use wxFopen(name, "r") in this - particular case, you only need to use this class for functions taking file - names not wrapped by wxWidgets.) - - @library{wxbase} - @category{conv} - - @see @ref overview_mbconv "wxMBConv classes overview" -*/ -class wxMBConvFile : public wxMBConv -{ -public: -}; diff --git a/interface/stream.h b/interface/stream.h deleted file mode 100644 index 532ac2d28d..0000000000 --- a/interface/stream.h +++ /dev/null @@ -1,774 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: stream.h -// Purpose: interface of wxCountingOutputStream -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxCountingOutputStream - @wxheader{stream.h} - - wxCountingOutputStream is a specialized output stream which does not write any - data anywhere, - instead it counts how many bytes would get written if this were a normal - stream. This - can sometimes be useful or required if some data gets serialized to a stream or - compressed - by using stream compression and thus the final size of the stream cannot be - known other - than pretending to write the stream. One case where the resulting size would - have to be - known is if the data has to be written to a piece of memory and the memory has - to be - allocated before writing to it (which is probably always the case when writing - to a - memory stream). - - @library{wxbase} - @category{streams} -*/ -class wxCountingOutputStream : public wxOutputStream -{ -public: - /** - Creates a wxCountingOutputStream object. - */ - wxCountingOutputStream(); - - /** - Destructor. - */ - ~wxCountingOutputStream(); - - /** - Returns the current size of the stream. - */ - size_t GetSize() const; -}; - - - -/** - @class wxBufferedInputStream - @wxheader{stream.h} - - This stream acts as a cache. It caches the bytes read from the specified - input stream (See wxFilterInputStream). - It uses wxStreamBuffer and sets the default in-buffer size to 1024 bytes. - This class may not be used without some other stream to read the data - from (such as a file stream or a memory stream). - - @library{wxbase} - @category{streams} - - @see wxStreamBuffer, wxInputStream, wxBufferedOutputStream -*/ -class wxBufferedInputStream : public wxFilterInputStream -{ -public: - -}; - - - -/** - @class wxStreamBuffer - @wxheader{stream.h} - - - @library{wxbase} - @category{streams} - - @see wxStreamBase -*/ -class wxStreamBuffer -{ -public: - //@{ - /** - Constructor. It initializes the stream buffer with the data of the specified - stream buffer. The new stream buffer has the same attributes, size, position - and they share the same buffer. This will cause problems if the stream to - which the stream buffer belong is destroyed and the newly cloned stream - buffer continues to be used, trying to call functions in the (destroyed) - stream. It is advised to use this feature only in very local area of the - program. - - @see @ref setbufferio() wxStreamBuffer:SetBufferIO - */ - wxStreamBuffer(wxStreamBase& stream, BufMode mode); - wxStreamBuffer(BufMode mode); - wxStreamBuffer(const wxStreamBuffer& buffer); - //@} - - /** - Destructor. It finalizes all IO calls and frees all internal buffers if - necessary. - */ - wxStreamBuffer(); - - /** - Fill the IO buffer. - */ - bool FillBuffer(); - - /** - Toggles the fixed flag. Usually this flag is toggled at the same time as - @e flushable. This flag allows (when it has the @false value) or forbids - (when it has the @true value) the stream buffer to resize dynamically the IO - buffer. - - @see SetBufferIO() - */ - void Fixed(bool fixed); - - /** - Flushes the IO buffer. - */ - bool FlushBuffer(); - - /** - Toggles the flushable flag. If @a flushable is disabled, no data are sent - to the parent stream. - */ - void Flushable(bool flushable); - - /** - Returns a pointer on the end of the stream buffer. - */ - void* GetBufferEnd() const; - - /** - Returns a pointer on the current position of the stream buffer. - */ - void* GetBufferPos() const; - - /** - Returns the size of the buffer. - */ - size_t GetBufferSize() const; - - /** - Returns a pointer on the start of the stream buffer. - */ - void* GetBufferStart() const; - - /** - Gets a single char from the stream buffer. It acts like the Read call. - - @see Read() - */ - char GetChar(); - - /** - Returns the amount of available data in the buffer. - */ - size_t GetDataLeft(); - - /** - Returns the current position (counted in bytes) in the stream buffer. - */ - off_t GetIntPosition() const; - - /** - Returns the amount of bytes read during the last IO call to the parent stream. - */ - size_t GetLastAccess() const; - - /** - Puts a single char to the stream buffer. - - @see Read() - */ - void PutChar(char c); - - //@{ - /** - Copies data to @e buffer. The function returns when @a buffer is full or when - there isn't - any more data in the current buffer. - - @see Write() - */ - size_t Read(void* buffer, size_t size); - Return value size_t Read(wxStreamBuffer* buffer); - //@} - - /** - Resets to the initial state variables concerning the buffer. - */ - void ResetBuffer(); - - /** - Changes the current position. - @a mode may be one of the following: - - @b wxFromStart - - The position is counted from the start of the stream. - - @b wxFromCurrent - - The position is counted from the current position of the stream. - - @b wxFromEnd - - The position is counted from the end of the stream. - - @return Upon successful completion, it returns the new offset as - measured in bytes from the beginning of the stream. - Otherwise, it returns wxInvalidOffset. - */ - off_t Seek(off_t pos, wxSeekMode mode); - - //@{ - /** - Destroys or invalidates the previous IO buffer and allocates a new one of the - specified size. - - @see Fixed(), Flushable() - */ - void SetBufferIO(char* buffer_start, char* buffer_end); - Remarks See also - wxStreamBuffer constructor - - wxStreamBuffer::Fixed - - wxStreamBuffer::Flushable - void SetBufferIO(size_t bufsize); - //@} - - /** - Sets the current position (in bytes) in the stream buffer. - */ - void SetIntPosition(size_t pos); - - /** - Returns the parent stream of the stream buffer. - */ - wxStreamBase* Stream(); - - /** - Gets the current position in the stream. This position is calculated from - the @e real position in the stream and from the internal buffer position: so - it gives you the position in the @e real stream counted from the start of - the stream. - - @return Returns the current position in the stream if possible, - wxInvalidOffset in the other case. - */ - off_t Tell() const; - - /** - Truncates the buffer to the current position. - Note: Truncate() cannot be used to enlarge the buffer. This is - usually not needed since the buffer expands automatically. - */ - void Truncate(); - - //@{ - /** - See Read(). - */ - size_t Write(const void* buffer, size_t size); - size_t Write(wxStreamBuffer* buffer); - //@} -}; - - - -/** - @class wxOutputStream - @wxheader{stream.h} - - wxOutputStream is an abstract base class which may not be used directly. - - @library{wxbase} - @category{streams} -*/ -class wxOutputStream : public wxStreamBase -{ -public: - /** - Creates a dummy wxOutputStream object. - */ - wxOutputStream(); - - /** - Destructor. - */ - ~wxOutputStream(); - - /** - Closes the stream, returning @false if an error occurs. The - stream is closed implicitly in the destructor if Close() is not - called explicitly. - If this stream wraps another stream or some other resource such - as a file, then the underlying resource is closed too if it is owned - by this stream, or left open otherwise. - */ - bool Close(); - - /** - Returns the number of bytes written during the last - Write(). It may return 0 even if there is no - error on the stream if it is only temporarily impossible to write to it. - */ - size_t LastWrite() const; - - /** - Puts the specified character in the output queue and increments the - stream position. - */ - void PutC(char c); - - /** - Changes the stream current position. - - @param pos - Offset to seek to. - @param mode - One of wxFromStart, wxFromEnd, wxFromCurrent. - - @return The new stream position or wxInvalidOffset on error. - */ - off_t SeekO(off_t pos, wxSeekMode mode = wxFromStart); - - /** - Returns the current stream position. - */ - off_t TellO() const; - - //@{ - /** - Reads data from the specified input stream and stores them - in the current stream. The data is read until an error is raised - by one of the two streams. - */ - wxOutputStream Write(const void* buffer, size_t size); - wxOutputStream Write(wxInputStream& stream_in); - //@} -}; - - - -/** - @class wxFilterClassFactory - @wxheader{stream.h} - - Allows the creation of filter streams to handle compression formats such - as gzip and bzip2. - - For example, given a filename you can search for a factory that will - handle it and create a stream to decompress it: - - @code - factory = wxFilterClassFactory::Find(filename, wxSTREAM_FILEEXT); - if (factory) - stream = factory-NewStream(new wxFFileInputStream(filename)); - @endcode - - wxFilterClassFactory::Find can also search - for a factory by MIME type, HTTP encoding or by wxFileSystem protocol. - The available factories can be enumerated - using @ref wxFilterClassFactory::getfirst "GetFirst() and GetNext". - - @library{wxbase} - @category{FIXME} - - @see wxFilterInputStream, wxFilterOutputStream, wxArchiveClassFactory, @ref - overview_wxarc "Archive formats such as zip" -*/ -class wxFilterClassFactory : public wxObject -{ -public: - /** - Returns @true if this factory can handle the given protocol, MIME type, HTTP - encoding or file extension. - When using wxSTREAM_FILEEXT for the second parameter, the first parameter - can be a complete filename rather than just an extension. - */ - bool CanHandle(const wxString& protocol, - wxStreamProtocolType type = wxSTREAM_PROTOCOL) const; - - /** - A static member that finds a factory that can handle a given protocol, MIME - type, HTTP encoding or file extension. Returns a pointer to the class - factory if found, or @NULL otherwise. It does not give away ownership of the - factory. - When using wxSTREAM_FILEEXT for the second parameter, the first parameter - can be a complete filename rather than just an extension. - */ - static const wxFilterClassFactory* Find(const wxString& protocol, - wxStreamProtocolType type = wxSTREAM_PROTOCOL); - - //@{ - /** - GetFirst and GetNext can be used to enumerate the available factories. - For example, to list them: - - GetFirst()/GetNext() return a pointer to a factory or @NULL if no more - are available. They do not give away ownership of the factory. - */ - static const wxFilterClassFactory* GetFirst() const; - const wxFilterClassFactory* GetNext() const; - //@} - - /** - Returns the wxFileSystem protocol supported by this factory. Equivalent - to wxString(*GetProtcols()). - */ - wxString GetProtocol() const; - - /** - Returns the protocols, MIME types, HTTP encodings or file extensions - supported by this factory, as an array of null terminated strings. It does - not give away ownership of the array or strings. - For example, to list the file extensions a factory supports: - */ - const wxChar* const* GetProtocols(wxStreamProtocolType type = wxSTREAM_PROTOCOL) const; - - //@{ - /** - Create a new input or output stream to decompress or compress a given stream. - If the parent stream is passed as a pointer then the new filter stream - takes ownership of it. If it is passed by reference then it does not. - */ - wxFilterInputStream* NewStream(wxInputStream& stream) const; - const wxFilterOutputStream* NewStream(wxOutputStream& stream) const; - const wxFilterInputStream* NewStream(wxInputStream* stream) const; - const wxFilterOutputStream* NewStream(wxOutputStream* stream) const; - //@} - - /** - Remove the file extension of @a location if it is one of the file - extensions handled by this factory. - */ - wxString PopExtension(const wxString& location) const; - - /** - Adds this class factory to the list returned - by @ref getfirst() GetFirst()/GetNext. - It is not necessary to do this to use the filter streams. It is usually - used when implementing streams, typically the implementation will - add a static instance of its factory class. - It can also be used to change the order of a factory already in the list, - bringing it to the front. This isn't a thread safe operation - so can't be done when other threads are running that will be using the list. - The list does not take ownership of the factory. - */ - void PushFront(); - - /** - Removes this class factory from the list returned - by @ref getfirst() GetFirst()/GetNext. - Removing from the list isn't a thread safe operation - so can't be done when other threads are running that will be using the list. - The list does not own the factories, so removing a factory does not delete it. - */ - void Remove(); -}; - - - -/** - @class wxFilterOutputStream - @wxheader{stream.h} - - A filter stream has the capability of a normal - stream but it can be placed on top of another stream. So, for example, it - can compress, encrypt the data which are passed to it and write them to another - stream. - - @library{wxbase} - @category{streams} - - @see wxFilterClassFactory, wxFilterInputStream -*/ -class wxFilterOutputStream : public wxOutputStream -{ -public: - //@{ - /** - Initializes a "filter" stream. - If the parent stream is passed as a pointer then the new filter stream - takes ownership of it. If it is passed by reference then it does not. - */ - wxFilterOutputStream(wxOutputStream& stream); - wxFilterOutputStream(wxOutputStream* stream); - //@} -}; - - - -/** - @class wxFilterInputStream - @wxheader{stream.h} - - A filter stream has the capability of a normal stream but it can be placed on - top - of another stream. So, for example, it can uncompress or decrypt the data which - are read - from another stream and pass it to the requester. - - @library{wxbase} - @category{streams} - - @see wxFilterClassFactory, wxFilterOutputStream -*/ -class wxFilterInputStream : public wxInputStream -{ -public: - //@{ - /** - Initializes a "filter" stream. - If the parent stream is passed as a pointer then the new filter stream - takes ownership of it. If it is passed by reference then it does not. - */ - wxFilterInputStream(wxInputStream& stream); - wxFilterInputStream(wxInputStream* stream); - //@} -}; - - - -/** - @class wxBufferedOutputStream - @wxheader{stream.h} - - This stream acts as a cache. It caches the bytes to be written to the specified - output stream (See wxFilterOutputStream). The - data is only written when the cache is full, when the buffered stream is - destroyed or when calling SeekO(). - - This class may not be used without some other stream to write the data - to (such as a file stream or a memory stream). - - @library{wxbase} - @category{streams} - - @see wxStreamBuffer, wxOutputStream -*/ -class wxBufferedOutputStream : public wxFilterOutputStream -{ -public: - /** - Creates a buffered stream using a buffer of a default size of 1024 bytes for - cashing - the stream @e parent. - */ - wxBufferedOutputStream(const wxOutputStream& parent); - - /** - Destructor. Calls Sync() and destroys the internal buffer. - */ - ~wxBufferedOutputStream(); - - /** - Calls Sync() and changes the stream position. - */ - off_t SeekO(off_t pos, wxSeekMode mode); - - /** - Flushes the buffer and calls Sync() on the parent stream. - */ - void Sync(); -}; - - - -/** - @class wxInputStream - @wxheader{stream.h} - - wxInputStream is an abstract base class which may not be used directly. - - @library{wxbase} - @category{streams} -*/ -class wxInputStream : public wxStreamBase -{ -public: - /** - Creates a dummy input stream. - */ - wxInputStream(); - - /** - Destructor. - */ - ~wxInputStream(); - - /** - Returns @true if some data is available in the stream right now, so that - calling Read() wouldn't block. - */ - bool CanRead() const; - - /** - Returns @true after an attempt has been made to read past the end of the - stream. - */ - bool Eof() const; - - /** - Returns the first character in the input queue and removes it, - blocking until it appears if necessary. - */ - char GetC(); - - /** - Returns the last number of bytes read. - */ - size_t LastRead() const; - - /** - Returns the first character in the input queue without removing it. - */ - char Peek(); - - //@{ - /** - Reads data from the input queue and stores it in the specified output stream. - The data is read until an error is raised by one of the two streams. - - @return This function returns a reference on the current object, so the - user can test any states of the stream right away. - */ - wxInputStream Read(void* buffer, size_t size); - Warning Return value - This function returns a reference on the current object, so the user can test - any states of the stream right away. - wxInputStream& Read(wxOutputStream& stream_out); - //@} - - /** - Changes the stream current position. - - @param pos - Offset to seek to. - @param mode - One of wxFromStart, wxFromEnd, wxFromCurrent. - - @return The new stream position or wxInvalidOffset on error. - */ - off_t SeekI(off_t pos, wxSeekMode mode = wxFromStart); - - /** - Returns the current stream position. - */ - off_t TellI() const; - - //@{ - /** - This function acts like the previous one except that it takes only one - character: it is sometimes shorter to use than the generic function. - */ - size_t Ungetch(const char* buffer, size_t size); - Return value bool Ungetch(char c); - //@} -}; - - - -/** - @class wxStreamBase - @wxheader{stream.h} - - This class is the base class of most stream related classes in wxWidgets. It - must - not be used directly. - - @library{wxbase} - @category{streams} - - @see wxStreamBuffer -*/ -class wxStreamBase -{ -public: - /** - Creates a dummy stream object. It doesn't do anything. - */ - wxStreamBase(); - - /** - Destructor. - */ - ~wxStreamBase(); - - /** - This function returns the last error. - - @b wxSTREAM_NO_ERROR - - No error occurred. - - @b wxSTREAM_EOF - - An End-Of-File occurred. - - @b wxSTREAM_WRITE_ERROR - - A generic error occurred on the last write call. - - @b wxSTREAM_READ_ERROR - - A generic error occurred on the last read call. - */ - wxStreamError GetLastError() const; - - /** - Returns the length of the stream in bytes. If the length cannot be determined - (this is always the case for socket streams for example), returns - @c wxInvalidOffset. - - @since 2.5.4 - */ - wxFileOffset GetLength() const; - - /** - GetLength() - This function returns the size of the stream. For example, for a file it is the - size of the file. - */ - size_t GetSize() const; - - /** - Returns @true if no error occurred on the stream. - - @see GetLastError() - */ - virtual bool IsOk() const; - - /** - Returns @true if the streams supports seeking to arbitrary offsets. - */ - bool IsSeekable() const; - - /** - Internal function. It is called when the stream wants to read data of the - specified size. It should return the size that was actually read. - */ - size_t OnSysRead(void* buffer, size_t bufsize); - - /** - Internal function. It is called when the stream needs to change the - current position. - */ - off_t OnSysSeek(off_t pos, wxSeekMode mode); - - /** - Internal function. Is is called when the stream needs to know the - real position. - */ - off_t OnSysTell() const; - - /** - See OnSysRead(). - */ - size_t OnSysWrite(const void* buffer, size_t bufsize); -}; - diff --git a/interface/string.h b/interface/string.h deleted file mode 100644 index 25c36a1d8d..0000000000 --- a/interface/string.h +++ /dev/null @@ -1,1377 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: string.h -// Purpose: interface of wxStringBuffer -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxStringBuffer - @wxheader{string.h} - - This tiny class allows to conveniently access the wxString - internal buffer as a writable pointer without any risk of forgetting to restore - the string to the usable state later. - - For example, assuming you have a low-level OS function called - @c GetMeaningOfLifeAsString(char *) returning the value in the provided - buffer (which must be writable, of course) you might call it like this: - - @code - wxString theAnswer; - GetMeaningOfLifeAsString(wxStringBuffer(theAnswer, 1024)); - if ( theAnswer != "42" ) - { - wxLogError("Something is very wrong!"); - } - @endcode - - Note that the exact usage of this depends on whether on not wxUSE_STL is - enabled. If - wxUSE_STL is enabled, wxStringBuffer creates a separate empty character buffer, - and - if wxUSE_STL is disabled, it uses GetWriteBuf() from wxString, keeping the same - buffer - wxString uses intact. In other words, relying on wxStringBuffer containing the - old - wxString data is probably not a good idea if you want to build your program in - both - with and without wxUSE_STL. - - @library{wxbase} - @category{FIXME} -*/ -class wxStringBuffer -{ -public: - /** - Constructs a writable string buffer object associated with the given string - and containing enough space for at least @a len characters. Basically, this - is equivalent to calling wxString::GetWriteBuf and - saving the result. - */ - wxStringBuffer(const wxString& str, size_t len); - - /** - Restores the string passed to the constructor to the usable state by calling - wxString::UngetWriteBuf on it. - */ - ~wxStringBuffer(); - - /** - Returns the writable pointer to a buffer of the size at least equal to the - length specified in the constructor. - */ - wxStringCharType* operator wxStringCharType *(); -}; - - - -/** - @class wxString - @wxheader{string.h} - - wxString is a class representing a Unicode character string. - wxString uses @c std::string internally to store its content - unless this is not supported by the compiler or disabled - specifically when building wxWidgets. Therefore wxString - inherits many features from @c std::string's. Most - implementations of @std::string are thread-safe and don't - use reference counting. By default, wxString uses @c std::string - internally even if wxUSE_STL is not defined. - - Since wxWidgets 3.0 wxString internally uses UCS-2 (basically 2-byte per - character wchar_t) under Windows and UTF-8 under Unix, Linux and - OS X to store its content. Much work has been done to make existing - code using ANSI string literals work as before. If you need to have a - wxString that uses wchar_t on Unix and Linux, too, you can specify - this on the command line with the @c configure @c --disable-utf8 switch. - - As a consequence of this change, iterating over a wxString by index - can become inefficient in UTF8 mode and iterators should be used instead: - - @code - wxString s = "hello"; - wxString::const_iterator i; - for (i = s.begin(); i != s.end(); ++i) - { - wxUniChar uni_ch = *i; - // do something with it - } - @endcode - - Please see the - @ref overview_string "wxString overview" and the - @ref overview_unicode "Unicode overview" for more information - about it. - - wxString uses the current locale encoding to convert any C string - literal to Unicode. The same is done for converting to and from - @c std::string and for the return value of c_str(). For this - conversion, the @a wxConvLibc class instance is used. See wxCSConv and wxMBConv. - - wxString implements most of the methods of the @c std::string class. - These standard functions are only listed here, but they are not - fully documented in this manual. Please see the STL documentation. - The behaviour of all these functions is identical to the behaviour - described there. - - You may notice that wxString sometimes has several functions which do - the same thing like, for example, Length(), Len() and length() which - all return the string length. In all cases of such duplication the - @c std::string compatible method should be used. - - Anything may be concatenated (appended to) with a string. However, you can't - append something to a C string (including literal constants), so to do this it - should be converted to a wxString first. - - @li operator<<() - @li operator+=() - @li operator+() - @li Append() - @li Prepend() - - A string may be constructed either from a C string, (some number of copies of) - a single character or a wide (UNICODE) string. For all constructors (except the - default which creates an empty string) there is also a corresponding assignment - operator. - - @li wxString() - @li operator=() - @li ~wxString() - - The MakeXXX() variants modify the string in place, while the other functions - return a new string which contains the original text converted to the upper or - lower case and leave the original string unchanged. - - @li MakeUpper() - @li Upper() - @li MakeLower() - @li Lower() - - Many functions in this section take a character index in the string. As with C - strings and/or arrays, the indices start from 0, so the first character of a - string is string[0]. Attempt to access a character beyond the end of the - string (which may be even 0 if the string is empty) will provoke an assert - failure in @ref overview_debugging "debug build", but no checks are - done in release builds. - This section also contains both implicit and explicit conversions to C style - strings. Although implicit conversion is quite convenient, it is advised to use - explicit c_str() method for the sake of clarity. - - @li GetChar() - @li GetWritableChar() - @li SetChar() - @li Last() - @li operator[]() - @li c_str() - @li mb_str() - @li wc_str() - @li fn_str() - - The default comparison function Cmp() is case-sensitive and - so is the default version of IsSameAs(). For case - insensitive comparisons you should use CmpNoCase() or - give a second parameter to IsSameAs. This last function is may be more - convenient if only equality of the strings matters because it returns a boolean - @true value if the strings are the same and not 0 (which is usually @false - in C)as Cmp() does. - Matches() is a poor man's regular expression matcher: it only understands - '*' and '?' metacharacters in the sense of DOS command line interpreter. - StartsWith() is helpful when parsing a line of text which should start - with some predefined prefix and is more efficient than doing direct string - comparison as you would also have to precalculate the length of the prefix then. - - @li Cmp() - @li CmpNoCase() - @li IsSameAs() - @li Matches() - @li StartsWith() - @li EndsWith() - - The string provides functions for conversion to signed and unsigned integer and - floating point numbers. All three functions take a pointer to the variable to - put the numeric value in and return @true if the @b entire string could be - converted to a number. - - @li ToLong() - @li ToLongLong() - @li ToULong() - @li ToULongLong() - @li ToDouble() - - These are "advanced" functions and they will be needed quite rarely. - Alloc() and Shrink() are only interesting for optimization purposes. - wxStringBuffer and wxStringBufferLength classes may be very useful - when working with some external API which requires the caller to provide - a writable buffer. - - @li Alloc() - @li Shrink() - @li wxStringBuffer - @li wxStringBufferLength - - Misc. other string functions. - - @li Trim() - @li Truncate() - @li Pad() - - These functions return the string length and check whether the string - is empty or empty it. - - @li Len() - @li IsEmpty() - @li operator!() - @li Empty() - @li Clear() - - - These functions allow to extract substring from this string. All of them don't - modify the original string and return a new string containing the extracted - substring. - - @li Mid() - @li operator()() - @li Left() - @li Right() - @li BeforeFirst() - @li BeforeLast() - @li AfterFirst() - @li AfterLast() - @li StartsWith() - @li EndsWith() - - These functions replace the standard @e strchr() and @e strstr() - functions. - - @li Find() - @li Replace() - - Both formatted versions (Printf/() and stream-like insertion operators - exist (for basic types only). Additionally, the Format() function allows - to use simply append formatted value to a string: - - @li Format() - @li FormatV() - @li Printf() - @li PrintfV() - @li operator>>() - - These functions are deprecated, please consider using new wxWidgets 2.0 - functions instead of them (or, even better, std::string compatible variants). - - Contains(), First(), Freq(), IsAscii(), IsNull(), - IsNumber(), IsWord(), Last(), Length(), LowerCase(), Remove(), Strip(), - SubString(), UpperCase() - - @library{wxbase} - @category{data} - - @stdobjects - ::Objects:, ::wxEmptyString, - - @see @ref overview_string "wxString overview", @ref overview_unicode - "Unicode overview" -*/ -class wxString -{ -public: - /** - An 'invalid' value for string index - */ - static const size_t npos; - - /** - @name Standard types - */ - //@{ - typedef wxUniChar value_type; - typedef wxUniChar char_type; - typedef wxUniCharRef reference; - typedef wxChar* pointer; - typedef const wxChar* const_pointer; - typedef size_t size_type; - typedef wxUniChar const_reference; - //@} - - /** - Default constructor - */ - wxString(); - - /** - Creates a string from another string. Just increases the ref - count by 1. - */ - wxString(const wxString& stringSrc); - - - /** - Constructs a string from the string literal @e psz using - the current locale encoding to convert it to Unicode (wxConvLibc). - */ - wxString(const char *psz); - - /** - Constructs a string from the string literal @e psz using - @e conv to convert it Unicode. - */ - wxString(const char *psz, const wxMBConv& conv); - - /** - Constructs a string from the first @e nLength character of the string literal @e psz using - the current locale encoding to convert it to Unicode (wxConvLibc). - */ - wxString(const char *psz, size_t nLength); - - /** - Constructs a string from the first @e nLength character of the string literal @e psz using - @e conv to convert it Unicode. - */ - wxString(const char *psz, const wxMBConv& conv, size_t nLength); - - /** - Constructs a string from the string literal @e pwz. - */ - wxString(const wchar_t *pwz); - - /** - Constructs a string from the first @e nLength characters of the string literal @e pwz. - */ - wxString(const wchar_t *pwz, size_t nLength); - - /** - Constructs a string from @e buf using the using - the current locale encoding to convert it to Unicode. - */ - wxString(const wxCharBuffer& buf); - - /** - Constructs a string from @e buf. - */ - wxString(const wxWCharBuffer& buf); - - /** - Constructs a string from @e str using the using the current locale encoding - to convert it to Unicode (wxConvLibc). - */ - wxString(const std::string& str); - - /** - Constructs a string from @e str. - */ - wxString(const std::wstring& str); - - - /** - String destructor. Note that this is not virtual, so wxString must not be - inherited from. - */ - ~wxString(); - - /** - Gets all the characters after the first occurrence of @e ch. - Returns the empty string if @e ch is not found. - */ - wxString AfterFirst(wxUniChar ch) const; - - /** - Gets all the characters after the last occurrence of @e ch. - Returns the whole string if @e ch is not found. - */ - wxString AfterLast(wxUniChar ch) const; - - /** - Preallocate enough space for wxString to store @a nLen characters. - - Please note that this method does the same thing as the standard - reserve() one and shouldn't be used in new code. - - This function may be used to increase speed when the string is - constructed by repeated concatenation as in - - @code - // delete all vowels from the string - wxString DeleteAllVowels(const wxString& original) - { - wxString result; - - size_t len = original.length(); - - result.Alloc(len); - - for ( size_t n = 0; n < len; n++ ) - { - if ( strchr("aeuio", tolower(original[n])) == NULL ) - result += original[n]; - } - - return result; - } - @endcode - - because it will avoid the need to reallocate string memory many times - (in case of long strings). Note that it does not set the maximal length - of a string -- it will still expand if more than @a nLen characters are - stored in it. Also, it does not truncate the existing string (use - Truncate() for this) even if its current length is greater than @a nLen. - - @return @true if memory was successfully allocated, @false otherwise. - */ - bool Alloc(size_t nLen); - - /** - Appends the string literal @e psz. - */ - wxString& Append(const char* psz); - - /** - Appends the wide string literal @e pwz. - */ - wxString& Append(const wchar_t* pwz) - - /** - Appends the string literal @e psz with max length @e nLen. - */ - wxString& Append(const char* psz, size_t nLen); - - /** - Appends the wide string literal @e psz with max length @e nLen. - */ - wxString& Append(const wchar_t* pwz, size_t nLen) - - /** - Appends the string @e s. - */ - wxString &Append(const wxString &s); - - /** - Appends the character @e ch @e count times. - */ - wxString &Append(wxUniChar ch, size_t count = 1u); - - /** - Gets all characters before the first occurrence of @e ch. - Returns the whole string if @a ch is not found. - */ - wxString BeforeFirst(wxUniChar ch) const; - - /** - Gets all characters before the last occurrence of @e ch. - Returns the empty string if @a ch is not found. - */ - wxString BeforeLast(wxUniChar ch) const; - - - /** - Empties the string and frees memory occupied by it. - See also: Empty() - */ - void Clear(); - - /** - Returns a deep copy of the string. - - That is, the returned string is guaranteed to not share data with this - string when using reference-counted wxString implementation. - - This method is primarily useful for passing strings between threads - (because wxString is not thread-safe). Unlike creating a copy using - @c wxString(c_str()), Clone() handles embedded NULs correctly. - - @since 2.9.0 - */ - wxString Clone() const; - - /** - Case-sensitive comparison. - Returns a positive value if the string is greater than the argument, - zero if it is equal to it or a negative value if it is less than the - argument (same semantics as the standard @c strcmp() function). - - See also CmpNoCase(), IsSameAs(). - */ - int Cmp(const wxString& s) const; - - /** - Case-insensitive comparison. - Returns a positive value if the string is greater than the argument, - zero if it is equal to it or a negative value if it is less than the - argument (same semantics as the standard @c strcmp() function). - - See also Cmp(), IsSameAs(). - */ - int CmpNoCase(const wxString& s) const; - - - //@{ - /** - Comparison operators - */ - bool operator ==(const wxString& x, const wxString& y); - bool operator ==(const wxString& x, wxUniChar ch); - bool operator !=(const wxString& x, const wxString& y); - bool operator !=(const wxString& x, wxUniChar ch); - bool operator(const wxString& x, const wxString& y); - bool operator(const wxString& x, wxUniChar ch); - bool operator =(const wxString& x, const wxString& y); - bool operator =(const wxString& x, wxUniChar ch); - bool operator(const wxString& x, const wxString& y); - bool operator(const wxString& x, wxUniChar ch); - bool operator =(const wxString& x, const wxString& y); - bool operator =(const wxString& x, wxUniChar ch); - //@} - - - /** - Returns @true if target appears anywhere in wxString; else @false. - This is a wxWidgets 1.xx compatibility function; you should not use it in new - code. - */ - bool Contains(const wxString& str) const; - - - /** - Makes the string empty, but doesn't free memory occupied by the string. - See also: Clear(). - */ - void Empty(); - - /** - This function can be used to test if the string ends with the specified - @e suffix. If it does, the function will return @true and put the - beginning of the string before the suffix into @e rest string if it is not - @NULL. Otherwise, the function returns @false and doesn't - modify the @e rest. - */ - bool EndsWith(const wxString& suffix, wxString *rest = NULL) const; - - /** - Searches for the given character @e ch. Returns the position or - @c wxNOT_FOUND if not found. - */ - int Find(wxUniChar ch, bool fromEnd = false) const; - - /** - Searches for the given string @e sub. Returns the starting position or - @c wxNOT_FOUND if not found. - */ - int Find(const wxString& sub) const; - - //@{ - /** - Same as Find(). - This is a wxWidgets 1.xx compatibility function; - you should not use it in new code. - */ - int First(wxUniChar ch) const; - int First(const wxString& str) const; - //@} - - /** - This static function returns the string containing the result of calling - Printf() with the passed parameters on it. - - @see FormatV(), Printf() - */ - static wxString Format(const wxChar format, ...); - - /** - This static function returns the string containing the result of calling - PrintfV() with the passed parameters on it. - - @see Format(), PrintfV() - */ - static wxString FormatV(const wxChar format, va_list argptr); - - /** - Returns the number of occurrences of @e ch in the string. - This is a wxWidgets 1.xx compatibility function; you should not - use it in new code. - */ - int Freq(wxUniChar ch) const; - - //@{ - /** - Converts given buffer of binary data from 8-bit string to wxString. In - Unicode build, the string is interpreted as being in ISO-8859-1 - encoding. The version without @e len parameter takes NUL-terminated - data. - - This is a convenience method useful when storing binary data in - wxString. It should be used @em only for that purpose and only in - conjunction with To8BitData(). Use mb_str() for conversion of character - data to known encoding. - - @since 2.8.4 - - @see wxString::To8BitData() - */ - static wxString From8BitData(const char* buf, size_t len); - static wxString From8BitData(const char* buf); - //@} - - //@{ - /** - Converts the string or character from an ASCII, 7-bit form - to the native wxString representation. - */ - static wxString FromAscii(const char* s); - static wxString FromAscii(const unsigned char* s); - static wxString FromAscii(const char* s, size_t len); - static wxString FromAscii(const unsigned char* s, size_t len); - static wxString FromAscii(char c); - //@} - - //@{ - /** - Converts C string encoded in UTF-8 to wxString. - Note that this method assumes that @a s is a valid UTF-8 sequence and - doesn't do any validation in release builds, it's validity is only checked in - debug builds. - */ - static wxString FromUTF8(const char* s); - static wxString FromUTF8(const char* s, size_t len); - //@} - - /** - Returns the character at position @a n (read-only). - */ - wxUniChar GetChar(size_t n) const; - - /** - wxWidgets compatibility conversion. Same as c_str(). - */ - const wxCStrData* GetData() const; - - /** - Returns a reference to the character at position @e n. - */ - wxUniCharRef GetWritableChar(size_t n); - - /** - Returns a writable buffer of at least @a len bytes. - It returns a pointer to a new memory block, and the - existing data will not be copied. - Call UngetWriteBuf() as soon as possible to put the - string back into a reasonable state. - This method is deprecated, please use wxStringBuffer or - wxStringBufferLength instead. - */ - wxStringCharType* GetWriteBuf(size_t len); - - /** - Returns @true if the string contains only ASCII characters. - This is a wxWidgets 1.xx compatibility function; you should not use it in new - code. - */ - bool IsAscii() const; - - /** - Returns @true if the string is empty. - */ - bool IsEmpty() const; - - /** - Returns @true if the string is empty (same as wxString::IsEmpty). - This is a wxWidgets 1.xx compatibility function; you should not use it in new - code. - */ - bool IsNull() const; - - /** - Returns @true if the string is an integer (with possible sign). - This is a wxWidgets 1.xx compatibility function; you should not use it in new - code. - */ - bool IsNumber() const; - - //@{ - /** - Test whether the string is equal to the single character @e c. The test is - case-sensitive if @a caseSensitive is @true (default) or not if it is @c - @false. - Returns @true if the string is equal to the character, @false otherwise. - See also Cmp(), CmpNoCase() - */ - bool IsSameAs(const wxString &s, bool caseSensitive = true) const; - bool IsSameAs(wxUniChar ch, bool caseSensitive = true) const; - //@} - - /** - Returns @true if the string is a word. - This is a wxWidgets 1.xx compatibility function; you should not use it in new - code. - */ - bool IsWord() const; - - //@{ - /** - Returns a reference to the last character (writable). - This is a wxWidgets 1.xx compatibility function; - you should not use it in new code. - */ - wxUniCharRef Last(); - const wxUniChar Last(); - //@} - - /** - Returns the first @a count characters of the string. - */ - wxString Left(size_t count) const; - - /** - Returns the length of the string. - */ - size_t Len() const; - - /** - Returns the length of the string (same as Len). - This is a wxWidgets 1.xx compatibility function; you should not use it in new - code. - */ - size_t Length() const; - - /** - Returns this string converted to the lower case. - */ - wxString Lower() const; - - /** - Same as MakeLower. - This is a wxWidgets 1.xx compatibility function; you should not use it in new - code. - */ - void LowerCase(); - - /** - Converts all characters to lower case and returns the result. - */ - wxString& MakeLower(); - - /** - Converts all characters to upper case and returns the result. - */ - wxString& MakeUpper(); - - /** - Returns @true if the string contents matches a mask containing '*' and '?'. - */ - bool Matches(const wxString& mask) const; - - /** - Returns a substring starting at @e first, with length @e count, or the rest of - the string if @a count is the default value. - */ - wxString Mid(size_t first, size_t count = wxSTRING_MAXLEN) const; - - - /** - Adds @a count copies of @a pad to the beginning, or to the end of the - string (the default). Removes spaces from the left or from the right (default). - */ - wxString& Pad(size_t count, wxUniChar pad = ' ', - bool fromRight = true); - - /** - Prepends @a str to this string, returning a reference to this string. - */ - wxString& Prepend(const wxString& str); - - /** - Similar to the standard function @e sprintf(). Returns the number of - characters written, or an integer less than zero on error. - Note that if @c wxUSE_PRINTF_POS_PARAMS is set to 1, then this function supports - Unix98-style positional parameters: - - @note This function will use a safe version of @e vsprintf() (usually called - @e vsnprintf()) whenever available to always allocate the buffer of correct - size. Unfortunately, this function is not available on all platforms and the - dangerous @e vsprintf() will be used then which may lead to buffer overflows. - */ - int Printf(const wxChar* pszFormat, ...); - - /** - Similar to vprintf. Returns the number of characters written, or an integer - less than zero - on error. - */ - int PrintfV(const wxChar* pszFormat, va_list argPtr); - - //@{ - /** - Removes @a len characters from the string, starting at @e pos. - This is a wxWidgets 1.xx compatibility function; you should not use it in new - code. - */ - wxString Remove(size_t pos); - wxString Remove(size_t pos, size_t len); - //@} - - /** - Removes the last character. - */ - wxString RemoveLast(); - - /** - Replace first (or all) occurrences of substring with another one. - @e replaceAll: global replace (default), or only the first occurrence. - Returns the number of replacements made. - */ - size_t Replace(const wxString& strOld, const wxString& strNew, - bool replaceAll = true); - - /** - Returns the last @a count characters. - */ - wxString Right(size_t count) const; - - /** - Sets the character at position @e n. - */ - void SetChar(size_t n, wxUniChar ch); - - /** - Minimizes the string's memory. This can be useful after a call to - Alloc() if too much memory were preallocated. - */ - void Shrink(); - - /** - This function can be used to test if the string starts with the specified - @e prefix. If it does, the function will return @true and put the rest - of the string (i.e. after the prefix) into @a rest string if it is not - @NULL. Otherwise, the function returns @false and doesn't modify the - @e rest. - */ - bool StartsWith(const wxString& prefix, wxString *rest = NULL) const; - - /** - Strip characters at the front and/or end. The same as Trim except that it - doesn't change this string. - This is a wxWidgets 1.xx compatibility function; you should not use it in new - code. - */ - wxString Strip(stripType s = trailing) const; - - /** - Returns the part of the string between the indices @a from and @e to - inclusive. - This is a wxWidgets 1.xx compatibility function, use Mid() - instead (but note that parameters have different meaning). - */ - wxString SubString(size_t from, size_t to) const; - - //@{ - /** - Converts the string to an 8-bit string in ISO-8859-1 encoding in the - form of a wxCharBuffer (Unicode builds only). - - This is a convenience method useful when storing binary data in - wxString. It should be used @em only for this purpose. It is only valid - to call this method on strings created using From8BitData(). - - @since 2.8.4 - - @see wxString::From8BitData() - */ - const char* To8BitData() const; - const wxCharBuffer To8BitData() const; - //@} - - //@{ - /** - Converts the string to an ASCII, 7-bit string in the form of - a wxCharBuffer (Unicode builds only) or a C string (ANSI builds). - Note that this conversion only works if the string contains only ASCII - characters. The @ref mbstr() mb_str method provides more - powerful means of converting wxString to C string. - */ - const char* ToAscii() const; - const wxCharBuffer ToAscii() const; - //@} - - /** - Attempts to convert the string to a floating point number. Returns @true on - success (the number is stored in the location pointed to by @e val) or @false - if the string does not represent such number (the value of @a val is not - modified in this case). - - @see ToLong(), ToULong() - */ - bool ToDouble(double val) const; - - /** - Attempts to convert the string to a signed integer in base @e base. Returns - @true on success in which case the number is stored in the location - pointed to by @a val or @false if the string does not represent a - valid number in the given base (the value of @a val is not modified - in this case). - The value of @a base must be comprised between 2 and 36, inclusive, or - be a special value 0 which means that the usual rules of @c C numbers are - applied: if the number starts with @c 0x it is considered to be in base - 16, if it starts with @c 0 - in base 8 and in base 10 otherwise. Note - that you may not want to specify the base 0 if you are parsing the numbers - which may have leading zeroes as they can yield unexpected (to the user not - familiar with C) results. - - @see ToDouble(), ToULong() - */ - bool ToLong(long val, int base = 10) const; - - /** - This is exactly the same as ToLong() but works with 64 - bit integer numbers. - Notice that currently it doesn't work (always returns @false) if parsing of 64 - bit numbers is not supported by the underlying C run-time library. Compilers - with C99 support and Microsoft Visual C++ version 7 and higher do support this. - - @see ToLong(), ToULongLong() - */ - bool ToLongLong(wxLongLong_t val, int base = 10) const; - - /** - Attempts to convert the string to an unsigned integer in base @e base. - Returns @true on success in which case the number is stored in the - location pointed to by @a val or @false if the string does not - represent a valid number in the given base (the value of @a val is not - modified in this case). Please notice that this function - behaves in the same way as the standard @c strtoul() and so it simply - converts negative numbers to unsigned representation instead of rejecting them - (e.g. -1 is returned as @c ULONG_MAX). - See ToLong() for the more detailed - description of the @a base parameter. - - @see ToDouble(), ToLong() - */ - bool ToULong(unsigned long val, int base = 10) const; - - /** - This is exactly the same as ToULong() but works with 64 - bit integer numbers. - Please see ToLongLong() for additional remarks. - */ - bool ToULongLong(wxULongLong_t val, int base = 10) const; - - //@{ - /** - Same as utf8_str(). - */ - const char* ToUTF8() const; - const wxCharBuffer ToUF8() const; - //@} - - /** - Removes white-space (space, tabs, form feed, newline and carriage return) from - the left or from the right end of the string (right is default). - */ - wxString& Trim(bool fromRight = true); - - /** - Truncate the string to the given length. - */ - wxString& Truncate(size_t len); - - //@{ - /** - Puts the string back into a reasonable state (in which it can be used - normally), after - GetWriteBuf() was called. - The version of the function without the @a len parameter will calculate the - new string length itself assuming that the string is terminated by the first - @c NUL character in it while the second one will use the specified length - and thus is the only version which should be used with the strings with - embedded @c NULs (it is also slightly more efficient as @c strlen() - doesn't have to be called). - This method is deprecated, please use - wxStringBuffer or - wxStringBufferLength instead. - */ - void UngetWriteBuf(); - void UngetWriteBuf(size_t len); - //@} - - /** - Returns this string converted to upper case. - */ - wxString Upper() const; - - /** - The same as MakeUpper. - This is a wxWidgets 1.xx compatibility function; you should not use it in new - code. - */ - void UpperCase(); - - /** - Returns a pointer to the string data (@c const char* when using UTF-8 - internally, @c const wchar_t* when using UCS-2 internally). - - Note that the returned value is not convertible to @c char* or - @c wchar_t*, use char_str() or wchar_str() if you need to pass - string value to a function expecting non-const pointer. - */ - const wxCStrData c_str() const; - - /** - Returns an object with string data that is implicitly convertible to - @c char* pointer. Note that any change to the returned buffer is lost and so - this function is only usable for passing strings to legacy libraries that - don't have const-correct API. Use wxStringBuffer if you want to modify - the string. - - @see c_str() - */ - wxWritableCharBuffer char_str(const wxMBConv& conv = wxConvLibc) const; - - /** - Returns buffer of the specified type containing the string data. - - This method is only useful in template code, otherwise you should - directly call mb_str() or wc_str() if you need to retrieve a narrow or - wide string from this wxString. The template parameter @a t should be - either @c char or @c wchar_t. - - Notice that retrieving a char buffer in UTF-8 build will return the - internal string representation in UTF-8 while in wchar_t build the char - buffer will contain the conversion of the string to the encoding of the - current locale (and so can fail). - - @param len If non-@NULL, filled with the length of the returned buffer. - @return - buffer containing the string contents in the specified type, - notice that it may be @NULL if the conversion failed (e.g. Unicode - string couldn't be converted to the current encoding when @a T is - @c char). - */ - template - wxCharTypeBuffer tchar_str(size_t *len = NULL) const; - - //@{ - /** - Returns string representation suitable for passing to OS' functions - for file handling. - */ - const wchar_t* fn_str() const; - const char* fn_str() const; - const wxCharBuffer fn_str() const; - //@} - - //@{ - /** - Returns multibyte (C string) representation of the string. - In Unicode build, converts using @e conv's wxMBConv::cWC2MB - method and returns wxCharBuffer. In ANSI build, this function - is same as c_str(). - The macro wxWX2MBbuf is defined as the correct return type (without const). - - @see wxMBConv, c_str(), wc_str(), fn_str(), char_str() - */ - const char* mb_str(const wxMBConv& conv = wxConvLibc) const; - const wxCharBuffer mb_str(const wxMBConv& conv = wxConvLibc) const; - //@} - - /** - Extraction from a stream. - */ - friend istream operator(istream& is, wxString& str); - - //@{ - /** - These functions work as C++ stream insertion operators: they insert the given - value into the string. Precision or format cannot be set using them, you can - use Printf() for this. - */ - wxString operator(const wxString& str); - wxString operator(wxUniChar ch); - wxString operator(int i); - wxString operator(float f); - wxString operator(double d); - //@} - - /** - Same as Mid (substring extraction). - */ - wxString operator ()(size_t start, size_t len); - - //@{ - /** - Concatenation: these operators return a new string equal to the - concatenation of the operands. - */ - wxString operator +(const wxString& x, const wxString& y); - wxString operator +(const wxString& x, wxUniChar y); - //@} - - //@{ - /** - Concatenation in place: the argument is appended to the string. - */ - void operator +=(const wxString& str); - void operator +=(wxUniChar c); - //@} - - //@{ - /** - Assignment: the effect of each operation is the same as for the corresponding - constructor (see @ref construct() "wxString constructors"). - */ - wxString operator =(const wxString& str); - wxString operator =(wxUniChar c); - //@} - - //@{ - /** - Element extraction. - */ - wxUniChar operator [](size_t i) const; - wxUniCharRef operator [](size_t i); - //@} - - /** - Empty string is @false, so !string will only return @true if the - string is empty. - - See also IsEmpty(). - */ - bool operator!() const; - - - //@{ - /** - Converts the strings contents to UTF-8 and returns it either as a - temporary wxCharBuffer object or as a pointer to the internal - string contents in UTF-8 build. - */ - const char* utf8_str() const; - const wxCharBuffer utf8_str() const; - //@} - - //@{ - /** - Converts the strings contents to the wide character represention - and returns it as a temporary wxWCharBuffer object or returns a - pointer to the internal string contents in wide character mode. - - The macro wxWX2WCbuf is defined as the correct return - type (without const). - - @see wxMBConv, c_str(), mb_str(), fn_str(), wchar_str() - */ - const wchar_t* wc_str() const; - const wxWCharBuffer wc_str() const; - //@} - - /** - Returns an object with string data that is implicitly convertible to - @c char* pointer. Note that changes to the returned buffer may or may - not be lost (depending on the build) and so this function is only usable for - passing strings to legacy libraries that don't have const-correct API. Use - wxStringBuffer if you want to modify the string. - - @see mb_str(), wc_str(), fn_str(), c_str(), char_str() - */ - wxWritableWCharBuffer wchar_str() const; - - /** - @name Iterator interface - - These methods return iterators to the beginnnig or - end of the string. - */ - //@{ - const_iterator begin() const; - iterator begin(); - const_iterator end() const; - iterator end(); - - const_reverse_iterator rbegin() const; - reverse_iterator rbegin(); - const_reverse_iterator rend() const; - reverse_iterator rend(); - //@} - - /** - @name STL interface - - The supported STL functions are listed here. Please see any - STL reference for their documentation. - */ - //@{ - size_t length() const; - size_type size() const; - size_type max_size() const; - size_type capacity() const; - void reserve(size_t sz); - - void resize(size_t nSize, wxUniChar ch = '\0'); - - wxString& append(const wxString& str, size_t pos, size_t n); - wxString& append(const wxString& str); - wxString& append(const char *sz, size_t n); - wxString& append(const wchar_t *sz, size_t n); - wxString& append(size_t n, wxUniChar ch); - wxString& append(const_iterator first, const_iterator last); - - wxString& assign(const wxString& str, size_t pos, size_t n); - wxString& assign(const wxString& str); - wxString& assign(const char *sz, size_t n); - wxString& assign(const wchar_t *sz, size_t n); - wxString& assign(size_t n, wxUniChar ch); - wxString& assign(const_iterator first, const_iterator last); - - void clear(); - - int compare(const wxString& str) const; - int compare(size_t nStart, size_t nLen, const wxString& str) const; - int compare(size_t nStart, size_t nLen, - const wxString& str, size_t nStart2, size_t nLen2) const; - int compare(size_t nStart, size_t nLen, - const char* sz, size_t nCount = npos) const; - int compare(size_t nStart, size_t nLen, - const wchar_t* sz, size_t nCount = npos) const; - - bool empty() const; - - wxString& erase(size_type pos = 0, size_type n = npos); - iterator erase(iterator first, iterator last); - iterator erase(iterator first); - - size_t find(const wxString& str, size_t nStart = 0) const; - size_t find(const char* sz, size_t nStart = 0, size_t n = npos) const; - size_t find(const wchar_t* sz, size_t nStart = 0, size_t n = npos) const; - size_t find(wxUniChar ch, size_t nStart = 0) const; - - wxString& insert(size_t nPos, const wxString& str); - wxString& insert(size_t nPos, const wxString& str, size_t nStart, size_t n); - wxString& insert(size_t nPos, const char *sz, size_t n); - wxString& insert(size_t nPos, const wchar_t *sz, size_t n); - wxString& insert(size_t nPos, size_t n, wxUniChar ch); - iterator insert(iterator it, wxUniChar ch); - void insert(iterator it, const_iterator first, const_iterator last); - void insert(iterator it, size_type n, wxUniChar ch); - - wxString& replace(size_t nStart, size_t nLen, const wxString& str); - wxString& replace(size_t nStart, size_t nLen, size_t nCount, wxUniChar ch); - wxString& replace(size_t nStart, size_t nLen, - const wxString& str, size_t nStart2, size_t nLen2); - wxString& replace(size_t nStart, size_t nLen, - const char* sz, size_t nCount); - wxString& replace(size_t nStart, size_t nLen, - const wchar_t* sz, size_t nCount); - wxString& replace(size_t nStart, size_t nLen, - const wxString& s, size_t nCount); - wxString& replace(iterator first, iterator last, const wxString& s); - wxString& replace(iterator first, iterator last, const char* s, size_type n); - wxString& replace(iterator first, iterator last, const wchar_t* s, size_type n); - wxString& replace(iterator first, iterator last, size_type n, wxUniChar ch); - wxString& replace(iterator first, iterator last, - const_iterator first1, const_iterator last1); - wxString& replace(iterator first, iterator last, - const char *first1, const char *last1); - wxString& replace(iterator first, iterator last, - const wchar_t *first1, const wchar_t *last1); - - size_t rfind(const wxString& str, size_t nStart = npos) const; - size_t rfind(const char* sz, size_t nStart = npos, size_t n = npos) const; - size_t rfind(const wchar_t* sz, size_t nStart = npos, size_t n = npos) const; - size_t rfind(wxUniChar ch, size_t nStart = npos) const; - - wxString substr(size_t nStart = 0, size_t nLen = npos) const; - - void swap(wxString& str); - - //@} - -}; - - -/** - FIXME -*/ -wxString Objects: -; - -/** - FIXME -*/ -wxString wxEmptyString; - - - - -/** - @class wxStringBufferLength - @wxheader{string.h} - - This tiny class allows to conveniently access the wxString - internal buffer as a writable pointer without any risk of forgetting to restore - the string to the usable state later, and allows the user to set the internal - length of the string. - - For example, assuming you have a low-level OS function called - @c int GetMeaningOfLifeAsString(char *) copying the value in the provided - buffer (which must be writable, of course), and returning the actual length - of the string, you might call it like this: - - @code - wxString theAnswer; - wxStringBuffer theAnswerBuffer(theAnswer, 1024); - int nLength = GetMeaningOfLifeAsString(theAnswerBuffer); - theAnswerBuffer.SetLength(nLength); - if ( theAnswer != "42" ) - { - wxLogError("Something is very wrong!"); - } - @endcode - - Note that the exact usage of this depends on whether on not wxUSE_STL is - enabled. If - wxUSE_STL is enabled, wxStringBuffer creates a separate empty character buffer, - and - if wxUSE_STL is disabled, it uses GetWriteBuf() from wxString, keeping the same - buffer - wxString uses intact. In other words, relying on wxStringBuffer containing the - old - wxString data is probably not a good idea if you want to build your program in - both - with and without wxUSE_STL. - - Note that SetLength @c must be called before wxStringBufferLength destructs. - - @library{wxbase} - @category{FIXME} -*/ -class wxStringBufferLength -{ -public: - /** - Constructs a writable string buffer object associated with the given string - and containing enough space for at least @a len characters. Basically, this - is equivalent to calling wxString::GetWriteBuf and - saving the result. - */ - wxStringBufferLength(const wxString& str, size_t len); - - /** - Restores the string passed to the constructor to the usable state by calling - wxString::UngetWriteBuf on it. - */ - ~wxStringBufferLength(); - - /** - Sets the internal length of the string referred to by wxStringBufferLength to - @a nLength characters. - Must be called before wxStringBufferLength destructs. - */ - void SetLength(size_t nLength); - - /** - Returns the writable pointer to a buffer of the size at least equal to the - length specified in the constructor. - */ - wxChar* operator wxChar *(); -}; - diff --git a/interface/sysopt.h b/interface/sysopt.h deleted file mode 100644 index 1c8286536a..0000000000 --- a/interface/sysopt.h +++ /dev/null @@ -1,78 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: sysopt.h -// Purpose: interface of wxSystemOptions -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxSystemOptions - @wxheader{sysopt.h} - - wxSystemOptions stores option/value pairs that wxWidgets itself or - applications can use to alter behaviour at run-time. It can be - used to optimize behaviour that doesn't deserve a distinct API, - but is still important to be able to configure. - - These options are currently recognised by wxWidgets. - - @library{wxbase} - @category{misc} - - @see wxSystemOptions::SetOption, wxSystemOptions::GetOptionInt, - wxSystemOptions::HasOption -*/ -class wxSystemOptions : public wxObject -{ -public: - /** - Default constructor. You don't need to create an instance of wxSystemOptions - since all of its functions are static. - */ - wxSystemOptions(); - - /** - Gets an option. The function is case-insensitive to @e name. - Returns empty string if the option hasn't been set. - - @see SetOption(), GetOptionInt(), - HasOption() - */ - wxString GetOption(const wxString& name) const; - - /** - Gets an option as an integer. The function is case-insensitive to @e name. - If the option hasn't been set, this function returns 0. - - @see SetOption(), GetOption(), - HasOption() - */ - int GetOptionInt(const wxString& name) const; - - /** - Returns @true if the given option is present. The function is - case-insensitive to @e name. - - @see SetOption(), GetOption(), - GetOptionInt() - */ - bool HasOption(const wxString& name) const; - - /** - Returns @true if the option with the given @a name had been set to 0 - value. This is mostly useful for boolean options for which you can't use - @c GetOptionInt(name) == 0 as this would also be @true if the option - hadn't been set at all. - */ - bool IsFalse(const wxString& name) const; - - //@{ - /** - Sets an option. The function is case-insensitive to @e name. - */ - void SetOption(const wxString& name, const wxString& value); - void SetOption(const wxString& name, int value); - //@} -}; - diff --git a/interface/tarstrm.h b/interface/tarstrm.h deleted file mode 100644 index 5edbc5add8..0000000000 --- a/interface/tarstrm.h +++ /dev/null @@ -1,354 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: tarstrm.h -// Purpose: interface of wxTarInputStream -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxTarInputStream - @wxheader{tarstrm.h} - - Input stream for reading tar files. - - wxTarInputStream::GetNextEntry returns an - wxTarEntry object containing the meta-data - for the next entry in the tar (and gives away ownership). Reading from - the wxTarInputStream then returns the entry's data. Eof() becomes @true - after an attempt has been made to read past the end of the entry's data. - When there are no more entries, GetNextEntry() returns @NULL and sets Eof(). - - Tar entries are seekable if the parent stream is seekable. In practice this - usually means they are only seekable if the tar is stored as a local file and - is not compressed. - - @library{wxbase} - @category{streams} - - @see @ref overview_wxarcbyname "Looking up an archive entry by name" -*/ -class wxTarInputStream : public wxArchiveInputStream -{ -public: - //@{ - /** - Constructor. In a Unicode build the second parameter @a conv is - used to translate fields from the standard tar header into Unicode. It has - no effect on the stream's data. @a conv is only used for the standard - tar headers, any pax extended headers are always UTF-8 encoded. - If the parent stream is passed as a pointer then the new filter stream - takes ownership of it. If it is passed by reference then it does not. - */ - wxTarInputStream(wxInputStream& stream, - wxMBConv& conv = wxConvLocal); - wxTarInputStream(wxInputStream* stream, - wxMBConv& conv = wxConvLocal); - //@} - - /** - Closes the current entry. On a non-seekable stream reads to the end of - the current entry first. - */ - bool CloseEntry(); - - /** - Closes the current entry if one is open, then reads the meta-data for - the next entry and returns it in a wxTarEntry - object, giving away ownership. The stream is then open and can be read. - */ - wxTarEntry* GetNextEntry(); - - /** - Closes the current entry if one is open, then opens the entry specified - by the @a entry object. - @a entry should be from the same tar file, and the tar should - be on a seekable stream. - */ - bool OpenEntry(wxTarEntry& entry); -}; - - - -/** - @class wxTarClassFactory - @wxheader{tarstrm.h} - - Class factory for the tar archive format. See the base class - for details. - - @library{wxbase} - @category{FIXME} - - @see @ref overview_wxarc "Archive formats such as zip", @ref - overview_wxarcgeneric "Generic archive programming", wxTarEntry, wxTarInputStream, wxTarOutputStream -*/ -class wxTarClassFactory : public wxArchiveClassFactory -{ -public: - -}; - - - -/** - @class wxTarOutputStream - @wxheader{tarstrm.h} - - Output stream for writing tar files. - - wxTarOutputStream::PutNextEntry is used to create - a new entry in the output tar, then the entry's data is written to the - wxTarOutputStream. Another call to PutNextEntry() closes the current - entry and begins the next. - - @library{wxbase} - @category{streams} - - @see @ref overview_wxarc "Archive formats such as zip", wxTarEntry, - wxTarInputStream -*/ -class wxTarOutputStream : public wxArchiveOutputStream -{ -public: - //@{ - /** - If the parent stream is passed as a pointer then the new filter stream - takes ownership of it. If it is passed by reference then it does not. - In a Unicode build the third parameter @a conv is used to translate the - headers fields into an 8-bit encoding. It has no effect on the stream's data. - When the @a format is @e wxTAR_PAX, pax extended headers are generated - when any header field will not fit the standard tar header block or if it - uses any non-ascii characters. - Extended headers are stored as extra 'files' within the tar, and will be - extracted as such by any other tar program that does not understand them. - The @a conv parameter only affect the standard tar headers, the extended - headers are always UTF-8 encoded. - When the @a format is @e wxTAR_USTAR, no extended headers are - generated, and instead a warning message is logged if any header field - overflows. - */ - wxTarOutputStream(wxOutputStream& stream, - wxTarFormat format = wxTAR_PAX, - wxMBConv& conv = wxConvLocal); - wxTarOutputStream(wxOutputStream* stream, - wxTarFormat format = wxTAR_PAX, - wxMBConv& conv = wxConvLocal); - //@} - - /** - The destructor calls Close() to finish - writing the tar if it has not been called already. - */ - ~wxTarOutputStream(); - - /** - Finishes writing the tar, returning @true if successful. - Called by the destructor if not called explicitly. - */ - bool Close(); - - /** - Close the current entry. It is called implicitly whenever another new - entry is created with CopyEntry() - or PutNextEntry(), or - when the tar is closed. - */ - bool CloseEntry(); - - /** - See wxArchiveOutputStream::CopyArchiveMetaData. - For the tar format this function does nothing. - */ - bool CopyArchiveMetaData(wxTarInputStream& s); - - /** - Takes ownership of @a entry and uses it to create a new entry - in the tar. @a entry is then opened in @a inputStream and its contents - copied to this stream. - For some other archive formats CopyEntry() is much more efficient than - transferring the data using Read() and Write() since it will copy them - without decompressing and recompressing them. For tar however it makes - no difference. - For tars on seekable streams, @a entry must be from the same tar file - as @e stream. For non-seekable streams, @a entry must also be the - last thing read from @e inputStream. - */ - bool CopyEntry(wxTarEntry* entry, wxTarInputStream& inputStream); - - //@{ - /** - The tar is zero padded to round its size up to @e BlockingFactor * 512 bytes. - Defaults to 10 for @e wxTAR_PAX and 20 for @e wxTAR_USTAR - (see the @ref wxtaroutputstream() constructor), as - specified in the POSIX standards. - */ - int GetBlockingFactor(); - const void SetBlockingFactor(int factor); - //@} - - /** - ) - Create a new directory entry - (see wxArchiveEntry::IsDir) - with the given name and timestamp. - PutNextEntry() can - also be used to create directory entries, by supplying a name with - a trailing path separator. - */ - bool PutNextDirEntry(const wxString& name); - - //@{ - /** - , @b wxFileOffset@e size = wxInvalidOffset) - Create a new entry with the given name, timestamp and size. - */ - bool PutNextEntry(wxTarEntry* entry); - bool PutNextEntry(const wxString& name); - //@} -}; - - - -/** - @class wxTarEntry - @wxheader{tarstrm.h} - - Holds the meta-data for an entry in a tar. - - @library{wxbase} - @category{FIXME} - - @see @ref overview_wxarc "Archive formats such as zip", wxTarInputStream, - wxTarOutputStream -*/ -class wxTarEntry : public wxArchiveEntry -{ -public: - //@{ - /** - Copy constructor. - */ - wxTarEntry(const wxString& name = wxEmptyString); - wxTarEntry(const wxTarEntry& entry); - //@} - - //@{ - /** - The entry's access time stamp. See also - wxArchiveEntry::Get/SetDateTime. - */ - wxDateTime GetAccessTime(); - const void SetAccessTime(const wxDateTime& dt); - //@} - - //@{ - /** - The entry's creation time stamp. See also - wxArchiveEntry::Get/SetDateTime. - */ - wxDateTime GetCreateTime(); - const void SetCreateTime(const wxDateTime& dt); - //@} - - //@{ - /** - OS specific IDs defining a device, these are only meaningful when - TypeFlag() is set to @e wxTAR_CHRTYPE - or @e wxTAR_BLKTYPE. - */ - int GetDevMajor(); - const int GetDevMinor(); - const void SetDevMajor(int dev); - void SetDevMinor(int dev); - //@} - - //@{ - /** - The user ID and group ID that has @ref mode() permissions over - this entry. These values aren't usually useful unless the file will only be - restored to the same system it originated from. @ref unamegname() - "Get/SetGroupName and - Get/SetUserName" can be used instead. - */ - int GetGroupId(); - const int GetUserId(); - const void SetGroupId(int id); - void SetUserId(int id); - //@} - - //@{ - /** - The names of the user and group that has @ref mode() permissions - over this entry. These are not present in very old tars. - */ - wxString GetGroupName(); - const wxString GetUserName(); - const void SetGroupName(const wxString& group); - void SetUserName(const wxString& user); - //@} - - //@{ - /** - The filename of a previous entry in the tar that this entry is a link to. - Only meaningful when TypeFlag() is set - to @e wxTAR_LNKTYPE or @e wxTAR_SYMTYPE. - */ - wxString GetLinkName(); - const void SetLinkName(const wxString& link); - //@} - - //@{ - /** - UNIX permission bits for this entry. Giving read, write and execute permissions - to the file's @ref unamegname() "User and Group" and to others. - Symbols are defined for them in wx/file.h. - */ - int GetMode(); - const void SetMode(int mode); - //@} - - //@{ - /** - The size of the entry's data in bytes. - The tar archive format stores the entry's size ahead of the entry's data. - Therefore when creating an archive on a non-seekable stream it is necessary to - supply the correct size when each entry is created. For seekable streams this - is not necessary as wxTarOutputStream will attempt - to seek back and fix the entry's header when the entry is closed, though it is - still more efficient if the size is given beforehand. - */ - void SetSize(wxFileOffset size) const; - wxFileOffset GetSize() const; - //@} - - //@{ - /** - Returns the type of the entry. It should be one of the following: - - When creating archives use just these values. When reading archives - any other values should be treated as @e wxTAR_REGTYPE. - */ - int GetTypeFlag(); - const void SetTypeFlag(int type); - //@} - - //@{ - /** - A static member that translates a filename into the internal format used - within the archive. If the third parameter is provided, the bool pointed - to is set to indicate whether the name looks like a directory name - (i.e. has a trailing path separator). - */ - wxString GetInternalName(); - const wxString GetInternalName(const wxString& name, - wxPathFormat format = wxPATH_NATIVE, - bool* pIsDir = NULL); - //@} - - /** - Assignment operator. - */ - wxTarEntry& operator operator=(const wxTarEntry& entry); -}; - diff --git a/interface/taskbar.h b/interface/taskbar.h deleted file mode 100644 index 9eb2faaefb..0000000000 --- a/interface/taskbar.h +++ /dev/null @@ -1,77 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: taskbar.h -// Purpose: interface of wxTaskBarIcon -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxTaskBarIcon - @wxheader{taskbar.h} - - This class represents a taskbar icon. A taskbar icon is an icon that appears in - the 'system tray' and responds to mouse clicks, optionally with a tooltip above it to help provide information. - - @library{wxadv} - @category{FIXME} -*/ -class wxTaskBarIcon : public wxEvtHandler -{ -public: - /** - Default constructor. - */ - wxTaskBarIcon(); - - /** - Destroys the wxTaskBarIcon object, removing the icon if not already removed. - */ - ~wxTaskBarIcon(); - - /** - This method is called by the library when the user requests popup menu - (on Windows and Unix platforms, this is when the user right-clicks the icon). - Override this function in order to provide popup menu associated with the icon. - If CreatePopupMenu returns @NULL (this happens by default), - no menu is shown, otherwise the menu is - displayed and then deleted by the library as soon as the user dismisses it. - The events can be handled by a class derived from wxTaskBarIcon. - */ - virtual wxMenu* CreatePopupMenu(); - - /** - This method is similar to wxWindow::Destroy and can - be used to schedule the task bar icon object for the delayed destruction: it - will be deleted during the next event loop iteration, which allows the task bar - icon to process any pending events for it before being destroyed. - */ - void Destroy(); - - /** - Returns @true if SetIcon() was called with no subsequent RemoveIcon(). - */ - bool IsIconInstalled(); - - /** - Returns @true if the object initialized successfully. - */ - bool IsOk(); - - /** - Pops up a menu at the current mouse position. The events can be handled by - a class derived from wxTaskBarIcon. - */ - bool PopupMenu(wxMenu* menu); - - /** - Removes the icon previously set with SetIcon(). - */ - bool RemoveIcon(); - - /** - Sets the icon, and optional tooltip text. - */ - bool SetIcon(const wxIcon& icon, const wxString& tooltip); -}; - diff --git a/interface/textctrl.h b/interface/textctrl.h deleted file mode 100644 index c4f03743d5..0000000000 --- a/interface/textctrl.h +++ /dev/null @@ -1,1615 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: textctrl.h -// Purpose: interface of wxTextAttr -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxTextAttr - @wxheader{textctrl.h} - - wxTextAttr represents the character and paragraph attributes, or style, - for a range of text in a wxTextCtrl or wxRichTextCtrl. - - When setting up a wxTextAttr object, pass a bitlist mask to - wxTextAttr::SetFlags to indicate which style elements should be changed. As - a convenience, when you call a setter such as SetFont, the relevant bit - will be set. - - @library{wxcore} - @category{richtext} - - @see wxTextCtrl, wxRichTextCtrl -*/ -class wxTextAttr -{ -public: - //@{ - /** - Constructors. - */ - wxTextAttr(); - wxTextAttr(const wxColour& colText, - const wxColour& colBack = wxNullColour, - const wxFont& font = wxNullFont, - wxTextAttrAlignment alignment = wxTEXT_ALIGNMENT_DEFAULT); - wxTextAttr(const wxTextAttr& attr); - //@} - - /** - Applies the attributes in @a style to the original object, but not those - attributes from @a style that are the same as those in @a compareWith (if passed). - */ - bool Apply(const wxTextAttr& style, - const wxTextAttr* compareWith = NULL); - - /** - Creates a font from the font attributes. - */ - wxFont CreateFont() const; - - /** - Returns the alignment flags. - See SetAlignment() for a list of available styles. - */ - wxTextAttrAlignment GetAlignment() const; - - /** - Returns the background colour. - */ - const wxColour GetBackgroundColour() const; - - /** - Returns a string containing the name of the font associated with the bullet - symbol. - Only valid for attributes with wxTEXT_ATTR_BULLET_SYMBOL. - */ - const wxString GetBulletFont() const; - - /** - Returns the standard bullet name, applicable if the bullet style is - wxTEXT_ATTR_BULLET_STYLE_STANDARD. - Currently the following standard bullet names are supported: - @c standard/circle - @c standard/square - @c standard/diamond - @c standard/triangle - For wxRichTextCtrl users only: if you wish your rich text controls to support - further bullet graphics, you can derive a - class from wxRichTextRenderer or wxRichTextStdRenderer, override @c - DrawStandardBullet and @c EnumerateStandardBulletNames, and - set an instance of the class using wxRichTextBuffer::SetRenderer. - */ - const wxString GetBulletName() const; - - /** - Returns the bullet number. - */ - int GetBulletNumber() const; - - /** - Returns the bullet style. - See SetBulletStyle() for a list of available styles. - */ - int GetBulletStyle() const; - - /** - Returns the bullet text, which could be a symbol, or (for example) cached - outline text. - */ - const wxString GetBulletText() const; - - /** - Returns the name of the character style. - */ - const wxString GetCharacterStyleName() const; - - /** - Returns flags indicating which attributes are applicable. - See SetFlags() for a list of available flags. - */ - long GetFlags() const; - - /** - Creates and returns a font specified by the font attributes in the wxTextAttr - object. Note that - wxTextAttr does not store a wxFont object, so this is only a temporary font. - For greater - efficiency, access the font attributes directly. - */ - wxFont GetFont() const; - - /** - Gets the font attributes from the given font, using only the attributes - specified by @a flags. - */ - bool GetFontAttributes(const wxFont& font, - int flags = wxTEXT_ATTR_FONT); - - /** - Returns the font encoding. - */ - wxFontEncoding GetFontEncoding() const; - - /** - Returns the font face name. - */ - const wxString GetFontFaceName() const; - - /** - Returns the font size in points. - */ - int GetFontSize() const; - - /** - Returns the font style. - */ - int GetFontStyle() const; - - /** - Returns @true if the font is underlined. - */ - bool GetFontUnderlined() const; - - /** - Returns the font weight. - */ - int GetFontWeight() const; - - /** - Returns the left indent in tenths of a millimetre. - */ - long GetLeftIndent() const; - - /** - Returns the left sub-indent in tenths of a millimetre. - */ - long GetLeftSubIndent() const; - - /** - Returns the line spacing value, one of wxTEXT_ATTR_LINE_SPACING_NORMAL, - wxTEXT_ATTR_LINE_SPACING_HALF, and wxTEXT_ATTR_LINE_SPACING_TWICE. - */ - int GetLineSpacing() const; - - /** - Returns the name of the list style. - */ - const wxString GetListStyleName() const; - - /** - Returns the outline level. - */ - bool GetOutlineLevel() const; - - /** - Returns the space in tenths of a millimeter after the paragraph. - */ - int GetParagraphSpacingAfter() const; - - /** - Returns the space in tenths of a millimeter before the paragraph. - */ - int GetParagraphSpacingBefore() const; - - /** - Returns the name of the paragraph style. - */ - const wxString GetParagraphStyleName() const; - - /** - Returns the right indent in tenths of a millimeter. - */ - long GetRightIndent() const; - - /** - Returns an array of tab stops, each expressed in tenths of a millimeter. Each - stop - is measured from the left margin and therefore each value must be larger than - the last. - */ - const wxArrayInt GetTabs() const; - - /** - Returns the text foreground colour. - */ - const wxColour GetTextColour() const; - - /** - Returns the text effect bits of interest. See SetFlags() for further - information. - */ - int GetTextEffectFlags() const; - - /** - Returns the text effects, a bit list of styles. See SetTextEffects() for - details. - */ - int GetTextEffects() const; - - /** - Returns the URL for the content. Content with wxTEXT_ATTR_URL style - causes wxRichTextCtrl to show a hand cursor over it, and wxRichTextCtrl - generates - a wxTextUrlEvent when the content is clicked. - */ - const wxString GetURL() const; - - /** - Returns @true if the attribute object specifies alignment. - */ - bool HasAlignment() const; - - /** - Returns @true if the attribute object specifies a background colour. - */ - bool HasBackgroundColour() const; - - /** - Returns @true if the attribute object specifies a standard bullet name. - */ - bool HasBulletName() const; - - /** - Returns @true if the attribute object specifies a bullet number. - */ - bool HasBulletNumber() const; - - /** - Returns @true if the attribute object specifies a bullet style. - */ - bool HasBulletStyle() const; - - /** - Returns @true if the attribute object specifies bullet text (usually - specifying a symbol). - */ - bool HasBulletText() const; - - /** - Returns @true if the attribute object specifies a character style name. - */ - bool HasCharacterStyleName() const; - - /** - Returns @true if the @a flag is present in the attribute object's flag - bitlist. - */ - bool HasFlag(long flag) const; - - /** - Returns @true if the attribute object specifies any font attributes. - */ - bool HasFont() const; - - /** - Returns @true if the attribute object specifies an encoding. - */ - bool HasFontEncoding() const; - - /** - Returns @true if the attribute object specifies a font face name. - */ - bool HasFontFaceName() const; - - /** - Returns @true if the attribute object specifies italic style. - */ - bool HasFontItalic() const; - - /** - Returns @true if the attribute object specifies a font point size. - */ - bool HasFontSize() const; - - /** - Returns @true if the attribute object specifies either underlining or no - underlining. - */ - bool HasFontUnderlined() const; - - /** - Returns @true if the attribute object specifies font weight (bold, light or - normal). - */ - bool HasFontWeight() const; - - /** - Returns @true if the attribute object specifies a left indent. - */ - bool HasLeftIndent() const; - - /** - Returns @true if the attribute object specifies line spacing. - */ - bool HasLineSpacing() const; - - /** - Returns @true if the attribute object specifies a list style name. - */ - bool HasListStyleName() const; - - /** - Returns @true if the attribute object specifies an outline level. - */ - bool HasOutlineLevel() const; - - /** - Returns @true if the attribute object specifies a page break before this - paragraph. - */ - bool HasPageBreak() const; - - /** - Returns @true if the attribute object specifies spacing after a paragraph. - */ - bool HasParagraphSpacingAfter() const; - - /** - Returns @true if the attribute object specifies spacing before a paragraph. - */ - bool HasParagraphSpacingBefore() const; - - /** - Returns @true if the attribute object specifies a paragraph style name. - */ - bool HasParagraphStyleName() const; - - /** - Returns @true if the attribute object specifies a right indent. - */ - bool HasRightIndent() const; - - /** - Returns @true if the attribute object specifies tab stops. - */ - bool HasTabs() const; - - /** - Returns @true if the attribute object specifies a text foreground colour. - */ - bool HasTextColour() const; - - /** - Returns @true if the attribute object specifies text effects. - */ - bool HasTextEffects() const; - - /** - Returns @true if the attribute object specifies a URL. - */ - bool HasURL() const; - - /** - Returns @true if the object represents a character style, that is, - the flags specify a font or a text background or foreground colour. - */ - bool IsCharacterStyle() const; - - /** - Returns @false if we have any attributes set, @true otherwise. - */ - bool IsDefault() const; - - /** - Returns @true if the object represents a paragraph style, that is, - the flags specify alignment, indentation, tabs, paragraph spacing, or - bullet style. - */ - bool IsParagraphStyle() const; - - //@{ - /** - Creates a new @c wxTextAttr which is a merge of @a base and - @a overlay. Properties defined in @a overlay take precedence over those - in @a base. Properties undefined/invalid in both are undefined in the - result. - */ - void Merge(const wxTextAttr& overlay); - static wxTextAttr Merge(const wxTextAttr& base, - const wxTextAttr& overlay); - //@} - - /** - Sets the paragraph alignment. These are the possible values for @a alignment: - - Of these, wxTEXT_ALIGNMENT_JUSTIFIED is unimplemented. In future justification - may be supported - when printing or previewing, only. - */ - void SetAlignment(wxTextAttrAlignment alignment); - - /** - Sets the background colour. - */ - void SetBackgroundColour(const wxColour& colBack); - - /** - Sets the name of the font associated with the bullet symbol. - Only valid for attributes with wxTEXT_ATTR_BULLET_SYMBOL. - */ - void SetBulletFont(const wxString& font); - - /** - Sets the standard bullet name, applicable if the bullet style is - wxTEXT_ATTR_BULLET_STYLE_STANDARD. - See GetBulletName() for a list - of supported names, and how to expand the range of supported types. - */ - void SetBulletName(const wxString& name); - - /** - Sets the bullet number. - */ - void SetBulletNumber(int n); - - /** - Sets the bullet style. The following styles can be passed: - - Currently wxTEXT_ATTR_BULLET_STYLE_BITMAP is not supported. - */ - void SetBulletStyle(int style); - - /** - Sets the bullet text, which could be a symbol, or (for example) cached outline - text. - */ - void SetBulletText(const wxString text); - - /** - Sets the character style name. - */ - void SetCharacterStyleName(const wxString& name); - - /** - Sets the flags determining which styles are being specified. The following - flags can be passed in a bitlist: - */ - void SetFlags(long flags); - - /** - Sets the attributes for the given font. Note that wxTextAttr does not store an - actual wxFont object. - */ - void SetFont(const wxFont& font); - - /** - Sets the font encoding. - */ - void SetFontEncoding(wxFontEncoding encoding); - - /** - Sets the paragraph alignment. - */ - void SetFontFaceName(const wxString& faceName); - - /** - Sets the font size in points. - */ - void SetFontSize(int pointSize); - - /** - Sets the font style (normal, italic or slanted). - */ - void SetFontStyle(int fontStyle); - - /** - Sets the font underlining. - */ - void SetFontUnderlined(bool underlined); - - /** - Sets the font weight. - */ - void SetFontWeight(int fontWeight); - - /** - Sets the left indent and left subindent in tenths of a millimetre. - The sub-indent is an offset from the left of the paragraph, and is used for all - but the - first line in a paragraph. A positive value will cause the first line to appear - to the left - of the subsequent lines, and a negative value will cause the first line to be - indented - relative to the subsequent lines. - wxRichTextBuffer uses indentation to render a bulleted item. The left indent is - the distance between - the margin and the bullet. The content of the paragraph, including the first - line, starts - at leftMargin + leftSubIndent. So the distance between the left edge of the - bullet and the - left of the actual paragraph is leftSubIndent. - */ - void SetLeftIndent(int indent, int subIndent = 0); - - /** - Sets the line spacing. @a spacing is a multiple, where 10 means single-spacing, - 15 means 1.5 spacing, and 20 means double spacing. The following constants are - defined for convenience: - */ - void SetLineSpacing(int spacing); - - /** - Sets the list style name. - */ - void SetListStyleName(const wxString& name); - - /** - Specifies the outline level. Zero represents normal text. At present, the - outline level is - not used, but may be used in future for determining list levels and for - applications - that need to store document structure information. - */ - void SetOutlineLevel(int level); - - /** - Specifies a page break before this paragraph. - */ - void SetPageBreak(bool pageBreak = true); - - /** - Sets the spacing after a paragraph, in tenths of a millimetre. - */ - void SetParagraphSpacingAfter(int spacing); - - /** - Sets the spacing before a paragraph, in tenths of a millimetre. - */ - void SetParagraphSpacingBefore(int spacing); - - /** - Sets the name of the paragraph style. - */ - void SetParagraphStyleName(const wxString& name); - - /** - Sets the right indent in tenths of a millimetre. - */ - void SetRightIndent(int indent); - - /** - Sets the tab stops, expressed in tenths of a millimetre. - Each stop is measured from the left margin and therefore each value must be - larger than the last. - */ - void SetTabs(const wxArrayInt& tabs); - - /** - Sets the text foreground colout. - */ - void SetTextColour(const wxColour& colText); - - /** - Sets the text effect bits of interest. You should also pass wxTEXT_ATTR_EFFECTS - to SetFlags(). - See SetFlags() for further information. - */ - void SetTextEffectFlags(int flags); - - /** - Sets the text effects, a bit list of styles. - The following styles can be passed: - - Of these, only wxTEXT_ATTR_EFFECT_CAPITALS and wxTEXT_ATTR_EFFECT_STRIKETHROUGH - are implemented. - wxTEXT_ATTR_EFFECT_CAPITALS capitalises text when displayed (leaving the case - of the actual buffer - text unchanged), and wxTEXT_ATTR_EFFECT_STRIKETHROUGH draws a line through text. - To set effects, you should also pass wxTEXT_ATTR_EFFECTS to SetFlags(), and call - SetTextEffectFlags() with the styles (taken from the - above set) that you are interested in setting. - */ - void SetTextEffects(int effects); - - /** - Sets the URL for the content. Sets the wxTEXT_ATTR_URL style; content with this - style - causes wxRichTextCtrl to show a hand cursor over it, and wxRichTextCtrl - generates - a wxTextUrlEvent when the content is clicked. - */ - void SetURL(const wxString& url); - - /** - Assignment from a wxTextAttr object. - */ - void operator operator=(const wxTextAttr& attr); -}; - -/** - Describes the possible return values of wxTextCtrl::HitTest(). - - The element names correspond to the relationship between the point asked - for and the character returned, e.g. @c wxTE_HT_BEFORE means that the point - is before (leftward or upward) it and so on. - */ -enum wxTextCtrlHitTestResult -{ - /// Indicates that wxTextCtrl::HitTest() is not implemented on this - /// platform. - wxTE_HT_UNKNOWN = -2, - - /// The point is before the character returned. - wxTE_HT_BEFORE, - - /// The point is directly on the character returned. - wxTE_HT_ON_TEXT, - - /// The point is below the last line of the control. - wxTE_HT_BELOW, - - /// The point is beyond the end of line containing the character returned. - wxTE_HT_BEYOND -}; - - -/** - @class wxTextCtrl - @wxheader{textctrl.h} - - A text control allows text to be displayed and edited. - - It may be single line or multi-line. - - @beginStyleTable - @style{wxTE_PROCESS_ENTER} - The control will generate the event wxEVT_COMMAND_TEXT_ENTER - (otherwise pressing Enter key is either processed internally by the - control or used for navigation between dialog controls). - @style{wxTE_PROCESS_TAB} - The control will receive wxEVT_CHAR events for TAB pressed - - normally, TAB is used for passing to the next control in a dialog - instead. For the control created with this style, you can still use - Ctrl-Enter to pass to the next control from the keyboard. - @style{wxTE_MULTILINE} - The text control allows multiple lines. - @style{wxTE_PASSWORD} - The text will be echoed as asterisks. - @style{wxTE_READONLY} - The text will not be user-editable. - @style{wxTE_RICH} - Use rich text control under Win32, this allows to have more than - 64KB of text in the control even under Win9x. This style is ignored - under other platforms. - @style{wxTE_RICH2} - Use rich text control version 2.0 or 3.0 under Win32, this style is - ignored under other platforms - @style{wxTE_AUTO_URL} - Highlight the URLs and generate the wxTextUrlEvents when mouse - events occur over them. This style is only supported for wxTE_RICH - Win32 and multi-line wxGTK2 text controls. - @style{wxTE_NOHIDESEL} - By default, the Windows text control doesn't show the selection - when it doesn't have focus - use this style to force it to always - show it. It doesn't do anything under other platforms. - @style{wxHSCROLL} - A horizontal scrollbar will be created and used, so that text won't - be wrapped. No effect under wxGTK1. - @style{wxTE_NO_VSCROLL} - For multiline controls only: vertical scrollbar will never be - created. This limits the amount of text which can be entered into - the control to what can be displayed in it under MSW but not under - GTK2. Currently not implemented for the other platforms. - @style{wxTE_LEFT} - The text in the control will be left-justified (default). - @style{wxTE_CENTRE} - The text in the control will be centered (currently wxMSW and - wxGTK2 only). - @style{wxTE_RIGHT} - The text in the control will be right-justified (currently wxMSW - and wxGTK2 only). - @style{wxTE_DONTWRAP} - Same as wxHSCROLL style: don't wrap at all, show horizontal - scrollbar instead. - @style{wxTE_CHARWRAP} - Wrap the lines too long to be shown entirely at any position - (wxUniv and wxGTK2 only). - @style{wxTE_WORDWRAP} - Wrap the lines too long to be shown entirely at word boundaries - (wxUniv and wxGTK2 only). - @style{wxTE_BESTWRAP} - Wrap the lines at word boundaries or at any other character if - there are words longer than the window width (this is the default). - @style{wxTE_CAPITALIZE} - On PocketPC and Smartphone, causes the first letter to be - capitalized. - @endStyleTable - - - @section textctrl_text_format wxTextCtrl Text Format - - The multiline text controls always store the text as a sequence of lines - separated by @c '\\n' characters, i.e. in the Unix text format even on - non-Unix platforms. This allows the user code to ignore the differences - between the platforms but at a price: the indices in the control such as - those returned by GetInsertionPoint() or GetSelection() can @b not be used - as indices into the string returned by GetValue() as they're going to be - slightly off for platforms using @c "\\r\\n" as separator (as Windows - does). - - Instead, if you need to obtain a substring between the 2 indices obtained - from the control with the help of the functions mentioned above, you should - use GetRange(). And the indices themselves can only be passed to other - methods, for example SetInsertionPoint() or SetSelection(). - - To summarize: never use the indices returned by (multiline) wxTextCtrl as - indices into the string it contains, but only as arguments to be passed - back to the other wxTextCtrl methods. This problem doesn't arise for - single-line platforms however where the indices in the control do - correspond to the positions in the value string. - - - @section textctrl_styles wxTextCtrl Styles. - - Multi-line text controls support styling, i.e. provide a possibility to set - colours and font for individual characters in it (note that under Windows - @c wxTE_RICH style is required for style support). To use the styles you - can either call SetDefaultStyle() before inserting the text or call - SetStyle() later to change the style of the text already in the control - (the first solution is much more efficient). - - In either case, if the style doesn't specify some of the attributes (for - example you only want to set the text colour but without changing the font - nor the text background), the values of the default style will be used for - them. If there is no default style, the attributes of the text control - itself are used. - - So the following code correctly describes what it does: the second call to - SetDefaultStyle() doesn't change the text foreground colour (which stays - red) while the last one doesn't change the background colour (which stays - grey): - - @code - text->SetDefaultStyle(wxTextAttr(*wxRED)); - text->AppendText("Red text\n"); - text->SetDefaultStyle(wxTextAttr(wxNullColour, *wxLIGHT_GREY)); - text->AppendText("Red on grey text\n"); - text->SetDefaultStyle(wxTextAttr(*wxBLUE); - text->AppendText("Blue on grey text\n"); - @endcode - - - @section textctrl_cpp_streams wxTextCtrl and C++ Streams - - This class multiply-inherits from @c std::streambuf (except for some really - old compilers using non-standard iostream library), allowing code such as - the following: - - @code - wxTextCtrl *control = new wxTextCtrl(...); - - ostream stream(control) - - stream << 123.456 << " some text\n"; - stream.flush(); - @endcode - - Note that even if your compiler doesn't support this (the symbol - @c wxHAS_TEXT_WINDOW_STREAM has value of 0 then) you can still use - wxTextCtrl itself in a stream-like manner: - - @code - wxTextCtrl *control = new wxTextCtrl(...); - - *control << 123.456 << " some text\n"; - @endcode - - However the possibility to create an ostream associated with wxTextCtrl may - be useful if you need to redirect the output of a function taking an - ostream as parameter to a text control. - - Another commonly requested need is to redirect @c std::cout to the text - control. This may be done in the following way: - - @code - #include - - wxTextCtrl *control = new wxTextCtrl(...); - - std::streambuf *sbOld = std::cout.rdbuf(); - std::cout.rdbuf(control); - - // use cout as usual, the output appears in the text control - ... - - std::cout.rdbuf(sbOld); - @endcode - - But wxWidgets provides a convenient class to make it even simpler so - instead you may just do - - @code - #include - - wxTextCtrl *control = new wxTextCtrl(...); - - wxStreamToTextRedirector redirect(control); - - // all output to cout goes into the text control until the exit from - // current scope - @endcode - - See wxStreamToTextRedirector for more details. - - - @section textctrl_event_handling Event Handling. - - The following commands are processed by default event handlers in - wxTextCtrl: @c wxID_CUT, @c wxID_COPY, @c wxID_PASTE, @c wxID_UNDO, @c - wxID_REDO. The associated UI update events are also processed - automatically, when the control has the focus. - - To process input from a text control, use these event handler macros to - direct input to member functions that take a wxCommandEvent argument. - - @beginEventTable{wxCommandEvent} - @event{EVT_TEXT(id, func)} - Respond to a wxEVT_COMMAND_TEXT_UPDATED event, generated when the text - changes. Notice that this event will be sent when the text controls - contents changes -- whether this is due to user input or comes from the - program itself (for example, if SetValue() is called); see - ChangeValue() for a function which does not send this event. This - event is however not sent during the control creation. - @event{EVT_TEXT_ENTER(id, func)} - Respond to a wxEVT_COMMAND_TEXT_ENTER event, generated when enter is - pressed in a text control which must have wxTE_PROCESS_ENTER style for - this event to be generated. - @event{EVT_TEXT_URL(id, func)} - A mouse event occurred over an URL in the text control (wxMSW and - wxGTK2 only currently). - @event{EVT_TEXT_MAXLEN(id, func)} - This event is generated when the user tries to enter more text into the - control than the limit set by SetMaxLength(), see its description. - @endEventTable - - @library{wxcore} - @category{ctrl} - - - @see wxTextCtrl::Create, wxValidator -*/ -class wxTextCtrl : public wxControl -{ -public: - //@{ - /** - Constructor, creating and showing a text control. - @see Create() - */ - wxTextCtrl(); - - /** - Constructor, creating and showing a text control. - - @param parent - Parent window. Should not be @NULL. - @param id - Control identifier. A value of -1 denotes a default value. - @param value - Default text value. - @param pos - Text control position. - @param size - Text control size. - @param style - Window style. See wxTextCtrl. - @param validator - Window validator. - @param name - Window name. - - @remarks The horizontal scrollbar (wxHSCROLL style flag) will only be - created for multi-line text controls. Without a horizontal - scrollbar, text lines that don't fit in the control's size will be - wrapped (but no newline character is inserted). Single line - controls don't have a horizontal scrollbar, the text is - automatically scrolled so that the insertion point is always - visible. - - @see Create(), wxValidator - */ - wxTextCtrl(wxWindow* parent, wxWindowID id, - const wxString& value = "", - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = 0, - const wxValidator& validator = wxDefaultValidator, - const wxString& name = wxTextCtrlNameStr); - //@} - - /** - Destructor, destroying the text control. - */ - ~wxTextCtrl(); - - /** - Appends the text to the end of the text control. - - @param text - Text to write to the text control. - - @remarks After the text is appended, the insertion point will be at the - end of the text control. If this behaviour is not desired, the - programmer should use GetInsertionPoint and SetInsertionPoint. - - @see WriteText() - */ - void AppendText(const wxString& text); - - /** - Call this function to enable auto-completion of the text typed in a - single-line text control using the given @a choices. - - Notice that currently this function is only implemented in wxGTK2 and - wxMSW ports and does nothing under the other platforms. - - @since 2.9.0 - - @return - @true if the auto-completion was enabled or @false if the operation - failed, typically because auto-completion is not supported by the - current platform. - - @see AutoCompleteFileNames() - */ - bool AutoComplete(const wxArrayString& choices); - - /** - Call this function to enable auto-completion of the text typed in a - single-line text control using all valid file system paths. - - Notice that currently this function is only implemented in wxGTK2 port - and does nothing under the other platforms. - - @since 2.9.0 - - @return - @true if the auto-completion was enabled or @false if the operation - failed, typically because auto-completion is not supported by the - current platform. - - @see AutoComplete() - */ - bool AutoCompleteFileNames(); - - /** - Returns @true if the selection can be copied to the clipboard. - */ - virtual bool CanCopy(); - - /** - Returns @true if the selection can be cut to the clipboard. - */ - virtual bool CanCut(); - - /** - Returns @true if the contents of the clipboard can be pasted into the - text control. - - On some platforms (Motif, GTK) this is an approximation and returns - @true if the control is editable, @false otherwise. - */ - virtual bool CanPaste(); - - /** - Returns @true if there is a redo facility available and the last - operation can be redone. - */ - virtual bool CanRedo(); - - /** - Returns @true if there is an undo facility available and the last - operation can be undone. - */ - virtual bool CanUndo(); - - /** - Sets the text value and marks the control as not-modified (which means - that IsModified() would return @false immediately after the call to - SetValue). - - This functions does not generate the @c wxEVT_COMMAND_TEXT_UPDATED - event but otherwise is identical to SetValue(). - See @ref overview_progevent "this topic" for more information. - - @since 2.7.1 - - @param value - The new value to set. It may contain newline characters if the text - control is multi-line. - */ - virtual void ChangeValue(const wxString& value); - - /** - Clears the text in the control. - - Note that this function will generate a @c wxEVT_COMMAND_TEXT_UPDATED - event, i.e. its effect is identical to calling @c SetValue(""). - */ - virtual void Clear(); - - /** - Copies the selected text to the clipboard. - */ - virtual void Copy(); - - /** - Creates the text control for two-step construction. - - This method should be called if the default constructor was used for - the control creation. Its parameters have the same meaning as for the - non-default constructor. - */ - bool Create(wxWindow* parent, wxWindowID id, - const wxString& value = "", - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = 0, - const wxValidator& validator = wxDefaultValidator, - const wxString& name = wxTextCtrlNameStr); - - /** - Copies the selected text to the clipboard and removes the selection. - */ - virtual void Cut(); - - /** - Resets the internal modified flag as if the current changes had been - saved. - */ - void DiscardEdits(); - - /** - This functions inserts into the control the character which would have - been inserted if the given key event had occurred in the text control. - - The @a event object should be the same as the one passed to @c - EVT_KEY_DOWN handler previously by wxWidgets. Please note that this - function doesn't currently work correctly for all keys under any - platform but MSW. - - @return - @true if the event resulted in a change to the control, @false - otherwise. - */ - bool EmulateKeyPress(const wxKeyEvent& event); - - /** - Returns the style currently used for the new text. - - @see SetDefaultStyle() - */ - const wxTextAttr GetDefaultStyle() const; - - /** - Returns the insertion point, or cursor, position. - - This is defined as the zero based index of the character position to - the right of the insertion point. For example, if the insertion point - is at the end of the single-line text control, it is equal to both - GetLastPosition() and GetValue().length() (but notice that the latter - equality is not necessarily true for multiline edit controls which may - use multiple new line characters). - */ - virtual long GetInsertionPoint() const; - - /** - Returns the zero based index of the last position in the text control, - which is equal to the number of characters in the control. - */ - virtual wxTextPos GetLastPosition() const; - - /** - Gets the length of the specified line, not including any trailing - newline character(s). - - @param lineNo - Line number (starting from zero). - - @return - The length of the line, or -1 if @a lineNo was invalid. - */ - int GetLineLength(long lineNo) const; - - /** - Returns the contents of a given line in the text control, not including - any trailing newline character(s). - - @param lineNo - The line number, starting from zero. - - @return - The contents of the line. - */ - wxString GetLineText(long lineNo) const; - - /** - Returns the number of lines in the text control buffer. - - @remarks Note that even empty text controls have one line (where the - insertion point is), so GetNumberOfLines() never - returns 0. - */ - int GetNumberOfLines() const; - - /** - Returns the string containing the text starting in the positions - @a from and up to @a to in the control. - - The positions must have been returned by another wxTextCtrl method. - Please note that the positions in a multiline wxTextCtrl do @b not - correspond to the indices in the string returned by GetValue() because - of the different new line representations (@c CR or @c CR LF) and so - this method should be used to obtain the correct results instead of - extracting parts of the entire value. It may also be more efficient, - especially if the control contains a lot of data. - */ - virtual wxString GetRange(long from, long to) const; - - /** - Gets the current selection span. - - If the returned values are equal, there was no selection. Please note - that the indices returned may be used with the other wxTextCtrl methods - but don't necessarily represent the correct indices into the string - returned by GetValue() for multiline controls under Windows (at least,) - you should use GetStringSelection() to get the selected text. - - @param from - The returned first position. - @param to - The returned last position. - */ - virtual void GetSelection(long* from, long* to) const; - - /** - Gets the text currently selected in the control. - - If there is no selection, the returned string is empty. - */ - virtual wxString GetStringSelection(); - - /** - Returns the style at this position in the text control. - - Not all platforms support this function. - - @return - @true on success, @false if an error occurred (this may also mean - that the styles are not supported under this platform). - - @see SetStyle(), wxTextAttr - */ - bool GetStyle(long position, wxTextAttr& style); - - /** - Gets the contents of the control. - Notice that for a multiline text control, the lines will be separated - by (Unix-style) @c \\n characters, even under Windows where they are - separated by a @c \\r\\n sequence in the native control. - */ - wxString GetValue() const; - - /** - This function finds the character at the specified position expressed - in pixels. - - If the return code is not @c wxTE_HT_UNKNOWN the row and column of the - character closest to this position are returned in the @a col and @a - row parameters (unless the pointers are @NULL which is allowed). Please - note that this function is currently only implemented in wxUniv, wxMSW - and wxGTK2 ports. - - @see PositionToXY(), XYToPosition() - */ - wxTextCtrlHitTestResult HitTest(const wxPoint& pt, - wxTextCoord col, - wxTextCoord row) const; - - /** - Returns @true if the controls contents may be edited by user (note that - it always can be changed by the program). - - In other words, this functions returns @true if the control hasn't been - put in read-only mode by a previous call to SetEditable(). - */ - bool IsEditable() const; - - /** - Returns @true if the control is currently empty. - - This is the same as @c GetValue().empty() but can be much more - efficient for the multiline controls containing big amounts of text. - - @since 2.7.1 - */ - bool IsEmpty() const; - - /** - Returns @true if the text has been modified by user. - - Note that calling SetValue() doesn't make the control modified. - - @see MarkDirty() - */ - bool IsModified() const; - - /** - Returns @true if this is a multi line edit control and @false - otherwise. - - @see IsSingleLine() - */ - bool IsMultiLine() const; - - /** - Returns @true if this is a single line edit control and @false - otherwise. - - @see @ref IsSingleLine() IsMultiLine - */ - bool IsSingleLine() const; - - /** - Loads and displays the named file, if it exists. - - @param filename - The filename of the file to load. - @param fileType - The type of file to load. This is currently ignored in wxTextCtrl. - - @return - @true if successful, @false otherwise. - */ - bool LoadFile(const wxString& filename, - int fileType = wxTEXT_TYPE_ANY); - - /** - Mark text as modified (dirty). - - @see IsModified() - */ - void MarkDirty(); - - /** - This event handler function implements default drag and drop behaviour, - which is to load the first dropped file into the control. - - @param event - The drop files event. - - @remarks This is not implemented on non-Windows platforms. - - @see wxDropFilesEvent - */ - void OnDropFiles(wxDropFilesEvent& event); - - /** - Pastes text from the clipboard to the text item. - */ - virtual void Paste(); - - /** - Converts given position to a zero-based column, line number pair. - - @param pos - Position. - @param x - Receives zero based column number. - @param y - Receives zero based line number. - - @return - @true on success, @false on failure (most likely due to a too large - position parameter). - - @see XYToPosition() - */ - bool PositionToXY(long pos, long* x, long* y) const; - - /** - If there is a redo facility and the last operation can be redone, - redoes the last operation. - - Does nothing if there is no redo facility. - */ - virtual void Redo(); - - /** - Removes the text starting at the first given position up to (but not - including) the character at the last position. - - @param from - The first position. - @param to - The last position. - */ - virtual void Remove(long from, long to); - - /** - Replaces the text starting at the first position up to (but not - including) the character at the last position with the given text. - - @param from - The first position. - @param to - The last position. - @param value - The value to replace the existing text with. - */ - virtual void Replace(long from, long to, const wxString& value); - - /** - Saves the contents of the control in a text file. - - @param filename - The name of the file in which to save the text. - @param fileType - The type of file to save. This is currently ignored in wxTextCtrl. - - @return - @true if the operation was successful, @false otherwise. - */ - bool SaveFile(const wxString& filename, - int fileType = wxTEXT_TYPE_ANY); - - /** - Changes the default style to use for the new text which is going to be - added to the control using WriteText() or AppendText(). - - If either of the font, foreground, or background colour is not set in - @a style, the values of the previous default style are used for them. - If the previous default style didn't set them neither, the global font - or colours of the text control itself are used as fall back. However if - the @a style parameter is the default wxTextAttr, then the default - style is just reset (instead of being combined with the new style which - wouldn't change it at all). - - @param style - The style for the new text. - - @return - @true on success, @false if an error occurred (this may also mean - that the styles are not supported under this platform). - - @see GetDefaultStyle() - */ - bool SetDefaultStyle(const wxTextAttr& style); - - /** - Makes the text item editable or read-only, overriding the - @b wxTE_READONLY flag. - - @param editable - If @true, the control is editable. If @false, the control is - read-only. - - @see IsEditable() - */ - virtual void SetEditable(const bool editable); - - /** - Sets the insertion point at the given position. - - @param pos - Position to set. - */ - virtual void SetInsertionPoint(long pos); - - /** - Sets the insertion point at the end of the text control. - - This is equivalent to calling wxTextCtrl::SetInsertionPoint() with - wxTextCtrl::GetLastPosition() argument. - */ - virtual void SetInsertionPointEnd(); - - /** - This function sets the maximum number of characters the user can enter - into the control. - - In other words, it allows to limit the text value length to @a len not - counting the terminating @c NUL character. If @a len is 0, the - previously set max length limit, if any, is discarded and the user may - enter as much text as the underlying native text control widget - supports (typically at least 32Kb). If the user tries to enter more - characters into the text control when it already is filled up to the - maximal length, a @c wxEVT_COMMAND_TEXT_MAXLEN event is sent to notify - the program about it (giving it the possibility to show an explanatory - message, for example) and the extra input is discarded. Note that in - wxGTK this function may only be used with single line text controls. - */ - virtual void SetMaxLength(unsigned long len); - - /** - Marks the control as being modified by the user or not. - - @see MarkDirty(), DiscardEdits() - */ - void SetModified(bool modified); - - /** - Selects the text starting at the first position up to (but not - including) the character at the last position. - - If both parameters are equal to -1 all text in the control is selected. - - @param from - The first position. - @param to - The last position. - - @see SelectAll() - */ - virtual void SetSelection(long from, long to); - - /** - Selects all text in the control. - - @see SetSelection() - */ - virtual void SelectAll(); - - /** - Changes the style of the given range. - - If any attribute within @a style is not set, the corresponding - attribute from GetDefaultStyle() is used. - - @param start - The start of the range to change. - @param end - The end of the range to change. - @param style - The new style for the range. - - @return - @true on success, @false if an error occurred (this may also mean - that the styles are not supported under this platform). - - @see GetStyle(), wxTextAttr - */ - bool SetStyle(long start, long end, const wxTextAttr& style); - - /** - Sets the text value and marks the control as not-modified (which means - that IsModified() would return @false immediately after the call to - SetValue). - - Note that this function generates a @c wxEVT_COMMAND_TEXT_UPDATED - event, to avoid this you can use ChangeValue() instead. - - @param value - The new value to set. It may contain newline characters if the text - control is multi-line. - */ - virtual void SetValue(const wxString& value); - - /** - Makes the line containing the given position visible. - - @param pos - The position that should be visible. - */ - void ShowPosition(long pos); - - /** - If there is an undo facility and the last operation can be undone, - undoes the last operation. - - Does nothing if there is no undo facility. - */ - virtual void Undo(); - - /** - Writes the text into the text control at the current insertion position. - - @param text - Text to write to the text control. - - @remarks Newlines in the text string are the only control characters - allowed, and they will cause appropriate line breaks. See () and - AppendText() for more convenient ways of writing to the window. - */ - void WriteText(const wxString& text); - - /** - Converts the given zero based column and line number to a position. - - @param x - The column number. - @param y - The line number. - - @return - The position value, or -1 if x or y was invalid. - */ - long XYToPosition(long x, long y); - - //@{ - /** - Operator definitions for appending to a text control. - - These operators can be used as with the standard C++ streams, for - example: - @code - wxTextCtrl *wnd = new wxTextCtrl(my_frame); - - (*wnd) << "Welcome to text control number " << 1 << ".\n"; - @endcode - */ - - wxTextCtrl& operator<<(const wxString& s); - wxTextCtrl& operator<<(int i); - wxTextCtrl& operator<<(long i); - wxTextCtrl& operator<<(float f); - wxTextCtrl& operator<<(double d); - wxTextCtrl& operator<<(char c); - wxTextCtrl& operator<<(wchar_t c); - //@} -}; - - - -/** - @class wxStreamToTextRedirector - @wxheader{textctrl.h} - - This class can be used to (temporarily) redirect all output sent to a C++ - ostream object to a wxTextCtrl instead. - - @note Some compilers and/or build configurations don't support multiply - inheriting wxTextCtrl from @c std::streambuf in which - case this class is not compiled in. You also must have @c wxUSE_STD_IOSTREAM - option on (i.e. set to 1) in your setup.h to be able to use it. Under Unix, - specify @c --enable-std_iostreams switch when running configure for this. - - Example of usage: - - @code - using namespace std; - - wxTextCtrl *text = new wxTextCtrl(...); - - { - wxStreamToTextRedirector redirect(text); - - // this goes to the text control - cout "Hello, text!" endl; - } - - // this goes somewhere else, presumably to stdout - cout "Hello, console!" endl; - @endcode - - - @library{wxcore} - @category{logging} - - @see wxTextCtrl -*/ -class wxStreamToTextRedirector -{ -public: - /** - The constructor starts redirecting output sent to @a ostr or @a cout for - the default parameter value to the text control @a text. - - @param text - The text control to append output too, must be non-@NULL - @param ostr - The C++ stream to redirect, cout is used if it is @NULL - */ - wxStreamToTextRedirector(wxTextCtrl text, ostream* ostr = NULL); - - /** - When a wxStreamToTextRedirector object is destroyed, the redirection is ended - and any output sent to the C++ ostream which had been specified at the time of - the object construction will go to its original destination. - */ - ~wxStreamToTextRedirector(); -}; - diff --git a/interface/textdlg.h b/interface/textdlg.h deleted file mode 100644 index dc7245790d..0000000000 --- a/interface/textdlg.h +++ /dev/null @@ -1,136 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: textdlg.h -// Purpose: interface of wxPasswordEntryDialog -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxPasswordEntryDialog - @wxheader{textdlg.h} - - This class represents a dialog that requests a one-line password string from - the user. - It is implemented as a generic wxWidgets dialog. - - @library{wxbase} - @category{cmndlg} - - @see @ref overview_wxpasswordentrydialogoverview "wxPassowrdEntryDialog - overview" -*/ -class wxPasswordEntryDialog : public wxTextEntryDialog -{ -public: - -}; - - - -/** - @class wxTextEntryDialog - @wxheader{textdlg.h} - - This class represents a dialog that requests a one-line text string from the - user. - It is implemented as a generic wxWidgets dialog. - - @library{wxbase} - @category{cmndlg} - - @see @ref overview_wxtextentrydialogoverview "wxTextEntryDialog overview" -*/ -class wxTextEntryDialog : public wxDialog -{ -public: - /** - Constructor. Use ShowModal() to show the dialog. - - @param parent - Parent window. - @param message - Message to show on the dialog. - @param defaultValue - The default value, which may be the empty string. - @param style - A dialog style, specifying the buttons (wxOK, wxCANCEL) - and an optional wxCENTRE style. Additionally, wxTextCtrl styles (such as - wxTE_PASSWORD) may be specified here. - @param pos - Dialog position. - */ - wxTextEntryDialog(wxWindow* parent, const wxString& message, - const wxString& caption = "Please enter text", - const wxString& defaultValue = "", - long style = wxOK | wxCANCEL | wxCENTRE, - const wxPoint& pos = wxDefaultPosition); - - /** - Destructor. - */ - ~wxTextEntryDialog(); - - /** - Returns the text that the user has entered if the user has pressed OK, or the - original value - if the user has pressed Cancel. - */ - wxString GetValue() const; - - /** - Sets the default text value. - */ - void SetValue(const wxString& value); - - /** - Shows the dialog, returning wxID_OK if the user pressed OK, and wxID_CANCEL - otherwise. - */ - int ShowModal(); -}; - - - -// ============================================================================ -// Global functions/macros -// ============================================================================ - -/** @ingroup group_funcmacro_dialog */ -//@{ - -/** - Pop up a dialog box with title set to @e caption, @c message, and a - @c default_value. The user may type in text and press OK to return this - text, or press Cancel to return the empty string. - - If @c centre is @true, the message text (which may include new line - characters) is centred; if @false, the message is left-justified. - - @header{wx/textdlg.h} -*/ -wxString wxGetTextFromUser(const wxString& message, - const wxString& caption = "Input text", - const wxString& default_value = "", - wxWindow* parent = NULL, - int x = wxDefaultCoord, - int y = wxDefaultCoord, - bool centre = true); - -/** - Similar to wxGetTextFromUser() but the text entered in the dialog is not - shown on screen but replaced with stars. This is intended to be used for - entering passwords as the function name implies. - - @header{wx/textdlg.h} -*/ -wxString wxGetPasswordFromUser(const wxString& message, - const wxString& caption = "Input text", - const wxString& default_value = "", - wxWindow* parent = NULL, - int x = wxDefaultCoord, - int y = wxDefaultCoord, - bool centre = true); - -//@} - diff --git a/interface/textfile.h b/interface/textfile.h deleted file mode 100644 index ca8b2d8da1..0000000000 --- a/interface/textfile.h +++ /dev/null @@ -1,241 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: textfile.h -// Purpose: interface of wxTextFile -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxTextFile - @wxheader{textfile.h} - - The wxTextFile is a simple class which allows to work with text files on line by - line basis. It also understands the differences in line termination characters - under different platforms and will not do anything bad to files with "non - native" line termination sequences - in fact, it can be also used to modify the - text files and change the line termination characters from one type (say DOS) to - another (say Unix). - - One word of warning: the class is not at all optimized for big files and thus - it will load the file entirely into memory when opened. Of course, you should - not - work in this way with large files (as an estimation, anything over 1 Megabyte is - surely too big for this class). On the other hand, it is not a serious - limitation for small files like configuration files or program sources - which are well handled by wxTextFile. - - The typical things you may do with wxTextFile in order are: - - Create and open it: this is done with either - wxTextFile::Create or wxTextFile::Open - function which opens the file (name may be specified either as the argument to - these functions or in the constructor), reads its contents in memory (in the - case of @c Open()) and closes it. - Work with the lines in the file: this may be done either with "direct - access" functions like wxTextFile::GetLineCount and - wxTextFile::GetLine (@e operator[] does exactly the same - but looks more like array addressing) or with "sequential access" functions - which include wxTextFile::GetFirstLine/ - wxTextFile::GetNextLine and also - wxTextFile::GetLastLine/wxTextFile::GetPrevLine. - For the sequential access functions the current line number is maintained: it is - returned by wxTextFile::GetCurrentLine and may be - changed with wxTextFile::GoToLine. - Add/remove lines to the file: wxTextFile::AddLine and - wxTextFile::InsertLine add new lines while - wxTextFile::RemoveLine deletes the existing ones. - wxTextFile::Clear resets the file to empty. - Save your changes: notice that the changes you make to the file will @b not be - saved automatically; calling wxTextFile::Close or doing - nothing discards them! To save the changes you must explicitly call - wxTextFile::Write - here, you may also change the line - termination type if you wish. - - - @library{wxbase} - @category{file} - - @see wxFile -*/ -class wxTextFile -{ -public: - /** - Constructor does not load the file into memory, use Open() to do it. - */ - wxTextFile(const wxString& strFile) const; - - /** - Destructor does nothing. - */ - ~wxTextFile() const; - - /** - Adds a line to the end of file. - */ - void AddLine(const wxString& str, - wxTextFileType type = typeDefault) const; - - /** - Delete all lines from the file, set current line number to 0. - */ - void Clear() const; - - /** - Closes the file and frees memory, @b losing all changes. Use Write() - if you want to save them. - */ - bool Close() const; - - //@{ - /** - Creates the file with the given name or the name which was given in the - @ref ctor() constructor. The array of file lines is initially - empty. - It will fail if the file already exists, Open() should - be used in this case. - */ - bool Create() const; - const bool Create(const wxString& strFile) const; - //@} - - /** - Returns @true if the current line is the last one. - */ - bool Eof() const; - - /** - Return @true if file exists - the name of the file should have been specified - in the constructor before calling Exists(). - */ - bool Exists() const; - - /** - Returns the current line: it has meaning only when you're using - GetFirstLine()/GetNextLine() functions, it doesn't get updated when - you're using "direct access" functions like GetLine(). GetFirstLine() and - GetLastLine() also change the value of the current line, as well as - GoToLine(). - */ - size_t GetCurrentLine() const; - - /** - Get the line termination string corresponding to given constant. @e typeDefault - is - the value defined during the compilation and corresponds to the native format - of the platform, i.e. it will be wxTextFileType_Dos under Windows, - wxTextFileType_Unix under Unix (including Mac OS X when compiling with the - Apple Developer Tools) and wxTextFileType_Mac under Mac OS (including - Mac OS X when compiling with CodeWarrior). - */ - static const char* GetEOL(wxTextFileType type = typeDefault) const; - - /** - This method together with GetNextLine() - allows more "iterator-like" traversal of the list of lines, i.e. you may - write something like: - */ - wxString GetFirstLine() const; - - /** - Gets the last line of the file. Together with - GetPrevLine() it allows to enumerate the lines - in the file from the end to the beginning like this: - */ - wxString GetLastLine(); - - /** - Retrieves the line number @a n from the file. The returned line may be - modified but you shouldn't add line terminator at the end - this will be done - by wxTextFile. - */ - wxString GetLine(size_t n) const; - - /** - Get the number of lines in the file. - */ - size_t GetLineCount() const; - - /** - Get the type of the line (see also wxTextFile::GetEOL) - */ - wxTextFileType GetLineType(size_t n) const; - - /** - Get the name of the file. - */ - const char* GetName() const; - - /** - Gets the next line (see GetFirstLine() for - the example). - */ - wxString GetNextLine(); - - /** - Gets the previous line in the file. - */ - wxString GetPrevLine(); - - /** - Changes the value returned by GetCurrentLine() - and used by wxTextFile::GetFirstLine/GetNextLine(). - */ - void GoToLine(size_t n) const; - - /** - Guess the type of file (which is supposed to be opened). If sufficiently - many lines of the file are in DOS/Unix/Mac format, the corresponding value will - be returned. If the detection mechanism fails wxTextFileType_None is returned. - */ - wxTextFileType GuessType() const; - - /** - Insert a line before the line number @e n. - */ - void InsertLine(const wxString& str, size_t n, - wxTextFileType type = typeDefault) const; - - /** - Returns @true if the file is currently opened. - */ - bool IsOpened() const; - - //@{ - /** - ) - Open() opens the file with the given name or the name which was given in the - @ref ctor() constructor and also loads file in memory on - success. It will fail if the file does not exist, - Create() should be used in this case. - The @e conv argument is only meaningful in Unicode build of wxWidgets when - it is used to convert the file to wide character representation. - */ - bool Open() const; - const bool Open(const wxString& strFile) const; - //@} - - /** - Delete line number @a n from the file. - */ - void RemoveLine(size_t n) const; - - /** - ) - Change the file on disk. The @a typeNew parameter allows you to change the - file format (default argument means "don't change type") and may be used to - convert, for example, DOS files to Unix. - The @e conv argument is only meaningful in Unicode build of wxWidgets when - it is used to convert all lines to multibyte representation before writing them - them to physical file. - Returns @true if operation succeeded, @false if it failed. - */ - bool Write(wxTextFileType typeNew = wxTextFileType_None) const; - - /** - The same as GetLine(). - */ - wxString operator[](size_t n) const; -}; - diff --git a/interface/tglbtn.h b/interface/tglbtn.h deleted file mode 100644 index 4a679c7ee1..0000000000 --- a/interface/tglbtn.h +++ /dev/null @@ -1,170 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: tglbtn.h -// Purpose: interface of wxBitmapToggleButton -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - - -/** - @class wxToggleButton - @wxheader{tglbtn.h} - - wxToggleButton is a button that stays pressed when clicked by the user. In - other words, it is similar to wxCheckBox in - functionality but looks like a wxButton. - - Since wxWidgets version 2.9.0 this control emits an update UI event. - - You can see wxToggleButton in action in the sixth page of the - controls() sample. - - @beginEventTable{wxCommandEvent} - @event{EVT_TOGGLEBUTTON(id, func)} - Handles a toggle button click event. - @endEventTable - - @library{wxcore} - @category{ctrl} - - - @see wxCheckBox, wxButton, wxBitmapToggleButton -*/ -class wxToggleButton : public wxControl -{ -public: - //@{ - /** - Constructor, creating and showing a toggle button. - - @param parent - Parent window. Must not be @NULL. - @param id - Toggle button identifier. The value wxID_ANY indicates a default value. - @param label - Text to be displayed next to the toggle button. - @param pos - Toggle button position. If wxDefaultPosition is specified then a - default position is chosen. - @param size - Toggle button size. If wxDefaultSize is specified then a - default size is chosen. - @param style - Window style. See wxToggleButton. - @param validator - Window validator. - @param name - Window name. - - @see Create(), wxValidator - */ - wxToggleButton(); - wxToggleButton(wxWindow* parent, wxWindowID id, - const wxString& label, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = 0, - const wxValidator& val = wxDefaultValidator, - const wxString& name = "checkBox"); - //@} - - /** - Destructor, destroying the toggle button. - */ - virtual ~wxToggleButton(); - - /** - Creates the toggle button for two-step construction. See wxToggleButton() - for details. - */ - bool Create(wxWindow* parent, wxWindowID id, - const wxString& label, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = 0, - const wxValidator& val = wxDefaultValidator, - const wxString& name = "checkBox"); - - /** - Gets the state of the toggle button. - - @return Returns @true if it is pressed, @false otherwise. - */ - bool GetValue() const; - - /** - Sets the toggle button to the given state. This does not cause a - @c EVT_TOGGLEBUTTON event to be emitted. - - @param state - If @true, the button is pressed. - */ - void SetValue(bool state); -}; - - -/** - @class wxBitmapToggleButton - @wxheader{tglbtn.h} - - wxBitmapToggleButton is a wxToggleButton - that contains a bitmap instead of text. - - This control emits an update UI event. - - @beginEventTable{wxCommandEvent} - @event{EVT_TOGGLEBUTTON(id, func)} - Handles a toggle button click event. - @endEventTable - - @library{wxcore} - @category{ctrl} - -*/ -class wxBitmapToggleButton : public wxControl -{ -public: - //@{ - /** - Constructor, creating and showing a toggle button with the bitmap @e label. - Internally calls Create(). - */ - wxBitmapToggleButton(); - wxBitmapToggleButton(wxWindow* parent, wxWindowID id, - const wxBitmap& label, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = 0, - const wxValidator& val = wxDefaultValidator, - const wxString& name = "checkBox"); - //@} - - /** - Create method for two-step construction. - */ - bool Create(wxWindow* parent, wxWindowID id, - const wxBitmap& label, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = 0, - const wxValidator& val = wxDefaultValidator, - const wxString& name = "checkBox"); - - /** - Gets the state of the toggle button. - - @return Returns @true if it is pressed, @false otherwise. - */ - virtual bool GetValue() const; - - /** - Sets the toggle button to the given state. This does not cause a - @c EVT_TOGGLEBUTTON event to be emitted. - - @param state - If @true, the button is pressed. - */ - virtual void SetValue(bool state); -}; - diff --git a/interface/thread.h b/interface/thread.h deleted file mode 100644 index 2c47ea1fdb..0000000000 --- a/interface/thread.h +++ /dev/null @@ -1,1017 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: thread.h -// Purpose: interface of wxCondition -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxCondition - @wxheader{thread.h} - - wxCondition variables correspond to pthread conditions or to Win32 event - objects. They may be used in a multithreaded application to wait until the - given condition becomes @true which happens when the condition becomes signaled. - - For example, if a worker thread is doing some long task and another thread has - to wait until it is finished, the latter thread will wait on the condition - object and the worker thread will signal it on exit (this example is not - perfect because in this particular case it would be much better to just - wxThread::Wait for the worker thread, but if there are several - worker threads it already makes much more sense). - - Note that a call to wxCondition::Signal may happen before the - other thread calls wxCondition::Wait and, just as with the - pthread conditions, the signal is then lost and so if you want to be sure that - you don't miss it you must keep the mutex associated with the condition - initially locked and lock it again before calling - wxCondition::Signal. Of course, this means that this call is - going to block until wxCondition::Wait is called by another - thread. - - @library{wxbase} - @category{threading} - - @see wxThread, wxMutex -*/ -class wxCondition -{ -public: - /** - Default and only constructor. The @a mutex must be locked by the caller - before calling Wait() function. - Use IsOk() to check if the object was successfully - initialized. - */ - wxCondition(wxMutex& mutex); - - /** - Destroys the wxCondition object. The destructor is not virtual so this class - should not be used polymorphically. - */ - ~wxCondition(); - - /** - Broadcasts to all waiting threads, waking all of them up. Note that this method - may be called whether the mutex associated with this condition is locked or - not. - - @see Signal() - */ - void Broadcast(); - - /** - Returns @true if the object had been initialized successfully, @false - if an error occurred. - */ - bool IsOk() const; - - /** - Signals the object waking up at most one thread. If several threads are waiting - on the same condition, the exact thread which is woken up is undefined. If no - threads are waiting, the signal is lost and the condition would have to be - signalled again to wake up any thread which may start waiting on it later. - Note that this method may be called whether the mutex associated with this - condition is locked or not. - - @see Broadcast() - */ - void Signal(); - - /** - Waits until the condition is signalled. - This method atomically releases the lock on the mutex associated with this - condition (this is why it must be locked prior to calling Wait) and puts the - thread to sleep until Signal() or - Broadcast() is called. It then locks the mutex - again and returns. - Note that even if Signal() had been called before - Wait without waking up any thread, the thread would still wait for another one - and so it is important to ensure that the condition will be signalled after - Wait or the thread may sleep forever. - - @return Returns wxCOND_NO_ERROR on success, another value if an error - occurred. - - @see WaitTimeout() - */ - wxCondError Wait(); - - /** - Waits until the condition is signalled or the timeout has elapsed. - This method is identical to Wait() except that it - returns, with the return code of @c wxCOND_TIMEOUT as soon as the given - timeout expires. - - @param milliseconds - Timeout in milliseconds - */ - wxCondError WaitTimeout(unsigned long milliseconds); -}; - - - -/** - @class wxCriticalSectionLocker - @wxheader{thread.h} - - This is a small helper class to be used with wxCriticalSection - objects. A wxCriticalSectionLocker enters the critical section in the - constructor and leaves it in the destructor making it much more difficult to - forget to leave a critical section (which, in general, will lead to serious - and difficult to debug problems). - - Example of using it: - - @code - void Set Foo() - { - // gs_critSect is some (global) critical section guarding access to the - // object "foo" - wxCriticalSectionLocker locker(gs_critSect); - - if ( ... ) - { - // do something - ... - - return; - } - - // do something else - ... - - return; - } - @endcode - - Without wxCriticalSectionLocker, you would need to remember to manually leave - the critical section before each @c return. - - @library{wxbase} - @category{threading} - - @see wxCriticalSection, wxMutexLocker -*/ -class wxCriticalSectionLocker -{ -public: - /** - Constructs a wxCriticalSectionLocker object associated with given - @a criticalsection and enters it. - */ - wxCriticalSectionLocker(wxCriticalSection& criticalsection); - - /** - Destructor leaves the critical section. - */ - ~wxCriticalSectionLocker(); -}; - - - -/** - @class wxThreadHelper - @wxheader{thread.h} - - The wxThreadHelper class is a mix-in class that manages a single background - thread. By deriving from wxThreadHelper, a class can implement the thread - code in its own wxThreadHelper::Entry method - and easily share data and synchronization objects between the main thread - and the worker thread. Doing this prevents the awkward passing of pointers - that is needed when the original object in the main thread needs to - synchronize with its worker thread in its own wxThread derived object. - - For example, wxFrame may need to make some calculations - in a background thread and then display the results of those calculations in - the main window. - - Ordinarily, a wxThread derived object would be created - with the calculation code implemented in - wxThread::Entry. To access the inputs to the - calculation, the frame object would often to pass a pointer to itself to the - thread object. Similarly, the frame object would hold a pointer to the - thread object. Shared data and synchronization objects could be stored in - either object though the object without the data would have to access the - data through a pointer. - - However, with wxThreadHelper, the frame object and the thread object are - treated as the same object. Shared data and synchronization variables are - stored in the single object, eliminating a layer of indirection and the - associated pointers. - - @library{wxbase} - @category{threading} - - @see wxThread -*/ -class wxThreadHelper -{ -public: - /** - This constructor simply initializes a member variable. - */ - wxThreadHelper(); - - /** - The destructor frees the resources associated with the thread. - */ - ~wxThreadHelper(); - - /** - Creates a new thread. The thread object is created in the suspended state, and - you - should call @ref wxThread::Run GetThread()-Run to start running - it. You may optionally specify the stack size to be allocated to it (Ignored on - platforms that don't support setting it explicitly, eg. Unix). - - @return One of: - */ - wxThreadError Create(unsigned int stackSize = 0); - - /** - This is the entry point of the thread. This function is pure virtual and must - be implemented by any derived class. The thread execution will start here. - The returned value is the thread exit code which is only useful for - joinable threads and is the value returned by - @ref wxThread::Wait GetThread()-Wait. - This function is called by wxWidgets itself and should never be called - directly. - */ - virtual ExitCode Entry(); - - /** - This is a public function that returns the wxThread object - associated with the thread. - */ - wxThread* GetThread(); - - /** - wxThread * m_thread - the actual wxThread object. - */ -}; - - - -/** - @class wxCriticalSection - @wxheader{thread.h} - - A critical section object is used for exactly the same purpose as - mutexes(). The only difference is that under Windows platform - critical sections are only visible inside one process, while mutexes may be - shared among processes, so using critical sections is slightly more - efficient. The terminology is also slightly different: mutex may be locked (or - acquired) and unlocked (or released) while critical section is entered and left - by the program. - - Finally, you should try to use - wxCriticalSectionLocker class whenever - possible instead of directly using wxCriticalSection for the same reasons - wxMutexLocker is preferrable to - wxMutex - please see wxMutex for an example. - - @library{wxbase} - @category{threading} - - @see wxThread, wxCondition, wxCriticalSectionLocker -*/ -class wxCriticalSection -{ -public: - /** - Default constructor initializes critical section object. - */ - wxCriticalSection(); - - /** - Destructor frees the resources. - */ - ~wxCriticalSection(); - - /** - Enter the critical section (same as locking a mutex). There is no error return - for this function. After entering the critical section protecting some global - data the thread running in critical section may safely use/modify it. - */ - void Enter(); - - /** - Leave the critical section allowing other threads use the global data protected - by it. There is no error return for this function. - */ - void Leave(); -}; - - - -/** - @class wxThread - @wxheader{thread.h} - - A thread is basically a path of execution through a program. Threads are - sometimes called @e light-weight processes, but the fundamental difference - between threads and processes is that memory spaces of different processes are - separated while all threads share the same address space. - - While it makes it much easier to share common data between several threads, it - also makes it much easier to shoot oneself in the foot, so careful use of - synchronization objects such as mutexes() or @ref wxCriticalSection - "critical sections" is recommended. In addition, don't create global thread - objects because they allocate memory in their constructor, which will cause - problems for the memory checking system. - - @section overview_typeswxthread Types of wxThreads - There are two types of threads in wxWidgets: @e detached and @e joinable, - modeled after the the POSIX thread API. This is different from the Win32 API - where all threads are joinable. - - By default wxThreads in wxWidgets use the detached behavior. Detached threads - delete themselves once they have completed, either by themselves when they - complete processing or through a call to Delete(), and thus - must be created on the heap (through the new operator, for example). - Conversely, joinable threads do not delete themselves when they are done - processing and as such are safe to create on the stack. Joinable threads - also provide the ability for one to get value it returned from Entry() - through Wait(). - - You shouldn't hurry to create all the threads joinable, however, because this - has a disadvantage as well: you @b must Wait() for a joinable thread or the - system resources used by it will never be freed, and you also must delete the - corresponding wxThread object yourself if you did not create it on the stack. - In contrast, detached threads are of the "fire-and-forget" kind: you only have to - start a detached thread and it will terminate and destroy itself. - - @section overview_deletionwxthread wxThread Deletion - Regardless of whether it has terminated or not, you should call - Wait() on a joinable thread to release its memory, as outlined in - @ref overview_typeswxthread "Types of wxThreads". If you created - a joinable thread on the heap, remember to delete it manually with the delete - operator or similar means as only detached threads handle this type of memory - management. - - Since detached threads delete themselves when they are finished processing, - you should take care when calling a routine on one. If you are certain the - thread is still running and would like to end it, you may call Delete() - to gracefully end it (which implies that the thread will be deleted after - that call to Delete()). It should be implied that you should never attempt - to delete a detached thread with the delete operator or similar means. - As mentioned, Wait() or Delete() attempts to gracefully terminate a - joinable and detached thread, respectively. It does this by waiting until - the thread in question calls TestDestroy() or ends processing (returns - from wxThread::Entry). - - Obviously, if the thread does call TestDestroy() and does not end the calling - thread will come to halt. This is why it is important to call TestDestroy() in - the Entry() routine of your threads as often as possible. - As a last resort you can end the thread immediately through Kill(). It is - strongly recommended that you do not do this, however, as it does not free - the resources associated with the object (although the wxThread object of - detached threads will still be deleted) and could leave the C runtime - library in an undefined state. - - @section overview_secondarythreads wxWidgets Calls in Secondary Threads - All threads other than the "main application thread" (the one - wxApp::OnInit or your main function runs in, for example) are considered - "secondary threads". These include all threads created by Create() or the - corresponding constructors. - - GUI calls, such as those to a wxWindow or wxBitmap are explicitly not safe - at all in secondary threads and could end your application prematurely. - This is due to several reasons, including the underlying native API and - the fact that wxThread does not run a GUI event loop similar to other APIs - as MFC. - - A workaround for some wxWidgets ports is calling wxMutexGUIEnter() - before any GUI calls and then calling wxMutexGUILeave() afterwords. However, - the recommended way is to simply process the GUI calls in the main thread - through an event that is posted by either wxQueueEvent(). - This does not imply that calls to these classes are thread-safe, however, - as most wxWidgets classes are not thread-safe, including wxString. - - @section overview_pollwxThread Don't Poll a wxThread - A common problem users experience with wxThread is that in their main thread - they will check the thread every now and then to see if it has ended through - IsRunning(), only to find that their application has run into problems - because the thread is using the default behavior and has already deleted - itself. Naturally, they instead attempt to use joinable threads in place - of the previous behavior. However, polling a wxThread for when it has ended - is in general a bad idea - in fact calling a routine on any running wxThread - should be avoided if possible. Instead, find a way to notify yourself when - the thread has ended. - - Usually you only need to notify the main thread, in which case you can - post an event to it via wxPostEvent() or wxEvtHandler::AddPendingEvent. - In the case of secondary threads you can call a routine of another class - when the thread is about to complete processing and/or set the value of - a variable, possibly using mutexes() and/or other synchronization means - if necessary. - - @library{wxbase} - @category{threading} - @see wxMutex, wxCondition, wxCriticalSection -*/ -class wxThread -{ -public: - /** - This constructor creates a new detached (default) or joinable C++ - thread object. It does not create or start execution of the real thread -- - for this you should use the Create() and Run() methods. - - The possible values for @a kind parameters are: - - @b wxTHREAD_DETACHED - Creates a detached thread. - - @b wxTHREAD_JOINABLE - Creates a joinable thread. - */ - wxThread(wxThreadKind kind = wxTHREAD_DETACHED); - - /** - The destructor frees the resources associated with the thread. Notice that you - should never delete a detached thread -- you may only call - Delete() on it or wait until it terminates (and auto - destructs) itself. Because the detached threads delete themselves, they can - only be allocated on the heap. - Joinable threads should be deleted explicitly. The Delete() and Kill() functions - will not delete the C++ thread object. It is also safe to allocate them on - stack. - */ - ~wxThread(); - - /** - Creates a new thread. The thread object is created in the suspended state, - and you should call Run() to start running it. You may optionally - specify the stack size to be allocated to it (Ignored on platforms that don't - support setting it explicitly, eg. Unix system without - @c pthread_attr_setstacksize). If you do not specify the stack size, - the system's default value is used. - @b Warning: It is a good idea to explicitly specify a value as systems' - default values vary from just a couple of KB on some systems (BSD and - OS/2 systems) to one or several MB (Windows, Solaris, Linux). So, if you - have a thread that requires more than just a few KB of memory, you will - have mysterious problems on some platforms but not on the common ones. On the - other hand, just indicating a large stack size by default will give you - performance issues on those systems with small default stack since those - typically use fully committed memory for the stack. On the contrary, if - use a lot of threads (say several hundred), virtual adress space can get tight - unless you explicitly specify a smaller amount of thread stack space for each - thread. - - @return One of: - - @b wxTHREAD_NO_ERROR - No error. - - @b wxTHREAD_NO_RESOURCE - There were insufficient resources to create the thread. - - @b wxTHREAD_NO_RUNNING - The thread is already running - */ - wxThreadError Create(unsigned int stackSize = 0); - - /** - Calling Delete() gracefully terminates a - detached thread, either when the thread calls TestDestroy() or finished - processing. - (Note that while this could work on a joinable thread you simply should not - call this routine on one as afterwards you may not be able to call - Wait() to free the memory of that thread). - See @ref overview_deletionwxthread "wxThread deletion" for a broader - explanation of this routine. - */ - wxThreadError Delete(); - - /** - This is the entry point of the thread. This function is pure virtual and must - be implemented by any derived class. The thread execution will start here. - The returned value is the thread exit code which is only useful for - joinable threads and is the value returned by Wait(). - This function is called by wxWidgets itself and should never be called - directly. - */ - virtual ExitCode Entry(); - - /** - This is a protected function of the wxThread class and thus can only be called - from a derived class. It also can only be called in the context of this - thread, i.e. a thread can only exit from itself, not from another thread. - This function will terminate the OS thread (i.e. stop the associated path of - execution) and also delete the associated C++ object for detached threads. - OnExit() will be called just before exiting. - */ - void Exit(ExitCode exitcode = 0); - - /** - Returns the number of system CPUs or -1 if the value is unknown. - - @see SetConcurrency() - */ - static int GetCPUCount(); - - /** - Returns the platform specific thread ID of the current thread as a - long. This can be used to uniquely identify threads, even if they are - not wxThreads. - */ - static unsigned long GetCurrentId(); - - /** - Gets the thread identifier: this is a platform dependent number that uniquely - identifies the - thread throughout the system during its existence (i.e. the thread identifiers - may be reused). - */ - unsigned long GetId() const; - - /** - Gets the priority of the thread, between zero and 100. - - The following priorities are defined: - - @b WXTHREAD_MIN_PRIORITY: 0 - - @b WXTHREAD_DEFAULT_PRIORITY: 50 - - @b WXTHREAD_MAX_PRIORITY: 100 - */ - int GetPriority() const; - - /** - Returns @true if the thread is alive (i.e. started and not terminating). - Note that this function can only safely be used with joinable threads, not - detached ones as the latter delete themselves and so when the real thread is - no longer alive, it is not possible to call this function because - the wxThread object no longer exists. - */ - bool IsAlive() const; - - /** - Returns @true if the thread is of the detached kind, @false if it is a - joinable - one. - */ - bool IsDetached() const; - - /** - Returns @true if the calling thread is the main application thread. - */ - static bool IsMain(); - - /** - Returns @true if the thread is paused. - */ - bool IsPaused() const; - - /** - Returns @true if the thread is running. - This method may only be safely used for joinable threads, see the remark in - IsAlive(). - */ - bool IsRunning() const; - - /** - Immediately terminates the target thread. @b This function is dangerous and - should - be used with extreme care (and not used at all whenever possible)! The resources - allocated to the thread will not be freed and the state of the C runtime library - may become inconsistent. Use Delete() for detached - threads or Wait() for joinable threads instead. - For detached threads Kill() will also delete the associated C++ object. - However this will not happen for joinable threads and this means that you will - still have to delete the wxThread object yourself to avoid memory leaks. - In neither case OnExit() of the dying thread will be - called, so no thread-specific cleanup will be performed. - This function can only be called from another thread context, i.e. a thread - cannot kill itself. - It is also an error to call this function for a thread which is not running or - paused (in the latter case, the thread will be resumed first) -- if you do it, - a @b wxTHREAD_NOT_RUNNING error will be returned. - */ - wxThreadError Kill(); - - /** - Called when the thread exits. This function is called in the context of the - thread associated with the wxThread object, not in the context of the main - thread. This function will not be called if the thread was - @ref Kill() killed. - This function should never be called directly. - */ - void OnExit(); - - /** - Suspends the thread. Under some implementations (Win32), the thread is - suspended immediately, under others it will only be suspended when it calls - TestDestroy() for the next time (hence, if the - thread doesn't call it at all, it won't be suspended). - This function can only be called from another thread context. - */ - wxThreadError Pause(); - - /** - Resumes a thread suspended by the call to Pause(). - This function can only be called from another thread context. - */ - wxThreadError Resume(); - - /** - Starts the thread execution. Should be called after - Create(). - This function can only be called from another thread context. - */ - wxThreadError Run(); - - /** - Sets the thread concurrency level for this process. This is, roughly, the - number of threads that the system tries to schedule to run in parallel. - The value of 0 for @a level may be used to set the default one. - Returns @true on success or @false otherwise (for example, if this function is - not implemented for this platform -- currently everything except Solaris). - */ - static bool SetConcurrency(size_t level); - - /** - Sets the priority of the thread, between 0 and 100. It can only be set - after calling Create() but before calling - Run(). - - The following priorities are defined: - - @b WXTHREAD_MIN_PRIORITY: 0 - - @b WXTHREAD_DEFAULT_PRIORITY: 50 - - @b WXTHREAD_MAX_PRIORITY: 100 - */ - void SetPriority(int priority); - - /** - Pauses the thread execution for the given amount of time. - - This is the same as wxMilliSleep(). - */ - static void Sleep(unsigned long milliseconds); - - /** - This function should be called periodically by the thread to ensure that - calls to Pause() and Delete() will work. If it returns @true, the thread - should exit as soon as possible. Notice that under some platforms (POSIX), - implementation of Pause() also relies on this function being called, so - not calling it would prevent both stopping and suspending thread from working. - */ - virtual bool TestDestroy(); - - /** - Return the thread object for the calling thread. @NULL is returned if - the calling thread is the main (GUI) thread, but IsMain() should be used - to test whether the thread is really the main one because @NULL may also - be returned for the thread not created with wxThread class. Generally - speaking, the return value for such a thread is undefined. - */ - static wxThread* This(); - - /** - Waits for a joinable thread to terminate and returns the value the thread - returned from Entry() or @c (ExitCode)-1 on error. Notice that, unlike - Delete() doesn't cancel the thread in any way so the caller waits for as - long as it takes to the thread to exit. - You can only Wait() for joinable (not detached) threads. - This function can only be called from another thread context. - See @ref overview_deletionwxthread "wxThread deletion" for a broader - explanation of this routine. - */ - ExitCode Wait() const; - - /** - Give the rest of the thread time slice to the system allowing the other - threads to run. - Note that using this function is @b strongly discouraged, since in - many cases it indicates a design weakness of your threading model (as - does using Sleep functions). - Threads should use the CPU in an efficient manner, i.e. they should - do their current work efficiently, then as soon as the work is done block - on a wakeup event (wxCondition, wxMutex, select(), poll(), ...) - which will get signalled e.g. by other threads or a user device once further - thread work is available. Using Yield or Sleep - indicates polling-type behaviour, since we're fuzzily giving up our timeslice - and wait until sometime later we'll get reactivated, at which time we - realize that there isn't really much to do and Yield again... - The most critical characteristic of Yield is that it's operating system - specific: there may be scheduler changes which cause your thread to not - wake up relatively soon again, but instead many seconds later, - causing huge performance issues for your application. @b with a - well-behaving, CPU-efficient thread the operating system is likely to properly - care for its reactivation the moment it needs it, whereas with - non-deterministic, Yield-using threads all bets are off and the system - scheduler is free to penalize drastically, and this effect gets worse - with increasing system load due to less free CPU resources available. - You may refer to various Linux kernel sched_yield discussions for more - information. - See also Sleep(). - */ - void Yield(); -}; - -/** - @class wxSemaphore - @wxheader{thread.h} - - wxSemaphore is a counter limiting the number of threads concurrently accessing - a shared resource. This counter is always between 0 and the maximum value - specified during the semaphore creation. When the counter is strictly greater - than 0, a call to wxSemaphore::Wait returns immediately and - decrements the counter. As soon as it reaches 0, any subsequent calls to - wxSemaphore::Wait block and only return when the semaphore - counter becomes strictly positive again as the result of calling - wxSemaphore::Post which increments the counter. - - In general, semaphores are useful to restrict access to a shared resource - which can only be accessed by some fixed number of clients at the same time. For - example, when modeling a hotel reservation system a semaphore with the counter - equal to the total number of available rooms could be created. Each time a room - is reserved, the semaphore should be acquired by calling - wxSemaphore::Wait and each time a room is freed it should be - released by calling wxSemaphore::Post. - - @library{wxbase} - @category{threading} -*/ -class wxSemaphore -{ -public: - /** - Specifying a @a maxcount of 0 actually makes wxSemaphore behave as if - there is no upper limit. If maxcount is 1, the semaphore behaves almost as a - mutex (but unlike a mutex it can be released by a thread different from the one - which acquired it). - @a initialcount is the initial value of the semaphore which must be between - 0 and @a maxcount (if it is not set to 0). - */ - wxSemaphore(int initialcount = 0, int maxcount = 0); - - /** - Destructor is not virtual, don't use this class polymorphically. - */ - ~wxSemaphore(); - - /** - Increments the semaphore count and signals one of the waiting - threads in an atomic way. Returns wxSEMA_OVERFLOW if the count - would increase the counter past the maximum. - - @return One of: - */ - wxSemaError Post(); - - /** - Same as Wait(), but returns immediately. - - @return One of: - */ - wxSemaError TryWait(); - - /** - Wait indefinitely until the semaphore count becomes strictly positive - and then decrement it and return. - - @return One of: - */ - wxSemaError Wait(); -}; - - - -/** - @class wxMutexLocker - @wxheader{thread.h} - - This is a small helper class to be used with wxMutex - objects. A wxMutexLocker acquires a mutex lock in the constructor and releases - (or unlocks) the mutex in the destructor making it much more difficult to - forget to release a mutex (which, in general, will promptly lead to serious - problems). See wxMutex for an example of wxMutexLocker - usage. - - @library{wxbase} - @category{threading} - - @see wxMutex, wxCriticalSectionLocker -*/ -class wxMutexLocker -{ -public: - /** - Constructs a wxMutexLocker object associated with mutex and locks it. - Call @ref IsOk() IsLocked to check if the mutex was - successfully locked. - */ - wxMutexLocker(wxMutex& mutex); - - /** - Destructor releases the mutex if it was successfully acquired in the ctor. - */ - ~wxMutexLocker(); - - /** - Returns @true if mutex was acquired in the constructor, @false otherwise. - */ - bool IsOk() const; -}; - - - -/** - @class wxMutex - @wxheader{thread.h} - - A mutex object is a synchronization object whose state is set to signaled when - it is not owned by any thread, and nonsignaled when it is owned. Its name comes - from its usefulness in coordinating mutually-exclusive access to a shared - resource as only one thread at a time can own a mutex object. - - Mutexes may be recursive in the sense that a thread can lock a mutex which it - had already locked before (instead of dead locking the entire process in this - situation by starting to wait on a mutex which will never be released while the - thread is waiting) but using them is not recommended under Unix and they are - @b not recursive there by default. The reason for this is that recursive - mutexes are not supported by all Unix flavours and, worse, they cannot be used - with wxCondition. On the other hand, Win32 mutexes are - always recursive. - - For example, when several threads use the data stored in the linked list, - modifications to the list should only be allowed to one thread at a time - because during a new node addition the list integrity is temporarily broken - (this is also called @e program invariant). - - @library{wxbase} - @category{threading} - - @see wxThread, wxCondition, wxMutexLocker, wxCriticalSection -*/ -class wxMutex -{ -public: - /** - Default constructor. - */ - wxMutex(wxMutexType type = wxMUTEX_DEFAULT); - - /** - Destroys the wxMutex object. - */ - ~wxMutex(); - - /** - Locks the mutex object. This is equivalent to - LockTimeout() with infinite timeout. - - @return One of: - */ - wxMutexError Lock(); - - /** - Try to lock the mutex object during the specified time interval. - - @return One of: - */ - wxMutexError LockTimeout(unsigned long msec); - - /** - Tries to lock the mutex object. If it can't, returns immediately with an error. - - @return One of: - */ - wxMutexError TryLock(); - - /** - Unlocks the mutex object. - - @return One of: - */ - wxMutexError Unlock(); -}; - - - -// ============================================================================ -// Global functions/macros -// ============================================================================ - -/** @ingroup group_funcmacro_thread */ -//@{ - -/** - This macro declares a (static) critical section object named @a cs if - @c wxUSE_THREADS is 1 and does nothing if it is 0. - - @header{wx/thread.h} -*/ -#define wxCRIT_SECT_DECLARE(cs) - -/** - This macro declares a critical section object named @a cs if - @c wxUSE_THREADS is 1 and does nothing if it is 0. As it doesn't include - the @c static keyword (unlike wxCRIT_SECT_DECLARE()), it can be used to - declare a class or struct member which explains its name. - - @header{wx/thread.h} -*/ -#define wxCRIT_SECT_DECLARE_MEMBER(cs) - -/** - This macro creates a wxCriticalSectionLocker named @a name and associated - with the critical section @a cs if @c wxUSE_THREADS is 1 and does nothing - if it is 0. - - @header{wx/thread.h} -*/ -#define wxCRIT_SECT_LOCKER(name, cs) - -/** - This macro combines wxCRIT_SECT_DECLARE() and wxCRIT_SECT_LOCKER(): it - creates a static critical section object and also the lock object - associated with it. Because of this, it can be only used inside a function, - not at global scope. For example: - - @code - int IncCount() - { - static int s_counter = 0; - - wxCRITICAL_SECTION(counter); - - return ++s_counter; - } - @endcode - - Note that this example assumes that the function is called the first time - from the main thread so that the critical section object is initialized - correctly by the time other threads start calling it, if this is not the - case this approach can @b not be used and the critical section must be made - a global instead. - - @header{wx/thread.h} -*/ -#define wxCRITICAL_SECTION(name) - -/** - This macro is equivalent to - @ref wxCriticalSection::Leave "critical_section.Leave()" if - @c wxUSE_THREADS is 1 and does nothing if it is 0. - - @header{wx/thread.h} -*/ -#define wxLEAVE_CRIT_SECT(critical_section) - -/** - This macro is equivalent to - @ref wxCriticalSection::Enter "critical_section.Enter()" if - @c wxUSE_THREADS is 1 and does nothing if it is 0. - - @header{wx/thread.h} -*/ -#define wxENTER_CRIT_SECT(critical_section) - -/** - Returns @true if this thread is the main one. Always returns @true if - @c wxUSE_THREADS is 0. - - @header{wx/thread.h} -*/ -bool wxIsMainThread(); - -/** - This function must be called when any thread other than the main GUI thread - wants to get access to the GUI library. This function will block the - execution of the calling thread until the main thread (or any other thread - holding the main GUI lock) leaves the GUI library and no other thread will - enter the GUI library until the calling thread calls wxMutexGuiLeave(). - - Typically, these functions are used like this: - - @code - void MyThread::Foo(void) - { - // before doing any GUI calls we must ensure that - // this thread is the only one doing it! - - wxMutexGuiEnter(); - - // Call GUI here: - my_window-DrawSomething(); - - wxMutexGuiLeave(); - } - @endcode - - This function is only defined on platforms which support preemptive - threads. - - @note Under GTK, no creation of top-level windows is allowed in any thread - but the main one. - - @header{wx/thread.h} -*/ -void wxMutexGuiEnter(); - -/** - This function is only defined on platforms which support preemptive - threads. - - @see wxMutexGuiEnter() - - @header{wx/thread.h} -*/ -void wxMutexGuiLeave(); - -//@} - diff --git a/interface/timer.h b/interface/timer.h deleted file mode 100644 index 49de74c8ef..0000000000 --- a/interface/timer.h +++ /dev/null @@ -1,184 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: timer.h -// Purpose: interface of wxTimer -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxTimer - @wxheader{timer.h} - - The wxTimer class allows you to execute code at specified intervals. Its - precision is platform-dependent, but in general will not be better than 1ms nor - worse than 1s. - - There are three different ways to use this class: - - You may derive a new class from wxTimer and override the - wxTimer::Notify member to perform the required action. - Or you may redirect the notifications to any - wxEvtHandler derived object by using the non-default - constructor or wxTimer::SetOwner. Then use the @c EVT_TIMER - macro to connect it to the event handler which will receive - wxTimerEvent notifications. - Or you may use a derived class and the @c EVT_TIMER - macro to connect it to an event handler defined in the derived class. - If the default constructor is used, the timer object will be its - own owner object, since it is derived from wxEvtHandler. - - In any case, you must start the timer with wxTimer::Start - after constructing it before it actually starts sending notifications. It can - be stopped later with wxTimer::Stop. - - @note A timer can only be used from the main thread. - - @library{wxbase} - @category{misc} - - @see wxStopWatch -*/ -class wxTimer : public wxEvtHandler -{ -public: - //@{ - /** - Creates a timer and associates it with @e owner. Please see - SetOwner() for the description of parameters. - */ - wxTimer(); - wxTimer(wxEvtHandler* owner, int id = -1); - //@} - - /** - Destructor. Stops the timer if it is running. - */ - ~wxTimer(); - - /** - Returns the ID of the events generated by this timer. - */ - int GetId() const; - - /** - Returns the current interval for the timer (in milliseconds). - */ - int GetInterval() const; - - /** - Returns the current @e owner of the timer. - If non-@NULL this is the event handler which will receive the - @ref overview_wxtimerevent "timer events" when the timer is running. - */ - wxEvtHandler GetOwner() const; - - /** - Returns @true if the timer is one shot, i.e. if it will stop after firing the - first notification automatically. - */ - bool IsOneShot() const; - - /** - Returns @true if the timer is running, @false if it is stopped. - */ - bool IsRunning() const; - - /** - This member should be overridden by the user if the default constructor was - used and SetOwner() wasn't called. - Perform whatever action which is to be taken periodically here. - */ - void Notify(); - - /** - Associates the timer with the given @a owner object. When the timer is - running, the owner will receive @ref overview_wxtimerevent "timer events" with - id equal to @a id specified here. - */ - void SetOwner(wxEvtHandler* owner, int id = -1); - - /** - (Re)starts the timer. If @a milliseconds parameter is -1 (value by default), - the previous value is used. Returns @false if the timer could not be started, - @true otherwise (in MS Windows timers are a limited resource). - If @a oneShot is @false (the default), the Notify() - function will be called repeatedly until the timer is stopped. If @true, - it will be called only once and the timer will stop automatically. To make your - code more readable you may also use the following symbolic constants: - - wxTIMER_CONTINUOUS - - Start a normal, continuously running, timer - - wxTIMER_ONE_SHOT - - Start a one shot timer - - If the timer was already running, it will be stopped by this method before - restarting it. - */ - bool Start(int milliseconds = -1, bool oneShot = false); - - /** - Stops the timer. - */ - void Stop(); -}; - - - -/** - @class wxTimerEvent - @wxheader{timer.h} - - wxTimerEvent object is passed to the event handler of timer events. - - For example: - - @code - class MyFrame : public wxFrame - { - public: - ... - void OnTimer(wxTimerEvent& event); - - private: - wxTimer m_timer; - }; - - BEGIN_EVENT_TABLE(MyFrame, wxFrame) - EVT_TIMER(TIMER_ID, MyFrame::OnTimer) - END_EVENT_TABLE() - - MyFrame::MyFrame() - : m_timer(this, TIMER_ID) - { - m_timer.Start(1000); // 1 second interval - } - - void MyFrame::OnTimer(wxTimerEvent& event) - { - // do whatever you want to do every second here - } - @endcode - - @library{wxbase} - @category{events} - - @see wxTimer -*/ -class wxTimerEvent : public wxEvent -{ -public: - /** - Returns the interval of the timer which generated this event. - */ - int GetInterval() const; - - /** - Returns the timer object which generated this event. - */ - wxTimer GetTimer() const; -}; - diff --git a/interface/tipdlg.h b/interface/tipdlg.h deleted file mode 100644 index 4b68bf8fb6..0000000000 --- a/interface/tipdlg.h +++ /dev/null @@ -1,114 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: tipdlg.h -// Purpose: interface of wxTipProvider -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxTipProvider - @wxheader{tipdlg.h} - - This is the class used together with wxShowTip() function. - It must implement wxTipProvider::GetTip function and return the - current tip from it (different tip each time it is called). - - You will never use this class yourself, but you need it to show startup tips - with wxShowTip. Also, if you want to get the tips text from elsewhere than a - simple text file, you will want to derive a new class from wxTipProvider and - use it instead of the one returned by wxCreateFileTipProvider(). - - @library{wxadv} - @category{FIXME} - - @see @ref overview_tipsoverview "Startup tips overview", ::wxShowTip -*/ -class wxTipProvider -{ -public: - /** - Constructor. - - @param currentTip - The starting tip index. - */ - wxTipProvider(size_t currentTip); - - /** - Returns the index of the current tip (i.e. the one which would be returned by - GetTip). - The program usually remembers the value returned by this function after calling - wxShowTip(). Note that it is not the same as the value which - was passed to wxShowTip + 1 because the user might have pressed the "Next" - button in the tip dialog. - */ - size_t GetCurrentTip() const; - - /** - Return the text of the current tip and pass to the next one. This function is - pure virtual, it should be implemented in the derived classes. - */ - wxString GetTip(); - - /** - Returns a modified tip. This function will be called immediately after read, - and before being check whether it is a comment, an empty string or a string - to translate. You can optionally override this in your custom user-derived - class - to optionally to modify the tip as soon as it is read. You can return any - modification to the string. If you return wxEmptyString, then this tip is - skipped, and the next one is read. - */ - virtual wxString PreProcessTip(const wxString& tip); -}; - - - -// ============================================================================ -// Global functions/macros -// ============================================================================ - -/** @ingroup group_funcmacro_dialog */ -//@{ - -/** - This function creates a wxTipProvider which may be used with wxShowTip(). - - @param filename - The name of the file containing the tips, one per line. - @param currentTip - The index of the first tip to show. Normally this index is remembered - between the 2 program runs. - - @see @ref overview_tips - - @header{wx/tipdlg.h} -*/ -wxTipProvider* wxCreateFileTipProvider(const wxString& filename, - size_t currentTip); - -/** - This function shows a "startup tip" to the user. The return value is the - state of the "Show tips at startup" checkbox. - - @param parent - The parent window for the modal dialog. - @param tipProvider - An object which is used to get the text of the tips. It may be created - with the wxCreateFileTipProvider() function. - @param showAtStartup - Should be true if startup tips are shown, false otherwise. This is - used as the initial value for "Show tips at startup" checkbox which is - shown in the tips dialog. - - @see @ref overview_tips - - @header{wx/tipdlg.h} -*/ -bool wxShowTip(wxWindow *parent, - wxTipProvider *tipProvider, - bool showAtStartup = true); - -//@} - diff --git a/interface/tipwin.h b/interface/tipwin.h deleted file mode 100644 index ef4a08e2a4..0000000000 --- a/interface/tipwin.h +++ /dev/null @@ -1,72 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: tipwin.h -// Purpose: interface of wxTipWindow -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxTipWindow - @wxheader{tipwin.h} - - Shows simple text in a popup tip window on creation. This is used by - wxSimpleHelpProvider to show popup help. The - window automatically destroys itself when the user clicks on it or it loses the - focus. - - You may also use this class to emulate the tooltips when you need finer - control over them than what the standard tooltips provide. - - @library{wxcore} - @category{managedwnd} -*/ -class wxTipWindow : public wxWindow -{ -public: - /** - Constructor. The tip is shown immediately after the window is constructed. - - @param parent - The parent window, must be non-@NULL - @param text - The text to show, may contain the new line characters - @param maxLength - The length of each line, in pixels. Set to a very large - value to avoid wrapping lines - @param windowPtr - Simply passed to - SetTipWindowPtr below, please see its - documentation for the description of this parameter - @param rectBounds - If non-@NULL, passed to - SetBoundingRect below, please see its - documentation for the description of this parameter - */ - wxTipWindow(wxWindow* parent, const wxString& text, - wxCoord maxLength = 100, - wxTipWindow** windowPtr = NULL, - wxRect* rectBounds = NULL); - - /** - By default, the tip window disappears when the user clicks the mouse or presses - a keyboard key or if it loses focus in any other way - for example because the - user switched to another application window. - Additionally, if a non-empty @a rectBound is provided, the tip window will - also automatically close if the mouse leaves this area. This is useful to - dismiss the tip mouse when the mouse leaves the object it is associated with. - - @param rectBound - The bounding rectangle for the mouse in the screen coordinates - */ - void SetBoundingRect(const wxRect& rectBound); - - /** - When the tip window closes itself (which may happen at any moment and - unexpectedly to the caller) it may @NULL out the pointer pointed to by - @e it windowPtr. This is helpful to avoid dereferencing the tip window which - had been already closed and deleted. - */ - void SetTipWindowPtr(wxTipWindow** windowPtr); -}; - diff --git a/interface/tokenzr.h b/interface/tokenzr.h deleted file mode 100644 index f576de6b5e..0000000000 --- a/interface/tokenzr.h +++ /dev/null @@ -1,161 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: tokenzr.h -// Purpose: interface of wxStringTokenizer -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - The behaviour of wxStringTokenizer is governed by the - wxStringTokenizer::wxStringTokenizer() or wxStringTokenizer::SetString() - with the parameter @e mode, which may be one of the following: -*/ -enum wxStringTokenizerMode -{ - wxTOKEN_INVALID = -1, ///< Invalid tokenizer mode. - - /** - Default behaviour: wxStringTokenizer will behave in the same way as - @c strtok() (::wxTOKEN_STRTOK) if the delimiters string only contains - white space characters but, unlike the standard function, it will - behave like ::wxTOKEN_RET_EMPTY, returning empty tokens if this is not - the case. This is helpful for parsing strictly formatted data where - the number of fields is fixed but some of them may be empty (i.e. - @c TAB or comma delimited text files). - */ - wxTOKEN_DEFAULT, - - /** - In this mode, the empty tokens in the middle of the string will be returned, - i.e. @c "a::b:" will be tokenized in three tokens @c 'a', " and @c 'b'. Notice - that all trailing delimiters are ignored in this mode, not just the last one, - i.e. a string @c "a::b::" would still result in the same set of tokens. - */ - wxTOKEN_RET_EMPTY, - - /** - In this mode, empty trailing tokens (including the one after the last delimiter - character) will be returned as well. The string @c "a::b:" will be tokenized in - four tokens: the already mentioned ones and another empty one as the last one - and a string @c "a::b::" will have five tokens. - */ - wxTOKEN_RET_EMPTY_ALL, - - /** - In this mode, the delimiter character after the end of the current token (there - may be none if this is the last token) is returned appended to the token. - Otherwise, it is the same mode as ::wxTOKEN_RET_EMPTY. Notice that there is no - mode like this one but behaving like ::wxTOKEN_RET_EMPTY_ALL instead of - ::wxTOKEN_RET_EMPTY, use ::wxTOKEN_RET_EMPTY_ALL and - wxStringTokenizer::GetLastDelimiter() to emulate it. - */ - wxTOKEN_RET_DELIMS, - - /** - In this mode the class behaves exactly like the standard @c strtok() function: - the empty tokens are never returned. - */ - wxTOKEN_STRTOK -}; - -/** - @class wxStringTokenizer - @wxheader{tokenzr.h} - - wxStringTokenizer helps you to break a string up into a number of tokens. - It replaces the standard C function @c strtok() and also extends it in a - number of ways. - - To use this class, you should create a wxStringTokenizer object, give it the - string to tokenize and also the delimiters which separate tokens in the string - (by default, white space characters will be used). - - Then wxStringTokenizer::GetNextToken() may be called repeatedly until - wxStringTokenizer::HasMoreTokens() returns @false. - - For example: - - @code - wxStringTokenizer tokenizer("first:second:third:fourth", ":"); - while ( tokenizer.HasMoreTokens() ) - { - wxString token = tokenizer.GetNextToken(); - - // process token here - } - @endcode - - @library{wxbase} - @category{data} - - @see wxStringTokenize() -*/ -class wxStringTokenizer : public wxObject -{ -public: - /** - Default constructor. You must call SetString() before calling any other - methods. - */ - wxStringTokenizer(); - /** - Constructor. Pass the string to tokenize, a string containing - delimiters, and the @a mode specifying how the string should be - tokenized. - - @see SetString() - */ - wxStringTokenizer(const wxString& str, - const wxString& delims = " \t\r\n", - wxStringTokenizerMode mode = wxTOKEN_DEFAULT); - - /** - Returns the number of tokens remaining in the input string. The number - of tokens returned by this function is decremented each time - GetNextToken() is called and when it reaches 0, HasMoreTokens() - returns @false. - */ - int CountTokens() const; - - /** - Returns the delimiter which ended scan for the last token returned by - GetNextToken() or @c NUL if there had been no calls to this function - yet or if it returned the trailing empty token in - ::wxTOKEN_RET_EMPTY_ALL mode. - - @since 2.7.0 - */ - wxChar GetLastDelimiter(); - - /** - Returns the next token or empty string if the end of string was reached. - */ - wxString GetNextToken() const; - - /** - Returns the current position (i.e. one index after the last returned - token or 0 if GetNextToken() has never been called) in the original - string. - */ - size_t GetPosition() const; - - /** - Returns the part of the starting string without all token already extracted. - */ - wxString GetString() const; - - /** - Returns @true if the tokenizer has further tokens, @false if none are left. - */ - bool HasMoreTokens() const; - - /** - Initializes the tokenizer. Pass the string to tokenize, a string - containing delimiters, and the @a mode specifying how the string - should be tokenized. - */ - void SetString(const wxString& to_tokenize, - const wxString& delims = " \t\r\n", - wxStringTokenizerMode mode = wxTOKEN_DEFAULT); -}; diff --git a/interface/toolbar.h b/interface/toolbar.h deleted file mode 100644 index c7deafc8bc..0000000000 --- a/interface/toolbar.h +++ /dev/null @@ -1,767 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: toolbar.h -// Purpose: interface of wxToolBar -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxToolBar - @wxheader{toolbar.h} - - The name wxToolBar is defined to be a synonym for one of the following - classes: - - - @b wxToolBar95 - The native Windows 95 toolbar. Used on Windows 95, NT 4 - and above. - - @b wxToolBarMSW - A Windows implementation. Used on 16-bit Windows. - - @b wxToolBarGTK - The GTK toolbar. - - You may also create a toolbar that is managed by the frame, by calling - wxFrame::CreateToolBar(). 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. - - The meaning of a "separator" is a vertical line under Windows and simple - space under GTK+. - - @b wxToolBar95: Note that this toolbar paints tools to reflect - system-wide colours. If you use more than 16 colours in your tool - bitmaps, you may wish to suppress this behaviour, otherwise system - colours in your bitmaps will inadvertently be mapped to system colours. - To do this, set the msw.remap system option before creating the toolbar: - - @code - wxSystemOptions::SetOption(wxT("msw.remap"), 0); - @endcode - - If you wish to use 32-bit images (which include an alpha channel for - transparency) use: - - @code - wxSystemOptions::SetOption(wxT("msw.remap"), 2); - @endcode - - Then colour remapping is switched off, and a transparent background - used. But only use this option under Windows XP with true colour: - - @code - if (wxTheApp->GetComCtl32Version() >= 600 && ::wxDisplayDepth() >= 32) - @endcode - - There are several different types of tools you can add to a toolbar. These - types are controlled by the ::wxItemKind enumeration. - - @beginStyleTable - @style{wxTB_FLAT} - Gives the toolbar a flat look (Windows and GTK only). - @style{wxTB_DOCKABLE} - Makes the toolbar floatable and dockable (GTK only). - @style{wxTB_HORIZONTAL} - Specifies horizontal layout (default). - @style{wxTB_VERTICAL} - Specifies vertical layout. - @style{wxTB_TEXT} - Shows the text in the toolbar buttons; by default only icons are shown. - @style{wxTB_NOICONS} - Specifies no icons in the toolbar buttons; by default they are shown. - @style{wxTB_NODIVIDER} - Specifies no divider (border) above the toolbar (Windows only) - @style{wxTB_NOALIGN} - Specifies no alignment with the parent window (Windows only, not very - useful). - @style{wxTB_HORZ_LAYOUT} - Shows the text and the icons alongside, not vertically stacked (Windows - and GTK 2 only). This style must be used with @c wxTB_TEXT. - @style{wxTB_HORZ_TEXT} - Combination of @c wxTB_HORZ_LAYOUT and @c wxTB_TEXT. - @style{wxTB_NO_TOOLTIPS} - Don't show the short help tooltips for the tools when the mouse hovers - over them. - @style{wxTB_BOTTOM} - Align the toolbar at the bottom of parent window. - @style{wxTB_RIGHT} - Align the toolbar at the right side of parent window. - @endStyleTable - - See also @ref overview_windowstyles. Note that the Win32 native toolbar - ignores @c wxTB_NOICONS style. Also, toggling the @c wxTB_TEXT works only - if the style was initially on. - - @beginEventTable{wxCommandEvent} - @event{EVT_TOOL(id, func)} - Process a @c wxEVT_COMMAND_TOOL_CLICKED event (a synonym for @c - wxEVT_COMMAND_MENU_SELECTED). Pass the id of the tool. - @event{EVT_MENU(id, func)} - The same as EVT_TOOL(). - @event{EVT_TOOL_RANGE(id1, id2, func)} - Process a @c wxEVT_COMMAND_TOOL_CLICKED event for a range of - identifiers. Pass the ids of the tools. - @event{EVT_MENU_RANGE(id1, id2, func)} - The same as EVT_TOOL_RANGE(). - @event{EVT_TOOL_RCLICKED(id, func)} - Process a @c wxEVT_COMMAND_TOOL_RCLICKED event. Pass the id of the - tool. - @event{EVT_TOOL_RCLICKED_RANGE(id1, id2, func)} - Process a @c wxEVT_COMMAND_TOOL_RCLICKED event for a range of ids. Pass - the ids of the tools. - @event{EVT_TOOL_ENTER(id, func)} - Process a @c wxEVT_COMMAND_TOOL_ENTER event. Pass the id of the toolbar - itself. The value of wxCommandEvent::GetSelection() is the tool id, or - -1 if the mouse cursor has moved off a tool. - @event{EVT_TOOL_DROPDOWN(id, func)} - Process a @c wxEVT_COMMAND_TOOL_DROPDOWN_CLICKED event. If unhandled, - displays the default dropdown menu set using - wxToolBar::SetDropdownMenu(). - @endEventTable - - The toolbar class emits menu commands in the same way that a frame menubar - does, so you can use one EVT_MENU() macro for both a menu item and a toolbar - button. The event handler functions take a wxCommandEvent argument. For most - event macros, the identifier of the tool is passed, but for EVT_TOOL_ENTER() - the toolbar window identifier is passed and the tool identifier is retrieved - from the wxCommandEvent. This is because the identifier may be -1 when the - mouse moves off a tool, and -1 is not allowed as an identifier in the event - system. - - @library{wxcore} - @category{miscwnd} - - @see @ref overview_toolbar -*/ -class wxToolBar : public wxControl -{ -public: - /** - Default constructor. - */ - wxToolBar(); - - /** - Constructs a toolbar. - - @param parent - Pointer to a parent window. - @param id - Window identifier. If -1, will automatically create an identifier. - @param pos - Window position. ::wxDefaultPosition is (-1, -1) which indicates that - wxWidgets should generate a default position for the window. If - using the wxWindow class directly, supply an actual position. - @param size - Window size. ::wxDefaultSize is (-1, -1) which indicates that - wxWidgets should generate a default size for the window. - @param style - Window style. See wxToolBar for details. - @param name - Window name. - - @remarks After a toolbar is created, you use AddTool() and perhaps - AddSeparator(), and then you must call Realize() to construct and - display the toolbar tools. - */ - wxToolBar(wxWindow* parent, wxWindowID id, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = wxTB_HORIZONTAL | wxBORDER_NONE, - const wxString& name = wxPanelNameStr); - - /** - Toolbar destructor. - */ - ~wxToolBar(); - - /** - Adds a new check (or toggle) tool to the toolbar. The parameters are the - same as in AddTool(). - - @see AddTool() - */ - wxToolBarToolBase* AddCheckTool(int toolId, - const wxString& label, - const wxBitmap& bitmap1, - const wxBitmap& bitmap2, - const wxString& shortHelpString = "", - const wxString& longHelpString = "", - wxObject* clientData = NULL); - - /** - Adds any control to the toolbar, typically e.g. a wxComboBox. - - @param control - The control to be added. - @param label - Text to be displayed near the control. - - @remarks - wxMSW: the label is only displayed if there is enough space - available below the embedded control. - - @remarks - wxMac: labels are only displayed if wxWidgets is built with @c - wxMAC_USE_NATIVE_TOOLBAR set to 1 - */ - bool AddControl(wxControl* control, const wxString label = ""); - - /** - Adds a new radio tool to the toolbar. Consecutive radio tools form a - radio group such that exactly one button in the group is pressed at any - moment, in other words whenever a button in the group is pressed the - previously pressed button is automatically released. You should avoid - having the radio groups of only one element as it would be impossible - for the user to use such button. - - By default, the first button in the radio group is initially pressed, - the others are not. - - - @see AddTool() - */ - wxToolBarToolBase* AddRadioTool(int toolId, - const wxString& label, - const wxBitmap& bitmap1, - const wxBitmap& bitmap2, - const wxString& shortHelpString = "", - const wxString& longHelpString = "", - wxObject* clientData = NULL); - - /** - Adds a separator for spacing groups of tools. - - @see AddTool(), SetToolSeparation() - */ - void AddSeparator(); - - /** - Adds a tool to the toolbar. - - @param tool - The tool to be added. - - @remarks After you have added tools to a toolbar, you must call - Realize() in order to have the tools appear. - - @see AddSeparator(), AddCheckTool(), AddRadioTool(), - InsertTool(), DeleteTool(), Realize(), SetDropdownMenu() - */ - wxToolBarToolBase* AddTool(wxToolBarToolBase* tool); - - /** - Adds a tool to the toolbar. This most commonly used version has fewer - parameters than the full version below which specifies the more rarely - used button features. - - @param toolId - An integer by which the tool may be identified in subsequent - operations. - @param label - The string to be displayed with the tool. - @param bitmap - The primary tool bitmap. - @param shortHelp - This string is used for the tools tooltip. - @param kind - May be ::wxITEM_NORMAL for a normal button (default), ::wxITEM_CHECK - for a checkable tool (such tool stays pressed after it had been - toggled) or ::wxITEM_RADIO for a checkable tool which makes part of - a radio group of tools each of which is automatically unchecked - whenever another button in the group is checked. ::wxITEM_DROPDOWN - specifies that a drop-down menu button will appear next to the - tool button (only GTK+ and MSW). Call SetDropdownMenu() afterwards. - - @remarks After you have added tools to a toolbar, you must call - Realize() in order to have the tools appear. - - @see AddSeparator(), AddCheckTool(), AddRadioTool(), - InsertTool(), DeleteTool(), Realize(), SetDropdownMenu() - */ - wxToolBarToolBase* AddTool(int toolId, const wxString& label, - const wxBitmap& bitmap, - const wxString& shortHelp = wxEmptyString, - wxItemKind kind = wxITEM_NORMAL); - - /** - Adds a tool to the toolbar. - - @param toolId - An integer by which the tool may be identified in subsequent - operations. - @param label - The string to be displayed with the tool. - @param bitmap - The primary tool bitmap. - @param bmpDisabled - The bitmap used when the tool is disabled. If it is equal to - ::wxNullBitmap (default), the disabled bitmap is automatically - generated by greying the normal one. - @param shortHelpString - This string is used for the tools tooltip. - @param longHelpString - This string is shown in the statusbar (if any) of the parent frame - when the mouse pointer is inside the tool. - @param kind - May be ::wxITEM_NORMAL for a normal button (default), ::wxITEM_CHECK - for a checkable tool (such tool stays pressed after it had been - toggled) or ::wxITEM_RADIO for a checkable tool which makes part of - a radio group of tools each of which is automatically unchecked - whenever another button in the group is checked. ::wxITEM_DROPDOWN - specifies that a drop-down menu button will appear next to the - tool button (only GTK+ and MSW). Call SetDropdownMenu() afterwards. - @param clientData - An optional pointer to client data which can be retrieved later - using GetToolClientData(). - - @remarks After you have added tools to a toolbar, you must call - Realize() in order to have the tools appear. - - @see AddSeparator(), AddCheckTool(), AddRadioTool(), - InsertTool(), DeleteTool(), Realize(), SetDropdownMenu() - */ - wxToolBarToolBase* AddTool(int toolId, const wxString& label, - const wxBitmap& bitmap, - const wxBitmap& bmpDisabled = wxNullBitmap, - wxItemKind kind = wxITEM_NORMAL, - const wxString& shortHelpString = wxEmptyString, - const wxString& longHelpString = wxEmptyString, - wxObject* clientData = NULL); - - /** - Deletes all the tools in the toolbar. - */ - void ClearTools(); - - /** - Removes the specified tool from the toolbar and deletes it. If you don't - want to delete the tool, but just to remove it from the toolbar (to - possibly add it back later), you may use RemoveTool() instead. - - @note It is unnecessary to call Realize() for the change to take - place, it will happen immediately. - - @returns @true if the tool was deleted, @false otherwise. - - @see DeleteToolByPos() - */ - bool DeleteTool(int toolId); - - /** - This function behaves like DeleteTool() but it deletes the tool at the - specified position and not the one with the given id. - */ - bool DeleteToolByPos(size_t pos); - - /** - Enables or disables the tool. - - @param toolId - Tool to enable or disable. - @param enable - If @true, enables the tool, otherwise disables it. - - @remarks Some implementations will change the visible state of the tool - to indicate that it is disabled. - - - @see GetToolEnabled(), ToggleTool() - */ - void EnableTool(int toolId, bool enable); - - /** - Returns a pointer to the tool identified by @a id or @NULL if no - corresponding tool is found. - */ - wxToolBarToolBase* FindById(int id); - - /** - Returns a pointer to the control identified by @a id or @NULL if no - corresponding control is found. - */ - wxControl* FindControl(int id); - - /** - Finds a tool for the given mouse position. - - @param x - X position. - @param y - Y position. - - @return A pointer to a tool if a tool is found, or @NULL otherwise. - - @remarks Currently not implemented in wxGTK (always returns @NULL - there). - */ - wxToolBarToolBase* FindToolForPosition(wxCoord x, wxCoord y) const; - - /** - Returns the left/right and top/bottom margins, which are also used for - inter-toolspacing. - - @see SetMargins() - */ - wxSize GetMargins() const; - - /** - Returns the size of bitmap that the toolbar expects to have. The default - bitmap size is 16 by 15 pixels. - - @remarks Note that this is the size of the bitmap you pass to AddTool(), - and not the eventual size of the tool button. - - @see SetToolBitmapSize(), GetToolSize() - */ - wxSize GetToolBitmapSize(); - - /** - Get any client data associated with the tool. - - @param toolId - Id of the tool, as passed to AddTool(). - - @return Client data, or @NULL if there is none. - */ - wxObject* GetToolClientData(int toolId) const; - - /** - Called to determine whether a tool is enabled (responds to user input). - - @param toolId - Id of the tool in question. - - @return @true if the tool is enabled, @false otherwise. - - @see EnableTool() - */ - bool GetToolEnabled(int toolId) const; - - /** - Returns the long help for the given tool. - - @param toolId - The tool in question. - - @see SetToolLongHelp(), SetToolShortHelp() - */ - wxString GetToolLongHelp(int toolId) const; - - /** - Returns the value used for packing tools. - - @see SetToolPacking() - */ - int GetToolPacking() const; - - /** - Returns the tool position in the toolbar, or @c wxNOT_FOUND if the tool - is not found. - */ - int GetToolPos(int toolId) const; - - /** - Returns the default separator size. - - @see SetToolSeparation() - */ - int GetToolSeparation() const; - - /** - Returns the short help for the given tool. - - @param toolId - The tool in question. - - @see GetToolLongHelp(), SetToolShortHelp() - */ - wxString GetToolShortHelp(int toolId) const; - - /** - Returns the size of a whole button, which is usually larger than a tool - bitmap because of added 3D effects. - - @see SetToolBitmapSize(), GetToolBitmapSize() - */ - wxSize GetToolSize(); - - /** - Gets the on/off state of a toggle tool. - - @param toolId - The tool in question. - - @return @true if the tool is toggled on, @false otherwise. - - @see ToggleTool() - */ - bool GetToolState(int toolId) const; - - /** - Returns the number of tools in the toolbar. - */ - int GetToolsCount() const; - - /** - Inserts the control into the toolbar at the given position. You must - call Realize() for the change to take place. - - @see AddControl(), InsertTool() - */ - wxToolBarToolBase* InsertControl(size_t pos, wxControl* control); - - /** - Inserts the separator into the toolbar at the given position. You must - call Realize() for the change to take place. - - @see AddSeparator(), InsertTool() - */ - wxToolBarToolBase* InsertSeparator(size_t pos); - - //@{ - /** - Inserts the tool with the specified attributes into the toolbar at the - given position. - - You must call Realize() for the change to take place. - - @see AddTool(), InsertControl(), InsertSeparator() - */ - wxToolBarToolBase* InsertTool(size_t pos, int toolId, - const wxBitmap& bitmap1, - const wxBitmap& bitmap2 = wxNullBitmap, - bool isToggle = false, - wxObject* clientData = NULL, - const wxString& shortHelpString = "", - const wxString& longHelpString = ""); - wxToolBarToolBase* InsertTool(size_t pos, - wxToolBarToolBase* tool); - //@} - - /** - Called when the user clicks on a tool with the left mouse button. This - is the old way of detecting tool clicks; although it will still work, - you should use the EVT_MENU() or EVT_TOOL() macro instead. - - @param toolId - The identifier passed to AddTool(). - @param toggleDown - @true if the tool is a toggle and the toggle is down, otherwise is - @false. - - @return If the tool is a toggle and this function returns @false, the - toggle state (internal and visual) will not be changed. This - provides a way of specifying that toggle operations are not - permitted in some circumstances. - - @see OnMouseEnter(), OnRightClick() - */ - bool OnLeftClick(int toolId, bool toggleDown); - - /** - This is called when the mouse cursor moves into a tool or out of the - toolbar. This is the old way of detecting mouse enter events; - although it will still work, you should use the EVT_TOOL_ENTER() - macro instead. - - @param toolId - Greater than -1 if the mouse cursor has moved into the tool, or -1 - if the mouse cursor has moved. The programmer can override this to - provide extra information about the tool, such as a short - description on the status line. - - @remarks With some derived toolbar classes, if the mouse moves quickly - out of the toolbar, wxWidgets may not be able to detect it. - Therefore this function may not always be called when expected. - */ - void OnMouseEnter(int toolId); - - /** - @deprecated This is the old way of detecting tool right clicks; - although it will still work, you should use the - EVT_TOOL_RCLICKED() macro instead. - - Called when the user clicks on a tool with the right mouse button. The - programmer should override this function to detect right tool clicks. - - @param toolId - The identifier passed to AddTool(). - @param x - The x position of the mouse cursor. - @param y - The y position of the mouse cursor. - - @remarks A typical use of this member might be to pop up a menu. - - @see OnMouseEnter(), OnLeftClick() - */ - void OnRightClick(int toolId, float x, float y); - - /** - This function should be called after you have added tools. - */ - bool Realize(); - - /** - Removes the given tool from the toolbar but doesn't delete it. This - allows to insert/add this tool back to this (or another) toolbar later. - - @note It is unnecessary to call Realize() for the change to take place, - it will happen immediately. - - - @see DeleteTool() - */ - wxToolBarToolBase* RemoveTool(int id); - - /** - Sets the bitmap resource identifier for specifying tool bitmaps as - indices into a custom bitmap. Windows CE only. - */ - void SetBitmapResource(int resourceId); - - /** - Sets the dropdown menu for the tool given by its @e id. The tool itself - will delete the menu when it's no longer needed. Only supported under - GTK+ und MSW. - - If you define a EVT_TOOL_DROPDOWN() handler in your program, you must - call wxEvent::Skip() from it or the menu won't be displayed. - */ - bool SetDropdownMenu(int id, wxMenu* menu); - - /** - Set the values to be used as margins for the toolbar. - - @param x - Left margin, right margin and inter-tool separation value. - @param y - Top margin, bottom margin and inter-tool separation value. - - @remarks This must be called before the tools are added if absolute - positioning is to be used, and the default (zero-size) margins are - to be overridden. - - @see GetMargins() - */ - void SetMargins(int x, int y); - - /** - Set the margins for the toolbar. - - @param size - Margin size. - - @remarks This must be called before the tools are added if absolute - positioning is to be used, and the default (zero-size) margins are - to be overridden. - - @see GetMargins(), wxSize - */ - void SetMargins(const wxSize& size); - - /** - Sets the default size of each tool bitmap. The default bitmap size is 16 - by 15 pixels. - - @param size - The size of the bitmaps in the toolbar. - - @remarks This should be called to tell the toolbar what the tool bitmap - size is. Call it before you add tools. - - @see GetToolBitmapSize(), GetToolSize() - */ - void SetToolBitmapSize(const wxSize& size); - - /** - Sets the client data associated with the tool. - */ - void SetToolClientData(int id, wxObject* clientData); - - /** - Sets the bitmap to be used by the tool with the given ID when the tool - is in a disabled state. This can only be used on Button tools, not - controls. - - @note The native toolbar classes on the main platforms all synthesize - the disabled bitmap from the normal bitmap, so this function will - have no effect on those platforms. - - */ - void SetToolDisabledBitmap(int id, const wxBitmap& bitmap); - - /** - Sets the long help for the given tool. - - @param toolId - The tool in question. - @param helpString - A string for the long help. - - @remarks You might use the long help for displaying the tool purpose on - the status line. - - @see GetToolLongHelp(), SetToolShortHelp(), - */ - void SetToolLongHelp(int toolId, const wxString& helpString); - - /** - Sets the bitmap to be used by the tool with the given ID. This can only - be used on Button tools, not controls. - */ - void SetToolNormalBitmap(int id, const wxBitmap& bitmap); - - /** - Sets the value used for spacing tools. The default value is 1. - - @param packing - The value for packing. - - @remarks The packing is used for spacing in the vertical direction if - the toolbar is horizontal, and for spacing in the horizontal - direction if the toolbar is vertical. - - @see GetToolPacking() - */ - void SetToolPacking(int packing); - - /** - Sets the default separator size. The default value is 5. - - @param separation - The separator size. - - @see AddSeparator() - */ - void SetToolSeparation(int separation); - - /** - Sets the short help for the given tool. - - @param toolId - The tool in question. - @param helpString - The string for the short help. - - @remarks An application might use short help for identifying the tool - purpose in a tooltip. - - - @see GetToolShortHelp(), SetToolLongHelp() - */ - void SetToolShortHelp(int toolId, const wxString& helpString); - - /** - Toggles a tool on or off. This does not cause any event to get emitted. - - @param toolId - Tool in question. - @param toggle - If @true, toggles the tool on, otherwise toggles it off. - - @remarks Only applies to a tool that has been specified as a toggle - tool. - */ - void ToggleTool(int toolId, bool toggle); -}; - diff --git a/interface/toolbook.h b/interface/toolbook.h deleted file mode 100644 index 358adbd212..0000000000 --- a/interface/toolbook.h +++ /dev/null @@ -1,45 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: toolbook.h -// Purpose: interface of wxToolbook -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxToolbook - @wxheader{toolbook.h} - - wxToolbook is a class similar to wxNotebook but which uses a wxToolBar to - show the labels instead of the tabs. - - There is no documentation for this class yet but its usage is identical to - wxNotebook (except for the features clearly related to tabs only), so please - refer to that class documentation for now. You can also use the - @ref page_samples_notebook to see wxToolbook in action. - - @beginStyleTable - @style{wxTBK_BUTTONBAR} - Use wxButtonToolBar-based implementation under Mac OS (ignored under - other platforms). - @style{wxTBK_HORZ_LAYOUT} - Shows the text and the icons alongside, not vertically stacked (only - implement under Windows and GTK 2 platforms as it relies on @c - wxTB_HORZ_LAYOUT flag support). - @endStyleTable - - The common wxBookCtrl styles described in the @ref overview_bookctrl are - also supported. - - @library{wxcore} - @category{miscwnd} - - @see @ref overview_bookctrl, wxBookCtrlBase, wxNotebook, - @ref page_samples_notebook -*/ -class wxToolbook : public wxBookCtrlBase -{ -public: - -}; - diff --git a/interface/tooltip.h b/interface/tooltip.h deleted file mode 100644 index 6d6779198a..0000000000 --- a/interface/tooltip.h +++ /dev/null @@ -1,75 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: tooltip.h -// Purpose: interface of wxToolTip -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxToolTip - @wxheader{tooltip.h} - - This class holds information about a tooltip associated with a window (see - wxWindow::SetToolTip()). - - The four static methods, wxToolTip::Enable(), wxToolTip::SetDelay() - wxToolTip::SetAutoPop() and wxToolTip::SetReshow() can be used to globally - alter tooltips behaviour. - - @library{wxcore} - @category{help} -*/ -class wxToolTip : public wxObject -{ -public: - /** - Constructor. - */ - wxToolTip(const wxString& tip); - - /** - Enable or disable tooltips globally. - - @note May not be supported on all platforms (eg. wxCocoa). - */ - static void Enable(bool flag); - - /** - Get the tooltip text. - */ - wxString GetTip() const; - - /** - Get the associated window. - */ - wxWindow* GetWindow() const; - - /** - Set the delay after which the tooltip disappears or how long a tooltip - remains visible. - - @note May not be supported on all platforms (eg. wxCocoa, GTK, Palmos). - */ - static void SetAutoPop(long msecs); - - /** - Set the delay after which the tooltip appears. - - @note May not be supported on all platforms (eg. wxCocoa). - */ - static void SetDelay(long msecs); - - /** - Set the delay between subsequent tooltips to appear. - - @note May not be supported on all platforms (eg. wxCocoa, GTK, Palmos). - */ - static void SetReshow(long msecs); - - /** - Set the tooltip text. - */ - void SetTip(const wxString& tip); -}; - diff --git a/interface/toplevel.h b/interface/toplevel.h deleted file mode 100644 index f0432e2e68..0000000000 --- a/interface/toplevel.h +++ /dev/null @@ -1,426 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: toplevel.h -// Purpose: interface of wxTopLevelWindow -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - Styles used with wxTopLevelWindow::RequestUserAttention(). -*/ -enum -{ - wxUSER_ATTENTION_INFO = 1, ///< Requests user attention, - wxUSER_ATTENTION_ERROR = 2 ///< Results in a more drastic action. -}; - -/** - Styles used with wxTopLevelWindow::ShowFullScreen(). -*/ -enum -{ - wxFULLSCREEN_NOMENUBAR = 0x0001, ///< Don't display the menu bar. - wxFULLSCREEN_NOTOOLBAR = 0x0002, ///< Don't display toolbar bars. - wxFULLSCREEN_NOSTATUSBAR = 0x0004, ///< Don't display the status bar. - wxFULLSCREEN_NOBORDER = 0x0008, ///< Don't display any border. - wxFULLSCREEN_NOCAPTION = 0x0010, ///< Don't display a caption. - - /** - Combination of all above, will display the least possible. - */ - wxFULLSCREEN_ALL = wxFULLSCREEN_NOMENUBAR | wxFULLSCREEN_NOTOOLBAR | - wxFULLSCREEN_NOSTATUSBAR | wxFULLSCREEN_NOBORDER | - wxFULLSCREEN_NOCAPTION -}; - -/** - @class wxTopLevelWindow - @wxheader{toplevel.h} - - wxTopLevelWindow is a common base class for wxDialog and wxFrame. It is an - abstract base class meaning that you never work with objects of this class - directly, but all of its methods are also applicable for the two classes - above. - - @library{wxcore} - @category{managedwnd} - - @see wxDialog, wxFrame -*/ -class wxTopLevelWindow : public wxWindow -{ -public: - /** - Returns @true if the platform supports making the window translucent. - - @see SetTransparent() - */ - virtual bool CanSetTransparent(); - - /** - A synonym for CentreOnScreen(). - */ - void CenterOnScreen(int direction); - - /** - Centres the window on screen. - - @param direction - Specifies the direction for the centering. May be @c wxHORIZONTAL, - @c wxVERTICAL or @c wxBOTH. - - @see wxWindow::CentreOnParent() - */ - void CentreOnScreen(int direction = wxBOTH); - - /** - Enables or disables the Close button (most often in the right upper - corner of a dialog) and the Close entry of the system menu (most often - in the left upper corner of the dialog). - - Currently only implemented for wxMSW and wxGTK. - - Returns @true if operation was successful. This may be wrong on X11 - (including GTK+) where the window manager may not support this operation - and there is no way to find out. - */ - bool EnableCloseButton(bool enable = true); - - /** - Returns a pointer to the button which is the default for this window, or - @c @NULL. The default button is the one activated by pressing the Enter - key. - */ - wxWindow* GetDefaultItem() const; - - /** - Returns the standard icon of the window. The icon will be invalid if it - hadn't been previously set by SetIcon(). - - @see GetIcons() - */ - const wxIcon GetIcon() const; - - /** - Returns all icons associated with the window, there will be none of them - if neither SetIcon() nor SetIcons() had been called before. Use - GetIcon() to get the main icon of the window. - - @see wxIconBundle - */ - const wxIconBundle GetIcons() const; - - /** - Gets a string containing the window title. - - @see SetTitle() - */ - wxString GetTitle() const; - - /** - Unique to the wxWinCE port. Responds to showing/hiding SIP (soft input - panel) area and resize window accordingly. Override this if you want to - avoid resizing or do additional operations. - */ - virtual bool HandleSettingChange(WXWPARAM wParam, - WXLPARAM lParam); - - /** - Iconizes or restores the window. - - @param iconize - If @true, iconizes the window; if @false, shows and restores it. - - @see IsIconized(), Maximize(), wxIconizeEvent. - */ - void Iconize(bool iconize); - - /** - Returns @true if this window is currently active, i.e. if the user is - currently working with it. - */ - bool IsActive() const; - - /** - Returns @true if this window is expected to be always maximized, either - due to platform policy or due to local policy regarding particular - class. - */ - virtual bool IsAlwaysMaximized() const; - - /** - Returns @true if the window is in fullscreen mode. - - @see ShowFullScreen() - */ - bool IsFullScreen(); - - /** - Returns @true if the window is iconized. - */ - bool IsIconized() const; - - /** - Returns @true if the window is maximized. - */ - bool IsMaximized() const; - - /** - This method is specific to wxUniversal port. - - Returns @true if this window is using native decorations, @false if we - draw them ourselves. - - @see UseNativeDecorations(), - UseNativeDecorationsByDefault() - */ - bool IsUsingNativeDecorations() const; - - /** - Maximizes or restores the window. - - @param maximize - If @true, maximizes the window, otherwise it restores it. - - @see Iconize() - */ - void Maximize(bool maximize); - - /** - Use a system-dependent way to attract users attention to the window when - it is in background. - - @a flags may have the value of either @c ::wxUSER_ATTENTION_INFO - (default) or @c ::wxUSER_ATTENTION_ERROR which results in a more drastic - action. When in doubt, use the default value. - - - @note This function should normally be only used when the application - is not already in foreground. - - This function is currently implemented for Win32 where it flashes - the window icon in the taskbar, and for wxGTK with task bars - supporting it. - - */ - void RequestUserAttention(int flags = wxUSER_ATTENTION_INFO); - - /** - Changes the default item for the panel, usually @a win is a button. - - @see GetDefaultItem() - */ - void SetDefaultItem(wxWindow* win); - - /** - Sets the icon for this window. - - @param icon - The wxIcon to associate with this window. - - @remarks The window takes a 'copy' of @a icon, but since it uses - reference counting, the copy is very quick. It is safe to - delete @a icon after calling this function. - - @see wxIcon - */ - void SetIcon(const wxIcon& icon); - - /** - Sets several icons of different sizes for this window: this allows to - use different icons for different situations (e.g. task switching bar, - taskbar, window title bar) instead of scaling, with possibly bad looking - results, the only icon set by SetIcon(). - - @param icons - The icons to associate with this window. - - @see wxIconBundle. - */ - void SetIcons(const wxIconBundle& icons); - - /** - Sets action or menu activated by pressing left hardware button on the - smart phones. Unavailable on full keyboard machines. - - @param id - Identifier for this button. - @param label - Text to be displayed on the screen area dedicated to this hardware - button. - @param subMenu - The menu to be opened after pressing this hardware button. - - @see SetRightMenu(). - */ - void SetLeftMenu(int id = wxID_ANY, - const wxString& label = wxEmptyString, - wxMenu* subMenu = NULL); - - /** - A simpler interface for setting the size hints than SetSizeHints(). - */ - void SetMaxSize(const wxSize& size); - - /** - A simpler interface for setting the size hints than SetSizeHints(). - */ - void SetMinSize(const wxSize& size); - - /** - Sets action or menu activated by pressing right hardware button on the - smart phones. Unavailable on full keyboard machines. - - @param id - Identifier for this button. - @param label - Text to be displayed on the screen area dedicated to this hardware - button. - @param subMenu - The menu to be opened after pressing this hardware button. - - @see SetLeftMenu(). - */ - void SetRightMenu(int id = wxID_ANY, - const wxString& label = wxEmptyString, - wxMenu* subMenu = NULL); - - /** - If the platform supports it, sets the shape of the window to that - depicted by @a region. The system will not display or respond to any - mouse event for the pixels that lie outside of the region. To reset the - window to the normal rectangular shape simply call SetShape() again with - an empty wxRegion. Returns @true if the operation is successful. - */ - bool SetShape(const wxRegion& region); - - /** - Allows specification of minimum and maximum window sizes, and window - size increments. If a pair of values is not set (or set to -1), no - constraints will be used. - - @param incW - Specifies the increment for sizing the width (GTK/Motif/Xt only). - @param incH - Specifies the increment for sizing the height (GTK/Motif/Xt only). - - @remarks Notice that this function not only prevents the user from - resizing the window outside the given bounds but it also - prevents the program itself from doing it using - wxWindow::SetSize(). - - */ - virtual void SetSizeHints(int minW, int minH, int maxW = -1, - int maxH = -1, - int incW = -1, - int incH = -1); - - /** - Allows specification of minimum and maximum window sizes, and window - size increments. If a pair of values is not set (or set to -1), no - constraints will be used. - - @param incSize - Increment size (only taken into account under X11-based ports such - as wxGTK/wxMotif/wxX11). - - @remarks Notice that this function not only prevents the user from - resizing the window outside the given bounds but it also - prevents the program itself from doing it using - wxWindow::SetSize(). - */ - void SetSizeHints(const wxSize& minSize, - const wxSize& maxSize = wxDefaultSize, - const wxSize& incSize = wxDefaultSize); - - /** - Sets the window title. - - @param title - The window title. - - @see GetTitle() - */ - virtual void SetTitle(const wxString& title); - - /** - If the platform supports it will set the window to be translucent. - - @param alpha - Determines how opaque or transparent the window will be, if the - platform supports the opreration. A value of 0 sets the window to be - fully transparent, and a value of 255 sets the window to be fully - opaque. - */ - virtual bool SetTransparent(int alpha); - - /** - This virtual function is not meant to be called directly but can be - overridden to return @false (it returns @true by default) to allow the - application to close even if this, presumably not very important, window - is still opened. By default, the application stays alive as long as - there are any open top level windows. - */ - virtual bool ShouldPreventAppExit() const; - - /** - Depending on the value of @a show parameter the window is either shown - full screen or restored to its normal state. @a style is a bit list - containing some or all of the following values, which indicate what - elements of the window to hide in full-screen mode: - - - @c ::wxFULLSCREEN_NOMENUBAR - - @c ::wxFULLSCREEN_NOTOOLBAR - - @c ::wxFULLSCREEN_NOSTATUSBAR - - @c ::wxFULLSCREEN_NOBORDER - - @c ::wxFULLSCREEN_NOCAPTION - - @c ::wxFULLSCREEN_ALL (all of the above) - - This function has not been tested with MDI frames. - - @note Showing a window full screen also actually @ref wxWindow::Show() - "Show()"s the window if it isn't shown. - - @see IsFullScreen() - */ - bool ShowFullScreen(bool show, long style = wxFULLSCREEN_ALL); - - /** - This method is specific to wxUniversal port. - - Use native or custom-drawn decorations for this window only. Notice that - to have any effect this method must be called before really creating the - window, i.e. two step creation must be used: - - @code - MyFrame *frame = new MyFrame; // use default ctor - frame->UseNativeDecorations(false); // change from default "true" - frame->Create(parent, title, ...); // really create the frame - @endcode - - @see UseNativeDecorationsByDefault(), - IsUsingNativeDecorations() - */ - void UseNativeDecorations(bool native = true); - - /** - This method is specific to wxUniversal port. - - Top level windows in wxUniversal port can use either system-provided - window decorations (i.e. title bar and various icons, buttons and menus - in it) or draw the decorations themselves. By default the system - decorations are used if they are available, but this method can be - called with @a native set to @false to change this for all windows - created after this point. - - Also note that if @c WXDECOR environment variable is set, then custom - decorations are used by default and so it may make sense to call this - method with default argument if the application can't use custom - decorations at all for some reason. - - @see UseNativeDecorations() - */ - void UseNativeDecorationsByDefault(bool native = true); -}; - diff --git a/interface/tracker.h b/interface/tracker.h deleted file mode 100644 index 67d4bc0a65..0000000000 --- a/interface/tracker.h +++ /dev/null @@ -1,36 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: tracker.h -// Purpose: interface of wxTrackable -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxTrackable - @wxheader{tracker.h} - - Add-on base class for a trackable object. This class maintains an internal - linked list of classes of type wxTrackerNode and calls OnObjectDestroy() on - them if this object is destroyed. The most common usage is by using the - wxWeakRef class template which automates this. This class has no public - API. Its only use is by deriving another class from it to make it trackable. - - @code - class MyClass: public Foo, public wxTrackable - { - // whatever - } - - typedef wxWeakRef MyClassRef; - @endcode - - @library{wxbase} - @category{smartpointers} -*/ -class wxTrackable -{ -public: - -}; - diff --git a/interface/treebase.h b/interface/treebase.h deleted file mode 100644 index 84ffd78598..0000000000 --- a/interface/treebase.h +++ /dev/null @@ -1,129 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: treebase.h -// Purpose: interface of wxTreeItemId -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxTreeItemId - @wxheader{treebase.h} - - An opaque reference to a tree item. - - @library{wxcore} - @category{misc} - - @see wxTreeCtrl, wxTreeItemData, @ref overview_treectrl -*/ -class wxTreeItemId -{ -public: - /** - Default constructor. A wxTreeItemId is not meant to be constructed - explicitly by the user; only those returned by the wxTreeCtrl functions - should be used. - */ - wxTreeItemId(); - - /** - Returns @true if this instance is referencing a valid tree item. - */ - bool IsOk() const; - - //@{ - /** - Operators for comparison between wxTreeItemId objects. - */ - bool operator ==(const wxTreeItemId& item) const; - bool operator !=(const wxTreeItemId& item) const; - //@} - - /** - Antonym of IsOk(), i.e. returns @true only if the item is not valid. - */ - bool operator !() const; -}; - -/** - @class wxTreeItemData - @wxheader{treebase.h} - - wxTreeItemData is some (arbitrary) user class associated with some item. The - main advantage of having this class is that wxTreeItemData objects are - destroyed automatically by the tree and, as this class has virtual - destructor, it means that the memory and any other resources associated with - a tree item will be automatically freed when it is deleted. Note that we - don't use wxObject as the base class for wxTreeItemData because the size of - this class is critical: in many applications, each tree leaf will have - wxTreeItemData associated with it and the number of leaves may be quite big. - - Also please note that because the objects of this class are deleted by the - tree using the operator @c delete, they must always be allocated on the heap - using @c new. - - @library{wxcore} - @category{containers} - - @see wxTreeCtrl -*/ -class wxTreeItemData : public wxClientData -{ -public: - /** - Default constructor. - - @beginWxPythonOnly - The following methods are added in wxPython for accessing the object: - - GetData(): Returns a reference to the Python Object. - - SetData(obj): Associates a new Python Object with the wxTreeItemData. - @endWxPythonOnly - */ - wxTreeItemData(); - - /** - Virtual destructor. - */ - ~wxTreeItemData(); - - /** - Returns the item associated with this node. - */ - const wxTreeItemId GetId(); - - /** - Sets the item associated with this node. - */ - void SetId(const wxTreeItemId& id); -}; - -/** - Indicates which type to associate an image with a wxTreeCtrl item. - - @see wxTreeCtrl::GetItemImage(), wxTreeCtrl::SetItemImage() -*/ -enum wxTreeItemIcon -{ - /** - To get/set the item image for when the item is - @b not selected and @b not expanded. - */ - wxTreeItemIcon_Normal, - /** - To get/set the item image for when the item is - @b selected and @b not expanded. - */ - wxTreeItemIcon_Selected, - /** - To get/set the item image for when the item is - @b not selected and @b expanded. - */ - wxTreeItemIcon_Expanded, - /** - To get/set the item image for when the item is - @b selected and @b expanded. - */ - wxTreeItemIcon_SelectedExpanded, - wxTreeItemIcon_Max -}; diff --git a/interface/treebook.h b/interface/treebook.h deleted file mode 100644 index c950031b2d..0000000000 --- a/interface/treebook.h +++ /dev/null @@ -1,295 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: treebook.h -// Purpose: interface of wxTreebookEvent -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxTreebookEvent - @wxheader{treebook.h} - - This class represents the events generated by a treebook control: currently, - there are four of them. The EVT_TREEBOOK_PAGE_CHANGING() and - EVT_TREEBOOK_PAGE_CHANGED() - have exactly the same behaviour as - wxNotebookEvent. - - The other two EVT_TREEBOOK_NODE_COLLAPSED() and EVT_TREEBOOK_NODE_EXPANDED() - are triggered when page node in the tree control is collapsed/expanded. The - page index could be retreived by calling GetSelection(). - - @beginEventTable{wxTreebookEvent} - @event{EVT_TREEBOOK_PAGE_CHANGED(id, func)} - The page selection was changed. Processes a @c - wxEVT_COMMAND_TREEBOOK_PAGE_CHANGED event. - @event{EVT_TREEBOOK_PAGE_CHANGING(id, func)} - The page selection is about to be changed. Processes a @c - wxEVT_COMMAND_TREEBOOK_PAGE_CHANGING event. This event can be @ref - wxNotifyEvent::Veto() "vetoed". - @event{EVT_TREEBOOK_NODE_COLLAPSED(id, func)} - The page node is going to be collapsed. Processes a @c - wxEVT_COMMAND_TREEBOOK_NODE_COLLAPSED event. - @event{EVT_TREEBOOK_NODE_EXPANDED(id, func)} - The page node is going to be expanded. Processes a @c - wxEVT_COMMAND_TREEBOOK_NODE_EXPANDED event. - @endEventTable - - @library{wxcore} - @category{events} - - @see wxTreebook, wxNotebookEvent -*/ -class wxTreebookEvent : public wxNotifyEvent -{ -public: - /** - @see wxNotebookEvent - */ - wxTreebookEvent(wxEventType commandType = wxEVT_NULL, int id = 0, - int nSel = wxNOT_FOUND, - int nOldSel = wxNOT_FOUND); - - /** - Returns the page that was selected before the change, @c wxNOT_FOUND if - none was selected. - */ - int GetOldSelection() const; - - /** - Returns the currently selected page, or @c wxNOT_FOUND if none was - selected. - - @see wxNotebookEvent::GetSelection() - */ - int GetSelection() const; -}; - - - -/** - @class wxTreebook - @wxheader{treebook.h} - - This class is an extension of the wxNotebook class that allows a tree - structured set of pages to be shown in a control. A classic example is a - netscape preferences dialog that shows a tree of preference sections on - the left and select section page on the right. - - To use the class simply create it and populate with pages using - InsertPage(), InsertSubPage(), AddPage(), AddSubPage(). - - If your tree is no more than 1 level in depth then you could simply use - AddPage() and AddSubPage() to sequentially populate your tree by adding at - every step a page or a subpage to the end of the tree. - - @beginEventTable{wxTreebookEvent} - @event{EVT_TREEBOOK_PAGE_CHANGED(id, func)} - The page selection was changed. Processes a @c - wxEVT_COMMAND_TREEBOOK_PAGE_CHANGED event. - @event{EVT_TREEBOOK_PAGE_CHANGING(id, func)} - The page selection is about to be changed. Processes a @c - wxEVT_COMMAND_TREEBOOK_PAGE_CHANGING event. This event can be @ref - wxNotifyEvent::Veto() "vetoed". - @event{EVT_TREEBOOK_NODE_COLLAPSED(id, func)} - The page node is going to be collapsed. Processes a @c - wxEVT_COMMAND_TREEBOOK_NODE_COLLAPSED event. - @event{EVT_TREEBOOK_NODE_EXPANDED(id, func)} - The page node is going to be expanded. Processes a @c - wxEVT_COMMAND_TREEBOOK_NODE_EXPANDED event. - @endEventTable - - @library{wxcore} - @category{miscwnd} - - @see wxTreebookEvent, wxNotebook, wxTreeCtrl, wxImageList, - @ref overview_bookctrl, @ref page_samples_notebook -*/ -class wxTreebook : public wxBookCtrlBase -{ -public: - /** - Default constructor. - */ - wxTreebook(); - - /** - Creates an empty wxTreebook. - - @param parent - The parent window. Must be non-@NULL. - @param id - The window identifier. - @param pos - The window position. - @param size - The window size. - @param style - The window style. See wxNotebook. - @param name - The name of the control (used only under Motif). - */ - wxTreebook(wxWindow* parent, wxWindowID id, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = wxBK_DEFAULT, - const wxString& name = wxEmptyString); - - /** - Destroys the wxTreebook object. Also deletes all the pages owned by the - control (inserted previously into it). - */ - ~wxTreebook(); - - /** - Adds a new page. The page is placed at the topmost level after all other - pages. @NULL could be specified for page to create an empty page. - */ - bool AddPage(wxWindow* page, const wxString& text, - bool bSelect = false, - int imageId = wxNOT_FOUND); - - /** - Adds a new child-page to the last top-level page. @NULL could be - specified for page to create an empty page. - */ - bool AddSubPage(wxWindow* page, const wxString& text, - bool bSelect = false, - int imageId = wxNOT_FOUND); - - /** - Sets the image list for the page control and takes ownership of the - list. - - @see wxImageList, SetImageList() - */ - void AssignImageList(wxImageList* imageList); - - /** - Changes the selection for the given page, returning the previous - selection. - - The call to this function does not generate the page changing events. - This is the only difference with SetSelection(). See - @ref overview_eventhandling_prog for more info. - */ - int ChangeSelection(size_t page); - - /** - Shortcut for @ref wxTreebook::ExpandNode() "ExpandNode"( @a pageId, - @false ). - */ - bool CollapseNode(size_t pageId); - - /** - Creates a treebook control. See wxTreebook::wxTreebook() for the - description of the parameters. - */ - bool Create(wxWindow* parent, wxWindowID id, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = wxBK_DEFAULT, - const wxString& name = wxEmptyString); - - /** - Deletes all pages inserted into the treebook. No event is generated. - */ - bool DeleteAllPages(); - - /** - Deletes the page at the specified position and all its children. Could - trigger page selection change in a case when selected page is removed. - In that case its parent is selected (or the next page if no parent). - */ - bool DeletePage(size_t pagePos); - - /** - Expands (collapses) the @a pageId node. Returns the previous state. May - generate page changing events (if selected page is under the collapsed - branch, then its parent is autoselected). - */ - bool ExpandNode(size_t pageId, bool expand = true); - - /** - Returns the image index for the given page. - */ - int GetPageImage(size_t n) const; - - /** - Returns the parent page of the given one or @c wxNOT_FOUND if this is a - top-level page. - */ - int GetPageParent(size_t page) const; - - /** - Returns the string for the given page. - */ - wxString GetPageText(size_t n) const; - - /** - Returns the currently selected page, or @c wxNOT_FOUND if none was - selected. - - @note This method may return either the previously or newly selected - page when called from the EVT_TREEBOOK_PAGE_CHANGED() handler - depending on the platform and so wxTreebookEvent::GetSelection() - should be used instead in this case. - */ - int GetSelection() const; - - /** - Inserts a new page just before the page indicated by @a pagePos. The new - page is placed before @a pagePos page and on the same level. @NULL could - be specified for page to create an empty page. - */ - bool InsertPage(size_t pagePos, wxWindow* page, - const wxString& text, - bool bSelect = false, - int imageId = wxNOT_FOUND); - - /** - Inserts a sub page under the specified page. - - @NULL could be specified for page to create an empty page. - */ - bool InsertSubPage(size_t pagePos, wxWindow* page, - const wxString& text, - bool bSelect = false, - int imageId = wxNOT_FOUND); - - /** - Returns @true if the page represented by @a pageId is expanded. - */ - bool IsNodeExpanded(size_t pageId) const; - - /** - Sets the image list for the page control. It does not take ownership of - the image list, you must delete it yourself. - - @see wxImageList, AssignImageList() - */ - void SetImageList(wxImageList* imageList); - - /** - Sets the image index for the given @a page. @a imageId is an index into - the image list which was set with SetImageList(). - */ - bool SetPageImage(size_t page, int imageId); - - /** - Sets the @a text for the given @a page. - */ - bool SetPageText(size_t page, const wxString& text); - - /** - @deprecated Please use ChangeSelection() instead. - - Sets the selection for the given page, returning the previous selection. - - The call to this function generates page changing events. - - @see GetSelection(), ChangeSelection() - */ - int SetSelection(size_t n); -}; - diff --git a/interface/treectrl.h b/interface/treectrl.h deleted file mode 100644 index 782a36837e..0000000000 --- a/interface/treectrl.h +++ /dev/null @@ -1,989 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: treectrl.h -// Purpose: interface of wxTreeItemData -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - - -/** - @class wxTreeCtrl - @wxheader{treectrl.h} - - A tree control presents information as a hierarchy, with items that may be - expanded to show further items. Items in a tree control are referenced by - wxTreeItemId handles, which may be tested for validity by calling - wxTreeItemId::IsOk(). - - A similar control with a fully native implemtation for GTK+ and OS X - as well is wxDataViewTreeCtrl. - - To intercept events from a tree control, use the event table macros - described in wxTreeEvent. - - @beginStyleTable - @style{wxTR_EDIT_LABELS} - Use this style if you wish the user to be able to edit labels in the - tree control. - @style{wxTR_NO_BUTTONS} - For convenience to document that no buttons are to be drawn. - @style{wxTR_HAS_BUTTONS} - Use this style to show + and - buttons to the left of parent items. - @style{wxTR_NO_LINES} - Use this style to hide vertical level connectors. - @style{wxTR_FULL_ROW_HIGHLIGHT} - Use this style to have the background colour and the selection highlight - extend over the entire horizontal row of the tree control window. (This - flag is ignored under Windows unless you specify @c wxTR_NO_LINES as - well.) - @style{wxTR_LINES_AT_ROOT} - Use this style to show lines between root nodes. Only applicable if @c - wxTR_HIDE_ROOT is set and @c wxTR_NO_LINES is not set. - @style{wxTR_HIDE_ROOT} - Use this style to suppress the display of the root node, effectively - causing the first-level nodes to appear as a series of root nodes. - @style{wxTR_ROW_LINES} - Use this style to draw a contrasting border between displayed rows. - @style{wxTR_HAS_VARIABLE_ROW_HEIGHT} - Use this style to cause row heights to be just big enough to fit the - content. If not set, all rows use the largest row height. The default is - that this flag is unset. Generic only. - @style{wxTR_SINGLE} - For convenience to document that only one item may be selected at a - time. Selecting another item causes the current selection, if any, to be - deselected. This is the default. - @style{wxTR_MULTIPLE} - Use this style to allow a range of items to be selected. If a second - range is selected, the current range, if any, is deselected. - @style{wxTR_DEFAULT_STYLE} - The set of flags that are closest to the defaults for the native control - for a particular toolkit. - @endStyleTable - - See also @ref overview_windowstyles. - - @b Win32 @b notes: - - wxTreeCtrl class uses the standard common treeview control under Win32 - implemented in the system library comctl32.dll. Some versions of this - library are known to have bugs with handling the tree control colours: the - usual symptom is that the expanded items leave black (or otherwise - incorrectly coloured) background behind them, especially for the controls - using non-default background colour. The recommended solution is to upgrade - the comctl32.dll to a newer version: see - http://www.microsoft.com/downloads/details.aspx?familyid=cb2cf3a2-8025-4e8f-8511-9b476a8d35d2 - - @library{wxcore} - @category{ctrl} - - - @see wxDataViewTreeCtrl, wxTreeEvent, wxTreeItemData, @ref overview_treectrl, wxListBox, - wxListCtrl, wxImageList -*/ -class wxTreeCtrl : public wxControl -{ -public: - /** - Default Constructor. - */ - wxTreeCtrl(); - - /** - Constructor, creating and showing a tree control. - - @param parent - Parent window. Must not be @NULL. - @param id - Window identifier. The value @c wxID_ANY indicates a default value. - @param pos - Window position. - @param size - Window size. If wxDefaultSize is specified then the window is sized - appropriately. - @param style - Window style. See wxTreeCtrl. - @param validator - Window validator. - @param name - Window name. - - @see Create(), wxValidator - */ - wxTreeCtrl(wxWindow* parent, wxWindowID id, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = wxTR_HAS_BUTTONS, - const wxValidator& validator = wxDefaultValidator, - const wxString& name = "treeCtrl"); - - - /** - Destructor, destroying the tree control. - */ - ~wxTreeCtrl(); - - /** - Adds the root node to the tree, returning the new item. - - The @a image and @a selImage parameters are an index within the normal - image list specifying the image to use for unselected and selected - items, respectively. If @a image -1 and @a selImage is -1, the same - image is used for both selected and unselected items. - */ - wxTreeItemId AddRoot(const wxString& text, int image = -1, - int selImage = -1, - wxTreeItemData* data = NULL); - - /** - Appends an item to the end of the branch identified by @a parent, return - a new item id. - - The @a image and @a selImage parameters are an index within the normal - image list specifying the image to use for unselected and selected - items, respectively. If @a image -1 and @a selImage is -1, the same - image is used for both selected and unselected items. - */ - wxTreeItemId AppendItem(const wxTreeItemId& parent, - const wxString& text, - int image = -1, - int selImage = -1, - wxTreeItemData* data = NULL); - - /** - Sets the buttons image list. The button images assigned with this method - will be automatically deleted by wxTreeCtrl as appropriate (i.e. it - takes ownership of the list). - - Setting or assigning the button image list enables the display of image - buttons. Once enabled, the only way to disable the display of button - images is to set the button image list to @NULL. - - This function is only available in the generic version. - - @see SetButtonsImageList(). - */ - void AssignButtonsImageList(wxImageList* imageList); - - /** - Sets the normal image list. The image list assigned with this method - will be automatically deleted by wxTreeCtrl as appropriate (i.e. it - takes ownership of the list). - - @see SetImageList(). - */ - void AssignImageList(wxImageList* imageList); - - /** - Sets the state image list. Image list assigned with this method will be - automatically deleted by wxTreeCtrl as appropriate (i.e. it takes - ownership of the list). - - @see SetStateImageList(). - */ - void AssignStateImageList(wxImageList* imageList); - - /** - Collapses the given item. - */ - void Collapse(const wxTreeItemId& item); - - /** - Collapses the root item. - - @see ExpandAll() - */ - void CollapseAll(); - - /** - Collapses this item and all of its children, recursively. - - @see ExpandAllChildren() - */ - void CollapseAllChildren(const wxTreeItemId& item); - - /** - Collapses the given item and removes all children. - */ - void CollapseAndReset(const wxTreeItemId& item); - - /** - Creates the tree control. See wxTreeCtrl::wxTreeCtrl() for further - details. - */ - bool Create(wxWindow* parent, wxWindowID id, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = wxTR_HAS_BUTTONS, - const wxValidator& validator = wxDefaultValidator, - const wxString& name = "treeCtrl"); - - /** - Deletes the specified item. A EVT_TREE_DELETE_ITEM() event will be - generated. - - This function may cause a subsequent call to GetNextChild() to fail. - */ - void Delete(const wxTreeItemId& item); - - /** - Deletes all items in the control. Note that this may not generate - EVT_TREE_DELETE_ITEM() events under some Windows versions although - normally such event is generated for each removed item. - */ - void DeleteAllItems(); - - /** - Deletes all children of the given item (but not the item itself). Note - that this will @b not generate any events unlike Delete() method. - - If you have called SetItemHasChildren(), you may need to call it again - since DeleteChildren() does not automatically clear the setting. - */ - void DeleteChildren(const wxTreeItemId& item); - - /** - Starts editing the label of the given @a item. This function generates a - EVT_TREE_BEGIN_LABEL_EDIT() event which can be vetoed so that no text - control will appear for in-place editing. - - If the user changed the label (i.e. s/he does not press ESC or leave the - text control without changes, a EVT_TREE_END_LABEL_EDIT() event will be - sent which can be vetoed as well. - - @see EndEditLabel(), wxTreeEvent - */ - void EditLabel(const wxTreeItemId& item); - - /** - Ends label editing. If @a cancelEdit is @true, the edit will be - cancelled. - - @note - This function is currently supported under Windows only. - - @see EditLabel() - */ - void EndEditLabel(bool cancelEdit); - - /** - Scrolls and/or expands items to ensure that the given item is visible. - */ - void EnsureVisible(const wxTreeItemId& item); - - /** - Expands the given item. - */ - void Expand(const wxTreeItemId& item); - - /** - Expands all items in the tree. - */ - void ExpandAll(); - - /** - Expands the given item and all its children recursively. - */ - void ExpandAllChildren(const wxTreeItemId& item); - - /** - Retrieves the rectangle bounding the @a item. If @a textOnly is @true, - only the rectangle around the item's label will be returned, otherwise - the item's image is also taken into account. - - The return value is @true if the rectangle was successfully retrieved or - @c @false if it was not (in this case @a rect is not changed) -- for - example, if the item is currently invisible. - - Notice that the rectangle coordinates are logical, not physical ones. - So, for example, the x coordinate may be negative if the tree has a - horizontal scrollbar and its position is not 0. - - @beginWxPythonOnly - The wxPython version of this method requires only the @a item and @a - textOnly parameters. The return value is either a wxRect object or @c - None. - @endWxPythonOnly - */ - bool GetBoundingRect(const wxTreeItemId& item, wxRect& rect, - bool textOnly = false) const; - - /** - Returns the buttons image list (from which application-defined button - images are taken). - - This function is only available in the generic version. - */ - wxImageList* GetButtonsImageList() const; - - /** - Returns the number of items in the branch. If @a recursively is @true, - returns the total number of descendants, otherwise only one level of - children is counted. - */ - unsigned int GetChildrenCount(const wxTreeItemId& item, - bool recursively = true) const; - - /** - Returns the number of items in the control. - */ - unsigned int GetCount() const; - - /** - Returns the edit control being currently used to edit a label. Returns - @NULL if no label is being edited. - - @note This is currently only implemented for wxMSW. - */ - wxTextCtrl* GetEditControl() const; - - /** - Returns the first child; call GetNextChild() for the next child. - - For this enumeration function you must pass in a 'cookie' parameter - which is opaque for the application but is necessary for the library to - make these functions reentrant (i.e. allow more than one enumeration on - one and the same object simultaneously). The cookie passed to - GetFirstChild() and GetNextChild() should be the same variable. - - Returns an invalid tree item (i.e. wxTreeItemId::IsOk() returns @false) - if there are no further children. - - @beginWxPythonOnly - In wxPython the returned wxTreeItemId and the new cookie value are both - returned as a tuple containing the two values. - @endWxPythonOnly - - @see GetNextChild(), GetNextSibling() - */ - wxTreeItemId GetFirstChild(const wxTreeItemId& item, - wxTreeItemIdValue& cookie) const; - - /** - Returns the first visible item. - */ - wxTreeItemId GetFirstVisibleItem() const; - - /** - Returns the normal image list. - */ - wxImageList* GetImageList() const; - - /** - Returns the current tree control indentation. - */ - int GetIndent() const; - - /** - Returns the background colour of the item. - */ - wxColour GetItemBackgroundColour(const wxTreeItemId& item) const; - - /** - Returns the tree item data associated with the item. - - @see wxTreeItemData - - @beginWxPythonOnly - wxPython provides the following shortcut method: - @li GetPyData(item): Returns the Python Object associated with the - wxTreeItemData for the given item Id. - @endWxPythonOnly - */ - wxTreeItemData* GetItemData(const wxTreeItemId& item) const; - - /** - Returns the font of the item label. - */ - wxFont GetItemFont(const wxTreeItemId& item) const; - - /** - Gets the specified item image. The value of @a which may be: - - ::wxTreeItemIcon_Normal: to get the normal item image. - - ::wxTreeItemIcon_Selected: to get the selected item image (i.e. the - image which is shown when the item is currently selected). - - ::wxTreeItemIcon_Expanded: to get the expanded image (this only makes - sense for items which have children - then this image is shown when - the item is expanded and the normal image is shown when it is - collapsed). - - ::wxTreeItemIcon_SelectedExpanded: to get the selected expanded image - (which is shown when an expanded item is currently selected). - */ - int GetItemImage(const wxTreeItemId& item, - wxTreeItemIcon which = wxTreeItemIcon_Normal) const; - - /** - Returns the item's parent. - */ - wxTreeItemId GetItemParent(const wxTreeItemId& item) const; - - /** - Gets the selected item image (this function is obsolete, use @ref - GetItemImage() "GetItemImage"( @a item, ::wxTreeItemIcon_Selected) - instead). - */ - int GetItemSelectedImage(const wxTreeItemId& item) const; - - /** - Gets the specified item state. - */ - int GetItemState(const wxTreeItemId& item) const; - - /** - Returns the item label. - */ - wxString GetItemText(const wxTreeItemId& item) const; - - /** - Returns the colour of the item label. - */ - wxColour GetItemTextColour(const wxTreeItemId& item) const; - - /** - Returns the last child of the item (or an invalid tree item if this item - has no children). - - @see GetFirstChild(), GetNextSibling(), GetLastChild() - */ - wxTreeItemId GetLastChild(const wxTreeItemId& item) const; - - /** - Returns the next child; call GetFirstChild() for the first child. For - this enumeration function you must pass in a 'cookie' parameter which is - opaque for the application but is necessary for the library to make - these functions reentrant (i.e. allow more than one enumeration on one - and the same object simultaneously). The cookie passed to - GetFirstChild() and GetNextChild() should be the same. - - Returns an invalid tree item if there are no further children. - - @beginWxPythonOnly - In wxPython the returned wxTreeItemId and the new cookie value are both - returned as a tuple containing the two values. - @endWxPythonOnly - - @see GetFirstChild() - */ - wxTreeItemId GetNextChild(const wxTreeItemId& item, - wxTreeItemIdValue& cookie) const; - - /** - Returns the next sibling of the specified item; call GetPrevSibling() - for the previous sibling. - - Returns an invalid tree item if there are no further siblings. - - @see GetPrevSibling() - */ - wxTreeItemId GetNextSibling(const wxTreeItemId& item) const; - - /** - Returns the next visible item or an invalid item if this item is the - last visible one. - - @note The @a item itself must be visible. - */ - wxTreeItemId GetNextVisible(const wxTreeItemId& item) const; - - /** - Returns the previous sibling of the specified item; call - GetNextSibling() for the next sibling. - - Returns an invalid tree item if there are no further children. - - @see GetNextSibling() - */ - wxTreeItemId GetPrevSibling(const wxTreeItemId& item) const; - - /** - Returns the previous visible item or an invalid item if this item is the - first visible one. - - @note The @a item itself must be visible. - */ - wxTreeItemId GetPrevVisible(const wxTreeItemId& item) const; - - /** - Returns @true if the control will use a quick calculation for the best - size, looking only at the first and last items. The default is @false. - - @see SetQuickBestSize() - */ - bool GetQuickBestSize() const; - - /** - Returns the root item for the tree control. - */ - wxTreeItemId GetRootItem() const; - - /** - Returns the selection, or an invalid item if there is no selection. This - function only works with the controls without @c wxTR_MULTIPLE style, - use GetSelections() for the controls which do have this style. - */ - wxTreeItemId GetSelection() const; - - /** - Fills the array of tree items passed in with the currently selected - items. This function can be called only if the control has the @c - wxTR_MULTIPLE style. - - Returns the number of selected items. - - @beginWxPythonOnly - The wxPython version of this method accepts no parameters and returns a - Python list of @ref wxTreeItemId "wxTreeItemId"s. - @endWxPythonOnly - */ - unsigned int GetSelections(wxArrayTreeItemIds& selection) const; - - /** - Returns the state image list (from which application-defined state - images are taken). - */ - wxImageList* GetStateImageList() const; - - /** - Calculates which (if any) item is under the given @a point, returning - the tree item id at this point plus extra information @a flags. @a flags - is a bitlist of the following: - - - @c wxTREE_HITTEST_ABOVE: Above the client area. - - @c wxTREE_HITTEST_BELOW: Below the client area. - - @c wxTREE_HITTEST_NOWHERE: In the client area but below the last item. - - @c wxTREE_HITTEST_ONITEMBUTTON: On the button associated with an item. - - @c wxTREE_HITTEST_ONITEMICON: On the bitmap associated with an item. - - @c wxTREE_HITTEST_ONITEMINDENT: In the indentation associated with an - item. - - @c wxTREE_HITTEST_ONITEMLABEL: On the label (string) associated with - an item. - - @c wxTREE_HITTEST_ONITEMRIGHT: In the area to the right of an item. - - @c wxTREE_HITTEST_ONITEMSTATEICON: On the state icon for a tree view - item that is in a user-defined state. - - @c wxTREE_HITTEST_TOLEFT: To the right of the client area. - - @c wxTREE_HITTEST_TORIGHT: To the left of the client area. - - @beginWxPythonOnly - In wxPython both the wxTreeItemId and the flags are returned as a tuple. - @endWxPythonOnly - */ - wxTreeItemId HitTest(const wxPoint& point, int& flags) const; - - - /** - Inserts an item after a given one (@a previous). - - The @a image and @a selImage parameters are an index within the normal - image list specifying the image to use for unselected and selected - items, respectively. If @a image -1 and @a selImage is -1, the same - image is used for both selected and unselected items. - */ - wxTreeItemId InsertItem(const wxTreeItemId& parent, - const wxTreeItemId& previous, - const wxString& text, - int image = -1, - int selImage = -1, - wxTreeItemData* data = NULL); - - /** - Inserts an item before one identified - by its position (@a before). @a before must be less than the number of - children. - - The @a image and @a selImage parameters are an index within the normal - image list specifying the image to use for unselected and selected - items, respectively. If @a image -1 and @a selImage is -1, the same - image is used for both selected and unselected items. - - @beginWxPythonOnly - In wxPython, this form of this method is called @c InsertItemBefore(). - @endWxPythonOnly - */ - wxTreeItemId InsertItem(const wxTreeItemId& parent, - size_t before, - const wxString& text, - int image = -1, - int selImage = -1, - wxTreeItemData* data = NULL); - - /** - Returns @true if the given item is in bold state. - - @see SetItemBold() - */ - bool IsBold(const wxTreeItemId& item) const; - - /** - Returns @true if the control is empty (i.e. has no items, even no root - one). - */ - bool IsEmpty() const; - - /** - Returns @true if the item is expanded (only makes sense if it has - children). - */ - bool IsExpanded(const wxTreeItemId& item) const; - - /** - Returns @true if the item is selected. - */ - bool IsSelected(const wxTreeItemId& item) const; - - /** - Returns @true if the item is visible on the screen. - */ - bool IsVisible(const wxTreeItemId& item) const; - - /** - Returns @true if the item has children. - */ - bool ItemHasChildren(const wxTreeItemId& item) const; - - /** - Override this function in the derived class to change the sort order of - the items in the tree control. The function should return a negative, - zero or positive value if the first item is less than, equal to or - greater than the second one. - - Please note that you @b must use wxRTTI macros DECLARE_DYNAMIC_CLASS() - and IMPLEMENT_DYNAMIC_CLASS() if you override this function because - otherwise the base class considers that it is not overridden and uses - the default comparison, i.e. sorts the items alphabetically, which - allows it optimize away the calls to the virtual function completely. - - @see SortChildren() - */ - int OnCompareItems(const wxTreeItemId& item1, - const wxTreeItemId& item2); - - /** - Appends an item as the first child of @a parent, return a new item id. - - The @a image and @a selImage parameters are an index within the normal - image list specifying the image to use for unselected and selected - items, respectively. If @a image -1 and @a selImage is -1, the same - image is used for both selected and unselected items. - */ - wxTreeItemId PrependItem(const wxTreeItemId& parent, - const wxString& text, - int image = -1, - int selImage = -1, - wxTreeItemData* data = NULL); - - /** - Scrolls the specified item into view. - */ - void ScrollTo(const wxTreeItemId& item); - - /** - Selects the given item. In multiple selection controls, can be also used - to deselect a currently selected item if the value of @a select is - @false. - */ - void SelectItem(const wxTreeItemId& item, bool select = true); - - /** - Sets the buttons image list (from which application-defined button - images are taken). - - The button images assigned with this method will @b not be deleted by - @ref wxTreeCtrl "wxTreeCtrl"'s destructor, you must delete it yourself. - Setting or assigning the button image list enables the display of image - buttons. Once enabled, the only way to disable the display of button - images is to set the button image list to @NULL. - - @note This function is only available in the generic version. - - @see AssignButtonsImageList(). - */ - void SetButtonsImageList(wxImageList* imageList); - - /** - Sets the normal image list. The image list assigned with this method - will @b not be deleted by @ref wxTreeCtrl "wxTreeCtrl"'s destructor, you - must delete it yourself. - - @see AssignImageList(). - */ - void SetImageList(wxImageList* imageList); - - /** - Sets the indentation for the tree control. - */ - void SetIndent(int indent); - - /** - Sets the colour of the item's background. - */ - void SetItemBackgroundColour(const wxTreeItemId& item, - const wxColour& col); - - /** - Makes item appear in bold font if @a bold parameter is @true or resets - it to the normal state. - - @see IsBold() - */ - void SetItemBold(const wxTreeItemId& item, bool bold = true); - - /** - Sets the item client data. - - @beginWxPythonOnly - - @b SetPyData( @a item, @c obj): Associate the given Python Object with - the wxTreeItemData for the given item Id. - @endWxPythonOnly - - */ - void SetItemData(const wxTreeItemId& item, wxTreeItemData* data); - - - /** - Gives the item the visual feedback for Drag'n'Drop actions, which is - useful if something is dragged from the outside onto the tree control - (as opposed to a DnD operation within the tree control, which already - is implemented internally). - */ - void SetItemDropHighlight(const wxTreeItemId& item, - bool highlight = true); - - /** - Sets the item's font. All items in the tree should have the same height - to avoid text clipping, so the fonts height should be the same for all - of them, although font attributes may vary. - - @see SetItemBold() - */ - void SetItemFont(const wxTreeItemId& item, const wxFont& font); - - /** - Force appearance of the button next to the item. This is useful to - allow the user to expand the items which don't have any children now, - but instead adding them only when needed, thus minimizing memory - usage and loading time. - */ - void SetItemHasChildren(const wxTreeItemId& item, - bool hasChildren = true); - - /** - Sets the specified item's image. See GetItemImage() for the description - of the @a which parameter. - */ - void SetItemImage(const wxTreeItemId& item, int image, - wxTreeItemIcon which = wxTreeItemIcon_Normal); - - /** - Sets the selected item image (this function is obsolete, use @ref - SetItemImage() "SetItemImage"( @a item, ::wxTreeItemIcon_Selected ) - instead). - */ - void SetItemSelectedImage(const wxTreeItemId& item, int selImage); - - /** - Sets the specified item state. The value of @a state may be: - - @c wxTREE_ITEMSTATE_NONE: to disable the item state (the state image will - be not displayed). - - @c wxTREE_ITEMSTATE_NEXT: to set the next item state. - - @c wxTREE_ITEMSTATE_PREV: to set the previous item state. - */ - void SetItemState(const wxTreeItemId& item, int state); - - /** - Sets the item label. - */ - void SetItemText(const wxTreeItemId& item, const wxString& text); - - /** - Sets the colour of the item's text. - */ - void SetItemTextColour(const wxTreeItemId& item, - const wxColour& col); - - /** - If @true is passed, specifies that the control will use a quick - calculation for the best size, looking only at the first and last items. - Otherwise, it will look at all items. The default is @false. - - @see GetQuickBestSize() - */ - void SetQuickBestSize(bool quickBestSize); - - /** - Sets the state image list (from which application-defined state images - are taken). Image list assigned with this method will @b not be deleted - by @ref wxTreeCtrl "wxTreeCtrl"'s destructor, you must delete it - yourself. - - @see AssignStateImageList(). - */ - void SetStateImageList(wxImageList* imageList); - - /** - Sets the mode flags associated with the display of the tree control. The - new mode takes effect immediately. - - @note Generic only; MSW ignores changes. - */ - void SetWindowStyle(long styles); - - /** - Sorts the children of the given item using OnCompareItems(). - You should override that method to change the sort order (the default is - ascending case-sensitive alphabetical order). - - @see wxTreeItemData, OnCompareItems() - */ - void SortChildren(const wxTreeItemId& item); - - /** - Toggles the given item between collapsed and expanded states. - */ - void Toggle(const wxTreeItemId& item); - - /** - Toggles the given item between selected and unselected states. For - multiselection controls only. - */ - void ToggleItemSelection(const wxTreeItemId& item); - - /** - Removes the selection from the currently selected item (if any). - */ - void Unselect(); - - /** - This function either behaves the same as Unselect() if the control - doesn't have @c wxTR_MULTIPLE style, or removes the selection from all - items if it does have this style. - */ - void UnselectAll(); - - /** - Unselects the given item. This works in multiselection controls only. - */ - void UnselectItem(const wxTreeItemId& item); -}; - - - -/** - @class wxTreeEvent - @wxheader{treectrl.h} - - A tree event holds information about events associated with wxTreeCtrl - objects. - - To process input from a tree control, use these event handler macros to - direct input to member functions that take a wxTreeEvent argument. - - @beginEventTable{wxTreeEvent} - @event{EVT_TREE_BEGIN_DRAG(id, func)} - Begin dragging with the left mouse button. - @event{EVT_TREE_BEGIN_RDRAG(id, func)} - Begin dragging with the right mouse button. - @event{EVT_TREE_END_DRAG(id, func)} - End dragging with the left or right mouse button. - @event{EVT_TREE_BEGIN_LABEL_EDIT(id, func)} - Begin editing a label. This can be prevented by calling Veto(). - @event{EVT_TREE_END_LABEL_EDIT(id, func)} - Finish editing a label. This can be prevented by calling Veto(). - @event{EVT_TREE_DELETE_ITEM(id, func)} - Delete an item. - @event{EVT_TREE_GET_INFO(id, func)} - Request information from the application. - @event{EVT_TREE_SET_INFO(id, func)} - Information is being supplied. - @event{EVT_TREE_ITEM_ACTIVATED(id, func)} - The item has been activated, i.e. chosen by double clicking it with - mouse or from keyboard. - @event{EVT_TREE_ITEM_COLLAPSED(id, func)} - The item has been collapsed. - @event{EVT_TREE_ITEM_COLLAPSING(id, func)} - The item is being collapsed. This can be prevented by calling Veto(). - @event{EVT_TREE_ITEM_EXPANDED(id, func)} - The item has been expanded. - @event{EVT_TREE_ITEM_EXPANDING(id, func)} - The item is being expanded. This can be prevented by calling Veto(). - @event{EVT_TREE_ITEM_RIGHT_CLICK(id, func)} - The user has clicked the item with the right mouse button. - @event{EVT_TREE_ITEM_MIDDLE_CLICK(id, func)} - The user has clicked the item with the middle mouse button. - @event{EVT_TREE_SEL_CHANGED(id, func)} - Selection has changed. - @event{EVT_TREE_SEL_CHANGING(id, func)} - Selection is changing. This can be prevented by calling Veto(). - @event{EVT_TREE_KEY_DOWN(id, func)} - A key has been pressed. - @event{EVT_TREE_ITEM_GETTOOLTIP(id, func)} - The opportunity to set the item tooltip is being given to the - application (call SetToolTip()). Windows only. - @event{EVT_TREE_ITEM_MENU(id, func)} - The context menu for the selected item has been requested, either by a - right click or by using the menu key. - @event{EVT_TREE_STATE_IMAGE_CLICK(id, func)} - The state image has been clicked. - @endEventTable - - @library{wxbase} - @category{events} - - @see wxTreeCtrl -*/ -class wxTreeEvent : public wxNotifyEvent -{ -public: - /** - Constructor, used by wxWidgets itself only. - */ - wxTreeEvent(wxEventType commandType, wxTreeCtrl* tree); - - /** - Returns the item (valid for all events). - */ - wxTreeItemId GetItem() const; - - /** - Returns the key code if the event is a key event. Use GetKeyEvent() to - get the values of the modifier keys for this event (i.e. Shift or Ctrl). - */ - int GetKeyCode() const; - - /** - Returns the key event for EVT_TREE_KEY_DOWN() events. - */ - const wxKeyEvent GetKeyEvent() const; - - /** - Returns the label if the event is a begin or end edit label event. - */ - const wxString GetLabel() const; - - /** - Returns the old item index (valid for EVT_TREE_ITEM_CHANGING() and - EVT_TREE_ITEM_CHANGED() events). - */ - wxTreeItemId GetOldItem() const; - - /** - Returns the position of the mouse pointer if the event is a drag or - menu-context event. - - In both cases the position is in client coordinates - i.e. relative to - the wxTreeCtrl window (so that you can pass it directly to e.g. - wxWindow::PopupMenu()). - */ - wxPoint GetPoint() const; - - /** - Returns @true if the label edit was cancelled. This should be called - from within an EVT_TREE_END_LABEL_EDIT() handler. - */ - bool IsEditCancelled() const; - - /** - Set the tooltip for the item (valid for EVT_TREE_ITEM_GETTOOLTIP() - events). Windows only. - */ - void SetToolTip(const wxString& tooltip); -}; diff --git a/interface/txtstrm.h b/interface/txtstrm.h deleted file mode 100644 index 89dd37741a..0000000000 --- a/interface/txtstrm.h +++ /dev/null @@ -1,302 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: txtstrm.h -// Purpose: interface of wxTextInputStream -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - - - -/** - @class wxTextInputStream - @wxheader{txtstrm.h} - - This class provides functions that reads text data using an input stream, - allowing you to read text, floats, and integers. - - The wxTextInputStream correctly reads text files (or streams) in DOS, - Macintosh and Unix formats and reports a single newline char as a line - ending. - - wxTextInputStream::operator>>() is overloaded and you can use this class - like a standard C++ iostream. Note, however, that the arguments are the - fixed size types wxUint32, wxInt32 etc and on a typical 32-bit computer, - none of these match to the "long" type (wxInt32 is defined as int on 32-bit - architectures) so that you cannot use long. To avoid problems (here and - elsewhere), make use of wxInt32, wxUint32 and similar types. - - If you're scanning through a file using wxTextInputStream, you should check - for @c EOF @b before reading the next item (word / number), because - otherwise the last item may get lost. You should however be prepared to - receive an empty item (empty string / zero number) at the end of file, - especially on Windows systems. This is unavoidable because most (but not - all) files end with whitespace (i.e. usually a newline). - - For example: - - @code - wxFileInputStream input( "mytext.txt" ); - wxTextInputStream text( input ); - wxUint8 i1; - float f2; - wxString line; - - text >> i1; // read a 8 bit integer. - text >> i1 >> f2; // read a 8 bit integer followed by float. - text >> line; // read a text line - @endcode - - @library{wxbase} - @category{streams} - - @see wxTextOutputStream -*/ -class wxTextInputStream -{ -public: - /** - Constructs a text stream associated to the given input stream. - - @param stream - The underlying input stream. - @param sep - The initial string separator characters. - @param conv - In Unicode build only: The encoding converter used to - convert the bytes in the underlying input stream to characters. - */ - wxTextInputStream(wxInputStream& stream, - const wxString& sep = " \t", - const wxMBConv& conv = wxConvAuto()); - - /** - Destructor. - */ - ~wxTextInputStream(); - - /** - Reads a character, returns 0 if there are no more characters in the - stream. - */ - wxChar GetChar(); - - /** - Reads a unsigned 16 bit integer from the stream. - - See Read8() for the description of the @a base parameter. - */ - wxUint16 Read16(int base = 10); - - /** - Reads a signed 16 bit integer from the stream. - - See Read8() for the description of the @a base parameter. - */ - wxInt16 Read16S(int base = 10); - - /** - Reads a 32 bit unsigned integer from the stream. - - See Read8() for the description of the @a base parameter. - */ - wxUint32 Read32(int base = 10); - - /** - Reads a 32 bit signed integer from the stream. - - See Read8() for the description of the @a base parameter. - */ - wxInt32 Read32S(int base = 10); - - /** - Reads a single unsigned byte from the stream, given in base @a base. - - The value of @a base must be comprised between 2 and 36, inclusive, or - be a special value 0 which means that the usual rules of C numbers are - applied: if the number starts with @c 0x it is considered to be in base - 16, if it starts with 0 - in base 8 and in base 10 otherwise. Note that - you may not want to specify the base 0 if you are parsing the numbers - which may have leading zeroes as they can yield unexpected (to the user - not familiar with C) results. - */ - wxUint8 Read8(int base = 10); - - /** - Reads a single signed byte from the stream. - - See Read8() for the description of the @a base parameter. - */ - wxInt8 Read8S(int base = 10); - - /** - Reads a double (IEEE encoded) from the stream. - */ - double ReadDouble(); - - /** - Reads a line from the input stream and returns it (without the end of - line character). - */ - wxString ReadLine(); - - /** - @deprecated Use ReadLine() or ReadWord() instead. - - Same as ReadLine(). - */ - wxString ReadString(); - - /** - Reads a word (a sequence of characters until the next separator) from - the input stream. - - @see SetStringSeparators() - */ - wxString ReadWord(); - - /** - Sets the characters which are used to define the word boundaries in - ReadWord(). - - The default separators are the @c space and @c TAB characters. - */ - void SetStringSeparators(const wxString& sep); -}; - - -/** - Specifies the end-of-line characters to use with wxTextOutputStream. -*/ -typedef enum -{ - /** - Specifies wxTextOutputStream to use the native end-of-line characters. - */ - wxEOL_NATIVE, - - /** - Specifies wxTextOutputStream to use Unix end-of-line characters. - */ - wxEOL_UNIX, - - /** - Specifies wxTextOutputStream to use Mac end-of-line characters. - */ - wxEOL_MAC, - - /** - Specifies wxTextOutputStream to use DOS end-of-line characters. - */ - wxEOL_DOS -} wxEOL; - - -/** - @class wxTextOutputStream - @wxheader{txtstrm.h} - - This class provides functions that write text data using an output stream, - allowing you to write text, floats, and integers. - - You can also simulate the C++ @c std::cout class: - - @code - wxFFileOutputStream output( stderr ); - wxTextOutputStream cout( output ); - - cout << "This is a text line" << endl; - cout << 1234; - cout << 1.23456; - @endcode - - The wxTextOutputStream writes text files (or streams) on DOS, Macintosh and - Unix in their native formats (concerning the line ending). - - @library{wxbase} - @category{streams} - - @see wxTextInputStream -*/ -class wxTextOutputStream -{ -public: - /** - Constructs a text stream object associated to the given output stream. - - @param stream - The output stream. - @param mode - The end-of-line mode. One of ::wxEOL_NATIVE, ::wxEOL_DOS, - ::wxEOL_MAC and ::wxEOL_UNIX. - @param conv - In Unicode build only: The object used to convert - Unicode text into ASCII characters written to the output stream. - */ - wxTextOutputStream(wxOutputStream& stream, - wxEOL mode = wxEOL_NATIVE, - const wxMBConv& conv = wxConvAuto()); - - /** - Destroys the wxTextOutputStream object. - - Also calls Flush(). - */ - ~wxTextOutputStream(); - - /** - Flushes the stream. - - This method should be called when using stateful encodings (currently - the only example of such encoding in wxWidgets is wxMBConvUTF7) to - write the end of the encoded data to the stream. - - @since 2.9.0 - */ - void Flush(); - - /** - Returns the end-of-line mode. One of ::wxEOL_DOS, ::wxEOL_MAC and - ::wxEOL_UNIX. - */ - wxEOL GetMode(); - - /** - Writes a character to the stream. - */ - void PutChar(wxChar c); - - /** - Set the end-of-line mode. One of ::wxEOL_NATIVE, ::wxEOL_DOS, - ::wxEOL_MAC and ::wxEOL_UNIX. - */ - void SetMode(wxEOL mode = wxEOL_NATIVE); - - /** - Writes the 16 bit integer @a i16 to the stream. - */ - void Write16(wxUint16 i16); - - /** - Writes the 32 bit integer @a i32 to the stream. - */ - void Write32(wxUint32 i32); - - /** - Writes the single byte @a i8 to the stream. - */ - void Write8(wxUint8 i8); - - /** - Writes the double @a f to the stream using the IEEE format. - */ - virtual void WriteDouble(double f); - - /** - Writes @a string as a line. Depending on the end-of-line mode the end of - line ('\\n') characters in the string are converted to the correct line - ending terminator. - */ - virtual void WriteString(const wxString& string); -}; - diff --git a/interface/uri.h b/interface/uri.h deleted file mode 100644 index 4c36e39445..0000000000 --- a/interface/uri.h +++ /dev/null @@ -1,299 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: uri.h -// Purpose: interface of wxURI -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - Host type of URI returned from wxURI::GetHostType(). -*/ -enum wxURIHostType -{ - wxURI_REGNAME, ///< Host is a normal register name (@c "www.mysite.com"). - wxURI_IPV4ADDRESS, ///< Host is a version 4 ip address (@c "192.168.1.100"). - wxURI_IPV6ADDRESS, ///< Host is a version 6 ip address (@c "[aa:aa:aa:aa::aa:aa]:5050"). - wxURI_IPVFUTURE ///< Host is a future ip address, wxURI is unsure what kind. -}; - -/** - @class wxURI - @wxheader{uri.h} - - wxURI is used to extract information from a URI (Uniform Resource - Identifier). - - For information about URIs, see RFC 3986 - . - - In short, a URL is a URI. In other words, URL is a subset of a URI - all - acceptable URLs are also acceptable URIs. - - wxURI automatically escapes invalid characters in a string, so there is no - chance of wxURI "failing" on construction/creation. - - wxURI supports copy construction and standard assignment operators. wxURI - can also be inherited from to provide furthur functionality. - - To obtain individual components you can use one of the GetXXX() methods. - However, you should check HasXXX() before calling a get method, which - determines whether or not the component referred to by the method is - defined according to RFC 2396. Consider an undefined component equivalent - to a @NULL C string. - - Example: - - @code - //protocol will hold the http protocol (i.e. "http") - wxString protocol; - wxURI myuri("http://mysite.com"); - if( myuri.HasScheme() ) - protocol = myuri.GetScheme(); - @endcode - - @note On URIs with a "file" scheme wxURI does not parse the userinfo, - server, or port portion. This is to keep compatability with - wxFileSystem, the old wxURL, and older url specifications. - - @library{wxbase} - @category{data} - - @see wxURL -*/ -class wxURI : public wxObject -{ -public: - /** - Creates an empty URI. - */ - wxURI(); - /** - Constructor for quick creation. - - @param uri - URI (Uniform Resource Identifier) to initialize with. - */ - wxURI(const wxChar* uri); - /** - Copies this URI from another URI. - - @param uri - URI (Uniform Resource Identifier) to initialize with. - */ - wxURI(const wxURI& uri); - - /** - Builds the URI from its individual components and adds proper - separators. - - If the URI is not a reference or is not resolved, the URI that is - returned is the same one passed to the constructor or Create(). - */ - wxString BuildURI() const; - - /** - Builds the URI from its individual components, adds proper separators, - and returns escape sequences to normal characters. - - @note It is preferred to call this over Unescape(BuildURI()) since - BuildUnescapedURI() performs some optimizations over the plain - method. - */ - wxString BuildUnescapedURI() const; - - /** - Creates this URI from the @a uri string. - - Returns the position at which parsing stopped (there is no such thing - as an "invalid" wxURI). - - @param uri - String to initialize from. - */ - const wxChar* Create(const wxString uri); - - /** - Obtains the fragment of this URI. - - The fragment of a URI is the last value of the URI, and is the value - after a "#" character after the path of the URI. - - @c "http://mysite.com/mypath#" - */ - const wxString& GetFragment() const; - - /** - Obtains the host type of this URI, which is one of wxURIHostType. - */ - const wxURIHostType& GetHostType() const; - - /** - Returns the password part of the userinfo component of this URI. Note - that this is explicitly depreciated by RFC 1396 and should generally be - avoided if possible. - - @c "http://:@mysite.com/mypath" - */ - const wxString& GetPassword() const; - - /** - Returns the (normalized) path of the URI. - - The path component of a URI comes directly after the scheme component - if followed by zero or one slashes ('/'), or after the server/port - component. - - Absolute paths include the leading '/' character. - - @c "http://mysite.com" - */ - const wxString& GetPath() const; - - /** - Returns a string representation of the URI's port. - - The Port of a URI is a value after the server, and must come after a - colon (:). - - @c "http://mysite.com:" - - @note You can easily get the numeric value of the port by using - wxAtoi() or wxString::Format(). - */ - const wxString& GetPort() const; - - /** - Returns the Query component of the URI. - - The query component is what is commonly passed to a cgi application, - and must come after the path component, and after a '?' character. - - @c "http://mysite.com/mypath?" - */ - const wxString& GetQuery() const; - - /** - Returns the Scheme component of the URI. - - The first part of the URI. - - @c "://mysite.com" - */ - const wxString& GetScheme() const; - - /** - Returns the Server component of the URI. - - The server of the URI can be a server name or a type of IP address. See - GetHostType() for the possible values for the host type of the server - component. - - @c "http:///mypath" - */ - const wxString& GetServer() const; - - /** - Returns the username part of the userinfo component of this URI. Note - that this is explicitly depreciated by RFC 1396 and should generally be - avoided if possible. - - @c "http://:@mysite.com/mypath" - */ - const wxString& GetUser() const; - - /** - Returns the UserInfo component of the URI. - - The component of a URI before the server component that is postfixed by - a '@' character. - - @c "http://@mysite.com/mypath" - */ - const wxString& GetUserInfo() const; - - /** - Returns @true if the Fragment component of the URI exists. - */ - bool HasFragment() const; - - /** - Returns @true if the Path component of the URI exists. - */ - bool HasPath() const; - - /** - Returns @true if the Port component of the URI exists. - */ - bool HasPort() const; - - /** - Returns @true if the Query component of the URI exists. - */ - bool HasQuery() const; - - /** - Returns @true if the Scheme component of the URI exists. - */ - bool HasScheme() const; - - /** - Returns @true if the Server component of the URI exists. - */ - bool HasServer() const; - - /** - Returns @true if the User component of the URI exists. - */ - bool HasUser() const; - - /** - Returns @true if a valid [absolute] URI, otherwise this URI is a URI - reference and not a full URI, and this function returns @false. - */ - bool IsReference() const; - - /** - Inherits this URI from a base URI - components that do not exist in - this URI are copied from the base, and if this URI's path is not an - absolute path (prefixed by a '/'), then this URI's path is merged with - the base's path. - - For instance, resolving "../mydir" from "http://mysite.com/john/doe" - results in the scheme (http) and server ("mysite.com") being copied - into this URI, since they do not exist. In addition, since the path of - this URI is not absolute (does not begin with '/'), the path of the - base's is merged with this URI's path, resulting in the URI - "http://mysite.com/john/mydir". - - @param base - Base URI to inherit from. Must be a full URI and not a reference. - @param flags - Currently either wxURI_STRICT or 0, in non-strict mode some - compatibility layers are enabled to allow loopholes from RFCs prior - to 2396. - */ - void Resolve(const wxURI& base, int flags = wxURI_STRICT); - - /** - Translates all escape sequences (normal characters and returns the - result. - - If you want to unescape an entire wxURI, use BuildUnescapedURI() - instead, as it performs some optimizations over this method. - - @param uri - String with escaped characters to convert. - */ - wxString Unescape(const wxString& uri); - - /** - Compares this URI to another URI, and returns @true if this URI equals - @a uricomp, otherwise it returns @false. - - @param uricomp - URI to compare to. - */ - void operator ==(const wxURI& uricomp); -}; - diff --git a/interface/url.h b/interface/url.h deleted file mode 100644 index 3d7eea0c99..0000000000 --- a/interface/url.h +++ /dev/null @@ -1,130 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: url.h -// Purpose: interface of wxURL -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - Error types returned from wxURL::GetError(). -*/ -typedef enum { - wxURL_NOERR = 0, ///< No error. - wxURL_SNTXERR, ///< Syntax error in the URL string. - wxURL_NOPROTO, ///< Found no protocol which can get this URL. - wxURL_NOHOST, ///< A host name is required for this protocol. - wxURL_NOPATH, ///< A path is required for this protocol. - wxURL_CONNERR, ///< Connection error. - wxURL_PROTOERR ///< An error occurred during negotiation. -} wxURLError; - -/** - @class wxURL - @wxheader{url.h} - - wxURL is a specialization of wxURI for parsing URLs. Please look at wxURI - documentation for more info about the functions you can use to retrieve the - various parts of the URL (scheme, server, port, etc). - - Supports standard assignment operators, copy constructors, and comparison - operators. - - @library{wxnet} - @category{net} - - @see wxSocketBase, wxProtocol -*/ -class wxURL : public wxURI -{ -public: - /** - Constructs a URL object from the string. The URL must be valid - according to RFC 1738. In particular, file URLs must be of the format - @c "file://hostname/path/to/file", otherwise GetError() will return a - value different from ::wxURL_NOERR. - - It is valid to leave out the hostname but slashes must remain in place, - in other words, a file URL without a hostname must contain three - consecutive slashes (e.g. @c "file:///somepath/myfile"). - - @param url - Url string to parse. - */ - wxURL(const wxString& url = wxEmptyString); - - /** - Destroys the URL object. - */ - ~wxURL(); - - /** - Returns the last error. This error refers to the URL parsing or to the - protocol. It can be one of ::wxURLError. - */ - wxURLError GetError() const; - - /** - Creates a new input stream on the specified URL. You can use all but - seek functionality of wxStream. Seek isn't available on all streams. - For example, HTTP or FTP streams don't deal with it. - - Note that this method is somewhat deprecated, all future wxWidgets - applications should use wxFileSystem instead. - - Example: - - @code - wxURL url("http://a.host/a.dir/a.file"); - if (url.GetError() == wxURL_NOERR) - { - wxInputStream *in_stream; - - in_stream = url.GetInputStream(); - // Then, you can use all IO calls of in_stream (See wxStream) - } - @endcode - - @return Returns the initialized stream. You will have to delete it - yourself. - - @see wxInputStream - */ - wxInputStream* GetInputStream(); - - /** - Returns a reference to the protocol which will be used to get the URL. - */ - wxProtocol GetProtocol(); - - /** - Returns @true if this object is correctly initialized, i.e. if - GetError() returns ::wxURL_NOERR. - */ - bool IsOk() const; - - /** - Sets the default proxy server to use to get the URL. The string - specifies the proxy like this: @c ":". - - @param url_proxy - Specifies the proxy to use. - - @see SetProxy() - */ - static void SetDefaultProxy(const wxString& url_proxy); - - /** - Sets the proxy to use for this URL. - - @see SetDefaultProxy() - */ - void SetProxy(const wxString& url_proxy); - - /** - Initializes this object with the given URL and returns ::wxURL_NOERR if - it's valid (see GetError() for more info). - */ - wxURLError SetURL(const wxString& url); -}; - diff --git a/interface/utils.h b/interface/utils.h deleted file mode 100644 index 41ca90a8b4..0000000000 --- a/interface/utils.h +++ /dev/null @@ -1,1012 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: utils.h -// Purpose: interface of various utility classes and functions -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxWindowDisabler - @wxheader{utils.h} - - This class disables all windows of the application (may be with the - exception of one of them) in its constructor and enables them back in its - destructor. - - This is useful when you want to indicate to the user that the application - is currently busy and cannot respond to user input. - - @library{wxcore} - @category{misc} - - @see wxBusyCursor -*/ -class wxWindowDisabler -{ -public: - /** - Disables all top level windows of the applications. - - If @a disable is @c false nothing is done. This can be convenient if - the windows should be disabled depending on some condition. - - @since 2.9.0 - */ - wxWindowDisabler(bool disable = true); - - /** - Disables all top level windows of the applications with the exception - of @a winToSkip if it is not @NULL. - */ - wxWindowDisabler(wxWindow* winToSkip); - - /** - Reenables the windows disabled by the constructor. - */ - ~wxWindowDisabler(); -}; - - - -/** - @class wxBusyCursor - @wxheader{utils.h} - - This class makes it easy to tell your user that the program is temporarily - busy. Just create a wxBusyCursor object on the stack, and within the - current scope, the hourglass will be shown. - - For example: - - @code - wxBusyCursor wait; - - for (int i = 0; i < 100000; i++) - DoACalculation(); - @endcode - - It works by calling wxBeginBusyCursor() in the constructor, and - wxEndBusyCursor() in the destructor. - - @library{wxcore} - @category{misc} - - @see wxBeginBusyCursor(), wxEndBusyCursor(), wxWindowDisabler -*/ -class wxBusyCursor -{ -public: - /** - Constructs a busy cursor object, calling wxBeginBusyCursor(). - */ - wxBusyCursor(wxCursor* cursor = wxHOURGLASS_CURSOR); - - /** - Destroys the busy cursor object, calling wxEndBusyCursor(). - */ - ~wxBusyCursor(); -}; - - - -/** - @class wxMouseState - @wxheader{utils.h} - - Represents the mouse state. - - The methods of this class generally mirror the corresponding methods of - wxMouseEvent. - - This class is implemented entirely in @, meaning no extra - library needs to be linked to use this class. - - @category{misc} - - @see wxGetMouseState() - */ -class wxMouseState -{ -public: - /** - Default constructor. - */ - wxMouseState(); - - /** - Returns X coordinate of the physical mouse event position. - */ - wxCoord GetX() const; - /** - Returns Y coordinate of the physical mouse event position. - */ - wxCoord GetY() const; - /** - Returns the physical mouse position. - */ - wxPoint GetPosition() const; - - /** - Returns @true if the left mouse button changed to down. - */ - bool LeftDown() const; - /** - Returns @true if the middle mouse button changed to down. - */ - bool MiddleDown() const; - /** - Returns @true if the right mouse button changed to down. - */ - bool RightDown() const; - /** - Returns @true if the first extra button mouse button changed to down. - */ - bool Aux1Down() const; - /** - Returns @true if the second extra button mouse button changed to down. - */ - bool Aux2Down() const; - - /** - Returns @true if the control key is down. - */ - bool ControlDown() const; - /** - Returns @true if the shift key is down. - */ - bool ShiftDown() const; - /** - Returns @true if the alt key is down. - */ - bool AltDown() const; - /** - Returns @true if the meta key is down. - */ - bool MetaDown() const; - /** - Same as MetaDown() under Mac systems, ControlDown() for the others. - */ - bool CmdDown() const; -}; - - -// ============================================================================ -// Global functions/macros -// ============================================================================ - - -/** @ingroup group_funcmacro_dialog */ -//@{ - -/** - Changes the cursor to the given cursor for all windows in the application. - Use wxEndBusyCursor() to revert the cursor back to its previous state. - These two calls can be nested, and a counter ensures that only the outer - calls take effect. - - @see wxIsBusy(), wxBusyCursor - - @header{wx/utils.h} -*/ -void wxBeginBusyCursor(wxCursor* cursor = wxHOURGLASS_CURSOR); - -/** - Changes the cursor back to the original cursor, for all windows in the - application. Use with wxBeginBusyCursor(). - - @see wxIsBusy(), wxBusyCursor - - @header{wx/utils.h} -*/ -void wxEndBusyCursor(); - -/** - Returns @true if between two wxBeginBusyCursor() and wxEndBusyCursor() - calls. - - @see wxBusyCursor. - - @header{wx/utils.h} -*/ -bool wxIsBusy(); - -/** - Ring the system bell. - - @note This function is categorized as a GUI one and so is not thread-safe. - - @header{wx/utils.h} -*/ -void wxBell(); - -/** - Shows a message box with the information about the wxWidgets build used, - including its version, most important build parameters and the version of - the underlying GUI toolkit. This is mainly used for diagnostic purposes - and can be invoked by Ctrl-Alt-middle clicking on any wxWindow which - doesn't otherwise handle this event. - - @since 2.9.0 - - @header{wx/utils.h} -*/ -void wxInfoMessageBox(wxWindow parent = NULL); - -//@} - - - -/** @ingroup group_funcmacro_env */ -//@{ - -/** - This is a macro defined as @c getenv() or its wide char version in Unicode - mode. - - Note that under Win32 it may not return correct value for the variables set - with wxSetEnv(), use wxGetEnv() function instead. - - @header{wx/utils.h} -*/ -wxChar* wxGetenv(const wxString& var); - -/** - Returns the current value of the environment variable @c var in @c value. - @c value may be @NULL if you just want to know if the variable exists and - are not interested in its value. - - Returns @true if the variable exists, @false otherwise. - - @header{wx/utils.h} -*/ -bool wxGetEnv(const wxString& var, wxString* value); - -/** - Sets the value of the environment variable @c var (adding it if necessary) - to @c value. - - Returns @true on success. - - @see wxUnsetEnv() - - @header{wx/utils.h} -*/ -bool wxSetEnv(const wxString& var, const wxString& value); - -/** - Removes the variable @c var from the environment. wxGetEnv() will return - @NULL after the call to this function. - - Returns @true on success. - - @header{wx/utils.h} -*/ -bool wxUnsetEnv(const wxString& var); - -//@} - - - -/** @ingroup group_funcmacro_misc */ -//@{ - -/** - Returns battery state as one of @c wxBATTERY_NORMAL_STATE, - @c wxBATTERY_LOW_STATE, @c wxBATTERY_CRITICAL_STATE, - @c wxBATTERY_SHUTDOWN_STATE or @c wxBATTERY_UNKNOWN_STATE. - @c wxBATTERY_UNKNOWN_STATE is also the default on platforms where this - feature is not implemented (currently everywhere but MS Windows). - - @header{wx/utils.h} -*/ -wxBatteryState wxGetBatteryState(); - -/** - Returns the type of power source as one of @c wxPOWER_SOCKET, - @c wxPOWER_BATTERY or @c wxPOWER_UNKNOWN. @c wxPOWER_UNKNOWN is also the - default on platforms where this feature is not implemented (currently - everywhere but MS Windows). - - @header{wx/utils.h} -*/ -wxPowerType wxGetPowerType(); - -/** - Under X only, returns the current display name. - - @see wxSetDisplayName() - - @header{wx/utils.h} -*/ -wxString wxGetDisplayName(); - -/** - For normal keys, returns @true if the specified key is currently down. - - For togglable keys (Caps Lock, Num Lock and Scroll Lock), returns @true if - the key is toggled such that its LED indicator is lit. There is currently - no way to test whether togglable keys are up or down. - - Even though there are virtual key codes defined for mouse buttons, they - cannot be used with this function currently. - - @header{wx/utils.h} -*/ -bool wxGetKeyState(wxKeyCode key); - -/** - Returns the mouse position in screen coordinates. - - @header{wx/utils.h} -*/ -wxPoint wxGetMousePosition(); - -/** - Returns the current state of the mouse. Returns a wxMouseState instance - that contains the current position of the mouse pointer in screen - coordinates, as well as boolean values indicating the up/down status of the - mouse buttons and the modifier keys. - - @header{wx/utils.h} -*/ -wxMouseState wxGetMouseState(); - -/** - This function enables or disables all top level windows. It is used by - wxSafeYield(). - - @header{wx/utils.h} -*/ -void wxEnableTopLevelWindows(bool enable = true); - -/** - Find the deepest window at the given mouse position in screen coordinates, - returning the window if found, or @NULL if not. - - @header{wx/utils.h} -*/ -wxWindow* wxFindWindowAtPoint(const wxPoint& pt); - -/** - @deprecated Replaced by wxWindow::FindWindowByLabel(). - - Find a window by its label. Depending on the type of window, the label may - be a window title or panel item label. If @a parent is @NULL, the search - will start from all top-level frames and dialog boxes; if non-@NULL, the - search will be limited to the given window hierarchy. The search is - recursive in both cases. - - @header{wx/utils.h} -*/ -wxWindow* wxFindWindowByLabel(const wxString& label, - wxWindow* parent = NULL); - -/** - @deprecated Replaced by wxWindow::FindWindowByName(). - - Find a window by its name (as given in a window constructor or @e Create - function call). If @a parent is @NULL, the search will start from all - top-level frames and dialog boxes; if non-@NULL, the search will be limited - to the given window hierarchy. The search is recursive in both cases. - - If no such named window is found, wxFindWindowByLabel() is called. - - @header{wx/utils.h} -*/ -wxWindow* wxFindWindowByName(const wxString& name, wxWindow* parent = NULL); - -/** - Find a menu item identifier associated with the given frame's menu bar. - - @header{wx/utils.h} -*/ -int wxFindMenuItemId(wxFrame* frame, const wxString& menuString, - const wxString& itemString); - -/** - @deprecated Ids generated by it can conflict with the Ids defined by the - user code, use @c wxID_ANY to assign ids which are guaranteed - to not conflict with the user-defined ids for the controls and - menu items you create instead of using this function. - - Generates an integer identifier unique to this run of the program. - - @header{wx/utils.h} -*/ -long wxNewId(); - -/** - Ensures that Ids subsequently generated by wxNewId() do not clash with the - given @a id. - - @header{wx/utils.h} -*/ -void wxRegisterId(long id); - -/** - Opens the @a url in user's default browser. If the @a flags parameter - contains @c wxBROWSER_NEW_WINDOW flag, a new window is opened for the URL - (currently this is only supported under Windows). The @a url may also be a - local file path (with or without the "file://" prefix), if it doesn't - correspond to an existing file and the URL has no scheme "http://" is - prepended to it by default. - - Returns @true if the application was successfully launched. - - @note For some configurations of the running user, the application which is - launched to open the given URL may be URL-dependent (e.g. a browser - may be used for local URLs while another one may be used for remote - URLs). - - @header{wx/utils.h} -*/ -bool wxLaunchDefaultBrowser(const wxString& url, int flags = 0); - -/** - Loads a user-defined Windows resource as a string. If the resource is - found, the function creates a new character array and copies the data into - it. A pointer to this data is returned. If unsuccessful, @NULL is returned. - - The resource must be defined in the @c .rc file using the following syntax: - - @code - myResource TEXT file.ext - @endcode - - Where @c file.ext is a file that the resource compiler can find. - - This function is available under Windows only. - - @header{wx/utils.h} -*/ -wxString wxLoadUserResource(const wxString& resourceName, - const wxString& resourceType = "TEXT"); - -/** - @deprecated Replaced by wxWindow::Close(). See the - @ref overview_windowdeletion "window deletion overview". - - Tells the system to delete the specified object when all other events have - been processed. In some environments, it is necessary to use this instead - of deleting a frame directly with the delete operator, because some GUIs - will still send events to a deleted window. - - @header{wx/utils.h} -*/ -void wxPostDelete(wxObject* object); - -/** - Under X only, sets the current display name. This is the X host and display - name such as "colonsay:0.0", and the function indicates which display - should be used for creating windows from this point on. Setting the display - within an application allows multiple displays to be used. - - @see wxGetDisplayName() - - @header{wx/utils.h} -*/ -void wxSetDisplayName(const wxString& displayName); - -/** - Strips any menu codes from @a str and returns the result. - - By default, the functions strips both the mnemonics character (@c '&') - which is used to indicate a keyboard shortkey, and the accelerators, which - are used only in the menu items and are separated from the main text by the - @c \t (TAB) character. By using @a flags of @c wxStrip_Mnemonics or - @c wxStrip_Accel to strip only the former or the latter part, respectively. - - Notice that in most cases wxMenuItem::GetLabelFromText() or - wxControl::GetLabelText() can be used instead. - - @header{wx/utils.h} -*/ -wxString wxStripMenuCodes(const wxString& str, int flags = wxStrip_All); - -//@} - - - -/** @ingroup group_funcmacro_networkuseros */ -//@{ - -/** - Copies the user's email address into the supplied buffer, by concatenating - the values returned by wxGetFullHostName() and wxGetUserId(). - - @return @true if successful, @false otherwise. - - @header{wx/utils.h} -*/ -wxString wxGetEmailAddress(); - -/** - @deprecated Use wxGetEmailAddress() instead. - - @param buf Buffer to store the email address in. - @param sz Size of the buffer. - - @return @true if successful, @false otherwise. - - @header{wx/utils.h} -*/ -bool wxGetEmailAddress(char* buf, int sz); - -/** - Returns the amount of free memory in bytes under environments which support - it, and -1 if not supported or failed to perform measurement. - - @header{wx/utils.h} -*/ -wxMemorySize wxGetFreeMemory(); - -/** - Return the (current) user's home directory. - - @see wxGetUserHome(), wxStandardPaths - - @header{wx/utils.h} -*/ -wxString wxGetHomeDir(); - -/** - Copies the current host machine's name into the supplied buffer. Please - note that the returned name is @e not fully qualified, i.e. it does not - include the domain name. - - Under Windows or NT, this function first looks in the environment variable - SYSTEM_NAME; if this is not found, the entry @b HostName in the wxWidgets - section of the WIN.INI file is tried. - - @return The hostname if successful or an empty string otherwise. - - @see wxGetFullHostName() - - @header{wx/utils.h} -*/ -wxString wxGetHostName(); - -/** - @deprecated Use wxGetHostName() instead. - - @param buf Buffer to store the host name in. - @param sz Size of the buffer. - - @return @true if successful, @false otherwise. - - @header{wx/utils.h} -*/ -bool wxGetHostName(char* buf, int sz); - -/** - Returns the FQDN (fully qualified domain host name) or an empty string on - error. - - @see wxGetHostName() - - @header{wx/utils.h} -*/ -wxString wxGetFullHostName(); - -/** - Returns the home directory for the given user. If the @a user is empty - (default value), this function behaves like wxGetHomeDir() (i.e. returns - the current user home directory). - - If the home directory couldn't be determined, an empty string is returned. - - @header{wx/utils.h} -*/ -wxString wxGetUserHome(const wxString& user = ""); - -/** - This function returns the "user id" also known as "login name" under Unix - (i.e. something like "jsmith"). It uniquely identifies the current user (on - this system). Under Windows or NT, this function first looks in the - environment variables USER and LOGNAME; if neither of these is found, the - entry @b UserId in the @b wxWidgets section of the WIN.INI file is tried. - - @return The login name if successful or an empty string otherwise. - - @see wxGetUserName() - - @header{wx/utils.h} -*/ -wxString wxGetUserId(); - -/** - @deprecated Use wxGetUserId() instead. - - @param buf Buffer to store the login name in. - @param sz Size of the buffer. - - @return @true if successful, @false otherwise. - - @header{wx/utils.h} -*/ -bool wxGetUserId(char* buf, int sz); - -/** - This function returns the full user name (something like "Mr. John Smith"). - - Under Windows or NT, this function looks for the entry UserName in the - wxWidgets section of the WIN.INI file. If PenWindows is running, the entry - Current in the section User of the PENWIN.INI file is used. - - @return The full user name if successful or an empty string otherwise. - - @see wxGetUserId() - - @header{wx/utils.h} -*/ -wxString wxGetUserName(); - -/** - @deprecated Use wxGetUserName() instead. - - @param buf Buffer to store the full user name in. - @param sz Size of the buffer. - - @return @true if successful, @false otherwise. - - @header{wx/utils.h} -*/ -bool wxGetUserName(char* buf, int sz); - -/** - Returns the string containing the description of the current platform in a - user-readable form. For example, this function may return strings like - "Windows NT Version 4.0" or "Linux 2.2.2 i386". - - @see wxGetOsVersion() - - @header{wx/utils.h} -*/ -wxString wxGetOsDescription(); - -/** - Gets the version and the operating system ID for currently running OS. See - wxPlatformInfo for more details about wxOperatingSystemId. - - @see wxGetOsDescription(), wxPlatformInfo - - @header{wx/utils.h} -*/ -wxOperatingSystemId wxGetOsVersion(int* major = NULL, int* minor = NULL); - -/** - Returns @true if the operating system the program is running under is 64 - bit. The check is performed at run-time and may differ from the value - available at compile-time (at compile-time you can just check if - sizeof(void*) == 8) since the program could be running in - emulation mode or in a mixed 32/64 bit system (bi-architecture operating - system). - - @note This function is not 100% reliable on some systems given the fact - that there isn't always a standard way to do a reliable check on the - OS architecture. - - @header{wx/utils.h} -*/ -bool wxIsPlatform64Bit(); - -/** - Returns @true if the current platform is little endian (instead of big - endian). The check is performed at run-time. - - @see @ref group_funcmacro_byteorder "Byte Order Functions and Macros" - - @header{wx/utils.h} -*/ -bool wxIsPlatformLittleEndian(); - -//@} - - - -/** @ingroup group_funcmacro_procctrl */ -//@{ - -/** - Executes another program in Unix or Windows. - - In the overloaded versions of this function, if @a flags parameter contains - @c wxEXEC_ASYNC flag (the default), flow of control immediately returns. If - it contains @c wxEXEC_SYNC, the current application waits until the other - program has terminated. - - In the case of synchronous execution, the return value is the exit code of - the process (which terminates by the moment the function returns) and will - be -1 if the process couldn't be started and typically 0 if the process - terminated successfully. Also, while waiting for the process to terminate, - wxExecute() will call wxYield(). Because of this, by default this function - disables all application windows to avoid unexpected reentrancies which - could result from the users interaction with the program while the child - process is running. If you are sure that it is safe to not disable the - program windows, you may pass @c wxEXEC_NODISABLE flag to prevent this - automatic disabling from happening. - - For asynchronous execution, however, the return value is the process id and - zero value indicates that the command could not be executed. As an added - complication, the return value of -1 in this case indicates that we didn't - launch a new process, but connected to the running one (this can only - happen when using DDE under Windows for command execution). In particular, - in this case only, the calling code will not get the notification about - process termination. - - If @a callback isn't @NULL and if execution is asynchronous, - wxProcess::OnTerminate() will be called when the process finishes. - Specifying this parameter also allows you to redirect the standard input - and/or output of the process being launched by calling - wxProcess::Redirect(). If the child process IO is redirected, under Windows - the process window is not shown by default (this avoids having to flush an - unnecessary console for the processes which don't create any windows - anyhow) but a @c wxEXEC_NOHIDE flag can be used to prevent this from - happening, i.e. with this flag the child process window will be shown - normally. - - Under Unix the flag @c wxEXEC_MAKE_GROUP_LEADER may be used to ensure that - the new process is a group leader (this will create a new session if - needed). Calling wxKill() passing wxKILL_CHILDREN will kill this process as - well as all of its children (except those which have started their own - session). - - The @c wxEXEC_NOEVENTS flag prevents processing of any events from taking - place while the child process is running. It should be only used for very - short-lived processes as otherwise the application windows risk becoming - unresponsive from the users point of view. As this flag only makes sense - with @c wxEXEC_SYNC, @c wxEXEC_BLOCK equal to the sum of both of these - flags is provided as a convenience. - - @note Currently wxExecute() can only be used from the main thread, calling - this function from another thread will result in an assert failure in - debug build and won't work. - - @param command - The command to execute and any parameters to pass to it as a single - string, i.e. "emacs file.txt". - @param flags - Must include either wxEXEC_ASYNC or wxEXEC_SYNC and can also include - wxEXEC_NOHIDE, wxEXEC_MAKE_GROUP_LEADER (in either case) or - wxEXEC_NODISABLE and wxEXEC_NOEVENTS or wxEXEC_BLOCK, which is equal to - their combination, in wxEXEC_SYNC case. - @param callback - An optional pointer to wxProcess. - - @see wxShell(), wxProcess, @ref page_samples_exec - - @header{wx/utils.h} - - @beginWxPerlOnly - This function is called @c Wx::ExecuteStdoutStderr and it only takes the - @a command argument, and returns a 3-element list (@c status, @c output, - @c errors), where @c output and @c errors are array references. - @endWxPerlOnly -*/ -long wxExecute(const wxString& command, int flags = wxEXEC_ASYNC, - wxProcess* callback = NULL); - -//@} - -/** @ingroup group_funcmacro_procctrl */ -//@{ -/** - This is an overloaded version of wxExecute(const wxString&,int,wxProcess*), - please see its documentation for general information. - - This version takes an array of values: a command, any number of arguments, - terminated by @NULL. - - @param argv - The command to execute should be the first element of this array, any - additional ones are the command parameters and the array must be - terminated with a @NULL pointer. - @param flags - Must include either wxEXEC_ASYNC or wxEXEC_SYNC and can also include - wxEXEC_NOHIDE, wxEXEC_MAKE_GROUP_LEADER (in either case) or - wxEXEC_NODISABLE and wxEXEC_NOEVENTS or wxEXEC_BLOCK, which is equal to - their combination, in wxEXEC_SYNC case. - @param callback - An optional pointer to wxProcess. - - @header{wx/utils.h} -*/ -long wxExecute(char** argv, int flags = wxEXEC_ASYNC, - wxProcess* callback = NULL); -long wxExecute(wchar_t** argv, int flags = wxEXEC_ASYNC, - wxProcess* callback = NULL); -//@} - -/** @ingroup group_funcmacro_procctrl */ -//@{ - -/** - This is an overloaded version of wxExecute(const wxString&,int,wxProcess*), - please see its documentation for general information. - - This version can be used to execute a process (always synchronously, the - contents of @a flags is or'd with @c wxEXEC_SYNC) and capture its output in - the array @e output. - - @param command - The command to execute and any parameters to pass to it as a single - string. - @param flags - Must include either wxEXEC_ASYNC or wxEXEC_SYNC and can also include - wxEXEC_NOHIDE, wxEXEC_MAKE_GROUP_LEADER (in either case) or - wxEXEC_NODISABLE and wxEXEC_NOEVENTS or wxEXEC_BLOCK, which is equal to - their combination, in wxEXEC_SYNC case. - - @header{wx/utils.h} -*/ -long wxExecute(const wxString& command, wxArrayString& output, - int flags = 0); - -/** - This is an overloaded version of wxExecute(const wxString&,int,wxProcess*), - please see its documentation for general information. - - This version adds the possibility to additionally capture the messages from - standard error output in the @a errors array. - - @param command - The command to execute and any parameters to pass to it as a single - string. - @param flags - Must include either wxEXEC_ASYNC or wxEXEC_SYNC and can also include - wxEXEC_NOHIDE, wxEXEC_MAKE_GROUP_LEADER (in either case) or - wxEXEC_NODISABLE and wxEXEC_NOEVENTS or wxEXEC_BLOCK, which is equal to - their combination, in wxEXEC_SYNC case. - - @header{wx/utils.h} -*/ -long wxExecute(const wxString& command, wxArrayString& output, - wxArrayString& errors, int flags = 0); - -/** - Returns the number uniquely identifying the current process in the system. - If an error occurs, 0 is returned. - - @header{wx/utils.h} -*/ -unsigned long wxGetProcessId(); - -/** - Equivalent to the Unix kill function: send the given signal @a sig to the - process with PID @a pid. The valid signal values are: - - @code - enum wxSignal - { - wxSIGNONE = 0, // verify if the process exists under Unix - wxSIGHUP, - wxSIGINT, - wxSIGQUIT, - wxSIGILL, - wxSIGTRAP, - wxSIGABRT, - wxSIGEMT, - wxSIGFPE, - wxSIGKILL, // forcefully kill, dangerous! - wxSIGBUS, - wxSIGSEGV, - wxSIGSYS, - wxSIGPIPE, - wxSIGALRM, - wxSIGTERM // terminate the process gently - }; - @endcode - - @c wxSIGNONE, @c wxSIGKILL and @c wxSIGTERM have the same meaning under - both Unix and Windows but all the other signals are equivalent to - @c wxSIGTERM under Windows. - - Returns 0 on success, -1 on failure. If the @a rc parameter is not @NULL, - it will be filled with a value of the the @c wxKillError enum: - - @code - enum wxKillError - { - wxKILL_OK, // no error - wxKILL_BAD_SIGNAL, // no such signal - wxKILL_ACCESS_DENIED, // permission denied - wxKILL_NO_PROCESS, // no such process - wxKILL_ERROR // another, unspecified error - }; - @endcode - - The @a flags parameter can be wxKILL_NOCHILDREN (the default), or - wxKILL_CHILDREN, in which case the child processes of this process will be - killed too. Note that under Unix, for wxKILL_CHILDREN to work you should - have created the process by passing wxEXEC_MAKE_GROUP_LEADER to - wxExecute(). - - @see wxProcess::Kill(), wxProcess::Exists(), @ref page_samples_exec - - @header{wx/utils.h} -*/ -int wxKill(long pid, int sig = wxSIGTERM, - wxKillError rc = NULL, int flags = 0); - -/** - Executes a command in an interactive shell window. If no command is - specified, then just the shell is spawned. - - @see wxExecute(), @ref page_samples_exec - - @header{wx/utils.h} -*/ -bool wxShell(const wxString& command = NULL); - -/** - This function shuts down or reboots the computer depending on the value of - the @a flags. - - @note Doing this requires the corresponding access rights (superuser under - Unix, SE_SHUTDOWN privilege under Windows NT) and that this function - is only implemented under Unix and Win32. - - @param flags - Either wxSHUTDOWN_POWEROFF or wxSHUTDOWN_REBOOT - - @return @true on success, @false if an error occurred. - - @header{wx/utils.h} -*/ -bool wxShutdown(wxShutdownFlags flags); - -//@} - - - -/** @ingroup group_funcmacro_time */ -//@{ - -/** - Sleeps for the specified number of microseconds. The microsecond resolution - may not, in fact, be available on all platforms (currently only Unix - platforms with nanosleep(2) may provide it) in which case this is the same - as calling wxMilliSleep() with the argument of @e microseconds/1000. - - @header{wx/utils.h} -*/ -void wxMicroSleep(unsigned long microseconds); - -/** - Sleeps for the specified number of milliseconds. Notice that usage of this - function is encouraged instead of calling usleep(3) directly because the - standard @e usleep() function is not MT safe. - - @header{wx/utils.h} -*/ -void wxMilliSleep(unsigned long milliseconds); - -/** - Returns a string representing the current date and time. - - @header{wx/utils.h} -*/ -wxString wxNow(); - -/** - Sleeps for the specified number of seconds. - - @header{wx/utils.h} -*/ -void wxSleep(int secs); - -/** - @deprecated This function is deprecated because its name is misleading: - notice that the argument is in milliseconds, not microseconds. - Please use either wxMilliSleep() or wxMicroSleep() depending on - the resolution you need. - - Sleeps for the specified number of milliseconds. - - @header{wx/utils.h} -*/ -void wxUsleep(unsigned long milliseconds); - -//@} - diff --git a/interface/valgen.h b/interface/valgen.h deleted file mode 100644 index 00ebc56fd4..0000000000 --- a/interface/valgen.h +++ /dev/null @@ -1,116 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: valgen.h -// Purpose: interface of wxGenericValidator -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxGenericValidator - @wxheader{valgen.h} - - wxGenericValidator performs data transfer (but not validation or filtering) - for the following basic controls: wxButton, wxCheckBox, wxListBox, - wxStaticText, wxRadioButton, wxRadioBox, wxChoice, wxComboBox, wxGauge, - wxSlider, wxScrollBar, wxSpinButton, wxTextCtrl, wxCheckListBox. - - It checks the type of the window and uses an appropriate type for that - window. For example, wxButton and wxTextCtrl transfer data to and from a - wxString variable; wxListBox uses a wxArrayInt; wxCheckBox uses a bool. - - For more information, please see @ref overview_validator. - - @library{wxcore} - @category{validator} - - @see @ref overview_validator, wxValidator, wxTextValidator -*/ -class wxGenericValidator : public wxValidator -{ -public: - /** - Copy constructor. - - @param validator - Validator to copy. - */ - wxGenericValidator(const wxGenericValidator& validator); - /** - Constructor taking a bool pointer. This will be used for wxCheckBox, - wxRadioButton, wxToggleButton and wxBitmapToggleButton. - - @param valPtr - A pointer to a variable that contains the value. This variable - should have a lifetime equal to or longer than the validator - lifetime (which is usually determined by the lifetime of the - window). - */ - wxGenericValidator(bool* valPtr); - /** - Constructor taking a wxString pointer. This will be used for wxButton, - wxComboBox, wxStaticText, wxTextCtrl. - - @param valPtr - A pointer to a variable that contains the value. This variable - should have a lifetime equal to or longer than the validator - lifetime (which is usually determined by the lifetime of the - window). - */ - wxGenericValidator(wxString* valPtr); - /** - Constructor taking an integer pointer. This will be used for wxChoice, - wxGauge, wxScrollBar, wxRadioBox, wxSlider, wxSpinButton and - wxSpinCtrl. - - @param valPtr - A pointer to a variable that contains the value. This variable - should have a lifetime equal to or longer than the validator - lifetime (which is usually determined by the lifetime of the - window). - */ - wxGenericValidator(int* valPtr); - /** - Constructor taking a wxArrayInt pointer. This will be used for - wxListBox, wxCheckListBox. - - @param valPtr - A pointer to a variable that contains the value. This variable - should have a lifetime equal to or longer than the validator - lifetime (which is usually determined by the lifetime of the - window). - */ - wxGenericValidator(wxArrayInt* valPtr); - /** - Constructor taking a wxDateTime pointer. This will be used for - wxDatePickerCtrl. - - @param valPtr - A pointer to a variable that contains the value. This variable - should have a lifetime equal to or longer than the validator - lifetime (which is usually determined by the lifetime of the - window). - */ - wxGenericValidator(wxDateTime* valPtr); - - /** - Destructor. - */ - ~wxGenericValidator(); - - /** - Clones the generic validator using the copy constructor. - */ - virtual wxValidator* Clone() const; - - /** - Transfers the value from the window to the appropriate data type. - */ - virtual bool TransferFromWindow(); - - /** - Transfers the value to the window. - */ - virtual bool TransferToWindow(); -}; - diff --git a/interface/validate.h b/interface/validate.h deleted file mode 100644 index 76f4abd835..0000000000 --- a/interface/validate.h +++ /dev/null @@ -1,116 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: validate.h -// Purpose: interface of wxValidator -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxValidator - @wxheader{validate.h} - - wxValidator is the base class for a family of validator classes that - mediate between a class of control, and application data. - - A validator has three major roles: - - -# To transfer data from a C++ variable or own storage to and from a - control. - -# To validate data in a control, and show an appropriate error message. - -# To filter events (such as keystrokes), thereby changing the behaviour - of the associated control. - - Validators can be plugged into controls dynamically. - - To specify a default, "null" validator, use ::wxDefaultValidator. - - For more information, please see @ref overview_validator. - - @beginWxPythonOnly - If you wish to create a validator class in wxPython you should derive the - class from @c wxPyValidator in order to get Python-aware capabilities for - the various virtual methods. - @endWxPythonOnly - - @library{wxcore} - @category{validator} - - @stdobjects - ::wxDefaultValidator - - @see @ref overview_validator, wxTextValidator, wxGenericValidator -*/ -class wxValidator : public wxEvtHandler -{ -public: - /** - Constructor. - */ - wxValidator(); - - /** - Destructor. - */ - ~wxValidator(); - - /** - All validator classes must implement the Clone() function, which - returns an identical copy of itself. - - This is because validators are passed to control constructors as - references which must be copied. Unlike objects such as pens and - brushes, it does not make sense to have a reference counting scheme to - do this cloning because all validators should have separate data. - - @return This base function returns @NULL. - */ - virtual wxObject* Clone() const; - - /** - Returns the window associated with the validator. - */ - wxWindow* GetWindow() const; - - /** - This functions switches on or turns off the error sound produced by the - validators if an invalid key is pressed. - */ - void SetBellOnError(bool doIt = true); - - /** - Associates a window with the validator. - */ - void SetWindow(wxWindow* window); - - /** - This overridable function is called when the value in the window must - be transferred to the validator. - - @return @false if there is a problem. - */ - virtual bool TransferFromWindow(); - - /** - This overridable function is called when the value associated with the - validator must be transferred to the window. - - @return @false if there is a problem. - */ - virtual bool TransferToWindow(); - - /** - This overridable function is called when the value in the associated - window must be validated. - - @return @false if the value in the window is not valid; you may pop up - an error dialog. - */ - virtual bool Validate(wxWindow* parent); -}; - -/** - An empty, "null" wxValidator instance. -*/ -wxValidator wxDefaultValidator; - diff --git a/interface/valtext.h b/interface/valtext.h deleted file mode 100644 index 27e9ba0c76..0000000000 --- a/interface/valtext.h +++ /dev/null @@ -1,127 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: valtext.h -// Purpose: interface of wxTextValidator -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxTextValidator - @wxheader{valtext.h} - - wxTextValidator validates text controls, providing a variety of filtering - behaviours. - - For more information, please see @ref overview_validator. - - @beginStyleTable - @style{wxFILTER_NONE} - No filtering takes place. - @style{wxFILTER_ASCII} - Non-ASCII characters are filtered out. - @style{wxFILTER_ALPHA} - Non-alpha characters are filtered out. - @style{wxFILTER_ALPHANUMERIC} - Non-alphanumeric characters are filtered out. - @style{wxFILTER_NUMERIC} - Non-numeric characters are filtered out. - @style{wxFILTER_INCLUDE_LIST} - Use an include list. The validator checks if the user input is on - the list, complaining if not. See SetIncludes(). - @style{wxFILTER_EXCLUDE_LIST} - Use an exclude list. The validator checks if the user input is on - the list, complaining if it is. See SetExcludes(). - @style{wxFILTER_INCLUDE_CHAR_LIST} - Use an include list. The validator checks if each input character is - in the list (one character per list element), complaining if not. - See SetIncludes(). - @style{wxFILTER_EXCLUDE_CHAR_LIST} - Use an include list. The validator checks if each input character is - in the list (one character per list element), complaining if it is. - See SetExcludes(). - @endStyleTable - - @library{wxcore} - @category{validator} - - @see @ref overview_validator, wxValidator, wxGenericValidator -*/ -class wxTextValidator : public wxValidator -{ -public: - /** - Default constructor. - */ - wxTextValidator(const wxTextValidator& validator); - /** - Constructor taking a style and optional pointer to a wxString variable. - - @param style - A bitlist of flags documented in the class description. - @param valPtr - A pointer to a wxString variable that contains the value. This - variable should have a lifetime equal to or longer than the - validator lifetime (which is usually determined by the lifetime of - the window). - */ - wxTextValidator(long style = wxFILTER_NONE, wxString* valPtr = NULL); - - /** - Clones the text validator using the copy constructor. - */ - virtual wxValidator* Clone() const; - - /** - Returns a reference to the exclude list (the list of invalid values). - */ - wxArrayString& GetExcludes() const; - - /** - Returns a reference to the include list (the list of valid values). - */ - wxArrayString& GetIncludes() const; - - /** - Returns the validator style. - */ - long GetStyle() const; - - /** - Receives character input from the window and filters it according to - the current validator style. - */ - void OnChar(wxKeyEvent& event); - - /** - Sets the exclude list (invalid values for the user input). - */ - void SetExcludes(const wxArrayString& stringList); - - /** - Sets the include list (valid values for the user input). - */ - void SetIncludes(const wxArrayString& stringList); - - /** - Sets the validator style. - */ - void SetStyle(long style); - - /** - Transfers the value in the text control to the string. - */ - virtual bool TransferFromWindow(); - - /** - Transfers the string value to the text control. - */ - virtual bool TransferToWindow(); - - /** - Validates the window contents against the include or exclude lists, - depending on the validator style. - */ - virtual bool Validate(wxWindow* parent); -}; - diff --git a/interface/variant.h b/interface/variant.h deleted file mode 100644 index e276cce933..0000000000 --- a/interface/variant.h +++ /dev/null @@ -1,578 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: variant.h -// Purpose: interface of wxVariant -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxVariant - @wxheader{variant.h} - - The wxVariant class represents a container for any type. A variant's value - can be changed at run time, possibly to a different type of value. - - As standard, wxVariant can store values of type bool, wxChar, double, long, - string, string list, time, date, void pointer, list of strings, and list of - variants. However, an application can extend wxVariant's capabilities by - deriving from the class wxVariantData and using the wxVariantData form of - the wxVariant constructor or assignment operator to assign this data to a - variant. Actual values for user-defined types will need to be accessed via - the wxVariantData object, unlike the case for basic data types where - convenience functions such as GetLong() can be used. - - Pointers to any wxObject derived class can also easily be stored in a - wxVariant. wxVariant will then use wxWidgets' built-in RTTI system to set - the type name (returned by GetType()) and to perform type-safety checks at - runtime. - - This class is useful for reducing the programming for certain tasks, such - as an editor for different data types, or a remote procedure call protocol. - - An optional name member is associated with a wxVariant. This might be used, - for example, in CORBA or OLE automation classes, where named parameters are - required. - - Note that as of wxWidgets 2.7.1, wxVariant is - @ref overview_refcount "reference counted". Additionally, the convenience - macros DECLARE_VARIANT_OBJECT() and IMPLEMENT_VARIANT_OBJECT() were added - so that adding (limited) support for conversion to and from wxVariant can - be very easily implemented without modifying either wxVariant or the class - to be stored by wxVariant. Since assignment operators cannot be declared - outside the class, the shift left operators are used like this: - - @code - // in the header file - DECLARE_VARIANT_OBJECT(MyClass) - - // in the implementation file - IMPLEMENT_VARIANT_OBJECT(MyClass) - - // in the user code - wxVariant variant; - MyClass value; - variant << value; - - // or - value << variant; - @endcode - - For this to work, MyClass must derive from wxObject, implement the - @ref overview_rtti "wxWidgets RTTI system" and support the assignment - operator and equality operator for itself. Ideally, it should also be - reference counted to make copying operations cheap and fast. This can be - most easily implemented using the reference counting support offered by - wxObject itself. By default, wxWidgets already implements the shift - operator conversion for a few of its drawing related classes: - - @code - IMPLEMENT_VARIANT_OBJECT(wxColour) - IMPLEMENT_VARIANT_OBJECT(wxImage) - IMPLEMENT_VARIANT_OBJECT(wxIcon) - IMPLEMENT_VARIANT_OBJECT(wxBitmap) - @endcode - - Note that as of wxWidgets 2.9.0, wxVariantData no longer inherits from - wxObject and wxVariant no longer uses the type-unsafe wxList class for list - operations but the type-safe wxVariantList class. Also, wxVariantData now - supports the wxVariantData::Clone() function for implementing the Unshare() - function. wxVariantData::Clone() is implemented automatically by - IMPLEMENT_VARIANT_OBJECT(). - - Since wxVariantData no longer derives from wxObject, any code that tests - the type of the data using wxDynamicCast() will require adjustment. You can - use the macro wxDynamicCastVariantData() with the same arguments as - wxDynamicCast(), to use C++ RTTI type information instead of wxWidgets - RTTI. - - @library{wxbase} - @category{data} - - @see wxVariantData -*/ -class wxVariant : public wxObject -{ -public: - /** - Default constructor. - */ - wxVariant(); - - /** - Constructs a variant directly with a wxVariantData object. wxVariant - will take ownership of the wxVariantData and will not increase its - reference count. - */ - wxVariant(wxVariantData* data, const wxString& name = ""); - - /** - Constructs a variant from another variant by increasing the reference - count. - */ - wxVariant(const wxVariant& variant); - - /** - Constructs a variant from a wide string literal. - */ - wxVariant(const wxChar* value, const wxString& name = ""); - - /** - Constructs a variant from a string. - */ - wxVariant(const wxString& value, const wxString& name = ""); - - /** - Constructs a variant from a wide char. - */ - wxVariant(wxChar value, const wxString& name = ""); - - /** - Constructs a variant from a long. - */ - wxVariant(long value, const wxString& name = ""); - - /** - Constructs a variant from a bool. - */ - wxVariant(bool value, const wxString& name = ""); - - /** - Constructs a variant from a double. - */ - wxVariant(double value, const wxString& name = ""); - - /** - Constructs a variant from a list of variants - */ - wxVariant(const wxVariantList& value, const wxString& name = ""); - - /** - Constructs a variant from a void pointer. - */ - wxVariant(void* value, const wxString& name = ""); - - /** - Constructs a variant from a pointer to an wxObject - derived class. - */ - wxVariant(wxObject* value, const wxString& name = ""); - - /** - Constructs a variant from a wxDateTime. - */ - wxVariant(wxDateTime& val, const wxString& name = ""); - - /** - Constructs a variant from a wxArrayString. - */ - wxVariant(wxArrayString& val, const wxString& name = ""); - - /** - Destructor. - - @note wxVariantData's destructor is protected, so wxVariantData cannot - usually be deleted. Instead, wxVariantData::DecRef() should be - called. See @ref overview_refcount_destruct - "reference-counted object destruction" for more info. - */ - ~wxVariant(); - - - /** - @name List Functionality - */ - //@{ - - /** - Returns the value at @a idx (zero-based). - */ - wxVariant operator [](size_t idx) const; - /** - Returns a reference to the value at @a idx (zero-based). This can be - used to change the value at this index. - */ - wxVariant& operator [](size_t idx); - - /** - Appends a value to the list. - */ - void Append(const wxVariant& value); - - /** - Makes the variant null by deleting the internal data and set the name - to wxEmptyString. - */ - void Clear(); - - /** - Deletes the contents of the list. - */ - void ClearList(); - - /** - Deletes the zero-based @a item from the list. - */ - bool Delete(size_t item); - - /** - Returns the number of elements in the list. - */ - size_t GetCount() const; - - /** - Returns a reference to the wxVariantList class used by wxVariant if - this wxVariant is currently a list of variants. - */ - wxVariantList& GetList() const; - - /** - Inserts a value at the front of the list. - */ - void Insert(const wxVariant& value); - - /** - Makes an empty list. This differs from a null variant which has no - data; a null list is of type list, but the number of elements in the - list is zero. - */ - void NullList(); - - //@} - - - //@{ - /** - Retrieves and converts the value of this variant to the type that - @a value is. - */ - bool Convert(long* value) const; - bool Convert(bool* value) const; - bool Convert(double* value) const; - bool Convert(wxString* value) const; - bool Convert(wxChar* value) const; - bool Convert(wxDateTime* value) const; - //@} - - /** - Returns the string array value. - */ - wxArrayString GetArrayString() const; - - /** - Returns the boolean value. - */ - bool GetBool() const; - - /** - Returns the character value. - */ - wxChar GetChar() const; - - /** - Returns a pointer to the internal variant data. To take ownership of - this data, you must call its wxVariantData::IncRef() method. When you - stop using it, wxVariantData::DecRef() must be called as well. - */ - wxVariantData* GetData() const; - - /** - Returns the date value. - */ - wxDateTime GetDateTime() const; - - /** - Returns the floating point value. - */ - double GetDouble() const; - - /** - Returns the integer value. - */ - long GetLong() const; - - /** - Returns a constant reference to the variant name. - */ - const wxString GetName() const; - - /** - Gets the string value. - */ - wxString GetString() const; - - /** - Returns the value type as a string. - - The built-in types are: - - "bool" - - "char" - - "datetime" - - "double" - - "list" - - "long" - - "string" - - "arrstring" - - "void*" - - If the variant is null, the value type returned is the string "null" - (not the empty string). - */ - wxString GetType() const; - - /** - Gets the void pointer value. - */ - void* GetVoidPtr() const; - - /** - Gets the wxObject pointer value. - */ - wxObject* GetWxObjectPtr() const; - - /** - Returns @true if there is no data associated with this variant, @false - if there is data. - */ - bool IsNull() const; - - /** - Returns @true if @a type matches the type of the variant, @false - otherwise. - */ - bool IsType(const wxString& type) const; - - /** - Returns @true if the data is derived from the class described by - @a type, @false otherwise. - */ - bool IsValueKindOf(const wxClassInfo* type) const; - - /** - Makes the variant null by deleting the internal data. - */ - void MakeNull(); - - /** - Makes a string representation of the variant value (for any type). - */ - wxString MakeString() const; - - /** - Returns @true if @a value matches an element in the list. - */ - bool Member(const wxVariant& value) const; - - /** - Sets the internal variant data, deleting the existing data if there is - any. - */ - void SetData(wxVariantData* data); - - /** - Makes sure that any data associated with this variant is not shared - with other variants. For this to work, wxVariantData::Clone() must be - implemented for the data types you are working with. - wxVariantData::Clone() is implemented for all the default data types. - */ - bool Unshare(); - - //@{ - /** - Inequality test operator. - */ - bool operator !=(const wxVariant& value) const; - bool operator !=(const wxString& value) const; - bool operator !=(const wxChar* value) const; - bool operator !=(wxChar value) const; - bool operator !=(const long value) const; - bool operator !=(const bool value) const; - bool operator !=(const double value) const; - bool operator !=(void* value) const; - bool operator !=(wxObject* value) const; - bool operator !=(const wxVariantList& value) const; - bool operator !=(const wxArrayString& value) const; - bool operator !=(const wxDateTime& value) const; - //@} - - //@{ - /** - Assignment operator, using @ref overview_refcount "reference counting" - if possible. - */ - void operator =(const wxVariant& value); - void operator =(wxVariantData* value); - void operator =(const wxString& value); - void operator =(const wxChar* value); - void operator =(wxChar value); - void operator =(const long value); - void operator =(const bool value); - void operator =(const double value); - void operator =(void* value); - void operator =(wxObject* value); - void operator =(const wxVariantList& value); - void operator =(const wxDateTime& value); - void operator =(const wxArrayString& value); - //@} - - //@{ - /** - Equality test operator. - */ - bool operator ==(const wxVariant& value) const; - bool operator ==(const wxString& value) const; - bool operator ==(const wxChar* value) const; - bool operator ==(wxChar value) const; - bool operator ==(const long value) const; - bool operator ==(const bool value) const; - bool operator ==(const double value) const; - bool operator ==(void* value) const; - bool operator ==(wxObject* value) const; - bool operator ==(const wxVariantList& value) const; - bool operator ==(const wxArrayString& value) const; - bool operator ==(const wxDateTime& value) const; - //@} - - //@{ - /** - Operator for implicit conversion to a long, using GetLong(). - */ - double operator double() const; - long operator long() const; - //@} - - /** - Operator for implicit conversion to a pointer to a void, using - GetVoidPtr(). - */ - void* operator void*() const; - - /** - Operator for implicit conversion to a wxChar, using GetChar(). - */ - char operator wxChar() const; - - /** - Operator for implicit conversion to a pointer to a wxDateTime, using - GetDateTime(). - */ - void* operator wxDateTime() const; - - /** - Operator for implicit conversion to a string, using MakeString(). - */ - wxString operator wxString() const; -}; - - - -/** - @class wxVariantData - @wxheader{variant.h} - - The wxVariantData class is used to implement a new type for wxVariant. - Derive from wxVariantData, and override the pure virtual functions. - - wxVariantData is @ref overview_refcount "reference counted", but you don't - normally have to care about this, as wxVariant manages the count - automatically. However, in case your application needs to take ownership of - wxVariantData, be aware that the object is created with a reference count - of 1, and passing it to wxVariant will not increase this. In other words, - IncRef() needs to be called only if you both take ownership of - wxVariantData and pass it to a wxVariant. Also note that the destructor is - protected, so you can never explicitly delete a wxVariantData instance. - Instead, DecRef() will delete the object automatically when the reference - count reaches zero. - - @library{wxbase} - @category{data} - - @see wxVariant, wxGetVariantCast() -*/ -class wxVariantData -{ -public: - /** - Default constructor. - */ - wxVariantData(); - - /** - This function can be overridden to clone the data. You must implement - this function in order for wxVariant::Unshare() to work for your data. - This function is implemented for all built-in data types. - */ - wxVariantData* Clone() const; - - /** - Decreases reference count. If the count reaches zero, the object is - automatically deleted. - - @note The destructor of wxVariantData is protected, so delete cannot be - used as normal. Instead, DecRef() should be called. - */ - void DecRef(); - - /** - Returns @true if this object is equal to @a data. - */ - bool Eq(wxVariantData& data) const; - - /** - Returns the string type of the data. - */ - wxString GetType() const; - - /** - If the data is a wxObject returns a pointer to the objects wxClassInfo - structure, if the data isn't a wxObject the method returns @NULL. - */ - wxClassInfo* GetValueClassInfo() const; - - /** - Increases reference count. Note that initially wxVariantData has - reference count of 1. - */ - void IncRef(); - - /** - Reads the data from @a stream. - */ - bool Read(ostream& stream); - /** - Reads the data from @a string. - */ - bool Read(wxString& string); - - /** - Writes the data to @a stream. - */ - bool Write(ostream& stream) const; - /** - Writes the data to @a string. - */ - bool Write(wxString& string) const; -}; - - - -// ============================================================================ -// Global functions/macros -// ============================================================================ - -/** @ingroup group_funcmacro_rtti */ -//@{ - -/** - This macro returns a pointer to the data stored in @a var (wxVariant) cast - to the type @a classname if the data is of this type (the check is done - during the run-time) or @NULL otherwise. - - @header{wx/variant.h} - - @see @ref overview_rtti, wxDynamicCast() -*/ -#define wxGetVariantCast(var, classname) - -//@} - diff --git a/interface/vector.h b/interface/vector.h deleted file mode 100644 index 65e39a4a1d..0000000000 --- a/interface/vector.h +++ /dev/null @@ -1,177 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: vector.h -// Purpose: interface of wxVector -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @wxheader{vector.h} - - wxVector is a template class which implements most of the @c std::vector - class and can be used like it. - - If wxWidgets is compiled in STL mode, wxVector will just be a typedef to - @c std::vector. Just like for @c std::vector, objects stored in wxVector - need to be @e assignable but don't have to be @e "default constructible". - - Please refer to the STL documentation for further information. - - @nolibrary - @category{containers} - - @see @ref overview_container, wxList, wxArray -*/ -template -class wxVector -{ -public: - typedef size_t size_type; - typedef T value_type; - typedef value_type* iterator; - typedef const value_type* const_iterator; - typedef value_type& reference; - - /** - Constructor. - */ - wxVector(); - - /** - Copy onstructor. - */ - wxVector(const wxVector& c); - - /** - Destructor. - */ - ~wxVector(); - - /** - Returns item at position @a idx. - */ - const value_type& at(size_type idx) const; - - /** - Returns item at position @a idx. - */ - value_type& at(size_type idx); - - /** - Return the last item. - */ - const value_type& back() const; - - /** - Return the last item. - */ - value_type& back(); - - /** - Return iterator to beginning of the vector. - */ - const_iterator begin() const; - - /** - Return iterator to beginning of the vector. - */ - iterator begin(); - - /** - Returns vector's current capacity, i.e. how much memory is allocated. - - @see reserve() - */ - size_type capacity() const; - - /** - Clears the vector. - */ - void clear(); - - /** - Returns @true if the vector is empty. - */ - bool empty() const; - - /** - Returns iterator to the end of the vector. - */ - const_iterator end() const; - - /** - Returns iterator to the end of the vector. - */ - iterator end(); - - /** - Erase item pointed to by iterator @a it. - - @return Iterator pointing to the item immediately after the erased one. - */ - iterator erase(iterator it); - - /** - Erase items in the range @a first to @a last (@a last is not erased). - - @return Iterator pointing to the item immediately after the erased - range. - */ - iterator erase(iterator first, iterator last); - - /** - Returns the first item. - */ - const value_type& front() const; - - /** - Returns the first item. - */ - value_type& front(); - - /** - Insert item @a v at given position @a it. - - @return Iterator for the inserted item. - */ - iterator insert(iterator it, const value_type& v = value_type()); - - /** - Assignment operator. - */ - wxVector& operator=(const wxVector& vb); - - /** - Returns item at position @a idx. - */ - const value_type& operator[](size_type idx) const; - - /** - Returns item at position @a idx. - */ - value_type& operator[](size_type idx); - - /** - Removes the last item. - */ - void pop_back(); - - /** - Adds an item to the end of the vector. - */ - void push_back(const value_type& v); - - /** - Reserves memory for at least @a n items. - - @see capacity() - */ - void reserve(size_type n); - - /** - Returns the size of the vector. - */ - size_type size() const; -}; - diff --git a/interface/version.h b/interface/version.h deleted file mode 100644 index d3a15946d3..0000000000 --- a/interface/version.h +++ /dev/null @@ -1,44 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: version.h -// Purpose: wxWidgets version numbers -// Author: wxWidgets team -// RCS-ID: $Id: numdlg.h 52425 2008-03-10 15:24:38Z FM $ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** @ingroup group_funcmacro_version */ -//@{ - -/** - This is a macro which evaluates to @true if the current wxWidgets version - is at least major.minor.release. - - For example, to test if the program is compiled with wxWidgets 2.2 or - higher, the following can be done: - - @code - wxString s; - #if wxCHECK_VERSION(2, 2, 0) - if ( s.StartsWith("foo") ) - #else // replacement code for old version - if ( strncmp(s, "foo", 3) == 0 ) - #endif - { - ... - } - @endcode - - @header{wx/version.h} -*/ -#define wxCHECK_VERSION( major, minor, release ) - -/** - Same as wxCHECK_VERSION() but also checks that wxSUBRELEASE_NUMBER is at - least subrel. - - @header{wx/version.h} -*/ -#define wxCHECK_VERSION_FULL( major, minor, release, subrel ) - -//@} - diff --git a/interface/vidmode.h b/interface/vidmode.h deleted file mode 100644 index a96d3192c9..0000000000 --- a/interface/vidmode.h +++ /dev/null @@ -1,88 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: vidmode.h -// Purpose: interface of wxVideoMode -// Author: wxWidgets team -// RCS-ID: $Id: display.h 52634 2008-03-20 13:45:17Z VS $ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @struct wxVideoMode - @wxheader{display.h} - - Determines the sizes and locations of displays connected to the system. - - @library{wxcore} - @category{misc} - - @stdobjects - ::wxDefaultVideoMode - - @see wxClientDisplayRect(), wxDisplaySize(), wxDisplaySizeMM() -*/ -struct wxVideoMode -{ -public: - /** - Constructs this class using the given parameters. - */ - wxVideoMode(int width = 0, int height = 0, int depth = 0, int freq = 0); - - bool operator==(const wxVideoMode& m) const - bool operator!=(const wxVideoMode& mode) const - - /** - Returns true if this mode matches the other one in the sense that all - non zero fields of the other mode have the same value in this one - (except for refresh which is allowed to have a greater value). - */ - bool Matches(const wxVideoMode& other) const; - - /** - Returns the screen width in pixels (e.g. 640), 0 means unspecified. - */ - int GetWidth() const; - - /** - Returns the screen height in pixels (e.g. 480), 0 means unspecified. - */ - int GetHeight() const; - - /** - Returns bits per pixel (e.g. 32), 1 is monochrome and 0 means - unspecified/known. - */ - int GetDepth() const; - - /** - Returns true if the object has been initialized - */ - bool IsOk() const; - - /** - The screen width in pixels (e.g. 640), 0 means unspecified. - */ - int w; - - /** - The screen height in pixels (e.g. 480), 0 means unspecified. - */ - int h; - - /** - Bits per pixel (e.g. 32), 1 is monochrome and 0 means - unspecified/known. - */ - int bpp; - - /** - Refresh frequency in Hz, 0 means unspecified/unknown. - */ - int refresh; -}; - -/** - A global wxVideoMode instance used by wxDisplay. -*/ -wxVideoMode wxDefaultVideoMode; - diff --git a/interface/vlbox.h b/interface/vlbox.h deleted file mode 100644 index d376222010..0000000000 --- a/interface/vlbox.h +++ /dev/null @@ -1,328 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: vlbox.h -// Purpose: interface of wxVListBox -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxVListBox - @wxheader{vlbox.h} - - wxVListBox is a wxListBox-like control with the following two main - differences from a regular wxListBox: it can have an arbitrarily huge - number of items because it doesn't store them itself but uses the - OnDrawItem() callback to draw them (so it is a virtual listbox) and its - items can have variable height as determined by OnMeasureItem() (so it is - also a listbox with the lines of variable height). - - Also, as a consequence of its virtual nature, it doesn't have any methods - to append or insert items in it as it isn't necessary to do it: you just - have to call SetItemCount() to tell the control how many items it should - display. Of course, this also means that you will never use this class - directly because it has pure virtual functions, but will need to derive - your own class from it (for example, wxHtmlListBox). - - However it emits the same events as wxListBox and the same event macros may - be used with it. Since wxVListBox does not store its items itself, the - events will only contain the index, not any contents such as the string of - an item. - - @library{wxcore} - @category{ctrl} - - - @see wxSimpleHtmlListBox, wxHtmlListBox -*/ -class wxVListBox : public wxVScrolledWindow -{ -public: - /** - Default constructor, you must call Create() later. - */ - wxVListBox(); - /** - Normal constructor which calls Create() internally. - */ - wxVListBox(wxWindow* parent, wxWindowID id = wxID_ANY, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = 0, const wxString& name = wxVListBoxNameStr); - - /** - Destructor. - */ - virtual ~wxVListBox(); - - /** - Deletes all items from the control. - */ - void Clear(); - - /** - Creates the control. To finish creating it you also should call - SetItemCount() to let it know about the number of items it contains. - - The only special style which may be used with wxVListBox is - @c wxLB_MULTIPLE which indicates that the listbox should support - multiple selection. - - @return @true on success or @false if the control couldn't be created. - */ - bool Create(wxWindow* parent, wxWindowID id = wxID_ANY, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, long style = 0, - const wxString& name = wxVListBoxNameStr); - - /** - Deselects all the items in the listbox. This method is only valid for - multi selection listboxes. - - @return @true if any items were changed, i.e. if there had been any - selected items before, or @false if all the items were already - deselected. - - @see SelectAll(), Select() - */ - bool DeselectAll(); - - /** - Returns the index of the first selected item in the listbox or - @c wxNOT_FOUND if no items are currently selected. - - @a cookie is an opaque parameter which should be passed to the - subsequent calls to GetNextSelected(). It is needed in order to allow - parallel iterations over the selected items. - - Here is a typical example of using these functions: - - @code - unsigned long cookie; - int item = hlbox->GetFirstSelected(cookie); - while ( item != wxNOT_FOUND ) - { - // ... process item ... - item = hlbox->GetNextSelected(cookie); - } - @endcode - - This method is only valid for multi selection listboxes. - */ - int GetFirstSelected(unsigned long& cookie) const; - - /** - Get the number of items in the control. - - @see SetItemCount() - */ - size_t GetItemCount() const; - - /** - Returns the margins used by the control. The @c x field of the returned - point is the horizontal margin and the @c y field is the vertical one. - - @see SetMargins() - */ - wxPoint GetMargins() const; - - /** - Returns the index of the next selected item or @c wxNOT_FOUND if there - are no more. - - This method is only valid for multi selection listboxes. - - @see GetFirstSelected() - */ - int GetNextSelected(unsigned long& cookie) const; - - /** - Returns the number of the items currently selected. - - It is valid for both single and multi selection controls. In the former - case it may only return 0 or 1 however. - - @see IsSelected(), GetFirstSelected(), GetNextSelected() - */ - size_t GetSelectedCount() const; - - /** - Get the currently selected item or @c wxNOT_FOUND if there is no - selection. - */ - int GetSelection() const; - - /** - Returns the background colour used for the selected cells. By default - the standard system colour is used. - - @see wxSystemSettings::GetColour(), SetSelectionBackground() - */ - const wxColour& GetSelectionBackground() const; - - /** - Returns @true if the listbox was created with @c wxLB_MULTIPLE style - and so supports multiple selection or @false if it is a single - selection listbox. - */ - bool HasMultipleSelection() const; - - /** - Returns @true if this item is the current one, @false otherwise. - - The current item is always the same as selected one for the single - selection listbox and in this case this method is equivalent to - IsSelected() but they are different for multi selection listboxes where - many items may be selected but only one (at most) is current. - */ - bool IsCurrent(size_t item) const; - - /** - Returns @true if this item is selected, @false otherwise. - */ - bool IsSelected(size_t item) const; - - /** - 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. - - @todo Change this function signature to non-const. - */ - void OnDrawBackground(wxDC& dc, const wxRect& rect, size_t n) const; - - /** - The derived class must implement this function to actually draw the - item with the given index on the provided DC. - - @param dc - The device context to use for drawing. - @param rect - The bounding rectangle for the item being drawn (DC clipping - region is set to this rectangle before calling this function). - @param n - The index of the item to be drawn. - - @todo Change this function signature to non-const. - */ - virtual void OnDrawItem(wxDC& dc, const wxRect& rect, size_t n) const; - - /** - This method may be used to draw separators between the lines. The - rectangle passed to it may be modified, typically to deflate it a bit - before passing to OnDrawItem(). - - The base class version of this method doesn't do anything. - - @param dc - The device context to use for drawing. - @param rect - The bounding rectangle for the item. - @param n - The index of the item. - - @todo Change this function signature to non-const. - */ - virtual void OnDrawSeparator(wxDC& dc, wxRect& rect, size_t n) const; - - /** - The derived class must implement this method to return the height of - the specified item (in pixels). - */ - virtual wxCoord OnMeasureItem(size_t n) const; - - /** - Selects or deselects the specified item which must be valid (i.e. not - equal to @c wxNOT_FOUND). - - @return @true if the items selection status has changed or @false - otherwise. - - This function is only valid for the multiple selection listboxes, use - SetSelection() for the single selection ones. - */ - bool Select(size_t item, bool select = true); - - /** - Selects all the items in the listbox. - - @return @true if any items were changed, i.e. if there had been any - unselected items before, or @false if all the items were - already selected. - - This method is only valid for multi selection listboxes. - - @see DeselectAll(), Select() - */ - bool SelectAll(); - - /** - Selects all items in the specified range which may be given in any - order. - - @return @true if the items selection status has changed or @false - otherwise. - - This method is only valid for multi selection listboxes. - - @see SelectAll(), Select() - */ - bool SelectRange(size_t from, size_t to); - - /** - Set the number of items to be shown in the control. - - This is just a synonym for wxVScrolledWindow::SetRowCount(). - */ - void SetItemCount(size_t count); - - //@{ - /** - Set the margins: horizontal margin is the distance between the window - border and the item contents while vertical margin is half of the - distance between items. - - By default both margins are 0. - */ - void SetMargins(const wxPoint& pt); - void SetMargins(wxCoord x, wxCoord y); - //@} - - /** - Set the selection to the specified item, if it is -1 the selection is - unset. The selected item will be automatically scrolled into view if it - isn't currently visible. - - This method may be used both with single and multiple selection - listboxes. - */ - void SetSelection(int selection); - - /** - Sets the colour to be used for the selected cells background. The - background of the standard cells may be changed by simply calling - wxWindow::SetBackgroundColour(). - - @note Using a non-default background colour may result in control - having an appearance different from the similar native controls - and should be avoided in general. - - @see GetSelectionBackground() - */ - void SetSelectionBackground(const wxColour& col); - - /** - Toggles the state of the specified @a item, i.e. selects it if it was - unselected and deselects it if it was selected. - - This method is only valid for multi selection listboxes. - - @see Select() - */ - void Toggle(size_t item); -}; - diff --git a/interface/vscroll.h b/interface/vscroll.h deleted file mode 100644 index c5acde34e3..0000000000 --- a/interface/vscroll.h +++ /dev/null @@ -1,882 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: vscroll.h -// Purpose: interface of wxVarHScrollHelper -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxVarScrollHelperBase - @wxheader{vscroll.h} - - This class provides all common base functionality for scroll calculations - shared among all variable scrolled window implementations as well as - automatic scrollbar functionality, saved scroll positions, controlling - target windows to be scrolled, as well as defining all required virtual - functions that need to be implemented for any orientation specific work. - - Documentation of this class is provided specifically for referencing use - of the functions provided by this class for use with the variable scrolled - windows that derive from here. You will likely want to derive your window - from one of the already implemented variable scrolled windows rather than - from wxVarScrollHelperBase directly. - - @library{wxcore} - @category{miscwnd} - - @see wxHScrolledWindow, wxHVScrolledWindow, wxVScrolledWindow -*/ -class wxVarScrollHelperBase -{ -public: - /** - Constructor taking the target window to be scrolled by this helper - class. This will attach scroll event handlers to the target window to - catch and handle scroll events appropriately. - */ - wxVarScrollHelperBase(wxWindow* winToScroll); - - /** - Virtual destructor for detaching scroll event handlers attached with - this helper class. - */ - virtual ~wxVarScrollHelperBase(); - - /** - Translates the logical coordinate given to the current device - coordinate. For example, if the window is scrolled 10 units and each - scroll unit represents 10 device units (which may not be the case since - this class allows for variable scroll unit sizes), a call to this - function with a coordinate of 15 will return -85. - - @see CalcUnscrolledPosition() - */ - int CalcScrolledPosition(int coord) const; - - /** - Translates the device coordinate given to the corresponding logical - coordinate. For example, if the window is scrolled 10 units and each - scroll unit represents 10 device units (which may not be the case since - this class allows for variable scroll unit sizes), a call to this - function with a coordinate of 15 will return 115. - - @see CalcScrolledPosition() - */ - int CalcUnscrolledPosition(int coord) const; - - /** - With physical scrolling on (when this is @true), the device origin is - changed properly when a wxPaintDC is prepared, children are actually - moved and laid out properly, and the contents of the window (pixels) - are actually moved. When this is @false, you are responsible for - repainting any invalidated areas of the window yourself to account for - the new scroll position. - */ - void EnablePhysicalScrolling(bool scrolling = true); - - /** - When the number of scroll units change, we try to estimate the total - size of all units when the full window size is needed (i.e. to - calculate the scrollbar thumb size). This is a rather expensive - operation in terms of unit access, so if the user code may estimate the - average size better or faster than we do, it should override this - function to implement its own logic. This function should return the - best guess for the total virtual window size. - - @note Although returning a totally wrong value would still work, it - risks resulting in very strange scrollbar behaviour so this - function should really try to make the best guess possible. - */ - virtual wxCoord EstimateTotalSize() const; - - /** - This function needs to be overridden in the in the derived class to - return the window size with respect to the opposing orientation. If - this is a vertical scrolled window, it should return the height. - - @see GetOrientationTargetSize() - */ - virtual int GetNonOrientationTargetSize() const; - - /** - This function need to be overridden to return the orientation that this - helper is working with, either @c wxHORIZONTAL or @c wxVERTICAL. - */ - virtual wxOrientation GetOrientation() const; - - /** - This function needs to be overridden in the in the derived class to - return the window size with respect to the orientation this helper is - working with. If this is a vertical scrolled window, it should return - the width. - - @see GetNonOrientationTargetSize() - */ - virtual int GetOrientationTargetSize() const; - - /** - This function will return the target window this helper class is - currently scrolling. - - @see SetTargetWindow() - */ - wxWindow* GetTargetWindow() const; - - /** - Returns the index of the first visible unit based on the scroll - position. - */ - size_t GetVisibleBegin() const; - - /** - Returns the index of the last visible unit based on the scroll - position. This includes the last unit even if it is only partially - visible. - */ - size_t GetVisibleEnd() const; - - /** - Returns @true if the given scroll unit is currently visible (even if - only partially visible) or @false otherwise. - */ - bool IsVisible(size_t unit) const; - - /** - This function must be overridden in the derived class, and should - return the size of the given unit in pixels. - */ - virtual wxCoord OnGetUnitSize(size_t unit) const; - - /** - This function doesn't have to be overridden but it may be useful to do - so if calculating the units' sizes is a relatively expensive operation - as it gives your code a chance to calculate several of them at once and - cache the result if necessary. - - OnGetUnitsSizeHint() is normally called just before OnGetUnitSize() but - you shouldn't rely on the latter being called for all units in the - interval specified here. It is also possible that OnGetUnitSize() will - be called for units outside of this interval, so this is really just a - hint, not a promise. - - Finally, note that @a unitMin is inclusive, while @a unitMax is - exclusive. - */ - virtual void OnGetUnitsSizeHint(size_t unitMin, size_t unitMax) const; - - /** - Recalculate all parameters and repaint all units. - */ - virtual void RefreshAll(); - - /** - Normally the window will scroll itself, but in some rare occasions you - might want it to scroll (part of) another window (e.g. a child of it in - order to scroll only a portion the area between the scrollbars like a - spreadsheet where only the cell area will move). - - @see GetTargetWindow() - */ - void SetTargetWindow(wxWindow* target); - - /** - Update the thumb size shown by the scrollbar. - */ - virtual void UpdateScrollbar(); - - /** - Returns the virtual scroll unit under the device unit given accounting - for scroll position or @c wxNOT_FOUND if none (i.e. if it is below the - last item). - */ - int VirtualHitTest(wxCoord coord) const; -}; - - - -/** - @class wxVarVScrollHelper - @wxheader{vscroll.h} - - This class provides functions wrapping the wxVarScrollHelperBase class, - targeted for vertical-specific scrolling. - - Like wxVarScrollHelperBase, this class is mostly only useful to those - classes built into wxWidgets deriving from here, and this documentation is - mostly only provided for referencing the functions provided by this class. - You will likely want to derive your window from wxVScrolledWindow rather - than from here directly. - - @library{wxcore} - @category{miscwnd} - - @see wxHScrolledWindow, wxHVScrolledWindow, wxVScrolledWindow -*/ -class wxVarVScrollHelper : public wxVarScrollHelperBase -{ -public: - /** - Constructor taking the target window to be scrolled by this helper - class. This will attach scroll event handlers to the target window to - catch and handle scroll events appropriately. - */ - wxVarVScrollHelper(wxWindow* winToScroll); - - /** - This class forwards calls from EstimateTotalSize() to this function so - derived classes can override either just the height or the width - estimation, or just estimate both differently if desired in any - wxHVScrolledWindow derived class. - - @note This function will not be called if EstimateTotalSize() is - overridden in your derived class. - */ - virtual wxCoord EstimateTotalHeight() const; - - /** - Returns the number of rows the target window contains. - - @see SetRowCount() - */ - size_t GetRowCount() const; - - /** - Returns the index of the first visible row based on the scroll - position. - */ - size_t GetVisibleRowsBegin() const; - - /** - Returns the index of the last visible row based on the scroll position. - This includes the last row even if it is only partially visible. - */ - size_t GetVisibleRowsEnd() const; - - /** - Returns @true if the given row is currently visible (even if only - partially visible) or @false otherwise. - */ - bool IsRowVisible(size_t row) const; - - /** - This function must be overridden in the derived class, and should - return the height of the given row in pixels. - */ - virtual wxCoord OnGetRowHeight(size_t row) const; - - /** - This function doesn't have to be overridden but it may be useful to do - so if calculating the rows' sizes is a relatively expensive operation - as it gives your code a chance to calculate several of them at once and - cache the result if necessary. - - OnGetRowsHeightHint() is normally called just before OnGetRowHeight() - but you shouldn't rely on the latter being called for all rows in the - interval specified here. It is also possible that OnGetRowHeight() will - be called for units outside of this interval, so this is really just a - hint, not a promise. - - Finally, note that @a rowMin is inclusive, while @a rowMax is - exclusive. - */ - virtual void OnGetRowsHeightHint(size_t rowMin, size_t rowMax) const; - - /** - Triggers a refresh for just the given row's area of the window if it's - visible. - */ - virtual void RefreshRow(size_t row); - - /** - Triggers a refresh for the area between the specified range of rows - given (inclusively). - */ - virtual void RefreshRows(size_t from, size_t to); - - /** - Scroll by the specified number of pages which may be positive (to - scroll down) or negative (to scroll up). - */ - virtual bool ScrollRowPages(int pages); - - /** - Scroll by the specified number of rows which may be positive (to scroll - down) or negative (to scroll up). - - @return @true if the window was scrolled, @false otherwise (for - example, if we're trying to scroll down but we are already - showing the last row). - */ - virtual bool ScrollRows(int rows); - - /** - Scroll to the specified row. It will become the first visible row in - the window. - - @return @true if we scrolled the window, @false if nothing was done. - */ - bool ScrollToRow(size_t row); - - /** - Set the number of rows the window contains. The derived class must - provide the heights for all rows with indices up to the one given here - in it's OnGetRowHeight() implementation. - - @see GetRowCount() - */ - void SetRowCount(size_t rowCount); -}; - - - -/** - @class wxVarHScrollHelper - @wxheader{vscroll.h} - - This class provides functions wrapping the wxVarScrollHelperBase class, - targeted for horizontal-specific scrolling. - - Like wxVarScrollHelperBase, this class is mostly only useful to those - classes built into wxWidgets deriving from here, and this documentation is - mostly only provided for referencing the functions provided by this class. - You will likely want to derive your window from wxHScrolledWindow rather - than from here directly. - - @library{wxcore} - @category{miscwnd} - - @see wxHScrolledWindow, wxHVScrolledWindow, wxVScrolledWindow -*/ -class wxVarHScrollHelper : public wxVarScrollHelperBase -{ -public: - /** - Constructor taking the target window to be scrolled by this helper - class. This will attach scroll event handlers to the target window to - catch and handle scroll events appropriately. - */ - wxVarHScrollHelper(wxWindow* winToScroll); - - /** - This class forwards calls from EstimateTotalSize() to this function so - derived classes can override either just the height or the width - estimation, or just estimate both differently if desired in any - wxHVScrolledWindow derived class. - - @note This function will not be called if EstimateTotalSize() is - overridden in your derived class. - */ - virtual wxCoord EstimateTotalWidth() const; - - /** - Returns the number of columns the target window contains. - - @see SetColumnCount() - */ - size_t GetColumnCount() const; - - /** - Returns the index of the first visible column based on the scroll - position. - */ - size_t GetVisibleColumnsBegin() const; - - /** - Returns the index of the last visible column based on the scroll - position. This includes the last column even if it is only partially - visible. - */ - size_t GetVisibleColumnsEnd() const; - - /** - Returns @true if the given column is currently visible (even if only - partially visible) or @false otherwise. - */ - bool IsColumnVisible(size_t column) const; - - /** - This function must be overridden in the derived class, and should - return the width of the given column in pixels. - */ - virtual wxCoord OnGetColumnWidth(size_t column) const; - - /** - This function doesn't have to be overridden but it may be useful to do - so if calculating the columns' sizes is a relatively expensive - operation as it gives your code a chance to calculate several of them - at once and cache the result if necessary. - - OnGetColumnsWidthHint() is normally called just before - OnGetColumnWidth() but you shouldn't rely on the latter being called - for all columns in the interval specified here. It is also possible - that OnGetColumnWidth() will be called for units outside of this - interval, so this is really just a hint, not a promise. - - Finally, note that @a columnMin is inclusive, while @a columnMax is - exclusive. - */ - virtual void OnGetColumnsWidthHint(size_t columnMin, - size_t columnMax) const; - - /** - Triggers a refresh for just the given column's area of the window if - it's visible. - */ - virtual void RefreshColumn(size_t column); - - /** - Triggers a refresh for the area between the specified range of columns - given (inclusively). - */ - virtual void RefreshColumns(size_t from, size_t to); - - /** - Scroll by the specified number of pages which may be positive (to - scroll right) or negative (to scroll left). - */ - virtual bool ScrollColumnPages(int pages); - - /** - Scroll by the specified number of columns which may be positive (to - scroll right) or negative (to scroll left). - - @return @true if the window was scrolled, @false otherwise (for - example, if we're trying to scroll right but we are already - showing the last column). - */ - virtual bool ScrollColumns(int columns); - - /** - Scroll to the specified column. It will become the first visible column - in the window. - - @return @true if we scrolled the window, @false if nothing was done. - */ - bool ScrollToColumn(size_t column); - - /** - Set the number of columns the window contains. The derived class must - provide the widths for all columns with indices up to the one given - here in it's OnGetColumnWidth() implementation. - - @see GetColumnCount() - */ - void SetColumnCount(size_t columnCount); -}; - - - -/** - @class wxVarHVScrollHelper - @wxheader{vscroll.h} - - This class provides functions wrapping the wxVarHScrollHelper and - wxVarVScrollHelper classes, targeted for scrolling a window in both axis. - Since this class is also the join class of the horizontal and vertical - scrolling functionality, it also addresses some wrappers that help avoid - the need to specify class scope in your wxHVScrolledWindow derived class - when using wxVarScrollHelperBase functionality. - - Like all three of it's scroll helper base classes, this class is mostly - only useful to those classes built into wxWidgets deriving from here, and - this documentation is mostly only provided for referencing the functions - provided by this class. You will likely want to derive your window from - wxHVScrolledWindow rather than from here directly. - - @library{wxcore} - @category{miscwnd} - - @see wxHScrolledWindow, wxHVScrolledWindow, wxVScrolledWindow -*/ -class wxVarHVScrollHelper : public wxVarVScrollHelper, - public wxVarHScrollHelper -{ -public: - /** - Constructor taking the target window to be scrolled by this helper - class. This will attach scroll event handlers to the target window to - catch and handle scroll events appropriately. - */ - wxVarHVScrollHelper(wxWindow* winToScroll); - - /** - With physical scrolling on (when this is @true), the device origin is - changed properly when a wxPaintDC is prepared, children are actually - moved and laid out properly, and the contents of the window (pixels) - are actually moved. When this is @false, you are responsible for - repainting any invalidated areas of the window yourself to account for - the new scroll position. - - @param vscrolling - Specifies if physical scrolling should be turned on when scrolling - vertically. - @param hscrolling - Specifies if physical scrolling should be turned on when scrolling - horizontally. - */ - void EnablePhysicalScrolling(bool vscrolling = true, - bool hscrolling = true); - - /** - Returns the number of columns and rows the target window contains. - - @see SetRowColumnCount() - */ - wxSize GetRowColumnCount() const; - - /** - Returns the index of the first visible column and row based on the - current scroll position. - */ - wxPosition GetVisibleBegin() const; - - /** - Returns the index of the last visible column and row based on the - scroll position. This includes any partially visible columns or rows. - */ - wxPosition GetVisibleEnd() const; - - //@{ - /** - Returns @true if both the given row and column are currently visible - (even if only partially visible) or @false otherwise. - */ - bool IsVisible(size_t row, size_t column) const; - bool IsVisible(const wxPosition& pos) const; - //@} - - //@{ - /** - Triggers a refresh for just the area shared between the given row and - column of the window if it is visible. - */ - virtual void RefreshRowColumn(size_t row, size_t column); - virtual void RefreshRowColumn(const wxPosition& pos); - //@} - - //@{ - /** - Triggers a refresh for the visible area shared between all given rows - and columns (inclusive) of the window. If the target window for both - orientations is the same, the rectangle of cells is refreshed; if the - target windows differ, the entire client size opposite the orientation - direction is refreshed between the specified limits. - */ - virtual void RefreshRowsColumns(size_t fromRow, size_t toRow, - size_t fromColumn, size_t toColumn); - virtual void RefreshRowsColumns(const wxPosition& from, - const wxPosition& to); - //@} - - //@{ - /** - Scroll to the specified row and column. It will become the first - visible row and column in the window. Returns @true if we scrolled the - window, @false if nothing was done. - */ - bool ScrollToRowColumn(size_t row, size_t column); - bool ScrollToRowColumn(const wxPosition& pos); - //@} - - /** - Set the number of rows and columns the target window will contain. The - derived class must provide the sizes for all rows and columns with - indices up to the ones given here in it's OnGetRowHeight() and - OnGetColumnWidth() implementations, respectively. - - @see GetRowColumnCount() - */ - void SetRowColumnCount(size_t rowCount, size_t columnCount); - - //@{ - /** - Returns the virtual scroll unit under the device unit given accounting - for scroll position or @c wxNOT_FOUND (for the row, column, or possibly - both values) if none. - */ - wxPosition VirtualHitTest(wxCoord x, wxCoord y) const; - wxPosition VirtualHitTest(const wxPoint& pos) const; - //@} -}; - - - -/** - @class wxVScrolledWindow - @wxheader{vscroll.h} - - In the name of this class, "V" may stand for "variable" because it can be - used for scrolling rows of variable heights; "virtual", because it is not - necessary to know the heights of all rows in advance -- only those which - are shown on the screen need to be measured; or even "vertical", because - this class only supports scrolling vertically. - - In any case, this is a generalization of wxScrolled which can be only used - when all rows have the same heights. It lacks some other wxScrolled - features however, notably it can't scroll specific pixel sizes of the - window or its exact client area size. - - To use this class, you need to derive from it and implement the - OnGetRowHeight() pure virtual method. You also must call SetRowCount() to - let the base class know how many rows it should display, but from that - moment on the scrolling is handled entirely by wxVScrolledWindow. You only - need to draw the visible part of contents in your @c OnPaint() method as - usual. You should use GetVisibleRowsBegin() and GetVisibleRowsEnd() to - select the lines to display. Note that the device context origin is not - shifted so the first visible row always appears at the point (0, 0) in - physical as well as logical coordinates. - - @section wxWidgets 2.8 Compatibility Functions - - The following functions provide backwards compatibility for applications - originally built using wxVScrolledWindow in 2.6 or 2.8. Originally, - wxVScrolledWindow referred to scrolling "lines". We now use "units" in - wxVarScrollHelperBase to avoid implying any orientation (since the - functions are used for both horizontal and vertical scrolling in derived - classes). And in the new wxVScrolledWindow and wxHScrolledWindow classes, - we refer to them as "rows" and "columns", respectively. This is to help - clear some confusion in not only those classes, but also in - wxHVScrolledWindow where functions are inherited from both. - - You are encouraged to update any existing code using these function to use - the new replacements mentioned below, and avoid using these functions for - any new code as they are deprecated. - - @beginTable - @row2col{ size_t %GetFirstVisibleLine() const, - Deprecated for GetVisibleRowsBegin(). } - @row2col{ size_t %GetLastVisibleLine() const, - Deprecated for GetVisibleRowsEnd(). This function originally had a - slight design flaw in that it was possible to return - (size_t)-1 (ie: a large positive number) if the scroll - position was 0 and the first line wasn't completely visible. } - @row2col{ size_t %GetLineCount() const, - Deprecated for GetRowCount(). } - @row2col{ int %HitTest(wxCoord x\, wxCoord y) const - @n int %HitTest(const wxPoint& pt) const, - Deprecated for VirtualHitTest(). } - @row2col{ virtual wxCoord %OnGetLineHeight(size_t line) const, - Deprecated for OnGetRowHeight(). } - @row2col{ virtual void %OnGetLinesHint(size_t lineMin\, size_t lineMax) const, - Deprecated for OnGetRowsHeightHint(). } - @row2col{ virtual void %RefreshLine(size_t line), - Deprecated for RefreshRow(). } - @row2col{ virtual void %RefreshLines(size_t from\, size_t to), - Deprecated for RefreshRows(). } - @row2col{ virtual bool %ScrollLines(int lines), - Deprecated for ScrollRows(). } - @row2col{ virtual bool %ScrollPages(int pages), - Deprecated for ScrollRowPages(). } - @row2col{ bool %ScrollToLine(size_t line), - Deprecated for ScrollToRow(). } - @row2col{ void %SetLineCount(size_t count), - Deprecated for SetRowCount(). } - @endTable - - @library{wxcore} - @category{miscwnd} - - @see wxHScrolledWindow, wxHVScrolledWindow -*/ -class wxVScrolledWindow : public wxPanel, public wxVarVScrollHelper -{ -public: - /** - Default constructor, you must call Create() later. - */ - wxVScrolledWindow(); - /** - This is the normal constructor, no need to call Create() after using - this constructor. - - @note @c wxVSCROLL is always automatically added to the style, there is - no need to specify it explicitly. - - @param parent - The parent window, must not be @NULL. - @param id - The identifier of this window, wxID_ANY by default. - @param pos - The initial window position. - @param size - The initial window size. - @param style - The window style. There are no special style bits defined for this - class. - @param name - The name for this window; usually not used. - */ - wxVScrolledWindow(wxWindow* parent, wxWindowID id = wxID_ANY, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, long style = 0, - const wxString& name = wxPanelNameStr); - - /** - Same as the non-default constuctor, but returns a status code: @true if - ok, @false if the window couldn't be created. - - Just as with the constructor, the @c wxVSCROLL style is always used, - there is no need to specify it explicitly. - */ - bool Create(wxWindow* parent, wxWindowID id = wxID_ANY, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, long style = 0, - const wxString& name = wxPanelNameStr); -}; - - - -/** - @class wxHScrolledWindow - @wxheader{vscroll.h} - - In the name of this class, "H" stands for "horizontal" because it can be - used for scrolling columns of variable widths. It is not necessary to know - the widths of all columns in advance -- only those which are shown on the - screen need to be measured. - - In any case, this is a generalization of wxScrolled which can be only used - when all columns have the same widths. It lacks some other wxScrolled - features however, notably it can't scroll specific pixel sizes of the - window or its exact client area size. - - To use this class, you need to derive from it and implement the - OnGetColumnWidth() pure virtual method. You also must call SetColumnCount() - to let the base class know how many columns it should display, but from - that moment on the scrolling is handled entirely by wxHScrolledWindow. You - only need to draw the visible part of contents in your @c OnPaint() method - as usual. You should use GetVisibleColumnsBegin() and - GetVisibleColumnsEnd() to select the lines to display. Note that the device - context origin is not shifted so the first visible column always appears at - the point (0, 0) in physical as well as logical coordinates. - - @library{wxcore} - @category{miscwnd} - - @see wxHVScrolledWindow, wxVScrolledWindow -*/ -class wxHScrolledWindow : public wxPanel, public wxVarHScrollHelper -{ -public: - /** - Default constructor, you must call Create() later. - */ - wxHScrolledWindow(); - /** - This is the normal constructor, no need to call Create() after using - this constructor. - - @note @c wxHSCROLL is always automatically added to the style, there is - no need to specify it explicitly. - - @param parent - The parent window, must not be @NULL. - @param id - The identifier of this window, wxID_ANY by default. - @param pos - The initial window position. - @param size - The initial window size. - @param style - The window style. There are no special style bits defined for this - class. - @param name - The name for this window; usually not used. - */ - wxHScrolledWindow(wxWindow* parent, wxWindowID id = wxID_ANY, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, long style = 0, - const wxString& name = wxPanelNameStr); - - /** - Same as the non-default constuctor, but returns a status code: @true if - ok, @false if the window couldn't be created. - - Just as with the constructor, the @c wxHSCROLL style is always used, - there is no need to specify it explicitly. - */ - bool Create(wxWindow* parent, wxWindowID id = wxID_ANY, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, long style = 0, - const wxString& name = wxPanelNameStr); -}; - - - -/** - @class wxHVScrolledWindow - @wxheader{vscroll.h} - - This window inherits all functionality of both vertical and horizontal, - variable scrolled windows. It automatically handles everything needed to - scroll both axis simultaneously with both variable row heights and variable - column widths. - - In any case, this is a generalization of wxScrolled which can be only used - when all rows and columns are the same size. It lacks some other wxScrolled - features however, notably it can't scroll specific pixel sizes of the - window or its exact client area size. - - To use this class, you must derive from it and implement both the - OnGetRowHeight() and OnGetColumnWidth() pure virtual methods to let the - base class know how many rows and columns it should display. You also need - to set the total rows and columns the window contains, but from that moment - on the scrolling is handled entirely by wxHVScrolledWindow. You only need - to draw the visible part of contents in your @c OnPaint() method as usual. - You should use GetVisibleBegin() and GetVisibleEnd() to select the lines to - display. Note that the device context origin is not shifted so the first - visible row and column always appear at the point (0, 0) in physical as - well as logical coordinates. - - @library{wxcore} - @category{miscwnd} - - @see wxHScrolledWindow, wxVScrolledWindow -*/ -class wxHVScrolledWindow : public wxPanel, public wxVarHVScrollHelper -{ -public: - /** - Default constructor, you must call Create() later. - */ - wxHVScrolledWindow(); - /** - This is the normal constructor, no need to call Create() after using - this constructor. - - @note @c wxHSCROLL and @c wxVSCROLL are always automatically added to - the style, there is no need to specify it explicitly. - - @param parent - The parent window, must not be @NULL. - @param id - The identifier of this window, wxID_ANY by default. - @param pos - The initial window position. - @param size - The initial window size. - @param style - The window style. There are no special style bits defined for this - class. - @param name - The name for this window; usually not used. - */ - wxHVScrolledWindow(wxWindow* parent, wxWindowID id = wxID_ANY, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, long style = 0, - const wxString& name = wxPanelNameStr); - - /** - Same as the non-default constuctor, but returns a status code: @true if - ok, @false if the window couldn't be created. - - Just as with the constructor, the @c wxHSCROLL and @c wxVSCROLL styles - are always used, there is no need to specify them explicitly. - */ - bool Create(wxWindow* parent, wxWindowID id = wxID_ANY, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, long style = 0, - const wxString& name = wxPanelNameStr); -}; - diff --git a/interface/weakref.h b/interface/weakref.h deleted file mode 100644 index f6522aa399..0000000000 --- a/interface/weakref.h +++ /dev/null @@ -1,166 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: weakref.h -// Purpose: interface of wxWeakRefDynamic -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @wxheader{weakref.h} - - wxWeakRefDynamic is a template class for weak references that is used in - the same way as wxWeakRef. The only difference is that wxWeakRefDynamic - defaults to using @c dynamic_cast for establishing the object - reference (while wxWeakRef defaults to @c static_cast). - - So, wxWeakRef will detect a type mismatch during compile time and will - have a little better run-time performance. The role of wxWeakRefDynamic - is to handle objects which derived type one does not know. - - @note wxWeakRef selects an implementation based on the static type - of T. If T does not have wxTrackable statically, it defaults to to a mixed- - mode operation, where it uses @c dynamic_cast as the last measure (if - available from the compiler and enabled when building wxWidgets). - - For general cases, wxWeakRef is the better choice. - - For API documentation, see: wxWeakRef - - @library{wxcore} - @category{FIXME} -*/ -template -class wxWeakRefDynamic -{ -public: - -}; - - - -/** - @wxheader{weakref.h} - - wxWeakRef is a template class for weak references to wxWidgets objects, - such as wxEvtHandler, wxWindow and - wxObject. A weak reference behaves much like an ordinary - pointer, but when the object pointed is destroyed, the weak reference is - automatically reset to a @NULL pointer. - - wxWeakRef can be used whenever one must keep a pointer to an object - that one does not directly own, and that may be destroyed before the object - holding the reference. - - wxWeakRef is a small object and the mechanism behind it is fast - (@b O(1)). So the overall cost of using it is small. - - Example - - @code - wxWindow *wnd = new wxWindow( parent, wxID_ANY, "wxWindow" ); - wxWeakRef wr = wnd; - wxWindowRef wr2 = wnd; // Same as above, but using a typedef - // Do things with window - wnd->Show( true ); - // Weak ref is used like an ordinary pointer - wr->Show( false ); - wnd->Destroy(); - // Now the weak ref has been reset, so we don't risk accessing - // a dangling pointer: - wxASSERT( wr==NULL ); - @endcode - - wxWeakRef works for any objects that are derived from wxTrackable. By default, - wxEvtHandler and wxWindow derive from wxTrackable. However, wxObject does not, so - types like wxFont and wxColour are not trackable. The example below shows how to - create a wxObject derived class that is trackable: - - @code - class wxMyTrackableObject : public wxObject, public wxTrackable - { - // ... other members here - }; - @endcode - - The following types of weak references are predefined: - - @code - typedef wxWeakRef wxEvtHandlerRef; - typedef wxWeakRef wxWindowRef; - @endcode - - - @library{wxbase} - @category{FIXME} - - @see wxSharedPtr, wxScopedPtr -*/ -template -class wxWeakRef -{ -public: - /** - Constructor. The weak reference is initialized to @e pobj. - */ - wxWeakRef(T* pobj = NULL); - - /** - Copy constructor. - */ - wxWeakRef(const wxWeakRef& wr); - - /** - Destructor. - */ - ~wxWeakRef(); - - /** - Called when the tracked object is destroyed. Be default sets - internal pointer to @NULL. You need to call this method if - you override it. - */ - virtual void OnObjectDestroy(); - - /** - Release currently tracked object and rests object reference. - */ - void Release(); - - /** - Returns pointer to the tracked object or @NULL. - */ - T* get() const; - - /** - Release currently tracked object and start tracking the same object as - the wxWeakRef @e wr. - */ - T* operator =(wxWeakRef& wr); - - /** - Implicit conversion to T*. Returns pointer to the tracked - object or @NULL. - */ - T* operator*() const; - - /** - Returns a reference to the tracked object. If the internal pointer is @NULL - this method will cause an assert in debug mode. - */ - T operator*() const; - - /** - Smart pointer member access. Returns a pointer to the - tracked object. If the internal pointer is @NULL this - method will cause an assert in debug mode. - */ - T* operator-(); - - /** - Releases the currently tracked object and starts tracking @e pobj. - A weak reference may be reset by passing @e @NULL as @e pobj. - */ - T* operator=(T* pobj); -}; - diff --git a/interface/wfstream.h b/interface/wfstream.h deleted file mode 100644 index de501d0490..0000000000 --- a/interface/wfstream.h +++ /dev/null @@ -1,269 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: wfstream.h -// Purpose: interface of wxTempFileOutputStream -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxTempFileOutputStream - @wxheader{wfstream.h} - - wxTempFileOutputStream is an output stream based on wxTempFile. It - provides a relatively safe way to replace the contents of the - existing file. - - @library{wxbase} - @category{streams} - - @see wxTempFile -*/ -class wxTempFileOutputStream : public wxOutputStream -{ -public: - /** - Associates wxTempFileOutputStream with the file to be replaced and opens it. - You should use - wxStreamBase::IsOk to verify if the constructor succeeded. - Call Commit() or wxOutputStream::Close to - replace the old file and close this one. Calling Discard() - (or allowing the destructor to do it) will discard the changes. - */ - wxTempFileOutputStream(const wxString& fileName); - - /** - Validate changes: deletes the old file of the given name and renames the new - file to the old name. Returns @true if both actions succeeded. If @false is - returned it may unfortunately mean two quite different things: either that - either the old file couldn't be deleted or that the new file couldn't be renamed - to the old name. - */ - bool Commit(); - - /** - Discard changes: the old file contents are not changed, the temporary file is - deleted. - */ - void Discard(); -}; - - - -/** - @class wxFFileOutputStream - @wxheader{wfstream.h} - - This class represents data written to a file. There are actually - two such groups of classes: this one is based on wxFFile - whereas wxFileInputStream is based in - the wxFile class. - - Note that wxOutputStream::SeekO - can seek beyond the end of the stream (file) and will thus not return - @e wxInvalidOffset for that. - - @library{wxbase} - @category{streams} - - @see wxBufferedOutputStream, wxFFileInputStream, wxFileInputStream -*/ -class wxFFileOutputStream : public wxOutputStream -{ -public: - //@{ - /** - Initializes a file stream in write-only mode using the file descriptor @e fp. - */ - wxFFileOutputStream(const wxString& filename, - const wxString& mode = "wb"); - wxFFileOutputStream(wxFFile& file); - wxFFileOutputStream(FILE* fp); - //@} - - /** - Destructor. - */ - ~wxFFileOutputStream(); - - /** - Returns @true if the stream is initialized and ready. - */ - bool IsOk() const; -}; - - - -/** - @class wxFileOutputStream - @wxheader{wfstream.h} - - This class represents data written to a file. There are actually - two such groups of classes: this one is based on wxFile - whereas wxFFileInputStream is based in - the wxFFile class. - - Note that wxOutputStream::SeekO - can seek beyond the end of the stream (file) and will thus not return - @e wxInvalidOffset for that. - - @library{wxbase} - @category{streams} - - @see wxBufferedOutputStream, wxFileInputStream, wxFFileInputStream -*/ -class wxFileOutputStream : public wxOutputStream -{ -public: - //@{ - /** - Initializes a file stream in write-only mode using the file descriptor @e fd. - */ - wxFileOutputStream(const wxString& ofileName); - wxFileOutputStream(wxFile& file); - wxFileOutputStream(int fd); - //@} - - /** - Destructor. - */ - ~wxFileOutputStream(); - - /** - Returns @true if the stream is initialized and ready. - */ - bool IsOk() const; -}; - - - -/** - @class wxFileInputStream - @wxheader{wfstream.h} - - This class represents data read in from a file. There are actually - two such groups of classes: this one is based on wxFile - whereas wxFFileInputStream is based in - the wxFFile class. - - Note that wxInputStream::SeekI - can seek beyond the end of the stream (file) and will thus not return - @e wxInvalidOffset for that. - - @library{wxbase} - @category{streams} - - @see wxBufferedInputStream, wxFileOutputStream, wxFFileOutputStream -*/ -class wxFileInputStream : public wxInputStream -{ -public: - //@{ - /** - Initializes a file stream in read-only mode using the specified file descriptor. - */ - wxFileInputStream(const wxString& ifileName); - wxFileInputStream(wxFile& file); - wxFileInputStream(int fd); - //@} - - /** - Destructor. - */ - ~wxFileInputStream(); - - /** - Returns @true if the stream is initialized and ready. - */ - bool IsOk() const; -}; - - - -/** - @class wxFFileInputStream - @wxheader{wfstream.h} - - This class represents data read in from a file. There are actually - two such groups of classes: this one is based on wxFFile - whereas wxFileInputStream is based in - the wxFile class. - - Note that wxInputStream::SeekI - can seek beyond the end of the stream (file) and will thus not return - @e wxInvalidOffset for that. - - @library{wxbase} - @category{streams} - - @see wxBufferedInputStream, wxFFileOutputStream, wxFileOutputStream -*/ -class wxFFileInputStream : public wxInputStream -{ -public: - //@{ - /** - Initializes a file stream in read-only mode using the specified file pointer @e - fp. - */ - wxFFileInputStream(const wxString& filename, - const wxString& mode = "rb"); - wxFFileInputStream(wxFFile& file); - wxFFileInputStream(FILE* fp); - //@} - - /** - Destructor. - */ - ~wxFFileInputStream(); - - /** - Returns @true if the stream is initialized and ready. - */ - bool IsOk() const; -}; - - - -/** - @class wxFFileStream - @wxheader{wfstream.h} - - - @library{wxbase} - @category{FIXME} - - @see wxStreamBuffer -*/ -class wxFFileStream : public wxFFileOutputStream -{ -public: - /** - Initializes a new file stream in read-write mode using the specified - @e iofilename name. - */ - wxFFileStream(const wxString& iofileName, const wxString& mode = "w+b"); -}; - - - -/** - @class wxFileStream - @wxheader{wfstream.h} - - - @library{wxbase} - @category{FIXME} - - @see wxStreamBuffer -*/ -class wxFileStream : public wxFileOutputStream -{ -public: - /** - Initializes a new file stream in read-write mode using the specified - @e iofilename name. - */ - wxFileStream(const wxString& iofileName); -}; - diff --git a/interface/window.h b/interface/window.h deleted file mode 100644 index 2161f7dda8..0000000000 --- a/interface/window.h +++ /dev/null @@ -1,2659 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: window.h -// Purpose: interface of wxWindow -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxWindow - @wxheader{window.h} - - wxWindow is the base class for all windows and represents any visible object on - screen. All controls, top level windows and so on are windows. Sizers and - device contexts are not, however, as they don't appear on screen themselves. - - Please note that all children of the window will be deleted automatically by - the destructor before the window itself is deleted which means that you don't - have to worry about deleting them manually. Please see the @ref - overview_windowdeletion "window deletion overview" for more information. - - Also note that in this, and many others, wxWidgets classes some - @c GetXXX() methods may be overloaded (as, for example, - wxWindow::GetSize or wxWindow::GetClientSize). In this case, the overloads - are non-virtual because having multiple virtual functions with the same name - results in a virtual function name hiding at the derived class level (in - English, this means that the derived class has to override all overloaded - variants if it overrides any of them). To allow overriding them in the derived - class, wxWidgets uses a unique protected virtual @c DoGetXXX() method - and all @c GetXXX() ones are forwarded to it, so overriding the former - changes the behaviour of the latter. - - @beginStyleTable - @style{wxBORDER_DEFAULT} - The window class will decide the kind of border to show, if any. - @style{wxBORDER_SIMPLE} - Displays a thin border around the window. wxSIMPLE_BORDER is the - old name for this style. - @style{wxBORDER_SUNKEN} - Displays a sunken border. wxSUNKEN_BORDER is the old name for this - style. - @style{wxBORDER_RAISED} - Displays a raised border. wxRAISED_BORDER is the old name for this - style. - @style{wxBORDER_STATIC} - Displays a border suitable for a static control. wxSTATIC_BORDER - is the old name for this style. Windows only. - @style{wxBORDER_THEME} - Displays a native border suitable for a control, on the current - platform. On Windows XP or Vista, this will be a themed border; on - most other platforms a sunken border will be used. For more - information for themed borders on Windows, please see Themed - borders on Windows. - @style{wxBORDER_NONE} - Displays no border, overriding the default border style for the - window. wxNO_BORDER is the old name for this style. - @style{wxBORDER_DOUBLE} - This style is obsolete and should not be used. - @style{wxTRANSPARENT_WINDOW} - The window is transparent, that is, it will not receive paint - events. Windows only. - @style{wxTAB_TRAVERSAL} - Use this to enable tab traversal for non-dialog windows. - @style{wxWANTS_CHARS} - Use this to indicate that the window wants to get all char/key - events for all keys - even for keys like TAB or ENTER which are - usually used for dialog navigation and which wouldn't be generated - without this style. If you need to use this style in order to get - the arrows or etc., but would still like to have normal keyboard - navigation take place, you should call Navigate in response to the - key events for Tab and Shift-Tab. - @style{wxNO_FULL_REPAINT_ON_RESIZE} - On Windows, this style used to disable repainting the window - completely when its size is changed. Since this behaviour is now - the default, the style is now obsolete and no longer has an effect. - @style{wxVSCROLL} - Use this style to enable a vertical scrollbar. Notice that this - style cannot be used with native controls which don't support - scrollbars nor with top-level windows in most ports. - @style{wxHSCROLL} - Use this style to enable a horizontal scrollbar. The same - limitations as for wxVSCROLL apply to this style. - @style{wxALWAYS_SHOW_SB} - If a window has scrollbars, disable them instead of hiding them - when they are not needed (i.e. when the size of the window is big - enough to not require the scrollbars to navigate it). This style is - currently implemented for wxMSW, wxGTK and wxUniversal and does - nothing on the other platforms. - @style{wxCLIP_CHILDREN} - Use this style to eliminate flicker caused by the background being - repainted, then children being painted over them. Windows only. - @style{wxFULL_REPAINT_ON_RESIZE} - Use this style to force a complete redraw of the window whenever it - is resized instead of redrawing just the part of the window - affected by resizing. Note that this was the behaviour by default - before 2.5.1 release and that if you experience redraw problems - with code which previously used to work you may want to try this. - Currently this style applies on GTK+ 2 and Windows only, and full - repainting is always done on other platforms. - @endStyleTable - - @beginExtraStyleTable - @style{wxWS_EX_VALIDATE_RECURSIVELY} - By default, Validate/TransferDataTo/FromWindow() only work on - direct children of the window (compatible behaviour). Set this flag - to make them recursively descend into all subwindows. - @style{wxWS_EX_BLOCK_EVENTS} - wxCommandEvents and the objects of the derived classes are - forwarded to the parent window and so on recursively by default. - Using this flag for the given window allows to block this - propagation at this window, i.e. prevent the events from being - propagated further upwards. Dialogs have this flag on by default. - @style{wxWS_EX_TRANSIENT} - Don't use this window as an implicit parent for the other windows: - this must be used with transient windows as otherwise there is the - risk of creating a dialog/frame with this window as a parent which - would lead to a crash if the parent is destroyed before the child. - @style{wxWS_EX_PROCESS_IDLE} - This window should always process idle events, even if the mode set - by wxIdleEvent::SetMode is wxIDLE_PROCESS_SPECIFIED. - @style{wxWS_EX_PROCESS_UI_UPDATES} - This window should always process UI update events, even if the - mode set by wxUpdateUIEvent::SetMode is - wxUPDATE_UI_PROCESS_SPECIFIED. - @endExtraStyleTable - - @library{wxcore} - @category{FIXME} - - @see @ref overview_eventhandling "Event handling overview", - @ref overview_windowsizing "Window sizing overview" -*/ -class wxWindow : public wxEvtHandler -{ -public: - /** - Default constructor - */ - wxWindow(); - - /** - Constructs a window, which can be a child of a frame, dialog or any other - non-control window. - - @param parent - Pointer to a parent window. - @param id - Window identifier. If wxID_ANY, will automatically create an identifier. - @param pos - Window position. wxDefaultPosition indicates that wxWidgets - should generate a default position for the window. If using the wxWindow - class directly, supply - an actual position. - @param size - Window size. wxDefaultSize indicates that wxWidgets - should generate a default size for the window. If no suitable size can be - found, the - window will be sized to 20x20 pixels so that the window is visible but - obviously not - correctly sized. - @param style - Window style. For generic window styles, please see wxWindow. - @param name - Window name. - */ - wxWindow(wxWindow* parent, wxWindowID id, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = 0, - const wxString& name = wxPanelNameStr); - - /** - Destructor. Deletes all sub-windows, then deletes itself. Instead of using - the @b delete operator explicitly, you should normally - use Destroy() so that wxWidgets - can delete a window only when it is safe to do so, in idle time. - - @see @ref overview_windowdeletion "Window Deletion Overview", - Destroy(), wxCloseEvent - */ - ~wxWindow(); - - /** - This method may be overridden in the derived classes to return @false to - indicate that this control doesn't accept input at all (i.e. behaves like e.g. - wxStaticText) and so doesn't need focus. - - @see AcceptsFocusFromKeyboard() - */ - virtual bool AcceptsFocus() const; - - /** - This method may be overridden in the derived classes to return @false to - indicate that while this control can, in principle, have focus if the user - clicks it with the mouse, it shouldn't be included in the TAB traversal chain - when using the keyboard. - */ - virtual bool AcceptsFocusFromKeyboard() const; - - /** - Overridden to indicate wehter this window or one of its children accepts - focus. Usually it's the same as AcceptsFocus() but is overridden for - container windows - */ - virtual bool AcceptsFocusRecursively() const; - - /** - Adds a child window. This is called automatically by window creation - functions so should not be required by the application programmer. - Notice that this function is mostly internal to wxWidgets and shouldn't be - called by the user code. - - @param child - Child window to add. - */ - virtual void AddChild(wxWindow* child); - - /** - Call this function to force one or both scrollbars to be always shown, even if - the window is big enough to show its entire contents without scrolling. - - @since 2.9.0 - - @param hflag - Whether the horizontal scroll bar should always be visible. - @param vflag - Whether the vertical scroll bar should always be visible. - - @remarks This function is currently only implemented under Mac/Carbon. - */ - void AlwaysShowScrollbars(bool hflag, bool vflag); - - /** - Sets the cached best size value. - */ - void CacheBestSize(const wxSize& size) const; - - /** - Returns @true if the system supports transparent windows and calling - SetTransparent() may succeed. If this function - returns @false, transparent windows are definitely not supported by the - current - system. - */ - bool CanSetTransparent(); - - /** - Directs all mouse input to this window. Call ReleaseMouse() to - release the capture. - Note that wxWidgets maintains the stack of windows having captured the mouse - and when the mouse is released the capture returns to the window which had had - captured it previously and it is only really released if there were no previous - window. In particular, this means that you must release the mouse as many times - as you capture it, unless the window receives - the wxMouseCaptureLostEvent event. - Any application which captures the mouse in the beginning of some operation - must handle wxMouseCaptureLostEvent - and cancel this operation when it receives the event. The event handler must - not recapture mouse. - - @see ReleaseMouse(), wxMouseCaptureLostEvent - */ - virtual void CaptureMouse(); - - /** - A synonym for Centre(). - */ - void Center(int direction); - - /** - A synonym for CentreOnParent(). - */ - void CenterOnParent(int direction); - - /** - Centres the window. - - @param direction - Specifies the direction for the centering. May be wxHORIZONTAL, wxVERTICAL - or wxBOTH. It may also include wxCENTRE_ON_SCREEN flag - if you want to center the window on the entire screen and not on its - parent window. - - @remarks If the window is a top level one (i.e. doesn't have a parent), - it will be centered relative to the screen anyhow. - - @see Center() - */ - void Centre(int direction = wxBOTH); - - /** - Centres the window on its parent. This is a more readable synonym for - Centre(). - - @param direction - Specifies the direction for the centering. May be wxHORIZONTAL, wxVERTICAL - or wxBOTH. - - @remarks This methods provides for a way to center top level windows over - their parents instead of the entire screen. If there - is no parent or if the window is not a top level - window, then behaviour is the same as Centre(). - - @see wxTopLevelWindow::CentreOnScreen - */ - void CentreOnParent(int direction = wxBOTH); - - /** - Clears the window by filling it with the current background colour. Does not - cause an erase background event to be generated. - */ - void ClearBackground(); - - //@{ - /** - Converts to screen coordinates from coordinates relative to this window. - - @param x - A pointer to a integer value for the x coordinate. Pass the client - coordinate in, and - a screen coordinate will be passed out. - @param y - A pointer to a integer value for the y coordinate. Pass the client - coordinate in, and - a screen coordinate will be passed out. - @param pt - The client position for the second form of the function. - */ - void ClientToScreen(int* x, int* y) const; - wxPoint ClientToScreen(const wxPoint& pt) const; - //@} - - /** - Converts client area size @a size to corresponding window size. In - other words, the returned value is what would GetSize() return if this - window had client area of given size. Components with wxDefaultCoord - value are left unchanged. Note that the conversion is not always - exact, it assumes that non-client area doesn't change and so doesn't - take into account things like menu bar (un)wrapping or (dis)appearance - of the scrollbars. - - @since 2.8.8 - - @see WindowToClientSize() - */ - virtual wxSize ClientToWindowSize(const wxSize& size); - - /** - Converts window size @a size to corresponding client area size. In - other words, the returned value is what would GetClientSize() return if - this window had given window size. Components with wxDefaultCoord value - are left unchanged. - - Note that the conversion is not always exact, it assumes that - non-client area doesn't change and so doesn't take into account things - like menu bar (un)wrapping or (dis)appearance of the scrollbars. - - @since 2.8.8 - - @see ClientToWindowSize() - */ - virtual wxSize WindowToClientSize(const wxSize& size); - - /** - This function simply generates a wxCloseEvent whose - handler usually tries to close the window. It doesn't close the window - itself, however. - - @param force - @false if the window's close handler should be able to veto the destruction - of this window, @true if it cannot. - - @remarks Close calls the close handler for the window, providing an - opportunity for the window to choose whether to destroy - the window. Usually it is only used with the top level - windows (wxFrame and wxDialog classes) as the others - are not supposed to have any special OnClose() logic. - - @see @ref overview_windowdeletion "Window Deletion Overview", - Destroy(), wxCloseEvent - */ - bool Close(bool force = false); - - //@{ - /** - Converts a point or size from dialog units to pixels. - For the x dimension, the dialog units are multiplied by the average character - width - and then divided by 4. - For the y dimension, the dialog units are multiplied by the average character - height - and then divided by 8. - - @remarks Dialog units are used for maintaining a dialog's proportions - even if the font changes. - - @see ConvertPixelsToDialog() - */ - wxPoint ConvertDialogToPixels(const wxPoint& pt); - wxSize ConvertDialogToPixels(const wxSize& sz); - //@} - - //@{ - /** - Converts a point or size from pixels to dialog units. - For the x dimension, the pixels are multiplied by 4 and then divided by the - average - character width. - For the y dimension, the pixels are multiplied by 8 and then divided by the - average - character height. - - @remarks Dialog units are used for maintaining a dialog's proportions - even if the font changes. - - @see ConvertDialogToPixels() - */ - wxPoint ConvertPixelsToDialog(const wxPoint& pt); - wxSize ConvertPixelsToDialog(const wxSize& sz); - //@} - - /** - Destroys the window safely. Use this function instead of the delete operator, - since - different window classes can be destroyed differently. Frames and dialogs - are not destroyed immediately when this function is called -- they are added - to a list of windows to be deleted on idle time, when all the window's events - have been processed. This prevents problems with events being sent to - non-existent - windows. - - @return @true if the window has either been successfully deleted, or it - has been added to the list of windows pending real - deletion. - */ - virtual bool Destroy(); - - /** - Destroys all children of a window. Called automatically by the destructor. - */ - virtual void DestroyChildren(); - - /** - Disables the window. Same as @ref Enable() Enable(@false). - - @return Returns @true if the window has been disabled, @false if it had - been already disabled before the call to this function. - */ - bool Disable(); - - /** - Gets the size which best suits the window: for a control, it would be - the minimal size which doesn't truncate the control, for a panel - the - same size as it would have after a call to Fit(). - - The default implementation of this function is designed for use in container - windows, such as wxPanel, and works something like this: - -# If the window has a sizer then it is used to calculate the best size. - -# Otherwise if the window has layout constraints then those are used to - calculate the best size. - -# Otherwise if the window has children then the best size is set to be large - enough to show all the children. - -# Otherwise if there are no children then the window's minimal size will be - used as its best size. - -# Otherwise if there is no minimal size set, then the current size is used - for the best size. - - @see @ref overview_windowsizing - */ - virtual wxSize DoGetBestSize() const; - - /** - Does the window-specific updating after processing the update event. - This function is called by UpdateWindowUI() in order to check return - values in the wxUpdateUIEvent and act appropriately. - */ - virtual void DoUpdateWindowUI(wxUpdateUIEvent& event); - - /** - Enables or disables eligibility for drop file events (OnDropFiles). - - @param accept - If @true, the window is eligible for drop file events. If @false, the window - will not accept drop file events. - - @remarks Windows only. - */ - virtual void DragAcceptFiles(bool accept); - - /** - Enable or disable the window for user input. Note that when a parent window is - disabled, all of its children are disabled as well and they are reenabled again - when the parent is. - - @param enable - If @true, enables the window for input. If @false, disables the window. - - @return Returns @true if the window has been enabled or disabled, @false - if nothing was done, i.e. if the window had already - been in the specified state. - - @see IsEnabled(), Disable(), wxRadioBox::Enable - */ - virtual bool Enable(bool enable = true); - - /** - Finds the window or control which currently has the keyboard focus. - - @remarks Note that this is a static function, so it can be called without - needing a wxWindow pointer. - - @see SetFocus(), HasFocus() - */ - static wxWindow* FindFocus(); - - /** - Find a child of this window, by @a id. May return @a this if - it matches itself. - */ - wxWindow* FindWindow(long id) const; - - - /** - Find a child of this window, by name. May return @a this if - it matches itself. - */ - wxWindow* FindWindow(const wxString& name) const; - - /** - Find the first window with the given @e id. - If @a parent is @NULL, the search will start from all top-level - frames and dialog boxes; if non-@NULL, the search will be limited to the given - window hierarchy. - The search is recursive in both cases. - - @see FindWindow() - */ - static wxWindow* FindWindowById(long id, wxWindow* parent = NULL); - - /** - Find a window by its label. Depending on the type of window, the label may be a - window title - or panel item label. If @a parent is @NULL, the search will start from all - top-level - frames and dialog boxes; if non-@NULL, the search will be limited to the given - window hierarchy. - The search is recursive in both cases. - - @see FindWindow() - */ - static wxWindow* FindWindowByLabel(const wxString& label, - wxWindow* parent = NULL); - - /** - Find a window by its name (as given in a window constructor or @b Create - function call). - If @a parent is @NULL, the search will start from all top-level - frames and dialog boxes; if non-@NULL, the search will be limited to the given - window hierarchy. - The search is recursive in both cases. - If no window with such name is found, - FindWindowByLabel() is called. - - @see FindWindow() - */ - static wxWindow* FindWindowByName(const wxString& name, - wxWindow* parent = NULL); - - /** - Sizes the window so that it fits around its subwindows. - - This function won't do anything if there are no subwindows and will only really - work correctly if sizers are used for the subwindows layout. - - Also, if the window has exactly one subwindow it is better (faster and the result - is more precise as Fit() adds some margin to account for fuzziness of its calculations) - to call: - - @code - window->SetClientSize(child->GetSize()); - @endcode - - instead of calling Fit(). - - @see @ref overview_windowsizing - */ - virtual void Fit(); - - /** - Similar to Fit(), but sizes the interior (virtual) size - of a window. Mainly useful with scrolled windows to reset scrollbars after - sizing changes that do not trigger a size event, and/or scrolled windows without - an interior sizer. This function similarly won't do anything if there are no - subwindows. - */ - virtual void FitInside(); - - /** - Freezes the window or, in other words, prevents any updates from taking - place on screen, the window is not redrawn at all. - - Thaw() must be called to reenable window redrawing. Calls to these two - functions may be nested but to ensure that the window is properly - repainted again, you must thaw it exactly as many times as you froze - it. - - If the window has any children, they are recursively frozen too. - - This method is useful for visual appearance optimization (for example, - it is a good idea to use it before doing many large text insertions in - a row into a wxTextCtrl under wxGTK) but is not implemented on all - platforms nor for all controls so it is mostly just a hint to wxWidgets - and not a mandatory directive. - - @see wxWindowUpdateLocker, Thaw(), IsFrozen() - */ - virtual void Freeze(); - - /** - Gets the accelerator table for this window. See wxAcceleratorTable. - */ - wxAcceleratorTable* GetAcceleratorTable() const; - - /** - Returns the accessible object for this window, if any. - See also wxAccessible. - */ - wxAccessible* GetAccessible(); - - /** - This method is deprecated, use GetEffectiveMinSize() instead. - */ - wxSize GetAdjustedBestSize() const; - - /** - Returns the background colour of the window. - - @see SetBackgroundColour(), SetForegroundColour(), - GetForegroundColour() - */ - wxColour GetBackgroundColour() const; - - /** - Returns the background style of the window. The background style can be one of: - - wxBG_STYLE_SYSTEM - - Use the default background, as determined by - the system or the current theme. - - wxBG_STYLE_COLOUR - - Use a solid colour for the background, this - style is set automatically if you call - SetBackgroundColour() so you only need to - set it explicitly if you had changed the background style to something else - before. - - wxBG_STYLE_CUSTOM - - Don't draw the background at all, it's - supposed that it is drawn by the user-defined erase background event handler. - This style should be used to avoid flicker when the background is entirely - custom-drawn. - - wxBG_STYLE_TRANSPARET - - The background is (partially) transparent, - this style is automatically set if you call - SetTransparent() which is used to set the - transparency level. - - @see SetBackgroundColour(), GetForegroundColour(), - SetBackgroundStyle(), SetTransparent() - */ - virtual wxBackgroundStyle GetBackgroundStyle() const; - - /** - This functions returns the best acceptable minimal size for the window. For - example, for a static control, it will be the minimal size such that the - control label is not truncated. For windows containing subwindows (typically - wxPanel), the size returned by this function will be the - same as the size the window would have had after calling - Fit(). - */ - wxSize GetBestSize() const; - - /** - Returns the currently captured window. - - @see HasCapture(), CaptureMouse(), ReleaseMouse(), - wxMouseCaptureLostEvent, wxMouseCaptureChangedEvent - */ - static wxWindow* GetCapture(); - - /** - Returns the caret() associated with the window. - */ - wxCaret* GetCaret() const; - - /** - Returns the character height for this window. - */ - virtual int GetCharHeight() const; - - /** - Returns the average character width for this window. - */ - virtual int GetCharWidth() const; - - //@{ - /** - Returns a reference to the list of the window's children. @c wxWindowList - is a type-safe wxList-like class whose elements are of type @c wxWindow*. - */ - wxWindowList& GetChildren(); - const wxWindowList& GetChildren() const; - //@} - - /** - Returns the default font and colours which are used by the control. This is - useful if you want to use the same font or colour in your own control as in a - standard control -- which is a much better idea than hard coding specific - colours or fonts which might look completely out of place on the users - system, especially if it uses themes. - The @a variant parameter is only relevant under Mac currently and is - ignore under other platforms. Under Mac, it will change the size of the - returned font. See SetWindowVariant() - for more about this. - This static method is "overridden" in many derived classes and so calling, - for example, wxButton::GetClassDefaultAttributes() will typically - return the values appropriate for a button which will be normally different - from those returned by, say, wxListCtrl::GetClassDefaultAttributes(). - The @c wxVisualAttributes structure has at least the fields - @c font, @c colFg and @c colBg. All of them may be invalid - if it was not possible to determine the default control appearance or, - especially for the background colour, if the field doesn't make sense as is - the case for @c colBg for the controls with themed background. - - @see InheritAttributes() - */ - static wxVisualAttributes GetClassDefaultAttributes(wxWindowVariant variant = wxWINDOW_VARIANT_NORMAL); - - //@{ - /** - Returns the size of the window 'client area' in pixels. The client area is the - area which may be drawn on by the programmer, excluding title bar, border, - scrollbars, etc. - Note that if this window is a top-level one and it is currently minimized, the - return size is empty (both width and height are 0). - - @param width - Receives the client width in pixels. - @param height - Receives the client height in pixels. - - @see GetSize(), GetVirtualSize() - */ - void GetClientSize(int* width, int* height) const; - wxSize GetClientSize() const; - //@} - - /** - Returns a pointer to the window's layout constraints, or @NULL if there are none. - */ - wxLayoutConstraints* GetConstraints() const; - - /** - Return the sizer that this window is a member of, if any, otherwise - @NULL. - */ - wxSizer* GetContainingSizer() const; - - /** - Return the cursor associated with this window. - - @see SetCursor() - */ - const wxCursor& GetCursor() const; - - /** - Currently this is the same as calling - wxWindow::GetClassDefaultAttributes(wxWindow::GetWindowVariant()). - One advantage of using this function compared to the static version is that - the call is automatically dispatched to the correct class (as usual with - virtual functions) and you don't have to specify the class name explicitly. - The other one is that in the future this function could return different - results, for example it might return a different font for an "Ok" button - than for a generic button if the users GUI is configured to show such buttons - in bold font. Of course, the down side is that it is impossible to call this - function without actually having an object to apply it to whereas the static - version can be used without having to create an object first. - */ - virtual wxVisualAttributes GetDefaultAttributes() const; - - /** - Returns the associated drop target, which may be @NULL. - - @see SetDropTarget(), @ref overview_dnd - */ - wxDropTarget* GetDropTarget() const; - - /** - Merges the window's best size into the min size and returns the result. - This is the value used by sizers to determine the appropriate - ammount of space to allocate for the widget. - - @see GetBestSize(), SetInitialSize(), @ref overview_windowsizing - */ - wxSize GetEffectiveMinSize() const; - - /** - Returns the event handler for this window. By default, the window is its - own event handler. - - @see SetEventHandler(), PushEventHandler(), - PopEventHandler(), wxEvtHandler::ProcessEvent, wxEvtHandler - */ - wxEvtHandler* GetEventHandler() const; - - /** - Returns the extra style bits for the window. - */ - long GetExtraStyle() const; - - /** - Returns the font for this window. - - @see SetFont() - */ - wxFont GetFont() const; - - /** - Returns the foreground colour of the window. - - @remarks The interpretation of foreground colour is open to - interpretation according to the window class; it may be - the text colour or other colour, or it may not be used - at all. - - @see SetForegroundColour(), SetBackgroundColour(), - GetBackgroundColour() - */ - wxColour GetForegroundColour(); - - /** - Returns the grandparent of a window, or @NULL if there isn't one. - */ - wxWindow* GetGrandParent() const; - - /** - Returns the platform-specific handle of the physical window. Cast it to an - appropriate - handle, such as @b HWND for Windows, @b Widget for Motif, @b GtkWidget for GTK - or @b WinHandle for PalmOS. - */ - void* GetHandle() const; - - /** - Gets the help text to be used as context-sensitive help for this window. - Note that the text is actually stored by the current wxHelpProvider - implementation, - and not in the window object itself. - - @see SetHelpText(), GetHelpTextAtPoint(), wxHelpProvider - */ - virtual wxString GetHelpText() const; - - /** - Gets the help text to be used as context-sensitive help for this window. This - method should be overridden if the help message depends on the position inside - the window, otherwise GetHelpText() can be used. - - @param point - Coordinates of the mouse at the moment of help event emission. - @param origin - Help event origin, see also wxHelpEvent::GetOrigin. - */ - virtual wxString GetHelpTextAtPoint(const wxPoint point, - wxHelpEvent::Origin origin) const; - - /** - Returns the identifier of the window. - - @remarks Each window has an integer identifier. If the application has - not provided one (or the default wxID_ANY) an unique - identifier with a negative value will be generated. - - @see SetId(), @ref overview_windowids "Window identifiers" - */ - int GetId() const; - - /** - Generic way of getting a label from any window, for - identification purposes. - - @remarks The interpretation of this function differs from class to class. - For frames and dialogs, the value returned is the - title. For buttons or static text controls, it is the - button text. This function can be useful for - meta-programs (such as testing tools or special-needs - access programs) which need to identify windows by name. - */ - virtual wxString GetLabel() const; - - /** - Returns the maximum size of window's client area. - This is an indication to the sizer layout mechanism that this is the maximum - possible size as well as the upper bound on window's size settable using - SetClientSize(). - - @see GetMaxSize() - */ - wxSize GetMaxClientSize() const; - - /** - Returns the maximum size of the window. This is an indication to the sizer - layout mechanism that this is the maximum possible size as well as the upper - bound on window's size settable using SetSize(). - - @see GetMaxClientSize() - */ - wxSize GetMaxSize() const; - - /** - Returns the minimum size of window's client area, an indication to the sizer - layout mechanism that this is the minimum required size of its client area. It - normally just returns the value set by - SetMinClientSize(), but it can be overridden - to do the calculation on demand. - - @see GetMinSize() - */ - virtual wxSize GetMinClientSize() const; - - /** - Returns the minimum size of the window, an indication to the sizer layout - mechanism that this is the minimum required size. - - This method normally just returns the value set by SetMinSize(), but it - can be overridden to do the calculation on demand. - - @see GetMinClientSize() - */ - virtual wxSize GetMinSize() const; - - /** - Returns the window's name. - - @remarks This name is not guaranteed to be unique; it is up to the - programmer to supply an appropriate name in the window - constructor or via SetName(). - - @see SetName() - */ - virtual wxString GetName() const; - - /** - Returns the next window after this one among the parent children or @NULL if - this window is the last child. - - @since 2.8.8 - - @see GetPrevSibling() - */ - wxWindow* GetNextSibling() const; - - /** - Returns the parent of the window, or @NULL if there is no parent. - */ - virtual wxWindow* GetParent() const; - - //@{ - /** - This function shows a popup menu at the given position in this window and - returns the selected id. It can be more convenient than the general purpose - PopupMenu() function for simple menus proposing a - choice in a list of strings to the user. - - @param menu - The menu to show - @param pos - The position at which to show the menu in client coordinates - @param x - The horizontal position of the menu - @param y - The vertical position of the menu - - @return The selected menu item id or wxID_NONE if none selected or an - error occurred. - */ - int GetPopupMenuSelectionFromUser(wxMenu& menu, - const wxPoint& pos); - int GetPopupMenuSelectionFromUser(wxMenu& menu, int x, int y); - //@} - - //@{ - /** - This gets the position of the window in pixels, relative to the parent window - for the child windows or relative to the display origin for the top level - windows. - - @param x - Receives the x position of the window if non-@NULL. - @param y - Receives the y position of the window if non-@NULL. - - @see GetScreenPosition() - */ - void GetPosition(int* x, int* y) const; - wxPoint GetPosition() const; - //@} - - /** - Returns the previous window before this one among the parent children or @c - @NULL if - this window is the first child. - - @since 2.8.8 - - @see GetNextSibling() - */ - wxWindow* GetPrevSibling() const; - - /** - Returns the position and size of the window as a wxRect object. - - @see GetScreenRect() - */ - wxRect GetRect() const; - - //@{ - /** - Returns the window position in screen coordinates, whether the window is a - child window or a top level one. - - @param x - Receives the x position of the window on the screen if non-@NULL. - @param y - Receives the y position of the window on the screen if non-@NULL. - - @see GetPosition() - */ - void GetScreenPosition(int* x, int* y) const; - wxPoint GetScreenPosition() const; - //@} - - /** - Returns the position and size of the window on the screen as a - wxRect object. - - @see GetRect() - */ - wxRect GetScreenRect() const; - - /** - Returns the built-in scrollbar position. - - @see See SetScrollbar() - */ - virtual int GetScrollPos(int orientation); - - /** - Returns the built-in scrollbar range. - - @see SetScrollbar() - */ - virtual int GetScrollRange(int orientation); - - /** - Returns the built-in scrollbar thumb size. - - @see SetScrollbar() - */ - virtual int GetScrollThumb(int orientation); - - //@{ - /** - Returns the size of the entire window in pixels, including title bar, border, - scrollbars, etc. - Note that if this window is a top-level one and it is currently minimized, the - returned size is the restored window size, not the size of the window icon. - - @param width - Receives the window width. - @param height - Receives the window height. - - @see GetClientSize(), GetVirtualSize() - */ - void GetSize(int* width, int* height) const; - const wxSize GetSize() const; - //@} - - /** - Return the sizer associated with the window by a previous call to - SetSizer() or @NULL. - */ - wxSizer* GetSizer() const; - - //@{ - /** - Gets the dimensions of the string as it would be drawn on the - window with the currently selected font. - The text extent is returned in @a w and @a h pointers (first form) or as a - wxSize object (second form). - - @param string - String whose extent is to be measured. - @param w - Return value for width. - @param h - Return value for height. - @param descent - Return value for descent (optional). - @param externalLeading - Return value for external leading (optional). - @param font - Font to use instead of the current window font (optional). - @param use16 - If @true, string contains 16-bit characters. The default is @false. - */ - virtual void GetTextExtent(const wxString& string, int* w, - int* h, - int* descent = NULL, - int* externalLeading = NULL, - const wxFont* font = NULL, - bool use16 = false) const; - const wxSize GetTextExtent(const wxString& string) const; - //@} - - /** - Get the associated tooltip or @NULL if none. - */ - wxToolTip* GetToolTip() const; - - /** - Returns the region specifying which parts of the window have been damaged. - Should - only be called within an wxPaintEvent handler. - - @see wxRegion, wxRegionIterator - */ - virtual wxRegion GetUpdateRegion() const; - - /** - Returns a pointer to the current validator for the window, or @NULL if there is - none. - */ - wxValidator* GetValidator() const; - - //@{ - /** - This gets the virtual size of the window in pixels. By default it - returns the client size of the window, but after a call to - SetVirtualSize() it will return - that size. - - @param width - Receives the window virtual width. - @param height - Receives the window virtual height. - */ - void GetVirtualSize(int* width, int* height) const; - const wxSize GetVirtualSize() const; - //@} - - /** - Returns the size of the left/right and top/bottom borders of this window in x - and y components of the result respectively. - */ - wxSize GetWindowBorderSize() const; - - /** - Gets the window style that was passed to the constructor or @b Create - method. @b GetWindowStyle() is another name for the same function. - */ - long GetWindowStyleFlag() const; - - /** - Returns the value previously passed to - SetWindowVariant(). - */ - wxWindowVariant GetWindowVariant() const; - - /** - This function will generate the appropriate call to - Navigate() if the key event is one normally used for - keyboard navigation and return @true in this case. - - @return Returns @true if the key pressed was for navigation and was - handled, @false otherwise. - - @see Navigate() - */ - bool HandleAsNavigationKey(const wxKeyEvent& event); - - /** - Shorthand for @c - wxWindow::GetEventHandler()-wxEvtHandler::SafelyProcessEvent(event). - */ - bool HandleWindowEvent(wxEvent& event); - - /** - Returns @true if this window has the current mouse capture. - - @see CaptureMouse(), ReleaseMouse(), wxMouseCaptureLostEvent, - wxMouseCaptureChangedEvent - */ - virtual bool HasCapture() const; - - /** - Returns @true if the window has the given @a exFlag bit set in its - extra styles. - - @see SetExtraStyle() - */ - bool HasExtraStyle(int exFlag) const; - - /** - Returns @true if the window has the given @a flag bit set. - */ - bool HasFlag(int flag) const; - - /** - Returns @true if the window (or in case of composite controls, its main - child window) has focus. - - @see FindFocus() - */ - virtual bool HasFocus() const; - - /** - This method should be overridden to return @true if this window has - multiple pages. All standard class with multiple pages such as - wxNotebook, wxListbook and - wxTreebook already override it to return @true - and user-defined classes with similar behaviour should do it as well to allow - the library to handle such windows appropriately. - */ - virtual bool HasMultiplePages() const; - - /** - Returns @true if this window has a scroll bar for this orientation. - - @param orient - Orientation to check, either wxHORIZONTAL or wxVERTICAL. - */ - virtual bool HasScrollbar(int orient) const; - - /** - Returns @true if this window background is transparent (as, for example, for - wxStaticText) and should show the parent window background. - This method is mostly used internally by the library itself and you normally - shouldn't have to call it. You may, however, have to override it in your - wxWindow-derived class to ensure that background is painted correctly. - */ - virtual bool HasTransparentBackground() const; - - /** - Equivalent to calling wxWindow::Show(@false). - */ - bool Hide(); - - /** - This function hides a window, like Hide(), but using a special visual - effect if possible. - - The parameters of this function are the same as for ShowWithEffect(), - please see their description there. - - @since 2.9.0 - */ - virtual bool HideWithEffect(wxShowEffect effect, - unsigned timeout = 0); - - /** - This function is (or should be, in case of custom controls) called during - window creation to intelligently set up the window visual attributes, that is - the font and the foreground and background colours. - By "intelligently" the following is meant: by default, all windows use their - own @ref GetClassDefaultAttributes() default attributes. However - if some of the parents attributes are explicitly (that is, using - SetFont() and not - wxWindow::SetOwnFont) changed and if the - corresponding attribute hadn't been explicitly set for this window itself, - then this window takes the same value as used by the parent. In addition, if - the window overrides ShouldInheritColours() - to return @false, the colours will not be changed no matter what and only the - font might. - This rather complicated logic is necessary in order to accommodate the - different usage scenarios. The most common one is when all default attributes - are used and in this case, nothing should be inherited as in modern GUIs - different controls use different fonts (and colours) than their siblings so - they can't inherit the same value from the parent. However it was also deemed - desirable to allow to simply change the attributes of all children at once by - just changing the font or colour of their common parent, hence in this case we - do inherit the parents attributes. - */ - void InheritAttributes(); - - /** - Sends an @c wxEVT_INIT_DIALOG event, whose handler usually transfers data - to the dialog via validators. - */ - void InitDialog(); - - /** - Resets the cached best size value so it will be recalculated the next time it - is needed. - */ - void InvalidateBestSize(); - - /** - Returns @true if the window contents is double-buffered by the system, i.e. if - any drawing done on the window is really done on a temporary backing surface - and transferred to the screen all at once later. - - @see wxBufferedDC - */ - virtual bool IsDoubleBuffered() const; - - /** - Returns @true if the window is enabled, i.e. if it accepts user input, @c - @false - otherwise. - Notice that this method can return @false even if this window itself hadn't - been explicitly disabled when one of its parent windows is disabled. To get the - intrinsic status of this window, use - IsThisEnabled() - - @see Enable() - */ - virtual bool IsEnabled() const; - - //@{ - /** - Returns @true if the given point or rectangle area has been exposed since the - last repaint. Call this in an paint event handler to optimize redrawing by - only redrawing those areas, which have been exposed. - */ - bool IsExposed(int x, int y) const; - const bool IsExposed(wxPoint amp;pt) const; - const bool IsExposed(int x, int y, int w, int h) const; - const bool IsExposed(wxRect amp;rect) const; - //@} - - /** - Returns @true if the window is currently frozen by a call to - Freeze(). - - @see Freeze(), Thaw() - */ - virtual bool IsFrozen() const; - - /** - Returns @true if the window is retained, @false otherwise. - - @remarks Retained windows are only available on X platforms. - */ - virtual bool IsRetained() const; - - /** - Return whether a scrollbar is always shown. - - @param orient - Orientation to check, either wxHORIZONTAL or wxVERTICAL. - - @see AlwaysShowScrollbars() - */ - bool IsScrollbarAlwaysShown(int orient); - - /** - Returns @true if the window is shown, @false if it has been hidden. - - @see IsShownOnScreen() - */ - virtual bool IsShown() const; - - /** - Returns @true if the window is physically visible on the screen, i.e. it - is shown and all its parents up to the toplevel window are shown as well. - - @see IsShown() - */ - virtual bool IsShownOnScreen() const; - - /** - Returns @true if this window is intrinsically enabled, @false otherwise, - i.e. - if @ref Enable() Enable(@false) had been called. This method is - mostly used for wxWidgets itself, user code should normally use - IsEnabled() instead. - */ - bool IsThisEnabled() const; - - /** - Returns @true if the given window is a top-level one. Currently all frames and - dialogs are considered to be top-level windows (even if they have a parent - window). - */ - bool IsTopLevel() const; - - /** - Invokes the constraint-based layout algorithm or the sizer-based algorithm - for this window. - - See SetAutoLayout(): when auto layout is on, this function gets called automatically - when the window is resized. - - @see @ref overview_windowsizing - */ - void Layout(); - - /** - Lowers the window to the bottom of the window hierarchy (Z-order). - - @see Raise() - */ - void Lower(); - - /** - Disables all other windows in the application so that - the user can only interact with this window. - - @param flag - If @true, this call disables all other windows in the application so that - the user can only interact with this window. If @false, the effect is - reversed. - */ - virtual void MakeModal(bool flag); - - //@{ - /** - Moves the window to the given position. - - @param x - Required x position. - @param y - Required y position. - @param pt - wxPoint object representing the position. - - @remarks Implementations of SetSize can also implicitly implement the - Move() function, which is defined in the base - wxWindow class as the call: - - @see SetSize() - */ - void Move(int x, int y); - void Move(const wxPoint& pt); - //@} - - /** - Moves this window in the tab navigation order after the specified @e win. - This means that when the user presses @c TAB key on that other window, - the focus switches to this window. - Default tab order is the same as creation order, this function and - MoveBeforeInTabOrder() allow to change - it after creating all the windows. - - @param win - A sibling of this window which should precede it in tab order, - must not be @NULL - */ - void MoveAfterInTabOrder(wxWindow* win); - - /** - Same as MoveAfterInTabOrder() except that - it inserts this window just before @a win instead of putting it right after - it. - */ - void MoveBeforeInTabOrder(wxWindow* win); - - /** - Performs a keyboard navigation action starting from this window. This method is - equivalent to calling NavigateIn() method on the - parent window. - - @param flags - A combination of wxNavigationKeyEvent::IsForward and - wxNavigationKeyEvent::WinChange. - - @return Returns @true if the focus was moved to another window or @false - if nothing changed. - - @remarks You may wish to call this from a text control custom keypress - handler to do the default navigation behaviour for the - tab key, since the standard default behaviour for a - multiline text control with the wxTE_PROCESS_TAB style - is to insert a tab and not navigate to the next - control. See also wxNavigationKeyEvent and - HandleAsNavigationKey. - */ - bool Navigate(int flags = wxNavigationKeyEvent::IsForward); - - /** - Performs a keyboard navigation action inside this window. - See Navigate() for more information. - */ - bool NavigateIn(int flags = wxNavigationKeyEvent::IsForward); - - /** - Create a new ID or range of IDs that are not currently in use. The - IDs will be reserved until assigned to a wxWindowIDRef() - or unreserved with UnreserveControlId(). - See @ref overview_windowids "Window IDs Overview" for more information. - - @param count - The number of sequential IDs to reserve. - - @return Returns the ID or the first ID of the range, or wxID_NONE if the - specified number of identifiers couldn't be allocated. - - @see UnreserveControlId(), wxIdManager, @ref overview_windowids - "Window IDs Overview" - */ - static wxWindowID NewControlId(int count = 1); - - /** - This virtual function is normally only used internally, but - sometimes an application may need it to implement functionality - that should not be disabled by an application defining an OnIdle - handler in a derived class. - This function may be used to do delayed painting, for example, - and most implementations call UpdateWindowUI() - in order to send update events to the window in idle time. - */ - virtual void OnInternalIdle(); - - /** - Same as #ScrollLines (-1). - */ - bool LineUp(); - - /** - Same as #ScrollLines (1). - */ - bool LineDown(); - - /** - Same as #ScrollPages (-1). - */ - bool PageUp(); - - /** - Same as #ScrollPages (1). - */ - bool PageDown(); - - - /** - Removes and returns the top-most event handler on the event handler stack. - - @param deleteHandler - If this is @true, the handler will be deleted after it is removed. The - default value is @false. - - @see SetEventHandler(), GetEventHandler(), - PushEventHandler(), wxEvtHandler::ProcessEvent, wxEvtHandler - */ - wxEvtHandler* PopEventHandler(bool deleteHandler = false) const; - - //@{ - /** - Pops up the given menu at the specified coordinates, relative to this - window, and returns control when the user has dismissed the menu. If a - menu item is selected, the corresponding menu event is generated and will be - processed as usually. If the coordinates are not specified, current mouse - cursor position is used. - - @param menu - Menu to pop up. - @param pos - The position where the menu will appear. - @param x - Required x position for the menu to appear. - @param y - Required y position for the menu to appear. - - @remarks Just before the menu is popped up, wxMenu::UpdateUI is called to - ensure that the menu items are in the correct state. - The menu does not get deleted by the window. - - @see wxMenu - */ - bool PopupMenu(wxMenu* menu, - const wxPoint& pos = wxDefaultPosition); - bool PopupMenu(wxMenu* menu, int x, int y); - //@} - - /** - Pushes this event handler onto the event stack for the window. - - @param handler - Specifies the handler to be pushed. - - @remarks An event handler is an object that is capable of processing the - events sent to a window. By default, the window is its - own event handler, but an application may wish to - substitute another, for example to allow central - implementation of event-handling for a variety of - different window classes. - - @see SetEventHandler(), GetEventHandler(), - PopEventHandler(), wxEvtHandler::ProcessEvent, wxEvtHandler - */ - void PushEventHandler(wxEvtHandler* handler); - - /** - Raises the window to the top of the window hierarchy (Z-order). - In current version of wxWidgets this works both for managed and child windows. - - @see Lower() - */ - void Raise(); - - /** - Causes this window, and all of its children recursively (except under wxGTK1 - where this is not implemented), to be repainted. Note that repainting doesn't - happen immediately but only during the next event loop iteration, if you need - to update the window immediately you should use Update() - instead. - - @param eraseBackground - If @true, the background will be - erased. - @param rect - If non-@NULL, only the given rectangle will - be treated as damaged. - - @see RefreshRect() - */ - virtual void Refresh(bool eraseBackground = true, - const wxRect* rect = NULL); - - /** - Redraws the contents of the given rectangle: only the area inside it will be - repainted. - This is the same as Refresh() but has a nicer syntax - as it can be called with a temporary wxRect object as argument like this - @c RefreshRect(wxRect(x, y, w, h)). - */ - void RefreshRect(const wxRect& rect, bool eraseBackground = true); - - /** - Registers a system wide hotkey. Every time the user presses the hotkey - registered here, this window - will receive a hotkey event. It will receive the event even if the application - is in the background - and does not have the input focus because the user is working with some other - application. - - @param hotkeyId - Numeric identifier of the hotkey. For applications this must be between 0 - and 0xBFFF. If - this function is called from a shared DLL, it must be a system wide unique - identifier between 0xC000 and 0xFFFF. - This is a MSW specific detail. - @param modifiers - A bitwise combination of wxMOD_SHIFT, wxMOD_CONTROL, wxMOD_ALT - or wxMOD_WIN specifying the modifier keys that have to be pressed along - with the key. - @param virtualKeyCode - The virtual key code of the hotkey. - - @return @true if the hotkey was registered successfully. @false if some - other application already registered a hotkey with this - modifier/virtualKeyCode combination. - - @remarks Use EVT_HOTKEY(hotkeyId, fnc) in the event table to capture the - event. This function is currently only implemented - under Windows. It is used in the Windows CE port for - detecting hardware button presses. - - @see UnregisterHotKey() - */ - bool RegisterHotKey(int hotkeyId, int modifiers, - int virtualKeyCode); - - /** - Releases mouse input captured with CaptureMouse(). - - @see CaptureMouse(), HasCapture(), ReleaseMouse(), - wxMouseCaptureLostEvent, wxMouseCaptureChangedEvent - */ - virtual void ReleaseMouse(); - - /** - Removes a child window. This is called automatically by window deletion - functions so should not be required by the application programmer. - Notice that this function is mostly internal to wxWidgets and shouldn't be - called by the user code. - - @param child - Child window to remove. - */ - virtual void RemoveChild(wxWindow* child); - - /** - Find the given @a handler in the windows event handler chain and remove (but - not delete) it from it. - - @param handler - The event handler to remove, must be non-@NULL and - must be present in this windows event handlers chain - - @return Returns @true if it was found and @false otherwise (this also - results in an assert failure so this function should - only be called when the handler is supposed to be - there). - - @see PushEventHandler(), PopEventHandler() - */ - bool RemoveEventHandler(wxEvtHandler* handler); - - /** - Reparents the window, i.e the window will be removed from its - current parent window (e.g. a non-standard toolbar in a wxFrame) - and then re-inserted into another. - - @param newParent - New parent. - */ - virtual bool Reparent(wxWindow* newParent); - - //@{ - /** - Converts from screen to client window coordinates. - - @param x - Stores the screen x coordinate and receives the client x coordinate. - @param y - Stores the screen x coordinate and receives the client x coordinate. - @param pt - The screen position for the second form of the function. - */ - virtual void ScreenToClient(int* x, int* y) const; - const virtual wxPoint ScreenToClient(const wxPoint& pt) const; - //@} - - /** - Scrolls the window by the given number of lines down (if @a lines is - positive) or up. - - @return Returns @true if the window was scrolled, @false if it was already - on top/bottom and nothing was done. - - @remarks This function is currently only implemented under MSW and - wxTextCtrl under wxGTK (it also works for wxScrolled classes - under all platforms). - - @see ScrollPages() - */ - virtual bool ScrollLines(int lines); - - /** - Scrolls the window by the given number of pages down (if @a pages is - positive) or up. - - @return Returns @true if the window was scrolled, @false if it was already - on top/bottom and nothing was done. - - @remarks This function is currently only implemented under MSW and wxGTK. - - @see ScrollLines() - */ - virtual bool ScrollPages(int pages); - - /** - Physically scrolls the pixels in the window and move child windows accordingly. - - @param dx - Amount to scroll horizontally. - @param dy - Amount to scroll vertically. - @param rect - Rectangle to scroll, if it is @NULL, the whole window is - scrolled (this is always the case under wxGTK which doesn't support this - parameter) - - @remarks Note that you can often use wxScrolled instead of using this - function directly. - */ - virtual void ScrollWindow(int dx, int dy, - const wxRect* rect = NULL); - - /** - Sets the accelerator table for this window. See wxAcceleratorTable. - */ - virtual void SetAcceleratorTable(const wxAcceleratorTable& accel); - - /** - Sets the accessible for this window. Any existing accessible for this window - will be deleted first, if not identical to @e accessible. - See also wxAccessible. - */ - void SetAccessible(wxAccessible* accessible); - - /** - Determines whether the Layout() function will - be called automatically when the window is resized. Please note that this only - happens for the windows usually used to contain children, namely - wxPanel and wxTopLevelWindow - (and the classes deriving from them). - This method is called implicitly by - SetSizer() but if you use - SetConstraints() you should call it - manually or otherwise the window layout won't be correctly updated when its - size changes. - - @param autoLayout - Set this to @true if you wish the Layout function to be - called automatically when the window is resized. - - @see SetConstraints() - */ - void SetAutoLayout(bool autoLayout); - - /** - Sets the background colour of the window. - Please see InheritAttributes() for - explanation of the difference between this method and - SetOwnBackgroundColour(). - - @param colour - The colour to be used as the background colour, pass - wxNullColour to reset to the default colour. - - @remarks The background colour is usually painted by the default - wxEraseEvent event handler function under Windows and - automatically under GTK. - - @see GetBackgroundColour(), SetForegroundColour(), - GetForegroundColour(), ClearBackground(), - Refresh(), wxEraseEvent - */ - virtual bool SetBackgroundColour(const wxColour& colour); - - /** - Sets the background style of the window. see - GetBackgroundStyle() for the description - of the possible style values. - - @see SetBackgroundColour(), GetForegroundColour(), - SetTransparent() - */ - virtual void SetBackgroundStyle(wxBackgroundStyle style); - - /** - This method is only implemented by ports which have support for - native TAB traversal (such as GTK+ 2.0). It is called by wxWidgets' - container control code to give the native system a hint when - doing TAB traversal. A call to this does not disable or change - the effect of programmatically calling - SetFocus(). - - @see wxFocusEvent, wxPanel::SetFocus, wxPanel::SetFocusIgnoringChildren - */ - virtual void SetCanFocus(bool canFocus); - - /** - Sets the caret() associated with the window. - */ - void SetCaret(wxCaret* caret) const; - - //@{ - /** - This sets the size of the window client area in pixels. Using this function to - size a window - tends to be more device-independent than SetSize(), since the application need - not - worry about what dimensions the border or title bar have when trying to fit the - window - around panel items, for example. - - @param width - The required client area width. - @param height - The required client area height. - @param size - The required client size. - */ - virtual void SetClientSize(int width, int height); - virtual void SetClientSize(const wxSize& size); - //@} - - /** - Sets the window to have the given layout constraints. The window - will then own the object, and will take care of its deletion. - If an existing layout constraints object is already owned by the - window, it will be deleted. - - @param constraints - The constraints to set. Pass @NULL to disassociate and delete the window's - constraints. - - @remarks You must call SetAutoLayout() to tell a window to use - the constraints automatically in OnSize; otherwise, you - must override OnSize and call Layout() explicitly. When - setting both a wxLayoutConstraints and a wxSizer, only - the sizer will have effect. - */ - void SetConstraints(wxLayoutConstraints* constraints); - - /** - This normally does not need to be called by user code. It is called - when a window is added to a sizer, and is used so the window can - remove itself from the sizer when it is destroyed. - */ - void SetContainingSizer(wxSizer* sizer); - - /** - Sets the window's cursor. Notice that the window cursor also sets it for the - children of the window implicitly. - The @a cursor may be @c wxNullCursor in which case the window cursor will - be reset back to default. - - @param cursor - Specifies the cursor that the window should normally display. - - @see ::wxSetCursor, wxCursor - */ - virtual void SetCursor(const wxCursor& cursor); - - /** - Associates a drop target with this window. - If the window already has a drop target, it is deleted. - - @see GetDropTarget(), @ref overview_dnd - */ - void SetDropTarget(wxDropTarget* target); - - /** - Sets the event handler for this window. - - @param handler - Specifies the handler to be set. - - @remarks An event handler is an object that is capable of processing the - events sent to a window. By default, the window is its - own event handler, but an application may wish to - substitute another, for example to allow central - implementation of event-handling for a variety of - different window classes. - - @see GetEventHandler(), PushEventHandler(), - PopEventHandler(), wxEvtHandler::ProcessEvent, wxEvtHandler - */ - void SetEventHandler(wxEvtHandler* handler); - - /** - Sets the extra style bits for the window. The currently defined extra style - bits are: - - @b wxWS_EX_VALIDATE_RECURSIVELY - - TransferDataTo/FromWindow() - and Validate() methods will recursively descend into all children of the - window if it has this style flag set. - - @b wxWS_EX_BLOCK_EVENTS - - Normally, the command - events are propagated upwards to the window parent recursively until a handler - for them is found. Using this style allows to prevent them from being - propagated beyond this window. Notice that wxDialog has this style on by - default for the reasons explained in the - @ref overview_eventhandling "Event Handling Overview". - - @b wxWS_EX_TRANSIENT - - This can be used to prevent a - window from being used as an implicit parent for the dialogs which were - created without a parent. It is useful for the windows which can disappear at - any moment as creating children of such windows results in fatal problems. - - @b wxWS_EX_CONTEXTHELP - - Under Windows, puts a query - button on the caption. When pressed, Windows will go into a context-sensitive - help mode and wxWidgets will send a wxEVT_HELP event if the user clicked on an - application window. - This style cannot be used together with wxMAXIMIZE_BOX or wxMINIMIZE_BOX, so - these two styles are automatically turned of if this one is used. - - @b wxWS_EX_PROCESS_IDLE - - This window should always process idle events, even - if the mode set by wxIdleEvent::SetMode is wxIDLE_PROCESS_SPECIFIED. - - @b wxWS_EX_PROCESS_UI_UPDATES - - This window should always process UI update events, - even if the mode set by wxUpdateUIEvent::SetMode is - wxUPDATE_UI_PROCESS_SPECIFIED. - */ - void SetExtraStyle(long exStyle); - - /** - This sets the window to receive keyboard input. - - @see HasFocus(), wxFocusEvent, wxPanel::SetFocus, - wxPanel::SetFocusIgnoringChildren - */ - virtual void SetFocus(); - - /** - This function is called by wxWidgets keyboard navigation code when the user - gives the focus to this window from keyboard (e.g. using @c TAB key). - By default this method simply calls SetFocus() but - can be overridden to do something in addition to this in the derived classes. - */ - virtual void SetFocusFromKbd(); - - /** - Sets the font for this window. This function should not be called for the - parent window if you don't want its font to be inherited by its children, - use SetOwnFont() instead in this case and - see InheritAttributes() for more - explanations. - Please notice that the given font is not automatically used for - wxPaintDC objects associated with this window, you need to - call wxDC::SetFont too. However this font is used by - any standard controls for drawing their text as well as by - GetTextExtent(). - - @param font - Font to associate with this window, pass - wxNullFont to reset to the default font. - - @return @true if the want was really changed, @false if it was already set - to this font and so nothing was done. - - @see GetFont(), InheritAttributes() - */ - bool SetFont(const wxFont& font); - - /** - Sets the foreground colour of the window. - Please see InheritAttributes() for - explanation of the difference between this method and - SetOwnForegroundColour(). - - @param colour - The colour to be used as the foreground colour, pass - wxNullColour to reset to the default colour. - - @remarks The interpretation of foreground colour is open to - interpretation according to the window class; it may be - the text colour or other colour, or it may not be used - at all. - - @see GetForegroundColour(), SetBackgroundColour(), - GetBackgroundColour(), ShouldInheritColours() - */ - virtual void SetForegroundColour(const wxColour& colour); - - /** - Sets the help text to be used as context-sensitive help for this window. - Note that the text is actually stored by the current wxHelpProvider - implementation, - and not in the window object itself. - - @see GetHelpText(), wxHelpProvider::AddHelp() - */ - virtual void SetHelpText(const wxString& helpText); - - /** - Sets the identifier of the window. - - @remarks Each window has an integer identifier. If the application has - not provided one, an identifier will be generated. - Normally, the identifier should be provided on creation - and should not be modified subsequently. - - @see GetId(), @ref overview_windowids "Window identifiers" - */ - void SetId(int id); - - /** - Sets the initial window size if none is given (i.e. at least one of the - components of the size passed to ctor/Create() is wxDefaultCoord). - */ - virtual void SetInitialBestSize(const wxSize& size); - - /** - A @e smart SetSize that will fill in default size components with the - window's @e best size values. - - Also sets the window's minsize to the value passed in for use with sizers. - This means that if a full or partial size is passed to this function then - the sizers will use that size instead of the results of GetBestSize() to - determine the minimum needs of the window for layout. - - Most controls will use this to set their initial size, and their min - size to the passed in value (if any.) - - @see SetSize(), GetBestSize(), GetEffectiveMinSize(), - @ref overview_windowsizing - */ - void SetInitialSize(const wxSize& size = wxDefaultSize); - - /** - Sets the window's label. - - @param label - The window label. - - @see GetLabel() - */ - virtual void SetLabel(const wxString& label); - - /** - Sets the maximum client size of the window, to indicate to the sizer - layout mechanism that this is the maximum possible size of its client area. - - @see SetMaxSize() - */ - void SetMaxClientSize(const wxSize& size); - - /** - Sets the maximum size of the window, to indicate to the sizer layout mechanism - that this is the maximum possible size. - - @see SetMaxClientSize() - */ - void SetMaxSize(const wxSize& size); - - /** - Sets the minimum client size of the window, to indicate to the sizer - layout mechanism that this is the minimum required size of window's client - area. - - You may need to call this if you change the window size after - construction and before adding to its parent sizer. - - Note, that just as with SetMinSize(), calling this method doesn't - prevent the program from explicitly making the window smaller than the - specified size. - - @see SetMinSize() - */ - void SetMinClientSize(const wxSize& size); - - /** - Sets the minimum size of the window, to indicate to the sizer layout - mechanism that this is the minimum required size. - - You may need to call this if you change the window size after - construction and before adding to its parent sizer. - - Notice that calling this method doesn't prevent the program from making - the window explicitly smaller than the specified size by calling - SetSize(), it just ensures that it won't become smaller than this size - during the automatic layout. - - @see SetMinClientSize() - */ - void SetMinSize(const wxSize& size); - - /** - Sets the window's name. - - @param name - A name to set for the window. - - @see GetName() - */ - virtual void SetName(const wxString& name); - - /** - Sets the background colour of the window but prevents it from being inherited - by the children of this window. - - @see SetBackgroundColour(), InheritAttributes() - */ - void SetOwnBackgroundColour(const wxColour& colour); - - /** - Sets the font of the window but prevents it from being inherited by the - children of this window. - - @see SetFont(), InheritAttributes() - */ - void SetOwnFont(const wxFont& font); - - /** - Sets the foreground colour of the window but prevents it from being inherited - by the children of this window. - - @see SetForegroundColour(), InheritAttributes() - */ - void SetOwnForegroundColour(const wxColour& colour); - - /** - Obsolete - use wxDC::SetPalette instead. - */ - virtual void SetPalette(wxPalette* palette); - - /** - Sets the position of one of the built-in scrollbars. - - @param orientation - Determines the scrollbar whose position is to be set. May be wxHORIZONTAL - or wxVERTICAL. - @param pos - Position in scroll units. - @param refresh - @true to redraw the scrollbar, @false otherwise. - - @remarks This function does not directly affect the contents of the - window: it is up to the application to take note of - scrollbar attributes and redraw contents accordingly. - - @see SetScrollbar(), GetScrollPos(), GetScrollThumb(), wxScrollBar, - wxScrolled - */ - virtual void SetScrollPos(int orientation, int pos, - bool refresh = true); - - /** - Sets the scrollbar properties of a built-in scrollbar. - - @param orientation - Determines the scrollbar whose page size is to be set. May be wxHORIZONTAL - or wxVERTICAL. - @param position - The position of the scrollbar in scroll units. - @param thumbSize - The size of the thumb, or visible portion of the scrollbar, in scroll units. - @param range - The maximum position of the scrollbar. - @param refresh - @true to redraw the scrollbar, @false otherwise. - - @remarks Let's say you wish to display 50 lines of text, using the same - font. The window is sized so that you can only see 16 - lines at a time. - - @see @ref overview_scrolling, wxScrollBar, wxScrolled, wxScrollWinEvent - */ - virtual void SetScrollbar(int orientation, int position, - int thumbSize, - int range, - bool refresh = true); - - //@{ - /** - Sets the size of the window in pixels. - - @param x - Required x position in pixels, or wxDefaultCoord to indicate that the - existing - value should be used. - @param y - Required y position in pixels, or wxDefaultCoord to indicate that the - existing - value should be used. - @param width - Required width in pixels, or wxDefaultCoord to indicate that the existing - value should be used. - @param height - Required height position in pixels, or wxDefaultCoord to indicate that the - existing - value should be used. - @param size - wxSize object for setting the size. - @param rect - wxRect object for setting the position and size. - @param sizeFlags - Indicates the interpretation of other parameters. It is a bit list of the - following: - wxSIZE_AUTO_WIDTH: a wxDefaultCoord width value is taken to indicate - a wxWidgets-supplied default width. - - wxSIZE_AUTO_HEIGHT: a wxDefaultCoord height value is taken to indicate - a wxWidgets-supplied default height. - - wxSIZE_AUTO: wxDefaultCoord size values are taken to indicate - a wxWidgets-supplied default size. - - wxSIZE_USE_EXISTING: existing dimensions should be used - if wxDefaultCoord values are supplied. - - wxSIZE_ALLOW_MINUS_ONE: allow negative dimensions (i.e. value of - wxDefaultCoord) to be interpreted - as real dimensions, not default values. - wxSIZE_FORCE: normally, if the position and the size of the window are - already the same as the parameters of this function, nothing is done. but - with - this flag a window resize may be forced even in this case (supported in wx - 2.6.2 and later and only implemented for MSW and ignored elsewhere - currently) - - @remarks The second form is a convenience for calling the first form with - default x and y parameters, and must be used with - non-default width and height values. - - @see Move() - */ - virtual void SetSize(int x, int y, int width, int height, - int sizeFlags = wxSIZE_AUTO); - virtual void SetSize(const wxRect& rect); - virtual void SetSize(int width, int height); - virtual void SetSize(const wxSize& size); - //@} - - /** - Sets the window to have the given layout sizer. The window - will then own the object, and will take care of its deletion. - If an existing layout constraints object is already owned by the - window, it will be deleted if the deleteOld parameter is @true. - Note that this function will also call - SetAutoLayout() implicitly with @true - parameter if the @a sizer is non-@NULL and @false otherwise. - - @param sizer - The sizer to set. Pass @NULL to disassociate and conditionally delete - the window's sizer. See below. - @param deleteOld - If @true (the default), this will delete any pre-existing sizer. - Pass @false if you wish to handle deleting the old sizer yourself. - @remarks SetSizer enables and disables Layout automatically. - */ - void SetSizer(wxSizer* sizer, bool deleteOld = true); - - /** - This method calls SetSizer() and then - wxSizer::SetSizeHints which sets the initial - window size to the size needed to accommodate all sizer elements and sets the - size hints which, if this window is a top level one, prevent the user from - resizing it to be less than this minimial size. - */ - void SetSizerAndFit(wxSizer* sizer, bool deleteOld = true); - - /** - This function tells a window if it should use the system's "theme" code - to draw the windows' background instead if its own background drawing - code. This does not always have any effect since the underlying platform - obviously needs to support the notion of themes in user defined windows. - One such platform is GTK+ where windows can have (very colourful) backgrounds - defined by a user's selected theme. - Dialogs, notebook pages and the status bar have this flag set to @true - by default so that the default look and feel is simulated best. - */ - virtual void SetThemeEnabled(bool enable); - - //@{ - /** - Attach a tooltip to the window. - See also: GetToolTip(), - wxToolTip - */ - void SetToolTip(const wxString& tip); - void SetToolTip(wxToolTip* tip); - //@} - - /** - Set the transparency of the window. If the system supports transparent windows, - returns @true, otherwise returns @false and the window remains fully opaque. - See also CanSetTransparent(). - The parameter @a alpha is in the range 0..255 where 0 corresponds to a - fully transparent window and 255 to the fully opaque one. The constants - @c wxIMAGE_ALPHA_TRANSPARENT and @c wxIMAGE_ALPHA_OPAQUE can be - used. - */ - bool SetTransparent(wxByte alpha); - - /** - Deletes the current validator (if any) and sets the window validator, having - called wxValidator::Clone to - create a new validator of this type. - */ - virtual void SetValidator(const wxValidator& validator); - - //@{ - /** - Sets the virtual size of the window in pixels. - */ - void SetVirtualSize(int width, int height); - void SetVirtualSize(const wxSize& size); - //@} - - /** - Identical to SetWindowStyleFlag(). - */ - void SetWindowStyle(long style); - - /** - Sets the style of the window. Please note that some styles cannot be changed - after the window creation and that Refresh() might - need to be be called after changing the others for the change to take place - immediately. - See @ref overview_windowstyles "Window styles" for more information about flags. - - @see GetWindowStyleFlag() - */ - virtual void SetWindowStyleFlag(long style); - - /** - This function can be called under all platforms but only does anything under - Mac OS X 10.3+ currently. Under this system, each of the standard control can - exist in several sizes which correspond to the elements of wxWindowVariant - enum: - - By default the controls use the normal size, of course, but this function can - be used to change this. - */ - void SetWindowVariant(wxWindowVariant variant); - - /** - Return @true from here to allow the colours of this window to be changed by - InheritAttributes(), returning @false - forbids inheriting them from the parent window. - The base class version returns @false, but this method is overridden in - wxControl where it returns @true. - */ - virtual bool ShouldInheritColours(); - - /** - Shows or hides the window. You may need to call Raise() - for a top level window if you want to bring it to top, although this is not - needed if Show() is called immediately after the frame creation. - - @param show - If @true displays the window. Otherwise, hides it. - - @return @true if the window has been shown or hidden or @false if nothing - was done because it already was in the requested state. - - @see IsShown(), Hide(), wxRadioBox::Show, wxShowEvent. - */ - virtual bool Show(bool show = true); - - /** - This function shows a window, like Show(), but using a special visual - effect if possible. - - @param effect - The effect to use. - - @param timeout - The @a timeout parameter specifies the time of the animation, in - milliseconds. If the default value of 0 is used, the default - animation time for the current platform is used. - - @note Currently this function is only implemented in wxMSW and does the - same thing as Show() in the other ports. - - @since 2.9.0 - - @see HideWithEffect() - */ - virtual bool ShowWithEffect(wxShowEffect effect, - unsigned timeout = 0); - - /** - Reenables window updating after a previous call to Freeze(). - - To really thaw the control, it must be called exactly the same number - of times as Freeze(). - - If the window has any children, they are recursively thawn too. - - @see wxWindowUpdateLocker, Freeze(), IsFrozen() - */ - virtual void Thaw(); - - /** - Turns the given @a flag on if it's currently turned off and vice versa. - This function cannot be used if the value of the flag is 0 (which is often - the case for default flags). - Also, please notice that not all styles can be changed after the control - creation. - - @return Returns @true if the style was turned on by this function, @false - if it was switched off. - - @see SetWindowStyleFlag(), HasFlag() - */ - bool ToggleWindowStyle(int flag); - - /** - Transfers values from child controls to data areas specified by their - validators. Returns - @false if a transfer failed. - If the window has @c wxWS_EX_VALIDATE_RECURSIVELY extra style flag set, - the method will also call TransferDataFromWindow() of all child windows. - - @see TransferDataToWindow(), wxValidator, Validate() - */ - virtual bool TransferDataFromWindow(); - - /** - Transfers values to child controls from data areas specified by their - validators. - If the window has @c wxWS_EX_VALIDATE_RECURSIVELY extra style flag set, - the method will also call TransferDataToWindow() of all child windows. - - @return Returns @false if a transfer failed. - - @see TransferDataFromWindow(), wxValidator, Validate() - */ - virtual bool TransferDataToWindow(); - - /** - Unregisters a system wide hotkey. - - @param hotkeyId - Numeric identifier of the hotkey. Must be the same id that was passed to - RegisterHotKey. - - @return @true if the hotkey was unregistered successfully, @false if the - id was invalid. - - @remarks This function is currently only implemented under MSW. - - @see RegisterHotKey() - */ - bool UnregisterHotKey(int hotkeyId); - - /** - Unreserve an ID or range of IDs that was reserved by NewControlId(). - See @ref overview_windowids "Window IDs Overview" for more information. - - @param id - The starting ID of the range of IDs to unreserve. - @param count - The number of sequential IDs to unreserve. - - @see NewControlId(), wxIdManager, @ref overview_windowids - "Window IDs Overview" - */ - static void UnreserveControlId(wxWindowID id, int count = 1); - - /** - Calling this method immediately repaints the invalidated area of the window and - all of its children recursively while this would usually only happen when the - flow of control returns to the event loop. - Notice that this function doesn't invalidate any area of the window so - nothing happens if nothing has been invalidated (i.e. marked as requiring - a redraw). Use Refresh() first if you want to - immediately redraw the window unconditionally. - */ - virtual void Update(); - - /** - This function sends wxUpdateUIEvents() to - the window. The particular implementation depends on the window; for - example a wxToolBar will send an update UI event for each toolbar button, - and a wxFrame will send an update UI event for each menubar menu item. - You can call this function from your application to ensure that your - UI is up-to-date at this point (as far as your wxUpdateUIEvent handlers - are concerned). This may be necessary if you have called - wxUpdateUIEvent::SetMode or - wxUpdateUIEvent::SetUpdateInterval to - limit the overhead that wxWidgets incurs by sending update UI events in idle - time. - @a flags should be a bitlist of one or more of the following values. - - If you are calling this function from an OnInternalIdle or OnIdle - function, make sure you pass the wxUPDATE_UI_FROMIDLE flag, since - this tells the window to only update the UI elements that need - to be updated in idle time. Some windows update their elements - only when necessary, for example when a menu is about to be shown. - The following is an example of how to call UpdateWindowUI from - an idle function. - - @see wxUpdateUIEvent, DoUpdateWindowUI(), OnInternalIdle() - */ - virtual void UpdateWindowUI(long flags = wxUPDATE_UI_NONE); - - /** - Validates the current values of the child controls using their validators. - If the window has @c wxWS_EX_VALIDATE_RECURSIVELY extra style flag set, - the method will also call Validate() of all child windows. - - @return Returns @false if any of the validations failed. - - @see TransferDataFromWindow(), TransferDataToWindow(), - wxValidator - */ - virtual bool Validate(); - - /** - Moves the pointer to the given position on the window. - @note This function is not supported under Mac because Apple Human - Interface Guidelines forbid moving the mouse cursor programmatically. - - @param x - The new x position for the cursor. - @param y - The new y position for the cursor. - */ - void WarpPointer(int x, int y); -}; - - -/// Valid values for wxWindow::ShowWithEffect() and wxWindow::HideWithEffect(). -enum wxShowEffect -{ - /// Roll window to the left - wxSHOW_EFFECT_ROLL_TO_LEFT, - /// Roll window to the right - wxSHOW_EFFECT_ROLL_TO_RIGHT, - /// Roll window to the top - wxSHOW_EFFECT_ROLL_TO_TOP, - /// Roll window to the bottom - wxSHOW_EFFECT_ROLL_TO_BOTTOM, - /// Slide window to the left - wxSHOW_EFFECT_SLIDE_TO_LEFT, - /// Slide window to the right - wxSHOW_EFFECT_SLIDE_TO_RIGHT, - /// Slide window to the top - wxSHOW_EFFECT_SLIDE_TO_TOP, - /// Slide window to the bottom - wxSHOW_EFFECT_SLIDE_TO_BOTTOM, - /// Fade in or out effect - wxSHOW_EFFECT_BLEND, - /// Expanding or collapsing effect - wxSHOW_EFFECT_EXPAND -}; - - - -// ============================================================================ -// Global functions/macros -// ============================================================================ - -/** @ingroup group_funcmacro_misc */ -//@{ - -/** - Find the deepest window at the mouse pointer position, returning the window - and current pointer position in screen coordinates. - - @header{wx/window.h} -*/ -wxWindow* wxFindWindowAtPointer(wxPoint& pt); - -/** - Gets the currently active window (implemented for MSW and GTK only - currently, always returns @NULL in the other ports). - - @header{wx/window.h} -*/ -wxWindow* wxGetActiveWindow(); - -/** - Returns the first top level parent of the given window, or in other words, - the frame or dialog containing it, or @NULL. - - @header{wx/window.h} -*/ -wxWindow* wxGetTopLevelParent(wxWindow* window); - -//@} - diff --git a/interface/windowid.h b/interface/windowid.h deleted file mode 100644 index 7b14cce3ed..0000000000 --- a/interface/windowid.h +++ /dev/null @@ -1,42 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: windowid.h -// Purpose: interface of wxIdManager -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxIdManager - @wxheader{windowid.h} - - wxIdManager is responsible for allocating and releasing window IDs. It - is used by wxWindow::NewControlId and - wxWindow::UnreserveControlId, and can also - be used be used directly. - - @library{wxcore} - @category{FIXME} - - @see wxWindow::NewControlId, wxWindow::UnreserveControlId, @ref - overview_windowidsoverview "Window IDs overview" -*/ -class wxIdManager -{ -public: - /** - Called directly by wxWindow::NewControlId, - this function will create a new ID or range of IDs. The IDs will be - reserved until assigned to a wxWindowIDRef() - or unreserved with UnreserveControlId(). - Only ID values that are not assigned to a wxWindowIDRef() - need to be unreserved. - - @param count - The number of sequential IDs to reserve. - - @return The value of the first ID in the sequence, or wxID_NONE. - */ - static wxWindowID ReserveControlId(int count = 1); -}; - diff --git a/interface/wizard.h b/interface/wizard.h deleted file mode 100644 index 8225b2f6d9..0000000000 --- a/interface/wizard.h +++ /dev/null @@ -1,473 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: wizard.h -// Purpose: interface of wxWizardPage -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxWizardPage - @wxheader{wizard.h} - - wxWizardPage is one of the screens in wxWizard: it must - know what are the following and preceding pages (which may be @NULL for the - first/last page). Except for this extra knowledge, wxWizardPage is just a - panel, so the controls may be placed directly on it in the usual way. - - This class allows the programmer to decide the order of pages in the wizard - dynamically (during run-time) and so provides maximal flexibility. Usually, - however, the order of pages is known in advance in which case - wxWizardPageSimple class is enough and it is simpler - to use. - - @library{wxadv} - @category{miscwnd} - - @see wxWizard, @ref overview_samplewizard "wxWizard sample" -*/ -class wxWizardPage : public wxPanel -{ -public: - /** - Constructor accepts an optional bitmap which will be used for this page - instead of the default one for this wizard (note that all bitmaps used should - be of the same size). Notice that no other parameters are needed because the - wizard will resize and reposition the page anyhow. - - @param parent - The parent wizard - @param bitmap - The page-specific bitmap if different from the global one - */ - wxWizardPage(wxWizard* parent, - const wxBitmap& bitmap = wxNullBitmap); - - /** - This method is called by wxWizard to get the bitmap to display alongside the - page. By default, @c m_bitmap member variable which was set in the - @ref wxwizardpage() constructor. - If the bitmap was not explicitly set (i.e. if @c wxNullBitmap is returned), - the default bitmap for the wizard should be used. - The only cases when you would want to override this function is if the page - bitmap depends dynamically on the user choices, i.e. almost never. - */ - wxBitmap GetBitmap() const; - - /** - Get the page which should be shown when the user chooses the @c "Next" - button: if @NULL is returned, this button will be disabled. The last - page of the wizard will usually return @NULL from here, but the others - will not. - - @see GetPrev() - */ - wxWizardPage* GetNext() const; - - /** - Get the page which should be shown when the user chooses the @c "Back" - button: if @NULL is returned, this button will be disabled. The first - page of the wizard will usually return @NULL from here, but the others - will not. - - @see GetNext() - */ - wxWizardPage* GetPrev() const; -}; - - - -/** - @class wxWizardEvent - @wxheader{wizard.h} - - wxWizardEvent class represents an event generated by the - wizard(): this event is first sent to the page itself and, - if not processed there, goes up the window hierarchy as usual. - - @library{wxadv} - @category{events} - - @see wxWizard, @ref overview_samplewizard "wxWizard sample" -*/ -class wxWizardEvent : public wxNotifyEvent -{ -public: - /** - Constructor. It is not normally used by the user code as the objects of this - type are constructed by wxWizard. - */ - wxWizardEvent(wxEventType type = wxEVT_NULL, int id = -1, - bool direction = true); - - /** - Return the direction in which the page is changing: for @c - EVT_WIZARD_PAGE_CHANGING, return @true if we're going forward or - @false otherwise and for @c EVT_WIZARD_PAGE_CHANGED return @true if - we came from the previous page and @false if we returned from the next - one. - */ - bool GetDirection() const; - - /** - Returns the wxWizardPage which was active when this - event was generated. - */ - wxWizardPage* GetPage() const; -}; - - - -/** - @class wxWizardPageSimple - @wxheader{wizard.h} - - wxWizardPageSimple is the simplest possible - wxWizardPage implementation: it just returns the - pointers given to its constructor from GetNext() and GetPrev() functions. - - This makes it very easy to use the objects of this class in the wizards where - the pages order is known statically - on the other hand, if this is not the - case you must derive your own class from wxWizardPage - instead. - - @library{wxadv} - @category{miscwnd} - - @see wxWizard, @ref overview_samplewizard "wxWizard sample" -*/ -class wxWizardPageSimple : public wxWizardPage -{ -public: - /** - Constructor takes the previous and next pages. They may be modified later by - SetPrev() or - SetNext(). - */ - wxWizardPageSimple(wxWizard* parent = NULL, - wxWizardPage* prev = NULL, - wxWizardPage* next = NULL, - const wxBitmap& bitmap = wxNullBitmap); - - /** - A convenience function to make the pages follow each other. - Example: - */ - static void Chain(wxWizardPageSimple* first, - wxWizardPageSimple* second); - - /** - Sets the next page. - */ - void SetNext(wxWizardPage* next); - - /** - Sets the previous page. - */ - void SetPrev(wxWizardPage* prev); -}; - - - -/** - @class wxWizard - @wxheader{wizard.h} - - wxWizard is the central class for implementing 'wizard-like' dialogs. These - dialogs are mostly familiar to Windows users and are nothing other than a - sequence of 'pages', each displayed inside a dialog which has the - buttons to navigate to the next (and previous) pages. - - The wizards are typically used to decompose a complex dialog into several - simple steps and are mainly useful to the novice users, hence it is important - to keep them as simple as possible. - - To show a wizard dialog, you must first create an instance of the wxWizard class - using either the non-default constructor or a default one followed by call to - the - wxWizard::Create function. Then you should add all pages you - want the wizard to show and call wxWizard::RunWizard. - Finally, don't forget to call @c wizard-Destroy(), otherwise your application - will hang on exit due to an undestroyed window. - - You can supply a bitmap to display on the left of the wizard, either for all - pages - or for individual pages. If you need to have the bitmap resize to the height of - the wizard, - call wxWizard::SetBitmapPlacement and if necessary, - wxWizard::SetBitmapBackgroundColour and wxWizard::SetMinimumBitmapWidth. - - To make wizard pages scroll when the display is too small to fit the whole - dialog, you can switch - layout adaptation on globally with wxDialog::EnableLayoutAdaptation or - per dialog with wxDialog::SetLayoutAdaptationMode. For more - about layout adaptation, see @ref overview_autoscrollingdialogs "Automatic - scrolling dialogs". - - @library{wxadv} - @category{cmndlg} - - @see wxWizardEvent, wxWizardPage, @ref overview_samplewizard "wxWizard sample" -*/ -class wxWizard : public wxDialog -{ -public: - //@{ - /** - Constructor which really creates the wizard -- if you use this constructor, you - shouldn't call Create(). - Notice that unlike almost all other wxWidgets classes, there is no @e size - parameter in the wxWizard constructor because the wizard will have a predefined - default size by default. If you want to change this, you should use the - GetPageAreaSizer() function. - - @param parent - The parent window, may be @NULL. - @param id - The id of the dialog, will usually be just -1. - @param title - The title of the dialog. - @param bitmap - The default bitmap used in the left side of the wizard. See - also GetBitmap. - @param pos - The position of the dialog, it will be centered on the screen - by default. - @param style - Window style is passed to wxDialog. - */ - wxWizard(); - wxWizard(wxWindow* parent, int id = -1, - const wxString& title = wxEmptyString, - const wxBitmap& bitmap = wxNullBitmap, - const wxPoint& pos = wxDefaultPosition, - long style = wxDEFAULT_DIALOG_STYLE); - //@} - - /** - Creates the wizard dialog. Must be called if the default constructor had been - used to create the object. - Notice that unlike almost all other wxWidgets classes, there is no @e size - parameter in the wxWizard constructor because the wizard will have a predefined - default size by default. If you want to change this, you should use the - GetPageAreaSizer() function. - - @param parent - The parent window, may be @NULL. - @param id - The id of the dialog, will usually be just -1. - @param title - The title of the dialog. - @param bitmap - The default bitmap used in the left side of the wizard. See - also GetBitmap. - @param pos - The position of the dialog, it will be centered on the screen - by default. - @param style - Window style is passed to wxDialog. - */ - bool Create(wxWindow* parent, int id = -1, - const wxString& title = wxEmptyString, - const wxBitmap& bitmap = wxNullBitmap, - const wxPoint& pos = wxDefaultPosition, - long style = wxDEFAULT_DIALOG_STYLE); - - /** - This method is obsolete, use - GetPageAreaSizer() instead. - Sets the page size to be big enough for all the pages accessible via the - given @e firstPage, i.e. this page, its next page and so on. - This method may be called more than once and it will only change the page size - if the size required by the new page is bigger than the previously set one. - This is useful if the decision about which pages to show is taken during - run-time, as in this case, the wizard won't be able to get to all pages starting - from a single one and you should call @e Fit separately for the others. - */ - void FitToPage(const wxWizardPage* firstPage); - - /** - Returns the bitmap used for the wizard. - */ - const wxBitmap GetBitmap() const; - - /** - Returns the colour that should be used to fill the area not taken up by the - wizard or page bitmap, - if a non-zero bitmap placement flag has been set. - See also SetBitmapPlacement(). - */ - const wxColour GetBitmapBackgroundColour() const; - - /** - Returns the flags indicating how the wizard or page bitmap should be expanded - and positioned to fit the - page height. By default, placement is 0 (no expansion is done). - See also SetBitmapPlacement() for the possible values. - */ - int GetBitmapPlacement(); - - /** - Get the current page while the wizard is running. @NULL is returned if - RunWizard() is not being executed now. - */ - wxWizardPage* GetCurrentPage() const; - - /** - Returns the minimum width for the bitmap that will be constructed to contain - the actual wizard or page bitmap - if a non-zero bitmap placement flag has been set. - See also SetBitmapPlacement(). - */ - int GetMinimumBitmapWidth() const; - - /** - Returns pointer to page area sizer. The wizard is laid out using sizers and - the page area sizer is the place-holder for the pages. All pages are resized - before - being shown to match the wizard page area. - Page area sizer has a minimal size that is the maximum of several values. First, - all pages (or other objects) added to the sizer. Second, all pages reachable - by repeatedly applying - wxWizardPage::GetNext to - any page inserted into the sizer. Third, - the minimal size specified using SetPageSize() and - FitToPage(). Fourth, the total wizard height may - be increased to accommodate the bitmap height. Fifth and finally, wizards are - never smaller than some built-in minimal size to avoid wizards that are too - small. - The caller can use wxSizer::SetMinSize to enlarge it - beyond the minimal size. If @c wxRESIZE_BORDER was passed to constructor, user - can resize wizard and consequently the page area (but not make it smaller than - the - minimal size). - It is recommended to add the first page to the page area sizer. For simple - wizards, - this will enlarge the wizard to fit the biggest page. For non-linear wizards, - the first page of every separate chain should be added. Caller-specified size - can be accomplished using wxSizer::SetMinSize. - Adding pages to the page area sizer affects the default border width around page - area that can be altered with SetBorder(). - */ - virtual wxSizer* GetPageAreaSizer() const; - - /** - Returns the size available for the pages. - */ - wxSize GetPageSize() const; - - /** - Return @true if this page is not the last one in the wizard. The base - class version implements this by calling - @ref wxWizardPage::getnext page-GetNext but this could be undesirable if, - for example, the pages are created on demand only. - - @see HasPrevPage() - */ - virtual bool HasNextPage(wxWizardPage* page); - - /** - Returns @true if this page is not the last one in the wizard. The base - class version implements this by calling - @ref wxWizardPage::getprev page-GetPrev but this could be undesirable if, - for example, the pages are created on demand only. - - @see HasNextPage() - */ - virtual bool HasPrevPage(wxWizardPage* page); - - /** - Executes the wizard starting from the given page, returning @true if it was - successfully finished or @false if user cancelled it. The @a firstPage - can not be @NULL. - */ - bool RunWizard(wxWizardPage* firstPage); - - /** - Sets the bitmap used for the wizard. - */ - void SetBitmap(const wxBitmap& bitmap); - - /** - Sets the colour that should be used to fill the area not taken up by the wizard - or page bitmap, - if a non-zero bitmap placement flag has been set. - See also SetBitmapPlacement(). - */ - void SetBitmapBackgroundColour(const wxColour& colour); - - /** - Sets the flags indicating how the wizard or page bitmap should be expanded and - positioned to fit the - page height. By default, placement is 0 (no expansion is done). @a placement is - a bitlist with the - following possible values: - - @b wxWIZARD_VALIGN_TOP - - Aligns the bitmap at the top. - - @b wxWIZARD_VALIGN_CENTRE - - Centres the bitmap vertically. - - @b wxWIZARD_VALIGN_BOTTOM - - Aligns the bitmap at the bottom. - - @b wxWIZARD_HALIGN_LEFT - - Left-aligns the bitmap. - - @b wxWIZARD_HALIGN_CENTRE - - Centres the bitmap horizontally. - - @b wxWIZARD_HALIGN_RIGHT - - Right-aligns the bitmap. - - @b wxWIZARD_TILE - - - See also SetMinimumBitmapWidth(). - */ - void SetBitmapPlacement(int placement); - - /** - Sets width of border around page area. Default is zero. For backward - compatibility, if there are no pages in - GetPageAreaSizer(), the default is 5 pixels. - If there is a five point border around all controls in a page and the border - around - page area is left as zero, a five point white space along all dialog borders - will be added to the control border in order to space page controls ten points - from the dialog - border and non-page controls. - */ - void SetBorder(int border); - - /** - Sets the minimum width for the bitmap that will be constructed to contain the - actual wizard or page bitmap - if a non-zero bitmap placement flag has been set. If this is not set when using - bitmap placement, the initial - layout may be incorrect. - See also SetBitmapPlacement(). - */ - void SetMinimumBitmapWidth(int width); - - /** - This method is obsolete, use - GetPageAreaSizer() instead. - Sets the minimal size to be made available for the wizard pages. The wizard - will take into account the size of the bitmap (if any) itself. Also, the - wizard will never be smaller than the default size. - The recommended way to use this function is to lay out all wizard pages using - the sizers (even though the wizard is not resizeable) and then use - wxSizer::CalcMin in a loop to calculate the maximum - of minimal sizes of the pages and pass it to SetPageSize(). - */ - void SetPageSize(const wxSize& sizePage); -}; - diff --git a/interface/wrapsizer.h b/interface/wrapsizer.h deleted file mode 100644 index 9a186de2fc..0000000000 --- a/interface/wrapsizer.h +++ /dev/null @@ -1,63 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: wrapsizer.h -// Purpose: interface of wxWrapSizer -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxWrapSizer - @wxheader{wrapsizer.h} - - A wrap sizer lays out its items in a single line, like a box sizer -- as long - as there is space available in that direction. Once all available space in - the primary direction has been used, a new line is added and items are added - there. - - So a wrap sizer has a primary orientation for adding items, and adds lines - as needed in the secondary direction. - - @library{wxcore} - @category{winlayout} - - @see wxBoxSizer, wxSizer, @ref overview_sizeroverview "Sizer overview" -*/ -class wxWrapSizer : public wxBoxSizer -{ -public: - /** - Constructor for a wxWrapSizer. @a orient determines the primary direction of - the sizer (the most common case being @c wxHORIZONTAL). The flags - parameter can be a combination of the values @c - wxEXTEND_LAST_ON_EACH_LINE which will cause the last item on each line - to use any remaining space on that line and @c wxREMOVE_LEADING_SPACES - which removes any spacer elements from the beginning of a row. Both of - these flags are on by default. - */ - wxWrapSizer(int orient = wxHORIZONTAL, - int flags = wxEXTEND_LAST_ON_EACH_LINE | - wxREMOVE_LEADING_SPACES); - - /** - Not used by an application. This is the mechanism by which sizers can inform - sub-items of the first determined size component. The sub-item can then better - determine its size requirements. - Returns @true if the information was used (and the sub-item min size was - updated). - */ - bool InformFirstDirection(int direction, int size, - int availableOtherDir); - -protected: - /** - Can be overridden in the derived classes to treat some normal items as - spacers. - - This method is used to determine whether the given @a item should be - considered to be a spacer for the purposes of @c wxREMOVE_LEADING_SPACES - implementation. By default only returns @true for the real spacers. - */ - virtual bool IsSpaceItem(wxSizerItem *item) const; -}; - diff --git a/interface/wupdlock.h b/interface/wupdlock.h deleted file mode 100644 index 525a9a09f6..0000000000 --- a/interface/wupdlock.h +++ /dev/null @@ -1,53 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: wupdlock.h -// Purpose: interface of wxWindowUpdateLocker -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxWindowUpdateLocker - @wxheader{wupdlock.h} - - This tiny class prevents redrawing of a wxWindow during its - lifetime by using wxWindow::Freeze and - wxWindow::Thaw methods. It is typically used for creating - automatic objects to temporarily suppress window updates before a batch of - operations is performed: - - @code - void MyFrame::Foo() - { - m_text = new wxTextCtrl(this, ...); - - wxWindowUpdateLocker noUpdates(m_text); - m_text-AppendText(); - ... many other operations with m_text... - m_text-WriteText(); - } - @endcode - - Using this class is easier and safer than calling - wxWindow::Freeze and wxWindow::Thaw because you - don't risk to forget calling the latter. - - @library{wxbase} - @category{FIXME} -*/ -class wxWindowUpdateLocker -{ -public: - /** - Creates an object preventing the updates of the specified @e win. The - parameter must be non-@NULL and the window must exist for longer than - wxWindowUpdateLocker object itself. - */ - wxWindowUpdateLocker(wxWindow* win); - - /** - Destructor reenables updates for the window this object is associated with. - */ - ~wxWindowUpdateLocker(); -}; - diff --git a/interface/wx/aboutdlg.h b/interface/wx/aboutdlg.h new file mode 100644 index 0000000000..1688a5a45c --- /dev/null +++ b/interface/wx/aboutdlg.h @@ -0,0 +1,224 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: aboutdlg.h +// Purpose: interface of wxAboutDialogInfo +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxAboutDialogInfo + @wxheader{aboutdlg.h} + + wxAboutDialogInfo contains information shown in the standard @e About + dialog displayed by the wxAboutBox() function. + + This class contains the general information about the program, such as its + name, version, copyright and so on, as well as lists of the program developers, + documentation writers, artists and translators. The simple properties from the + former group are represented as a string with the exception of the program icon + and the program web site, while the lists from the latter group are stored as + wxArrayString and can be either set entirely at once using + wxAboutDialogInfo::SetDevelopers and similar functions or built one by one using + wxAboutDialogInfo::AddDeveloper etc. + + Please also notice that while all the main platforms have the native + implementation of the about dialog, they are often more limited than the + generic version provided by wxWidgets and so the generic version is used if + wxAboutDialogInfo has any fields not supported by the native version. Currently + GTK+ version supports all the possible fields natively but MSW and Mac versions + don't support URLs, licence text nor custom icons in the about dialog and if + either of those is used, wxAboutBox() will automatically use the generic version + so you should avoid specifying these fields to achieve more native look and feel. + + @library{wxadv} + @category{misc} + + @see wxAboutDialogInfo::SetArtists +*/ +class wxAboutDialogInfo +{ +public: + /** + Default constructor leaves all fields are initially uninitialized, in general + you should call at least SetVersion(), SetCopyright() and SetDescription(). + */ + wxAboutDialogInfo(); + + /** + Adds an artist name to be shown in the program credits. + + @see SetArtists() + */ + void AddArtist(const wxString& artist); + + /** + Adds a developer name to be shown in the program credits. + + @see SetDevelopers() + */ + void AddDeveloper(const wxString& developer); + + /** + Adds a documentation writer name to be shown in the program credits. + + @see SetDocWriters() + */ + void AddDocWriter(const wxString& docwriter); + + /** + Adds a translator name to be shown in the program credits. Notice that if no + translator names are specified explicitely, wxAboutBox() will try to use the + translation of the string @c translator-credits from the currently used message + catalog -- this can be used to show just the name of the translator of the + program in the current language. + + @see SetTranslators() + */ + void AddTranslator(const wxString& translator); + + /** + Sets the the list of artists to be shown in the program credits. + + @see AddArtist() + */ + void SetArtists(const wxArrayString& artists); + + /** + Set the short string containing the program copyright information. Notice that + any occurrences of @c "(C)" in @a copyright will be replaced by the + copyright symbol (circled C) automatically, which means that you can avoid + using this symbol in the program source code which can be problematic, + */ + void SetCopyright(const wxString& copyright); + + /** + Set brief, but possibly multiline, description of the program. + */ + void SetDescription(const wxString& desc); + + /** + Set the list of developers of the program. + + @see AddDeveloper() + */ + void SetDevelopers(const wxArrayString& developers); + + /** + Set the list of documentation writers. + + @see AddDocWriter() + */ + void SetDocWriters(const wxArrayString& docwriters); + + /** + Set the icon to be shown in the dialog. By default the icon of the main frame + will be shown if the native about dialog supports custom icons. If it doesn't + but a valid icon is specified using this method, the generic about dialog is + used instead so you should avoid calling this function for maximally native + look and feel. + */ + void SetIcon(const wxIcon& icon); + + /** + Set the long, multiline string containing the text of the program licence. + + Only GTK+ version supports showing the licence text in the native about dialog + currently so the generic version will be used under all the other platforms if + this method is called. To preserve the native look and feel it is advised that + you do not call this method but provide a separate menu item in the + @c "Help" menu for displaying the text of your program licence. + */ + void SetLicence(const wxString& licence); + + /** + This is the same as SetLicence(). + */ + void SetLicense(const wxString& licence); + + /** + Set the name of the program. If this method is not called, the string returned + by wxApp::GetAppName will be shown in the dialog. + */ + void SetName(const wxString& name); + + /** + Set the list of translators. Please see AddTranslator() for additional + discussion. + */ + void SetTranslators(const wxArrayString& translators); + + /** + Set the version of the program. The version is in free format, i.e. not + necessarily in the @c x.y.z form but it shouldn't contain the "version" word. + */ + void SetVersion(const wxString& version); + + /** + Set the web site for the program and its description (which defaults to @a url + itself if empty). + + Please notice that only GTK+ version currently supports showing the link in the + native about dialog so if this method is called, the generic version will be + used under all the other platforms. + */ + void SetWebSite(const wxString& url, + const wxString& desc = wxEmptyString); +}; + + +// ============================================================================ +// Global functions/macros +// ============================================================================ + +/** @ingroup group_funcmacro_dialog */ +//@{ + +/** + This function shows the standard about dialog containing the information + specified in @a info. If the current platform has a native about dialog + which is capable of showing all the fields in @a info, the native dialog is + used, otherwise the function falls back to the generic wxWidgets version of + the dialog, i.e. does the same thing as wxGenericAboutBox. + + Here is an example of how this function may be used: + + @code + void MyFrame::ShowSimpleAboutDialog(wxCommandEvent& WXUNUSED(event)) + { + wxAboutDialogInfo info; + info.SetName(_("My Program")); + info.SetVersion(_("1.2.3 Beta")); + info.SetDescription(_("This program does something great.")); + info.SetCopyright(_T("(C) 2007 Me ")); + + wxAboutBox(info); + } + @endcode + + Please see the @ref page_samples_dialogs for more examples of using this + function and wxAboutDialogInfo for the description of the information which + can be shown in the about dialog. + + @header{wx/aboutdlg.h} +*/ +void wxAboutBox(const wxAboutDialogInfo& info); + +/** + This function does the same thing as wxAboutBox() except that it always uses + the generic wxWidgets version of the dialog instead of the native one. + + This is mainly useful if you need to customize the dialog by e.g. adding + custom controls to it (customizing the native dialog is not currently + supported). + + See the @ref page_samples_dialogs for an example of about dialog + customization. + + @see wxAboutDialogInfo + + @header{wx/aboutdlg.h} +*/ +void wxGenericAboutBox(const wxAboutDialogInfo& info); + +//@} diff --git a/interface/wx/accel.h b/interface/wx/accel.h new file mode 100644 index 0000000000..616f2b047a --- /dev/null +++ b/interface/wx/accel.h @@ -0,0 +1,216 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: accel.h +// Purpose: interface of wxAccelerator* classes +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + + +/** wxAcceleratorEntry flags */ +enum wxAcceleratorEntryFlags +{ + /** no modifiers */ + wxACCEL_NORMAL, + + /** hold Alt key down */ + wxACCEL_ALT, + + /** hold Ctrl key down */ + wxACCEL_CTRL, + + /** hold Shift key down */ + wxACCEL_SHIFT, + + /** Command key on OS X; identic to wxACCEL_CTRL on other platforms. */ + wxACCEL_CMD +}; + + +/** + @class wxAcceleratorEntry + @wxheader{accel.h} + + An object used by an application wishing to create an accelerator table + (see wxAcceleratorTable). + + @library{wxcore} + @category{misc} + + @see wxAcceleratorTable, wxWindow::SetAcceleratorTable +*/ +class wxAcceleratorEntry +{ +public: + /** + Constructor. + + @param flags + A combination of the wxAcceleratorEntryFlags values, which + indicates which modifier keys are held down. + @param keyCode + The keycode to be detected. See @ref page_keycodes for a full list of keycodes. + @param cmd + The menu or control command identifier (ID). + @param item + The menu item associated with this accelerator. + */ + wxAcceleratorEntry(int flags = 0, int keyCode = 0, int cmd = 0, + wxMenuItem *item = NULL); + + /** + Copy ctor. + */ + wxAcceleratorEntry(const wxAcceleratorEntry& entry); + + /** + Returns the command identifier for the accelerator table entry. + */ + int GetCommand() const; + + /** + Returns the flags for the accelerator table entry. + */ + int GetFlags() const; + + /** + Returns the keycode for the accelerator table entry. + */ + int GetKeyCode() const; + + /** + Returns the menu item associated with this accelerator entry. + */ + wxMenuItem *GetMenuItem() const; + + /** + Sets the accelerator entry parameters. + + @param flags + A combination of the wxAcceleratorEntryFlags values, which + indicates which modifier keys are held down. + @param keyCode + The keycode to be detected. See @ref page_keycodes for a full list of keycodes. + @param cmd + The menu or control command identifier (ID). + @param item + The menu item associated with this accelerator. + */ + void Set(int flags, int keyCode, int cmd, wxMenuItem *item = NULL); + + /** + Returns @true if this object is correctly initialized. + */ + bool IsOk() const; + + /** + Returns a wxString for this accelerator. + This function formats it using the @c "flags-keycode" format + where @c flags maybe a hyphen-separed list of @c "shift|alt|ctrl". + */ + wxString ToString() const; + + /** + Parses the given string and sets the accelerator accordingly. + + @param str + Should be a string in the form "flags-keycode" + + @return @true if the given string correctly initialized this object + (i.e. if IsOk() returns true after this call) + */ + bool FromString(const wxString& str); + + + wxAcceleratorEntry& operator=(const wxAcceleratorEntry& entry); + bool operator==(const wxAcceleratorEntry& entry) const; + bool operator!=(const wxAcceleratorEntry& entry) const; +}; + + +/** + @class wxAcceleratorTable + @wxheader{accel.h} + + An accelerator table allows the application to specify a table of keyboard + shortcuts for menu or button commands. + + The object ::wxNullAcceleratorTable is defined to be a table with no data, and + is the initial accelerator table for a window. + + Example: + + @code + wxAcceleratorEntry entries[4]; + entries[0].Set(wxACCEL_CTRL, (int) 'N', ID_NEW_WINDOW); + entries[1].Set(wxACCEL_CTRL, (int) 'X', wxID_EXIT); + entries[2].Set(wxACCEL_SHIFT, (int) 'A', ID_ABOUT); + entries[3].Set(wxACCEL_NORMAL, WXK_DELETE, wxID_CUT); + + wxAcceleratorTable accel(4, entries); + frame->SetAcceleratorTable(accel); + @endcode + + @remarks + An accelerator takes precedence over normal processing and can be a convenient + way to program some event handling. For example, you can use an accelerator table + to enable a dialog with a multi-line text control to accept CTRL-Enter as meaning + 'OK'. + + @library{wxcore} + @category{misc} + + @stdobjects + ::wxNullAcceleratorTable + + @see wxAcceleratorEntry, wxWindow::SetAcceleratorTable +*/ +class wxAcceleratorTable : public wxObject +{ +public: + /** + Default ctor. + */ + wxAcceleratorTable(); + + /** + Initializes the accelerator table from an array of wxAcceleratorEntry. + + @param n + Number of accelerator entries. + @param entries + The array of entries. + */ + wxAcceleratorTable(int n, const wxAcceleratorEntry entries[]); + + /** + Loads the accelerator table from a Windows resource (Windows only). + + @onlyfor{wxmsw} + + @param resource + Name of a Windows accelerator. + */ + wxAcceleratorTable(const wxString& resource); + + /** + Destroys the wxAcceleratorTable object. + See @ref overview_refcount_destruct for more info. + */ + virtual ~wxAcceleratorTable(); + + /** + Returns @true if the accelerator table is valid. + */ + bool IsOk() const; +}; + + +// ============================================================================ +// Global functions/macros +// ============================================================================ + +/** + An empty accelerator table. +*/ +wxAcceleratorTable wxNullAcceleratorTable; diff --git a/interface/wx/access.h b/interface/wx/access.h new file mode 100644 index 0000000000..9218d85226 --- /dev/null +++ b/interface/wx/access.h @@ -0,0 +1,421 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: access.h +// Purpose: interface of wxAccessible +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + + +/** + wxAccessible functions return a wxAccStatus error code, + which may be one of this enum's values. +*/ +typedef enum +{ + wxACC_FAIL, //!< The function failed. + wxACC_FALSE, //!< The function returned false. + wxACC_OK, //!< The function completed successfully. + wxACC_NOT_IMPLEMENTED, //!< The function is not implemented. + wxACC_NOT_SUPPORTED //!< The function is not supported. +} wxAccStatus; + + +/** + Directions of navigation are represented by this enum. +*/ +typedef enum +{ + wxNAVDIR_DOWN, + wxNAVDIR_FIRSTCHILD, + wxNAVDIR_LASTCHILD, + wxNAVDIR_LEFT, + wxNAVDIR_NEXT, + wxNAVDIR_PREVIOUS, + wxNAVDIR_RIGHT, + wxNAVDIR_UP +} wxNavDir; + + +/** + The role of a user interface element is represented by the values of this enum. +*/ +typedef enum { + wxROLE_NONE, + wxROLE_SYSTEM_ALERT, + wxROLE_SYSTEM_ANIMATION, + wxROLE_SYSTEM_APPLICATION, + wxROLE_SYSTEM_BORDER, + wxROLE_SYSTEM_BUTTONDROPDOWN, + wxROLE_SYSTEM_BUTTONDROPDOWNGRID, + wxROLE_SYSTEM_BUTTONMENU, + wxROLE_SYSTEM_CARET, + wxROLE_SYSTEM_CELL, + wxROLE_SYSTEM_CHARACTER, + wxROLE_SYSTEM_CHART, + wxROLE_SYSTEM_CHECKBUTTON, + wxROLE_SYSTEM_CLIENT, + wxROLE_SYSTEM_CLOCK, + wxROLE_SYSTEM_COLUMN, + wxROLE_SYSTEM_COLUMNHEADER, + wxROLE_SYSTEM_COMBOBOX, + wxROLE_SYSTEM_CURSOR, + wxROLE_SYSTEM_DIAGRAM, + wxROLE_SYSTEM_DIAL, + wxROLE_SYSTEM_DIALOG, + wxROLE_SYSTEM_DOCUMENT, + wxROLE_SYSTEM_DROPLIST, + wxROLE_SYSTEM_EQUATION, + wxROLE_SYSTEM_GRAPHIC, + wxROLE_SYSTEM_GRIP, + wxROLE_SYSTEM_GROUPING, + wxROLE_SYSTEM_HELPBALLOON, + wxROLE_SYSTEM_HOTKEYFIELD, + wxROLE_SYSTEM_INDICATOR, + wxROLE_SYSTEM_LINK, + wxROLE_SYSTEM_LIST, + wxROLE_SYSTEM_LISTITEM, + wxROLE_SYSTEM_MENUBAR, + wxROLE_SYSTEM_MENUITEM, + wxROLE_SYSTEM_MENUPOPUP, + wxROLE_SYSTEM_OUTLINE, + wxROLE_SYSTEM_OUTLINEITEM, + wxROLE_SYSTEM_PAGETAB, + wxROLE_SYSTEM_PAGETABLIST, + wxROLE_SYSTEM_PANE, + wxROLE_SYSTEM_PROGRESSBAR, + wxROLE_SYSTEM_PROPERTYPAGE, + wxROLE_SYSTEM_PUSHBUTTON, + wxROLE_SYSTEM_RADIOBUTTON, + wxROLE_SYSTEM_ROW, + wxROLE_SYSTEM_ROWHEADER, + wxROLE_SYSTEM_SCROLLBAR, + wxROLE_SYSTEM_SEPARATOR, + wxROLE_SYSTEM_SLIDER, + wxROLE_SYSTEM_SOUND, + wxROLE_SYSTEM_SPINBUTTON, + wxROLE_SYSTEM_STATICTEXT, + wxROLE_SYSTEM_STATUSBAR, + wxROLE_SYSTEM_TABLE, + wxROLE_SYSTEM_TEXT, + wxROLE_SYSTEM_TITLEBAR, + wxROLE_SYSTEM_TOOLBAR, + wxROLE_SYSTEM_TOOLTIP, + wxROLE_SYSTEM_WHITESPACE, + wxROLE_SYSTEM_WINDOW +} wxAccRole; + +/** + Objects are represented by a wxAccObject enum value. +*/ +typedef enum { + wxOBJID_WINDOW = 0x00000000, + wxOBJID_SYSMENU = 0xFFFFFFFF, + wxOBJID_TITLEBAR = 0xFFFFFFFE, + wxOBJID_MENU = 0xFFFFFFFD, + wxOBJID_CLIENT = 0xFFFFFFFC, + wxOBJID_VSCROLL = 0xFFFFFFFB, + wxOBJID_HSCROLL = 0xFFFFFFFA, + wxOBJID_SIZEGRIP = 0xFFFFFFF9, + wxOBJID_CARET = 0xFFFFFFF8, + wxOBJID_CURSOR = 0xFFFFFFF7, + wxOBJID_ALERT = 0xFFFFFFF6, + wxOBJID_SOUND = 0xFFFFFFF5 +} wxAccObject; + + +/** + Selection actions are identified by the wxAccSelectionFlags values. +*/ +typedef enum +{ + wxACC_SEL_NONE = 0, + wxACC_SEL_TAKEFOCUS = 1, + wxACC_SEL_TAKESELECTION = 2, + wxACC_SEL_EXTENDSELECTION = 4, + wxACC_SEL_ADDSELECTION = 8, + wxACC_SEL_REMOVESELECTION = 16 +} wxAccSelectionFlags; + +//@{ +/** + Represents a status of the system. +*/ +#define wxACC_STATE_SYSTEM_ALERT_HIGH 0x00000001 +#define wxACC_STATE_SYSTEM_ALERT_MEDIUM 0x00000002 +#define wxACC_STATE_SYSTEM_ALERT_LOW 0x00000004 +#define wxACC_STATE_SYSTEM_ANIMATED 0x00000008 +#define wxACC_STATE_SYSTEM_BUSY 0x00000010 +#define wxACC_STATE_SYSTEM_CHECKED 0x00000020 +#define wxACC_STATE_SYSTEM_COLLAPSED 0x00000040 +#define wxACC_STATE_SYSTEM_DEFAULT 0x00000080 +#define wxACC_STATE_SYSTEM_EXPANDED 0x00000100 +#define wxACC_STATE_SYSTEM_EXTSELECTABLE 0x00000200 +#define wxACC_STATE_SYSTEM_FLOATING 0x00000400 +#define wxACC_STATE_SYSTEM_FOCUSABLE 0x00000800 +#define wxACC_STATE_SYSTEM_FOCUSED 0x00001000 +#define wxACC_STATE_SYSTEM_HOTTRACKED 0x00002000 +#define wxACC_STATE_SYSTEM_INVISIBLE 0x00004000 +#define wxACC_STATE_SYSTEM_MARQUEED 0x00008000 +#define wxACC_STATE_SYSTEM_MIXED 0x00010000 +#define wxACC_STATE_SYSTEM_MULTISELECTABLE 0x00020000 +#define wxACC_STATE_SYSTEM_OFFSCREEN 0x00040000 +#define wxACC_STATE_SYSTEM_PRESSED 0x00080000 +#define wxACC_STATE_SYSTEM_PROTECTED 0x00100000 +#define wxACC_STATE_SYSTEM_READONLY 0x00200000 +#define wxACC_STATE_SYSTEM_SELECTABLE 0x00400000 +#define wxACC_STATE_SYSTEM_SELECTED 0x00800000 +#define wxACC_STATE_SYSTEM_SELFVOICING 0x01000000 +#define wxACC_STATE_SYSTEM_UNAVAILABLE 0x02000000 +//@} + +//@{ +/** + An event identifier that can be sent via wxAccessible::NotifyEvent. +*/ +#define wxACC_EVENT_SYSTEM_SOUND 0x0001 +#define wxACC_EVENT_SYSTEM_ALERT 0x0002 +#define wxACC_EVENT_SYSTEM_FOREGROUND 0x0003 +#define wxACC_EVENT_SYSTEM_MENUSTART 0x0004 +#define wxACC_EVENT_SYSTEM_MENUEND 0x0005 +#define wxACC_EVENT_SYSTEM_MENUPOPUPSTART 0x0006 +#define wxACC_EVENT_SYSTEM_MENUPOPUPEND 0x0007 +#define wxACC_EVENT_SYSTEM_CAPTURESTART 0x0008 +#define wxACC_EVENT_SYSTEM_CAPTUREEND 0x0009 +#define wxACC_EVENT_SYSTEM_MOVESIZESTART 0x000A +#define wxACC_EVENT_SYSTEM_MOVESIZEEND 0x000B +#define wxACC_EVENT_SYSTEM_CONTEXTHELPSTART 0x000C +#define wxACC_EVENT_SYSTEM_CONTEXTHELPEND 0x000D +#define wxACC_EVENT_SYSTEM_DRAGDROPSTART 0x000E +#define wxACC_EVENT_SYSTEM_DRAGDROPEND 0x000F +#define wxACC_EVENT_SYSTEM_DIALOGSTART 0x0010 +#define wxACC_EVENT_SYSTEM_DIALOGEND 0x0011 +#define wxACC_EVENT_SYSTEM_SCROLLINGSTART 0x0012 +#define wxACC_EVENT_SYSTEM_SCROLLINGEND 0x0013 +#define wxACC_EVENT_SYSTEM_SWITCHSTART 0x0014 +#define wxACC_EVENT_SYSTEM_SWITCHEND 0x0015 +#define wxACC_EVENT_SYSTEM_MINIMIZESTART 0x0016 +#define wxACC_EVENT_SYSTEM_MINIMIZEEND 0x0017 +#define wxACC_EVENT_OBJECT_CREATE 0x8000 +#define wxACC_EVENT_OBJECT_DESTROY 0x8001 +#define wxACC_EVENT_OBJECT_SHOW 0x8002 +#define wxACC_EVENT_OBJECT_HIDE 0x8003 +#define wxACC_EVENT_OBJECT_REORDER 0x8004 +#define wxACC_EVENT_OBJECT_FOCUS 0x8005 +#define wxACC_EVENT_OBJECT_SELECTION 0x8006 +#define wxACC_EVENT_OBJECT_SELECTIONADD 0x8007 +#define wxACC_EVENT_OBJECT_SELECTIONREMOVE 0x8008 +#define wxACC_EVENT_OBJECT_SELECTIONWITHIN 0x8009 +#define wxACC_EVENT_OBJECT_STATECHANGE 0x800A +#define wxACC_EVENT_OBJECT_LOCATIONCHANGE 0x800B +#define wxACC_EVENT_OBJECT_NAMECHANGE 0x800C +#define wxACC_EVENT_OBJECT_DESCRIPTIONCHANGE 0x800D +#define wxACC_EVENT_OBJECT_VALUECHANGE 0x800E +#define wxACC_EVENT_OBJECT_PARENTCHANGE 0x800F +#define wxACC_EVENT_OBJECT_HELPCHANGE 0x8010 +#define wxACC_EVENT_OBJECT_DEFACTIONCHANGE 0x8011 +#define wxACC_EVENT_OBJECT_ACCELERATORCHANGE 0x8012 +//@} + +/** + @class wxAccessible + @wxheader{access.h} + + The wxAccessible class allows wxWidgets applications, and wxWidgets itself, + to return extended information about user interface elements to client + applications such as screen readers. This is the main way in which wxWidgets + implements accessibility features. + + At present, only Microsoft Active Accessibility is supported by this class. + + To use this class, derive from wxAccessible, implement appropriate + functions, and associate an object of the class with a window using + wxWindow::SetAccessible. + + All functions return an indication of success, failure, or not implemented + using values of the wxAccStatus enum type. + + If you return @c wxACC_NOT_IMPLEMENTED from any function, the system will try + to implement the appropriate functionality. However this will not work with + all functions. + + Most functions work with an object @e id, which can be zero to refer to + 'this' UI element, or greater than zero to refer to the nth child element. + This allows you to specify elements that don't have a corresponding wxWindow or + wxAccessible; for example, the sash of a splitter window. + + For details on the semantics of functions and types, please refer to the + Microsoft Active Accessibility 1.2 documentation. + + This class is compiled into wxWidgets only if the wxUSE_ACCESSIBILITY setup + symbol is set to 1. + + @onlyfor{wxmsw} + + @library{wxcore} + @category{misc} + + @see @sample{access} +*/ +class wxAccessible : public wxObject +{ +public: + /** + Constructor, taking an optional window. The object can be associated with + a window later. + */ + wxAccessible(wxWindow* win = NULL); + + /** + Destructor. + */ + ~wxAccessible(); + + /** + Performs the default action for the object. + @a childId is 0 (the action for this object) or greater than 0 (the action + for a child). + + @return wxACC_NOT_SUPPORTED if there is no default action for this + window (e.g. an edit control). + */ + virtual wxAccStatus DoDefaultAction(int childId); + + /** + Gets the specified child (starting from 1). If @a child is @NULL and the return + value is wxACC_OK, this means that the child is a simple element and not an + accessible object. + */ + virtual wxAccStatus GetChild(int childId, wxAccessible** child); + + /** + Returns the number of children in @a childCount. + */ + virtual wxAccStatus GetChildCount(int* childCount); + + /** + Gets the default action for this object (0) or a child (greater than 0). + + Return wxACC_OK even if there is no action. @a actionName is the action, or the + empty string if there is no action. The retrieved string describes the action that is + performed on an object, not what the object does as a result. For example, a toolbar + button that prints a document has a default action of "Press" rather than "Prints + the current document." + */ + virtual wxAccStatus GetDefaultAction(int childId, + wxString* actionName); + + /** + Returns the description for this object or a child. + */ + virtual wxAccStatus GetDescription(int childId, + wxString* description); + + /** + Gets the window with the keyboard focus. If childId is 0 and child is @NULL, no + object in this subhierarchy has the focus. If this object has the focus, child + should be 'this'. + */ + virtual wxAccStatus GetFocus(int* childId, wxAccessible** child); + + /** + Returns help text for this object or a child, similar to tooltip text. + */ + virtual wxAccStatus GetHelpText(int childId, wxString* helpText); + + /** + Returns the keyboard shortcut for this object or child. + Returns e.g. ALT+K. + */ + virtual wxAccStatus GetKeyboardShortcut(int childId, + wxString* shortcut); + + /** + Returns the rectangle for this object (id is 0) or a child element (id is + greater than 0). + @a rect is in screen coordinates. + */ + virtual wxAccStatus GetLocation(wxRect& rect, int elementId); + + /** + Gets the name of the specified object. + */ + virtual wxAccStatus GetName(int childId, wxString* name); + + /** + Returns the parent of this object, or @NULL. + */ + virtual wxAccStatus GetParent(wxAccessible** parent); + + /** + Returns a role constant describing this object. See wxAccRole for a list + of these roles. + */ + virtual wxAccStatus GetRole(int childId, wxAccRole* role); + + /** + Gets a variant representing the selected children of this object. + + Acceptable values are: + @li a null variant (IsNull() returns @true) + @li a list variant (GetType() == wxT("list")) + @li an integer representing the selected child element, + or 0 if this object is selected (GetType() == wxT("long")) + @li a "void*" pointer to a wxAccessible child object + */ + virtual wxAccStatus GetSelections(wxVariant* selections); + + /** + Returns a state constant. See wxAccStatus for a list of these states. + */ + virtual wxAccStatus GetState(int childId, long* state); + + /** + Returns a localized string representing the value for the object + or child. + */ + virtual wxAccStatus GetValue(int childId, wxString* strValue); + + /** + Returns the window associated with this object. + */ + wxWindow* GetWindow(); + + /** + Returns a status value and object id to indicate whether the given point + was on this or a child object. Can return either a child object, or an + integer representing the child element, starting from 1. + + @a pt is in screen coordinates. + */ + virtual wxAccStatus HitTest(const wxPoint& pt, int* childId, + wxAccessible** childObject); + + /** + Navigates from @a fromId to @a toId or to @a toObject. + */ + virtual wxAccStatus Navigate(wxNavDir navDir, int fromId, + int* toId, + wxAccessible** toObject); + + /** + Allows the application to send an event when something changes in + an accessible object. + */ + virtual static void NotifyEvent(int eventType, wxWindow* window, + wxAccObject objectType, + int objectType); + + /** + Selects the object or child. See wxAccSelectionFlags for a list + of the selection actions. + */ + virtual wxAccStatus Select(int childId, + wxAccSelectionFlags selectFlags); + + /** + Sets the window associated with this object. + */ + void SetWindow(wxWindow* window); +}; + diff --git a/interface/wx/animate.h b/interface/wx/animate.h new file mode 100644 index 0000000000..62e2ab5a8f --- /dev/null +++ b/interface/wx/animate.h @@ -0,0 +1,290 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: animate.h +// Purpose: interface of wxAnimation* classes +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + Supported animation types. +*/ +enum wxAnimationType +{ + wxANIMATION_TYPE_INVALID, + + /** represents an animated GIF file. */ + wxANIMATION_TYPE_GIF, + + /** represents an ANI file. */ + wxANIMATION_TYPE_ANI, + + /** autodetect the filetype. */ + wxANIMATION_TYPE_ANY +}; + +/** + @class wxAnimationCtrl + @wxheader{animate.h} + + This is a static control which displays an animation. + wxAnimationCtrl API is as simple as possible and won't give you full control + on the animation; if you need it then use wxMediaCtrl. + + This control is useful to display a (small) animation while doing a long task + (e.g. a "throbber"). + + It is only available if @c wxUSE_ANIMATIONCTRL is set to 1 (the default). + + @beginStyleTable + @style{wxAC_DEFAULT_STYLE} + The default style: wxBORDER_NONE. + @style{wxAC_NO_AUTORESIZE} + By default, the control will adjust its size to exactly fit to the + size of the animation when SetAnimation is called. If this style + flag is given, the control will not change its size + @endStyleTable + + @library{wxadv} + @category{ctrl} + + @nativeimpl{wxgtk,wxmsw} + + + + @see wxAnimation, @sample{animate} +*/ +class wxAnimationCtrl : public wxControl +{ +public: + /** + Initializes the object and calls Create() with + all the parameters. + */ + wxAnimationCtrl(wxWindow* parent, wxWindowID id, + const wxAnimation& anim = wxNullAnimation, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxAC_DEFAULT_STYLE, + const wxString& name = wxAnimationCtrlNameStr); + + /** + Creates the control with the given @a anim animation. + + After control creation you must explicitely call Play() to start to play + the animation. Until that function won't be called, the first frame + of the animation is displayed. + + @param parent + Parent window, must be non-@NULL. + @param id + The identifier for the control. + @param anim + The initial animation shown in the control. + @param pos + Initial position. + @param size + Initial size. + @param style + The window style, see wxAC_* flags. + @param name + Control name. + + @return @true if the control was successfully created or @false if + creation failed. + */ + bool Create(wxWindow* parent, wxWindowID id, + const wxAnimation& anim = wxNullAnimation, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxAC_DEFAULT_STYLE, + const wxString& name = wxAnimationCtrlNameStr); + + /** + Returns the animation associated with this control. + */ + virtual wxAnimation GetAnimation() const; + + /** + Returns the inactive bitmap shown in this control when the; + see SetInactiveBitmap() for more info. + */ + wxBitmap GetInactiveBitmap() const; + + /** + Returns @true if the animation is being played. + */ + virtual bool IsPlaying() const; + + /** + Loads the animation from the given file and calls SetAnimation(). + See wxAnimation::LoadFile for more info. + */ + virtual bool LoadFile(const wxString& file, + wxAnimationType animType = wxANIMATION_TYPE_ANY); + + /** + Loads the animation from the given stream and calls SetAnimation(). + See wxAnimation::Load() for more info. + */ + virtual bool Load(wxInputStream& file, + wxAnimationType animType = wxANIMATION_TYPE_ANY); + + /** + Starts playing the animation. + + The animation is always played in loop mode (unless the last frame of the + animation has an infinite delay time) and always start from the first frame + even if you @ref Stop "stopped" it while some other frame was displayed. + */ + virtual bool Play(); + + /** + Sets the animation to play in this control. + + If the previous animation is being played, it's @ref Stop() stopped. + Until Play() isn't called, a static image, the first frame of the given + animation or the background colour will be shown + (see SetInactiveBitmap() for more info). + */ + virtual void SetAnimation(const wxAnimation& anim); + + /** + Sets the bitmap to show on the control when it's not playing an animation. + + If you set as inactive bitmap ::wxNullBitmap (which is the default), then the + first frame of the animation is instead shown when the control is inactive; + in this case, if there's no valid animation associated with the control + (see SetAnimation()), then the background colour of the window is shown. + + If the control is not playing the animation, the given bitmap will be + immediately shown, otherwise it will be shown as soon as Stop() is called. + + Note that the inactive bitmap, if smaller than the control's size, will be + centered in the control; if bigger, it will be stretched to fit it. + */ + virtual void SetInactiveBitmap(const wxBitmap& bmp); + + /** + Stops playing the animation. + The control will show the first frame of the animation, a custom static image or + the window's background colour as specified by the last SetInactiveBitmap() call. + */ + virtual void Stop(); +}; + + + +/** + @class wxAnimation + @wxheader{animate.h} + + This class encapsulates the concept of a platform-dependent animation. + An animation is a sequence of frames of the same size. + Sound is not supported by wxAnimation. + + @library{wxadv} + @category{gdi} + + @stdobjects + ::wxNullAnimation + + @see wxAnimationCtrl, @sample{animate} +*/ +class wxAnimation : public wxGDIObject +{ +public: + /** + Copy ctor. + */ + wxAnimation(const wxAnimation& anim); + + /** + Loads an animation from a file. + + @param name + The name of the file to load. + @param type + See LoadFile for more info. + */ + wxAnimation(const wxString& name, + wxAnimationType type = wxANIMATION_TYPE_ANY); + + /** + Destructor. + See @ref overview_refcount_destruct for more info. + */ + virtual ~wxAnimation(); + + /** + Returns the delay for the i-th frame in milliseconds. + If @c -1 is returned the frame is to be displayed forever. + */ + virtual int GetDelay(unsigned int i) const; + + /** + Returns the i-th frame as a wxImage. + */ + virtual wxImage GetFrame(unsigned int i) const; + + /** + Returns the number of frames for this animation. + */ + virtual unsigned int GetFrameCount() const; + + /** + Returns the size of the animation. + */ + virtual wxSize GetSize() const; + + /** + Returns @true if animation data is present. + */ + virtual bool IsOk() const; + + /** + Loads an animation from the given stream. + + @param stream + The stream to use to load the animation. + @param type + One of the following values: + @li wxANIMATION_TYPE_GIF: loads an animated GIF file; + @li wxANIMATION_TYPE_ANI: load an ANI file; + @li wxANIMATION_TYPE_ANY: tries to autodetect the filetype. + + @return @true if the operation succeeded, @false otherwise. + */ + virtual bool Load(wxInputStream& stream, + wxAnimationType type = wxANIMATION_TYPE_ANY); + + /** + Loads an animation from a file. + + @param name + A filename. + @param type + One of the wxAnimationType values; wxANIMATION_TYPE_ANY + means that the function should try to autodetect the filetype. + + @return @true if the operation succeeded, @false otherwise. + */ + virtual bool LoadFile(const wxString& name, + wxAnimationType type = wxANIMATION_TYPE_ANY); + + /** + Assignment operator, using @ref overview_refcount "reference counting". + */ + wxAnimation& operator =(const wxAnimation& brush); +}; + + +// ============================================================================ +// Global functions/macros +// ============================================================================ + +/** + An empty animation object. +*/ +wxAnimation wxNullAnimation; + diff --git a/interface/wx/app.h b/interface/wx/app.h new file mode 100644 index 0000000000..cf79e46a12 --- /dev/null +++ b/interface/wx/app.h @@ -0,0 +1,865 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: app.h +// Purpose: interface of wxApp +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + + +/** + @class wxAppConsole + @wxheader{app.h} + + This class is essential for writing console-only or hybrid apps without + having to define wxUSE_GUI=0. + + @todo MORE INFO + + @library{wxbase} + @category{appmanagement} + + @see @ref overview_app +*/ +class wxAppConsole : public wxEvtHandler +{ +protected: + /** + Creates the wxAppTraits object when GetTraits() needs it for the first time. + + @see wxAppTraits + */ + virtual wxAppTraits* CreateTraits(); + +public: + + /** + Destructor. + */ + virtual ~wxAppConsole(); + + /** + Dispatches the next event in the windowing system event queue. + Blocks until an event appears if there are none currently + (use Pending() if this is not wanted). + + This can be used for programming event loops, e.g. + + @code + while (app.Pending()) + Dispatch(); + @endcode + + @return @false if the event loop should stop and @true otherwise. + + @see Pending() + */ + virtual bool Dispatch(); + + /** + Call this to explicitly exit the main message (event) loop. + You should normally exit the main loop (and the application) by deleting + the top window. + */ + virtual void ExitMainLoop(); + + /** + This function is called before processing any event and allows the application + to preempt the processing of some events. + + If this method returns -1 the event is processed normally, otherwise either + @true or @false should be returned and the event processing stops immediately + considering that the event had been already processed (for the former return + value) or that it is not going to be processed at all (for the latter one). + */ + virtual int FilterEvent(wxEvent& event); + + /** + Returns the user-readable application name. + + The difference between this string and the one returned by GetAppName() is that + this one is meant to be shown to the user and so should be used for the window + titles, page headers and so on while the other one should be only used internally, + e.g. for the file names or configuration file keys. + By default, returns the same string as GetAppName(). + + @since 2.9.0 + */ + wxString GetAppDisplayName() const; + + /** + Returns the application name. + + @remarks wxWidgets sets this to a reasonable default before calling + OnInit(), but the application can reset it at will. + + @see GetAppDisplayName() + */ + wxString GetAppName() const; + + /** + Gets the class name of the application. The class name may be used in a + platform specific manner to refer to the application. + + @see SetClassName() + */ + wxString GetClassName() const; + + /** + Returns the one and only global application object. + Usually ::wxTheApp is usead instead. + + @see SetInstance() + */ + static wxAppConsole* GetInstance(); + + /** + Returns a pointer to the wxAppTraits object for the application. + If you want to customize the wxAppTraits object, you must override the + CreateTraits() function. + */ + wxAppTraits* GetTraits(); + + /** + Returns the user-readable vendor name. The difference between this string + and the one returned by GetVendorName() is that this one is meant to be shown + to the user and so should be used for the window titles, page headers and so on + while the other one should be only used internally, e.g. for the file names or + configuration file keys. + + By default, returns the same string as GetVendorName(). + + @since 2.9.0 + */ + const wxString& GetVendorDisplayName() const; + + /** + Returns the application's vendor name. + */ + const wxString& GetVendorName() const; + + /** + This function simply invokes the given method @a func of the specified + event handler @a handler with the @a event as parameter. It exists solely + to allow to catch the C++ exceptions which could be thrown by all event + handlers in the application in one place: if you want to do this, override + this function in your wxApp-derived class and add try/catch clause(s) to it. + */ + virtual void HandleEvent(wxEvtHandler* handler, + wxEventFunction func, + wxEvent& event) const; + + /** + Returns @true if the main event loop is currently running, i.e. if the + application is inside OnRun(). + + This can be useful to test whether events can be dispatched. For example, + if this function returns @false, non-blocking sockets cannot be used because + the events from them would never be processed. + */ + static bool IsMainLoopRunning(); + + /** + Called in response of an "open-application" Apple event. + Override this to create a new document in your app. + + @onlyfor{wxmac} + */ + virtual void MacNewFile(); + + /** + Called in response of an "open-document" Apple event. + + You need to override this method in order to open a document file after the + user double clicked on it or if the document file was dropped on either the + running application or the application icon in Finder. + + @onlyfor{wxmac} + */ + virtual void MacOpenFile(const wxString& fileName); + + /** + Called in response of a "get-url" Apple event. + + @onlyfor{wxmac} + */ + virtual void MacOpenURL(const wxString& url); + + /** + Called in response of a "print-document" Apple event. + + @onlyfor{wxmac} + */ + virtual void MacPrintFile(const wxString& fileName); + + /** + Called in response of a "reopen-application" Apple event. + + @onlyfor{wxmac} + */ + virtual void MacReopenApp(); + + /** + Called by wxWidgets on creation of the application. Override this if you wish + to provide your own (environment-dependent) main loop. + + @return 0 under X, and the wParam of the WM_QUIT message under Windows. + */ + virtual int MainLoop(); + + /** + This function is called when an assert failure occurs, i.e. the condition + specified in wxASSERT() macro evaluated to @false. + + It is only called in debug mode (when @c __WXDEBUG__ is defined) as + asserts are not left in the release code at all. + The base class version shows the default assert failure dialog box proposing to + the user to stop the program, continue or ignore all subsequent asserts. + + @param file + the name of the source file where the assert occurred + @param line + the line number in this file where the assert occurred + @param func + the name of the function where the assert occurred, may be + empty if the compiler doesn't support C99 __FUNCTION__ + @param cond + the condition of the failed assert in text form + @param msg + the message specified as argument to wxASSERT_MSG or wxFAIL_MSG, will + be @NULL if just wxASSERT or wxFAIL was used + */ + virtual void OnAssertFailure(const wxChar *file, + int line, + const wxChar *func, + const wxChar *cond, + const wxChar *msg); + + /** + Called when command line parsing fails (i.e. an incorrect command line option + was specified by the user). The default behaviour is to show the program usage + text and abort the program. + + Return @true to continue normal execution or @false to return + @false from OnInit() thus terminating the program. + + @see OnInitCmdLine() + */ + virtual bool OnCmdLineError(wxCmdLineParser& parser); + + /** + Called when the help option (@c --help) was specified on the command line. + The default behaviour is to show the program usage text and abort the program. + + Return @true to continue normal execution or @false to return + @false from OnInit() thus terminating the program. + + @see OnInitCmdLine() + */ + virtual bool OnCmdLineHelp(wxCmdLineParser& parser); + + /** + Called after the command line had been successfully parsed. You may override + this method to test for the values of the various parameters which could be + set from the command line. + + Don't forget to call the base class version unless you want to suppress + processing of the standard command line options. + Return @true to continue normal execution or @false to return @false from + OnInit() thus terminating the program. + + @see OnInitCmdLine() + */ + virtual bool OnCmdLineParsed(wxCmdLineParser& parser); + + /** + This function is called if an unhandled exception occurs inside the main + application event loop. It can return @true to ignore the exception and to + continue running the loop or @false to exit the loop and terminate the + program. In the latter case it can also use C++ @c throw keyword to + rethrow the current exception. + + The default behaviour of this function is the latter in all ports except under + Windows where a dialog is shown to the user which allows him to choose between + the different options. You may override this function in your class to do + something more appropriate. + + Finally note that if the exception is rethrown from here, it can be caught in + OnUnhandledException(). + */ + virtual bool OnExceptionInMainLoop(); + + /** + Override this member function for any processing which needs to be + done as the application is about to exit. OnExit is called after + destroying all application windows and controls, but before + wxWidgets cleanup. Note that it is not called at all if + OnInit() failed. + + The return value of this function is currently ignored, return the same + value as returned by the base class method if you override it. + */ + virtual int OnExit(); + + /** + This function may be called if something fatal happens: an unhandled + exception under Win32 or a a fatal signal under Unix, for example. However, + this will not happen by default: you have to explicitly call + wxHandleFatalExceptions() to enable this. + + Generally speaking, this function should only show a message to the user and + return. You may attempt to save unsaved data but this is not guaranteed to + work and, in fact, probably won't. + + @see wxHandleFatalExceptions() + */ + virtual void OnFatalException(); + + /** + This must be provided by the application, and will usually create the + application's main window, optionally calling SetTopWindow(). + + You may use OnExit() to clean up anything initialized here, provided + that the function returns @true. + + Notice that if you want to to use the command line processing provided by + wxWidgets you have to call the base class version in the derived class + OnInit(). + + Return @true to continue processing, @false to exit the application + immediately. + */ + virtual bool OnInit(); + + /** + Called from OnInit() and may be used to initialize the parser with the + command line options for this application. The base class versions adds + support for a few standard options only. + */ + virtual void OnInitCmdLine(wxCmdLineParser& parser); + + /** + This virtual function is where the execution of a program written in wxWidgets + starts. The default implementation just enters the main loop and starts + handling the events until it terminates, either because ExitMainLoop() has + been explicitly called or because the last frame has been deleted and + GetExitOnFrameDelete() flag is @true (this is the default). + + The return value of this function becomes the exit code of the program, so it + should return 0 in case of successful termination. + */ + virtual int OnRun(); + + /** + This function is called when an unhandled C++ exception occurs inside + OnRun() (the exceptions which occur during the program startup and shutdown + might not be caught at all). Notice that by now the main event loop has been + terminated and the program will exit, if you want to prevent this from happening + (i.e. continue running after catching an exception) you need to override + OnExceptionInMainLoop(). + + The default implementation shows information about the exception in debug build + but does nothing in the release build. + */ + virtual void OnUnhandledException(); + + /** + Returns @true if unprocessed events are in the window system event queue. + + @see Dispatch() + */ + virtual bool Pending(); + + /** + Set the application name to be used in the user-visible places such as window + titles. See GetAppDisplayName() for more about the differences between the + display name and name. + */ + void SetAppDisplayName(const wxString& name); + + /** + Sets the name of the application. This name should be used for file names, + configuration file entries and other internal strings. For the user-visible + strings, such as the window titles, the application display name set by + SetAppDisplayName() is used instead. + + By default the application name is set to the name of its executable file. + + @see GetAppName() + */ + void SetAppName(const wxString& name); + + /** + Sets the class name of the application. This may be used in a platform specific + manner to refer to the application. + + @see GetClassName() + */ + void SetClassName(const wxString& name); + + /** + Allows external code to modify global ::wxTheApp, but you should really + know what you're doing if you call it. + + @param app + Replacement for the global application object. + + @see GetInstance() + */ + static void SetInstance(wxAppConsole* app); + + /** + Set the vendor name to be used in the user-visible places. + See GetVendorDisplayName() for more about the differences between the + display name and name. + */ + void SetVendorDisplayName(const wxString& name); + + /** + Sets the name of application's vendor. The name will be used + in registry access. A default name is set by wxWidgets. + + @see GetVendorName() + */ + void SetVendorName(const wxString& name); + + /** + Yields control to pending messages in the windowing system. + + This can be useful, for example, when a time-consuming process writes to a + text window. Without an occasional yield, the text window will not be updated + properly, and on systems with cooperative multitasking, such as Windows 3.1 + other processes will not respond. + + Caution should be exercised, however, since yielding may allow the + user to perform actions which are not compatible with the current task. + Disabling menu items or whole menus during processing can avoid unwanted + reentrance of code: see ::wxSafeYield for a better function. + + Note that Yield() will not flush the message logs. This is intentional as + calling Yield() is usually done to quickly update the screen and popping up + a message box dialog may be undesirable. If you do wish to flush the log + messages immediately (otherwise it will be done during the next idle loop + iteration), call wxLog::FlushActive. + + Calling Yield() recursively is normally an error and an assert failure is + raised in debug build if such situation is detected. However if the + @a onlyIfNeeded parameter is @true, the method will just silently + return @false instead. + */ + virtual bool Yield(bool onlyIfNeeded = false); + + /** + Number of command line arguments (after environment-specific processing). + */ + int argc; + + /** + Command line arguments (after environment-specific processing). + + Under Windows and Linux/Unix, you should parse the command line + arguments and check for files to be opened when starting your + application. Under OS X, you need to override MacOpenFile() + since command line arguments are used differently there. + + You may use the wxCmdLineParser to parse command line arguments. + */ + wxChar** argv; +}; + + + + +/** + @class wxApp + @wxheader{app.h} + + The wxApp class represents the application itself. It is used to: + + @li set and get application-wide properties; + @li implement the windowing system message or event loop; + @li initiate application processing via wxApp::OnInit; + @li allow default processing of events not handled by other + objects in the application. + + You should use the macro IMPLEMENT_APP(appClass) in your application + implementation file to tell wxWidgets how to create an instance of your + application class. + + Use DECLARE_APP(appClass) in a header file if you want the wxGetApp function + (which returns a reference to your application object) to be visible to other + files. + + @library{wxbase} + @category{appmanagement} + + @see @ref overview_app +*/ +class wxApp : public wxAppConsole +{ +public: + /** + Constructor. Called implicitly with a definition of a wxApp object. + */ + wxApp(); + + /** + Destructor. Will be called implicitly on program exit if the wxApp + object is created on the stack. + */ + virtual ~wxApp(); + + /** + Returns @true if the application will exit when the top-level frame is deleted. + + @see SetExitOnFrameDelete() + */ + bool GetExitOnFrameDelete() const; + + /** + Returns @true if the application will use the best visual on systems that support + different visuals, @false otherwise. + + @see SetUseBestVisual() + */ + bool GetUseBestVisual() const; + + /** + Returns a pointer to the top window. + + @remarks If the top window hasn't been set using SetTopWindow(), + this function will find the first top-level window + (frame or dialog) and return that. + + @see SetTopWindow() + */ + virtual wxWindow* GetTopWindow() const; + + /** + Returns @true if the application is active, i.e. if one of its windows is + currently in the foreground. + + If this function returns @false and you need to attract users attention to + the application, you may use wxTopLevelWindow::RequestUserAttention to do it. + */ + virtual bool IsActive() const; + + /** + Windows-only function for processing a message. This function is called + from the main message loop, checking for windows that may wish to process it. + + The function returns @true if the message was processed, @false otherwise. + If you use wxWidgets with another class library with its own message loop, + you should make sure that this function is called to allow wxWidgets to + receive messages. For example, to allow co-existence with the Microsoft + Foundation Classes, override the PreTranslateMessage function: + + @code + // Provide wxWidgets message loop compatibility + BOOL CTheApp::PreTranslateMessage(MSG *msg) + { + if (wxTheApp && wxTheApp->ProcessMessage((WXMSW *)msg)) + return true; + else + return CWinApp::PreTranslateMessage(msg); + } + @endcode + + @onlyfor{wxmsw} + */ + bool ProcessMessage(WXMSG* msg); + + /** + Sends idle events to a window and its children. + Please note that this function is internal to wxWidgets and shouldn't be used + by user code. + + @remarks These functions poll the top-level windows, and their children, + for idle event processing. If @true is returned, more OnIdle + processing is requested by one or more window. + + @see wxIdleEvent + */ + virtual bool SendIdleEvents(wxWindow* win, wxIdleEvent& event); + + /** + Allows the programmer to specify whether the application will exit when the + top-level frame is deleted. + + @param flag + If @true (the default), the application will exit when the top-level frame + is deleted. If @false, the application will continue to run. + + @see GetExitOnFrameDelete(), @ref overview_app_shutdown + */ + void SetExitOnFrameDelete(bool flag); + + /** + Allows external code to modify global ::wxTheApp, but you should really + know what you're doing if you call it. + + @param app + Replacement for the global application object. + + @see GetInstance() + */ + static void SetInstance(wxAppConsole* app); + + /** + Allows runtime switching of the UI environment theme. + + Currently implemented for wxGTK2-only. + Return @true if theme was successfully changed. + + @param theme + The name of the new theme or an absolute path to a gtkrc-theme-file + */ + virtual bool SetNativeTheme(const wxString& theme); + + /** + Sets the 'top' window. You can call this from within OnInit() to let wxWidgets + know which is the main window. You don't have to set the top window; + it is only a convenience so that (for example) certain dialogs without parents + can use a specific window as the top window. If no top window is specified by the + application, wxWidgets just uses the first frame or dialog in its top-level window + list, when it needs to use the top window. + + @param window + The new top window. + + @see GetTopWindow(), OnInit() + */ + void SetTopWindow(wxWindow* window); + + /** + Allows the programmer to specify whether the application will use the best + visual on systems that support several visual on the same display. This is typically + the case under Solaris and IRIX, where the default visual is only 8-bit whereas + certain applications are supposed to run in TrueColour mode. + + Note that this function has to be called in the constructor of the wxApp + instance and won't have any effect when called later on. + This function currently only has effect under GTK. + + @param flag + If @true, the app will use the best visual. + @param forceTrueColour + If @true then the application will try to force using a TrueColour + visual and abort the app if none is found. + */ + void SetUseBestVisual(bool flag, bool forceTrueColour = false); +}; + + + +// ============================================================================ +// Global functions/macros +// ============================================================================ + + +/** @ingroup group_funcmacro_rtti */ +//@{ + +/** + This is used in headers to create a forward declaration of the wxGetApp() + function implemented by IMPLEMENT_APP(). + + It creates the declaration className& wxGetApp(). + + @header{wx/app.h} + + Example: + + @code + DECLARE_APP(MyApp) + @endcode +*/ +#define DECLARE_APP( className ) + +/** + This is used in the application class implementation file to make the + application class known to wxWidgets for dynamic construction. + + @header{wx/app.h} + + Example: + + @code + IMPLEMENT_APP(MyApp) + @endcode + + @see DECLARE_APP(). +*/ +#define IMPLEMENT_APP( className ) + +//@} + + + +/** + The global pointer to the singleton wxApp object. + + @see wxApp::GetInstance() +*/ +wxApp *wxTheApp; + + + +/** @ingroup group_funcmacro_appinitterm */ +//@{ + +/** + This function doesn't exist in wxWidgets but it is created by using the + IMPLEMENT_APP() macro. + + Thus, before using it anywhere but in the same module where this macro is + used, you must make it available using DECLARE_APP(). + + The advantage of using this function compared to directly using the global + ::wxTheApp pointer is that the latter is of type wxApp* and so wouldn't + allow you to access the functions specific to your application class but + not present in wxApp while wxGetApp() returns the object of the right type. + + @header{wx/app.h} +*/ +wxAppDerivedClass& wxGetApp(); + +/** + If @a doIt is @true, the fatal exceptions (also known as general protection + faults under Windows or segmentation violations in the Unix world) will be + caught and passed to wxApp::OnFatalException. + + By default, i.e. before this function is called, they will be handled in + the normal way which usually just means that the application will be + terminated. Calling wxHandleFatalExceptions() with @a doIt equal to @false + will restore this default behaviour. + + Notice that this function is only available if @c wxUSE_ON_FATAL_EXCEPTION + is 1 and under Windows platform this requires a compiler with support for + SEH (structured exception handling) which currently means only Microsoft + Visual C++ or a recent Borland C++ version. + + @header{wx/app.h} +*/ +bool wxHandleFatalExceptions(bool doIt = true); + +/** + This function is used in wxBase only and only if you don't create + wxApp object at all. In this case you must call it from your + @c main() function before calling any other wxWidgets functions. + + If the function returns @false the initialization could not be performed, + in this case the library cannot be used and wxUninitialize() shouldn't be + called neither. + + This function may be called several times but wxUninitialize() must be + called for each successful call to this function. + + @header{wx/app.h} +*/ +bool wxInitialize(); + +/** + This function is for use in console (wxBase) programs only. It must be called + once for each previous successful call to wxInitialize(). + + @header{wx/app.h} +*/ +void wxUninitialize(); + +/** + This function wakes up the (internal and platform dependent) idle system, + i.e. it will force the system to send an idle event even if the system + currently @e is idle and thus would not send any idle event until after + some other event would get sent. This is also useful for sending events + between two threads and is used by the corresponding functions + wxPostEvent() and wxEvtHandler::AddPendingEvent(). + + @header{wx/app.h} +*/ +void wxWakeUpIdle(); + +/** + Calls wxApp::Yield. + + @deprecated + This function is kept only for backwards compatibility. Please use + the wxApp::Yield method instead in any new code. + + @header{wx/app.h} +*/ +bool wxYield(); + +/** + This function is similar to wxYield, except that it disables the user input to + all program windows before calling wxYield and re-enables it again + afterwards. If @a win is not @NULL, this window will remain enabled, + allowing the implementation of some limited user interaction. + Returns the result of the call to ::wxYield. + + @header{wx/app.h} +*/ +bool wxSafeYield(wxWindow* win = NULL, bool onlyIfNeeded = false); + +/** + This function initializes wxWidgets in a platform-dependent way. Use this if you + are not using the default wxWidgets entry code (e.g. main or WinMain). + + For example, you can initialize wxWidgets from an Microsoft Foundation Classes + (MFC) application using this function. + + @note This overload of wxEntry is available under all platforms. + + @see wxEntryStart() + + @header{wx/app.h} +*/ +int wxEntry(int& argc, wxChar** argv); + +/** + See wxEntry(int&,wxChar**) for more info about this function. + + Notice that under Windows CE platform, and only there, the type of @a pCmdLine + is @c wchar_t *, otherwise it is @c char *, even in Unicode build. + + @remarks To clean up wxWidgets, call wxApp::OnExit followed by the static + function wxApp::CleanUp. For example, if exiting from an MFC application + that also uses wxWidgets: + @code + int CTheApp::ExitInstance() + { + // OnExit isn't called by CleanUp so must be called explicitly. + wxTheApp->OnExit(); + wxApp::CleanUp(); + + return CWinApp::ExitInstance(); + } + @endcode + + @header{wx/app.h} +*/ +int wxEntry(HINSTANCE hInstance, + HINSTANCE hPrevInstance = NULL, + char* pCmdLine = NULL, + int nCmdShow = SW_SHOWNORMAL); + +//@} + + + +/** @ingroup group_funcmacro_procctrl */ +//@{ + +/** + Exits application after calling wxApp::OnExit. + + Should only be used in an emergency: normally the top-level frame + should be deleted (after deleting all other frames) to terminate the + application. See wxCloseEvent and wxApp. + + @header{wx/app.h} +*/ +void wxExit(); + +//@} + diff --git a/interface/wx/apptrait.h b/interface/wx/apptrait.h new file mode 100644 index 0000000000..7da10c02b9 --- /dev/null +++ b/interface/wx/apptrait.h @@ -0,0 +1,125 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: apptrait.h +// Purpose: interface of wxAppTraits +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxAppTraits + @wxheader{apptrait.h} + + The wxAppTraits class defines various configurable aspects of a wxApp. + You can access it using wxApp::GetTraits() function and you can create your + own wxAppTraits overriding the wxApp::CreateTraits() function. + + Note that wxAppTraits is an abstract class since it contains many + pure virtual functions. + In fact, by default, wxWidgets creates a @c wxConsoleAppTraits object for + console applications (i.e. those applications linked against wxBase library + only - see the @ref page_libs page) and a @c wxGUIAppTraits object for GUI + applications. + Both these classes are derived by wxAppTraits and represent concrete + implementation of the wxAppTraits interface. + + @library{wxbase} + @category{appmanagement} + + @see @ref overview_app, wxApp +*/ +class wxAppTraits +{ +public: + /** + Called by wxWidgets to create the default configuration object for the + application. The default version creates a registry-based wxRegConfig + class under MSW and wxFileConfig under all other platforms. + + The wxApp::GetAppName and wxApp::GetVendorName methods are used to + determine the registry key or file name. + */ + virtual wxConfigBase* CreateConfig(); + + /** + Creates the global font mapper object used for encodings/charset mapping. + */ + virtual wxFontMapper* CreateFontMapper() = 0; + + /** + Creates a wxLog class for the application to use for logging errors. + The default implementation returns a new wxLogGui class. + + @see wxLog + */ + virtual wxLog* CreateLogTarget() = 0; + + /** + Creates the global object used for printing out messages. + */ + virtual wxMessageOutput* CreateMessageOutput() = 0; + + /** + Returns the renderer to use for drawing the generic controls (return + value may be @NULL in which case the default renderer for the current + platform is used); this is used in GUI mode only and always returns @NULL + in console. + + @note the returned pointer needs to be deleted by the caller. + */ + virtual wxRendererNative* CreateRenderer() = 0; + + /** + This method returns the name of the desktop environment currently + running in a Unix desktop. Currently only "KDE" or "GNOME" are + supported and the code uses the X11 session protocol vendor name + to figure out, which desktop environment is running. The method + returns an empty string otherwise and on all other platforms. + */ + virtual wxString GetDesktopEnvironment() const = 0; + + /** + Returns the wxStandardPaths object for the application. + It's normally the same for wxBase and wxGUI except in the case of wxMac + and wxCocoa. + + @todo the real function returns a reference to wxStandardPathsBase; + user looking at these docs will write code: + wxStandardPaths &ref = ...->GetStandardPaths(); + which won't compile... + */ + virtual wxStandardPaths& GetStandardPaths(); + + /** + Returns the wxWidgets port ID used by the running program and eventually + fills the given pointers with the values of the major and minor digits + of the native toolkit currently used. + + The version numbers returned are thus detected at run-time and not compile-time + (except when this is not possible e.g. wxMotif). + + E.g. if your program is using wxGTK port this function will return wxPORT_GTK + and put in given pointers the versions of the GTK library in use. + See wxPlatformInfo for more details. + */ + virtual wxPortId GetToolkitVersion(int* major = NULL, int* minor = NULL) const = 0; + + /** + Returns @true if @c fprintf(stderr) goes somewhere, @false otherwise. + */ + virtual bool HasStderr() = 0; + + /** + Returns @true if the library was built as wxUniversal. + Always returns @false for wxBase-only apps. + */ + virtual bool IsUsingUniversalWidgets() const = 0; + + /** + Shows the assert dialog with the specified message in GUI mode or just prints + the string to stderr in console mode. + Returns @true to suppress subsequent asserts, @false to continue as before. + */ + virtual bool ShowAssertDialog(const wxString& msg) = 0; +}; + diff --git a/interface/wx/archive.h b/interface/wx/archive.h new file mode 100644 index 0000000000..cb2069dc60 --- /dev/null +++ b/interface/wx/archive.h @@ -0,0 +1,638 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: archive.h +// Purpose: interface of wxArchive* classes +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxArchiveInputStream + @wxheader{archive.h} + + This is an abstract base class which serves as a common interface to + archive input streams such as wxZipInputStream. + + wxArchiveInputStream::GetNextEntry returns an wxArchiveEntry object containing + the meta-data for the next entry in the archive (and gives away ownership). + + Reading from the wxArchiveInputStream then returns the entry's data. Eof() + becomes @true after an attempt has been made to read past the end of the + entry's data. + + When there are no more entries, GetNextEntry() returns @NULL and sets Eof(). + + @library{wxbase} + @category{archive} + + @see @ref overview_archive, wxArchiveEntry, wxArchiveOutputStream +*/ +class wxArchiveInputStream : public wxFilterInputStream +{ +public: + /** + Closes the current entry. On a non-seekable stream reads to the end of + the current entry first. + */ + virtual bool CloseEntry() = 0; + + /** + Closes the current entry if one is open, then reads the meta-data for + the next entry and returns it in a wxArchiveEntry object, giving away + ownership. Reading this wxArchiveInputStream then returns the entry's data. + */ + wxArchiveEntry* GetNextEntry(); + + /** + Closes the current entry if one is open, then opens the entry specified + by the wxArchiveEntry object. + + @a entry must be from the same archive file that this wxArchiveInputStream + is reading, and it must be reading it from a seekable stream. + */ + virtual bool OpenEntry(wxArchiveEntry& entry) = 0; +}; + + + +/** + @class wxArchiveOutputStream + @wxheader{archive.h} + + This is an abstract base class which serves as a common interface to + archive output streams such as wxZipOutputStream. + + wxArchiveOutputStream::PutNextEntry is used to create a new entry in the + output archive, then the entry's data is written to the wxArchiveOutputStream. + Another call to PutNextEntry() closes the current entry and begins the next. + + @library{wxbase} + @category{archive} + + @see @ref overview_archive, wxArchiveEntry, wxArchiveInputStream +*/ +class wxArchiveOutputStream : public wxFilterOutputStream +{ +public: + /** + Calls Close() if it has not already been called. + */ + virtual ~wxArchiveOutputStream(); + + /** + Closes the archive, returning @true if it was successfully written. + Called by the destructor if not called explicitly. + + @see wxOutputStream::Close() + */ + virtual bool Close(); + + /** + Close the current entry. + It is called implicitly whenever another new entry is created with CopyEntry() + or PutNextEntry(), or when the archive is closed. + */ + virtual bool CloseEntry() = 0; + + /** + Some archive formats have additional meta-data that applies to the archive + as a whole. + For example in the case of zip there is a comment, which is stored at the end + of the zip file. CopyArchiveMetaData() can be used to transfer such information + when writing a modified copy of an archive. + + Since the position of the meta-data can vary between the various archive + formats, it is best to call CopyArchiveMetaData() before transferring + the entries. The wxArchiveOutputStream will then hold on to the meta-data + and write it at the correct point in the output file. + + When the input archive is being read from a non-seekable stream, the + meta-data may not be available when CopyArchiveMetaData() is called, + in which case the two streams set up a link and transfer the data + when it becomes available. + */ + virtual bool CopyArchiveMetaData(wxArchiveInputStream& stream) = 0; + + /** + Takes ownership of @a entry and uses it to create a new entry in the + archive. @a entry is then opened in the input stream @a stream + and its contents copied to this stream. + + For archive types which compress entry data, CopyEntry() is likely to be + much more efficient than transferring the data using Read() and Write() + since it will copy them without decompressing and recompressing them. + + @a entry must be from the same archive file that @a stream is + accessing. For non-seekable streams, @a entry must also be the last + thing read from @a stream. + */ + virtual bool CopyEntry(wxArchiveEntry* entry, + wxArchiveInputStream& stream) = 0; + + /** + Create a new directory entry (see wxArchiveEntry::IsDir) with the given + name and timestamp. + + PutNextEntry() can also be used to create directory entries, by supplying + a name with a trailing path separator. + */ + virtual bool PutNextDirEntry(const wxString& name, + const wxDateTime& dt = wxDateTime::Now()) = 0; + + /** + Takes ownership of entry and uses it to create a new entry in the archive. + The entry's data can then be written by writing to this wxArchiveOutputStream. + */ + virtual bool PutNextEntry(wxArchiveEntry* entry) = 0; + + /** + Create a new entry with the given name, timestamp and size. The entry's + data can then be written by writing to this wxArchiveOutputStream. + */ + virtual bool PutNextEntry(const wxString& name, + const wxDateTime& dt = wxDateTime::Now(), + wxFileOffset size = wxInvalidOffset) = 0; +}; + + + +/** + @class wxArchiveEntry + @wxheader{archive.h} + + This is an abstract base class which serves as a common interface to + archive entry classes such as wxZipEntry. + These hold the meta-data (filename, timestamp, etc.), for entries + in archive files such as zips and tars. + + @section wxarchiveentry_nonseekable About non-seekable streams + + This information applies only when reading archives from non-seekable streams. + When the stream is seekable GetNextEntry() returns a fully populated wxArchiveEntry. + See @ref overview_archive_noseek for more information. + + For generic programming, when the worst case must be assumed, you can rely on + all the fields of wxArchiveEntry being fully populated when + wxArchiveInputStream::GetNextEntry() returns, with the the following exceptions: + + @li GetSize(): guaranteed to be available after the entry has been read to Eof(), + or CloseEntry() has been called; + @li IsReadOnly(): guaranteed to be available after the end of the archive has + been reached, i.e. after GetNextEntry() returns NULL and Eof() is true. + + @library{wxbase} + @category{archive} + + @see @ref overview_archive, @ref overview_archive_generic, + wxArchiveInputStream, wxArchiveOutputStream, wxArchiveNotifier +*/ +class wxArchiveEntry : public wxObject +{ +public: + /** + Returns a copy of this entry object. + */ + wxArchiveEntry* Clone() const; + + /** + Gets the entry's timestamp. + */ + virtual wxDateTime GetDateTime() const = 0; + + /** + Sets the entry's timestamp. + */ + virtual void SetDateTime(const wxDateTime& dt) = 0; + + /** + Returns the entry's name, by default in the native format. + The name can include directory components, i.e. it can be a full path. + + If this is a directory entry, (i.e. if IsDir() is @true) then the + returned string is the name with a trailing path separator. + */ + virtual wxString GetName(wxPathFormat format = wxPATH_NATIVE) const = 0; + + /** + Sets the entry's name. + Setting a name with a trailing path separator sets IsDir(). + + @see GetName() + */ + virtual void SetName(const wxString& name, + wxPathFormat format = wxPATH_NATIVE) = 0; + + /** + Returns the size of the entry's data in bytes. + */ + virtual wxFileOffset GetSize() const = 0; + + /** + Sets the size of the entry's data in bytes. + */ + virtual void SetSize(wxFileOffset size) = 0; + + /** + Returns the path format used internally within the archive to store + filenames. + */ + virtual wxPathFormat GetInternalFormat() const = 0; + + /** + Returns the entry's filename in the internal format used within the + archive. The name can include directory components, i.e. it can be a + full path. + + The names of directory entries are returned without any trailing path + separator. This gives a canonical name that can be used in comparisons. + + @see @ref overview_archive_byname + */ + virtual wxString GetInternalName() const = 0; + + /** + Returns a numeric value unique to the entry within the archive. + */ + virtual wxFileOffset GetOffset() const = 0; + + /** + Returns @true if this is a directory entry. + + Directory entries are entries with no data, which are used to store + the meta-data of directories. They also make it possible for completely + empty directories to be stored. + + @note + The names of entries within an archive can be complete paths, and + unarchivers typically create whatever directories are necessary as they + restore files, even if the archive contains no explicit directory entries. + */ + virtual bool IsDir() const = 0; + + /** + Marks this entry as a directory if @a isDir is @true. See IsDir() for more info. + */ + virtual void SetIsDir(bool isDir = true) = 0; + + /** + Returns @true if the entry is a read-only file. + */ + virtual bool IsReadOnly() const = 0; + + /** + Sets this entry as a read-only file. + */ + virtual void SetIsReadOnly(bool isReadOnly = true) = 0; + + /** + Sets the notifier (see wxArchiveNotifier) for this entry. + + Whenever the wxArchiveInputStream updates this entry, it will then invoke + the associated notifier's wxArchiveNotifier::OnEntryUpdated method. + + Setting a notifier is not usually necessary. It is used to handle + certain cases when modifying an archive in a pipeline (i.e. between + non-seekable streams). + */ + void SetNotifier(wxArchiveNotifier& notifier); + + /** + Unsets the notifier eventually attached to this entry. + */ + virtual void UnsetNotifier(); +}; + + +/** + Type of stream enumeration; used by wxArchiveClassFactory methods. +*/ +enum wxStreamProtocolType +{ + wxSTREAM_PROTOCOL, //!< wxFileSystem protocol (should be only one) + wxSTREAM_MIMETYPE, //!< MIME types the stream handles + wxSTREAM_ENCODING, //!< Not used for archives + wxSTREAM_FILEEXT //!< File extensions the stream handles +}; + +/** + @class wxArchiveClassFactory + @wxheader{archive.h} + + Allows the creation of streams to handle archive formats such as zip and tar. + + For example, given a filename you can search for a factory that will + handle it and create a stream to read it: + + @code + factory = wxArchiveClassFactory::Find(filename, wxSTREAM_FILEEXT); + if (factory) + stream = factory->NewStream(new wxFFileInputStream(filename)); + @endcode + + wxArchiveClassFactory::Find can also search for a factory by MIME type + or wxFileSystem protocol. + + The available factories can be enumerated using + wxArchiveClassFactory::GetFirst() and wxArchiveClassFactory::GetNext(). + + @library{wxbase} + @category{archive} + + @see @ref overview_archive, @ref overview_archive_generic, wxArchiveEntry, + wxArchiveInputStream, wxArchiveOutputStream, wxFilterClassFactory +*/ +class wxArchiveClassFactory : public wxObject +{ +public: + /** + Returns @true if this factory can handle the given protocol, MIME type + or file extension. + + When using wxSTREAM_FILEEXT for the second parameter, the first parameter + can be a complete filename rather than just an extension. + */ + bool CanHandle(const wxChar* protocol, + wxStreamProtocolType type = wxSTREAM_PROTOCOL) const; + + /** + A static member that finds a factory that can handle a given protocol, MIME + type or file extension. Returns a pointer to the class factory if found, or + @NULL otherwise. It does not give away ownership of the factory. + + When using wxSTREAM_FILEEXT for the second parameter, the first parameter + can be a complete filename rather than just an extension. + */ + static const wxArchiveClassFactory* Find(const wxChar* protocol, + wxStreamProtocolType type = wxSTREAM_PROTOCOL); + + /** + Returns the wxMBConv object that the created streams will use when + translating meta-data. The initial default, set by the constructor, + is wxConvLocal. + */ + wxMBConv GetConv() const; + + /** + Sets the wxMBConv object that the created streams will use when + translating meta-data. + */ + void SetConv(wxMBConv& conv); + + //@{ + /** + GetFirst and GetNext can be used to enumerate the available factories. + For example, to list them: + + @code + wxString list; + const wxArchiveClassFactory *factory = wxArchiveClassFactory::GetFirst(); + + while (factory) { + list << factory->GetProtocol() << _T("\n"); + factory = factory->GetNext(); + } + @endcode + + GetFirst() and GetNext() return a pointer to a factory or @NULL if no more + are available. They do not give away ownership of the factory. + */ + static const wxArchiveClassFactory* GetFirst() const; + const wxArchiveClassFactory* GetNext() const; + //@} + + /** + Calls the static GetInternalName() function for the archive entry type, + for example wxZipEntry::GetInternalName. + */ + wxString GetInternalName(const wxString& name, + wxPathFormat format = wxPATH_NATIVE) const; + + /** + Returns the wxFileSystem protocol supported by this factory. + Equivalent to @code wxString(*GetProtocols()) @endcode. + */ + wxString GetProtocol() const; + + /** + Returns the protocols, MIME types or file extensions supported by this + factory, as an array of null terminated strings. + + It does not give away ownership of the array or strings. + For example, to list the file extensions a factory supports: + + @code + wxString list; + const wxChar *const *p; + + for (p = factory->GetProtocols(wxSTREAM_FILEEXT); *p; p++) + list << *p << _T("\n"); + @encode + */ + const wxChar* const* GetProtocols(wxStreamProtocolType type = wxSTREAM_PROTOCOL) const; + + /** + Create a new wxArchiveEntry object of the appropriate type. + */ + wxArchiveEntry* NewEntry() const; + + //@{ + /** + Create a new input or output stream to read or write an archive. + + If the parent stream is passed as a pointer then the new archive stream + takes ownership of it. If it is passed by reference then it does not. + */ + wxArchiveInputStream* NewStream(wxInputStream& stream) const; + wxArchiveOutputStream* NewStream(wxOutputStream& stream) const; + wxArchiveInputStream* NewStream(wxInputStream* stream) const; + wxArchiveOutputStream* NewStream(wxOutputStream* stream) const; + //@} + + /** + Adds this class factory to the list returned by GetFirst() or GetNext(). + + It is not necessary to do this to use the archive streams. It is usually + used when implementing streams, typically the implementation will + add a static instance of its factory class. + + It can also be used to change the order of a factory already in the list, + bringing it to the front. This isn't a thread safe operation + so can't be done when other threads are running that will be using the list. + The list does not take ownership of the factory. + */ + void PushFront(); + + /** + Removes this class factory from the list returned by GetFirst() and GetNext(). + + Removing from the list isn't a thread safe operation so can't be done when + other threads are running that will be using the list. + The list does not own the factories, so removing a factory does not delete it. + */ + void Remove(); +}; + + + +/** + @class wxArchiveNotifier + @wxheader{archive.h} + + If you need to know when a wxArchiveInputStream updates a wxArchiveEntry + object, you can create a notifier by deriving from this abstract base class, + overriding wxArchiveNotifier::OnEntryUpdated. + + An instance of your notifier class can then be assigned to the wxArchiveEntry + object using wxArchiveEntry::SetNotifier. + Your OnEntryUpdated() method will then be invoked whenever the input + stream updates the entry. + + Setting a notifier is not usually necessary. It is used to handle + certain cases when modifying an archive in a pipeline (i.e. between + non-seekable streams). + See @ref overview_archive_noseek. + + @library{wxbase} + @category{archive} + + @see @ref overview_archive_noseek, wxArchiveEntry, wxArchiveInputStream, + wxArchiveOutputStream +*/ +class wxArchiveNotifier +{ +public: + /** + This method must be overridden in your derived class. + */ + void OnEntryUpdated(class wxArchiveEntry& entry); +}; + + + +/** + @class wxArchiveIterator + @wxheader{archive.h} + + An input iterator template class that can be used to transfer an archive's + catalogue to a container. It is only available if wxUSE_STL is set to 1 + in setup.h, and the uses for it outlined below require a compiler which + supports member templates. + + @code + template class Arc, class T = typename Arc::entry_type* + class wxArchiveIterator + { + // this constructor creates an 'end of sequence' object + wxArchiveIterator(); + + // template parameter 'Arc' should be the type of an archive input stream + wxArchiveIterator(Arc& arc) { + // ... + } + }; + @endcode + + The first template parameter should be the type of archive input stream + (e.g. wxArchiveInputStream) and the second can either be a pointer to an entry + (e.g. wxArchiveEntry*), or a string/pointer pair (e.g. std::pairwxString, + wxArchiveEntry*). + + The @c wx/archive.h header defines the following typedefs: + + @code + typedef wxArchiveIterator wxArchiveIter; + + typedef wxArchiveIterator > wxArchivePairIter; + @endcode + + The header for any implementation of this interface should define similar + typedefs for its types, for example in @c wx/zipstrm.h there is: + + @code + typedef wxArchiveIterator wxZipIter; + + typedef wxArchiveIterator > wxZipPairIter; + @endcode + + Transferring the catalogue of an archive @e arc to a vector @e cat, + can then be done something like this: + + @code + std::vector cat((wxArchiveIter)arc, wxArchiveIter()); + @endcode + + When the iterator is dereferenced, it gives away ownership of an entry + object. So in the above example, when you have finished with @e cat + you must delete the pointers it contains. + + If you have smart pointers with normal copy semantics (i.e. not auto_ptr + or wxScopedPtr), then you can create an iterator which uses them instead. + + For example, with a smart pointer class for zip entries @e ZipEntryPtr: + + @code + typedef std::vector ZipCatalog; + typedef wxArchiveIterator ZipIter; + ZipCatalog cat((ZipIter)zip, ZipIter()); + @endcode + + Iterators that return std::pair objects can be used to populate a std::multimap, + to allow entries to be looked up by name. + The string is initialised using the wxArchiveEntry object's + wxArchiveEntry::GetInternalName function. + + @code + typedef std::multimap ZipCatalog; + ZipCatalog cat((wxZipPairIter)zip, wxZipPairIter()); + @endcode + + Note that this iterator also gives away ownership of an entry + object each time it is dereferenced. So in the above example, when + you have finished with @e cat you must delete the pointers it contains. + + Or if you have them, a pair containing a smart pointer can be used + (again @e ZipEntryPtr), no worries about ownership: + + @code + typedef std::multimap ZipCatalog; + typedef wxArchiveIterator > ZipPairIter; + ZipCatalog cat((ZipPairIter)zip, ZipPairIter()); + @endcode + + @library{wxbase} + @category{archive} + + @see wxArchiveEntry, wxArchiveInputStream, wxArchiveOutputStream +*/ +class wxArchiveIterator +{ +public: + /** + Default constructor. + */ + wxArchiveIterator(); + + /** + Construct the iterator that returns all the entries in the archive input + stream @a arc. + */ + wxArchiveIterator(Arc& arc); + + /** + Returns an entry object from the archive input stream, giving away + ownership. + */ + const T operator*() const; + + //@{ + /** + Position the input iterator at the next entry in the archive input stream. + */ + wxArchiveIterator operator++(); + wxArchiveIterator operator++(int); + //@} +}; + diff --git a/interface/wx/arrstr.h b/interface/wx/arrstr.h new file mode 100644 index 0000000000..34652fe144 --- /dev/null +++ b/interface/wx/arrstr.h @@ -0,0 +1,376 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: arrstr.h +// Purpose: interface of wxArrayString +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @todo + the following functions are not documented; do they need to be? + WXDLLIMPEXP_BASE int wxCMPFUNC_CONV wxStringSortAscending(wxString*, wxString*); + WXDLLIMPEXP_BASE int wxCMPFUNC_CONV wxStringSortDescending(wxString*, wxString*); +*/ + +/** + @class wxArrayString + @wxheader{arrstr.h} + + wxArrayString is an efficient container for storing wxString objects. + + It has the same features as all wxArray classes, i.e. it dynamically expands + when new items are added to it (so it is as easy to use as a linked list), + but the access time to the elements is constant, instead of being linear in + number of elements as in the case of linked lists. It is also very size + efficient and doesn't take more space than a C array @e wxString[] type + (wxArrayString uses its knowledge of internals of wxString class to achieve this). + + This class is used in the same way as other dynamic arrays(), except that no + ::WX_DEFINE_ARRAY declaration is needed for it. + When a string is added or inserted in the array, a copy of the string is created, + so the original string may be safely deleted (e.g. if it was a @e wxChar * + pointer the memory it was using can be freed immediately after this). + In general, there is no need to worry about string memory deallocation when using + this class - it will always free the memory it uses itself. + + The references returned by wxArrayString::Item, wxArrayString::Last or + wxArrayString::operator[] are not constant, so the array elements may + be modified in place like this: + + @code + array.Last().MakeUpper(); + @endcode + + @note none of the methods of wxArrayString is virtual including its + destructor, so this class should not be used as a base class. + + Although this is not true strictly speaking, this class may be considered as + a specialization of wxArray class for the wxString member data: it is not + implemented like this, but it does have all of the wxArray functions. + + @todo what about stl? how does it integrate? + + @library{wxbase} + @category{containers} + + @see wxArray, wxString, @ref overview_string +*/ +class wxArrayString : public wxArray +{ +public: + /** + Default constructor. + */ + wxArrayString(); + + /** + Copy constructor. + */ + wxArrayString(const wxArrayString& array); + + //@{ + /** + Constructor from a C string array. Pass a size @a sz and an array @a arr. + **/ + wxArrayString(size_t sz, const char** arr); + wxArrayString(size_t sz, const wchar_t** arr); + //@} + + /** + Constructor from a wxString array. Pass a size @a sz and array @a arr. + */ + wxArrayString(size_t sz, const wxString* arr); + + /** + Destructor frees memory occupied by the array strings. For performance + reasons it is not virtual, so this class should not be derived from. + */ + ~wxArrayString(); + + /** + Appends the given number of @a copies of the new item @a str to the + array and returns the index of the first new item in the array. + + @see Insert() + */ + size_t Add(const wxString& str, size_t copies = 1); + + /** + Preallocates enough memory to store @a nCount items. This function may be + used to improve array class performance before adding a known number of items + consecutively. + + @todo FIX THIS LINK + + @see @ref wxArray::memorymanagement "Dynamic array memory management" + */ + void Alloc(size_t nCount); + + /** + Clears the array contents and frees memory. + + @see Empty() + */ + void Clear(); + + /** + Empties the array: after a call to this function GetCount() will return 0. + However, this function does not free the memory used by the array and so + should be used when the array is going to be reused for storing other strings. + Otherwise, you should use Clear() to empty the array and free memory. + */ + void Empty(); + + /** + Returns the number of items in the array. + */ + size_t GetCount() const; + + /** + Search the element in the array, starting from the beginning if @a bFromEnd + is @false or from end otherwise. If @a bCase, comparison is case sensitive + (default), otherwise the case is ignored. + + This function uses linear search for wxArrayString. + Returns index of the first item matched or @c wxNOT_FOUND if there is no match. + */ + int Index(const wxString& sz, bool bCase = true, bool bFromEnd = false) const; + + /** + Insert the given number of @a copies of the new element in the array before the + position @a nIndex. Thus, for example, to insert the string in the beginning of + the array you would write: + + @code + Insert("foo", 0); + @endcode + + If @a nIndex is equal to GetCount() this function behaves as Add(). + */ + void Insert(const wxString& str, size_t nIndex, + size_t copies = 1); + + /** + Returns @true if the array is empty, @false otherwise. This function returns the + same result as GetCount() == 0 but is probably easier to read. + */ + bool IsEmpty() const; + + /** + Return the array element at position @a nIndex. An assert failure will + result from an attempt to access an element beyond the end of array in debug + mode, but no check is done in release mode. + + @see operator[] for the operator version. + */ + wxString& Item(size_t nIndex) const; + + /** + Returns the last element of the array. Attempt to access the last element of + an empty array will result in assert failure in debug build, however no checks + are done in release mode. + */ + wxString& Last() const; + + /** + Removes the first item matching this value. An assert failure is provoked by + an attempt to remove an element which does not exist in debug build. + + @see Index() + */ + void Remove(const wxString& sz); + + /** + Removes @a count items starting at position @a nIndex from the array. + */ + void RemoveAt(size_t nIndex, size_t count = 1); + + /** + Releases the extra memory allocated by the array. This function is useful to + minimize the array memory consumption. + + @todo FIX THIS LINK + + @see Alloc(), @ref wxArray::memorymanagement "Dynamic array memory + management" + */ + void Shrink(); + + /** + Sorts the array in alphabetical order or in reverse alphabetical order if + @a reverseOrder is @true. The sort is case-sensitive. + */ + void Sort(bool reverseOrder = false); + + /** + Sorts the array using the specified @a compareFunction for item comparison. + @a CompareFunction is defined as a function taking two @e const wxString + parameters and returning an @e int value less than, equal to or greater + than 0 if the first string is less than, equal to or greater than the + second one. + + Example: + The following example sorts strings by their length. + + @code + static int CompareStringLen(const wxString& first, const wxString& second) + { + return first.length() - second.length(); + } + + ... + + wxArrayString array; + + array.Add("one"); + array.Add("two"); + array.Add("three"); + array.Add("four"); + + array.Sort(CompareStringLen); + @endcode + */ + void Sort(CompareFunction compareFunction); + + /** + Compares 2 arrays respecting the case. Returns @true if the arrays have + different number of elements or if the elements don't match pairwise. + */ + bool operator !=(const wxArrayString& array) const; + + /** + Assignment operator. + */ + wxArrayString& operator=(const wxArrayString&); + + /** + Compares 2 arrays respecting the case. Returns @true only if the arrays have + the same number of elements and the same strings in the same order. + */ + bool operator ==(const wxArrayString& array) const; + + /** + Return the array element at position @a nIndex. An assert failure will + result from an attempt to access an element beyond the end of array in + debug mode, but no check is done in release mode. + + This is the operator version of the Item() method. + */ + wxString& operator[](size_t nIndex) const; +}; + + +/** + @class wxSortedArrayString + @wxheader{arrstr.h} + + wxSortedArrayString is an efficient container for storing wxString objects + which always keeps the string in alphabetical order. + + wxSortedArrayString uses binary search in its wxArrayString::Index() function + (instead of linear search for wxArrayString::Index()) which makes it much more + efficient if you add strings to the array rarely (because, of course, you have + to pay for Index() efficiency by having Add() be slower) but search for them + often. Several methods should not be used with sorted array (basically, all + those which break the order of items) which is mentioned in their description. + + @todo what about STL? who does it integrates? + + @library{wxbase} + @category{containers} + + @see wxArray, wxString, @ref overview_string +*/ +class wxSortedArrayString : public wxArrayString +{ +public: + + /** + Copy constructor. Note that when an array is assigned to a sorted array, + its contents is automatically sorted during construction. + */ + wxArrayString(const wxArrayString& array); + + /** + @copydoc wxArrayString::Add() + + @warning + For sorted arrays, the index of the inserted item will not be, in general, + equal to GetCount() - 1 because the item is inserted at the correct position + to keep the array sorted and not appended. + */ + size_t Add(const wxString& str, size_t copies = 1); + + + /** + @copydoc wxArrayString::Index() + + This function uses binary search for wxSortedArrayString, but it ignores + the @a bCase and @a bFromEnd parameters. + */ + int Index(const wxString& sz, bool bCase = true, + bool bFromEnd = false); + + /** + @warning this function should not be used with sorted arrays because it + could break the order of items and, for example, subsequent calls + to Index() would then not work! + */ + void Insert(const wxString& str, size_t nIndex, + size_t copies = 1); + + //@{ + /** + @warning this function should not be used with sorted array because it could + break the order of items and, for example, subsequent calls to Index() + would then not work! Also, sorting a wxSortedArrayString doesn't make + sense because its elements are always already sorted. + */ + void Sort(bool reverseOrder = false); + void Sort(CompareFunction compareFunction); + //@} +}; + + +// ============================================================================ +// Global functions/macros +// ============================================================================ + +/** @ingroup group_funcmacro_string */ +//@{ + +/** + Splits the given wxString object using the separator @a sep and returns the + result as a wxArrayString. + + If the @a escape character is non-@NULL, then the occurrences of @a sep + immediately prefixed with @a escape are not considered as separators. + Note that empty tokens will be generated if there are two or more adjacent + separators. + + @see wxJoin() + + @header{wx/arrstr.h} +*/ +wxArrayString wxSplit(const wxString& str, const wxChar sep, + const wxChar escape = '\\'); + +/** + Concatenate all lines of the given wxArrayString object using the separator + @a sep and returns the result as a wxString. + + If the @a escape character is non-@NULL, then it's used as prefix for each + occurrence of @a sep in the strings contained in @a arr before joining them + which is necessary in order to be able to recover the original array + contents from the string later using wxSplit(). + + @see wxSplit() + + @header{wx/arrstr.h} +*/ +wxString wxJoin(const wxArrayString& arr, const wxChar sep, + const wxChar escape = '\\'); + +//@} + diff --git a/interface/wx/artprov.h b/interface/wx/artprov.h new file mode 100644 index 0000000000..fc50474b81 --- /dev/null +++ b/interface/wx/artprov.h @@ -0,0 +1,283 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: artprov.h +// Purpose: interface of wxArtProvider +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxArtProvider + @wxheader{artprov.h} + + wxArtProvider class is used to customize the look of wxWidgets application. + + When wxWidgets needs to display an icon or a bitmap (e.g. in the standard file + dialog), it does not use a hard-coded resource but asks wxArtProvider for it + instead. This way users can plug in their own wxArtProvider class and easily + replace standard art with their own version. + + All that is needed is to derive a class from wxArtProvider, override either its + wxArtProvider::CreateBitmap() and/or its wxArtProvider::CreateIconBundle() methods + and register the provider with wxArtProvider::Push(): + + @code + class MyProvider : public wxArtProvider + { + protected: + wxBitmap CreateBitmap(const wxArtID& id, + const wxArtClient& client, + const wxSize size) + + // optionally override this one as well + wxIconBundle CreateIconBundle(const wxArtID& id, + const wxArtClient& client) + { ... } + }; + ... + wxArtProvider::Push(new MyProvider); + @endcode + + If you need bitmap images (of the same artwork) that should be displayed at + different sizes you should probably consider overriding wxArtProvider::CreateIconBundle + and supplying icon bundles that contain different bitmap sizes. + + There's another way of taking advantage of this class: you can use it in your + code and use platform native icons as provided by wxArtProvider::GetBitmap or + wxArtProvider::GetIcon. + + @todo IS THIS NB TRUE? + (@note this is not yet really possible as of wxWidgets 2.3.3, the set of wxArtProvider + bitmaps is too small). + + @section wxartprovider_identify Identifying art resources + + Every bitmap and icon bundle are known to wxArtProvider under an unique ID that + is used when requesting a resource from it. The ID is represented by wxArtID type + and can have one of these predefined values (you can see bitmaps represented by these + constants in the @ref page_samples_artprovider): + + + +
+ @li wxART_ERROR + @li wxART_QUESTION + @li wxART_WARNING + @li wxART_INFORMATION + @li wxART_ADD_BOOKMARK + @li wxART_DEL_BOOKMARK + @li wxART_HELP_SIDE_PANEL + @li wxART_HELP_SETTINGS + @li wxART_HELP_BOOK + @li wxART_HELP_FOLDER + @li wxART_HELP_PAGE + @li wxART_GO_BACK + @li wxART_GO_FORWARD + @li wxART_GO_UP + + @li wxART_GO_DOWN + @li wxART_GO_TO_PARENT + @li wxART_GO_HOME + @li wxART_PRINT + @li wxART_HELP + @li wxART_TIP + @li wxART_REPORT_VIEW + @li wxART_LIST_VIEW + @li wxART_NEW_DIR + @li wxART_FOLDER + @li wxART_FOLDER_OPEN + @li wxART_GO_DIR_UP + @li wxART_EXECUTABLE_FILE + @li wxART_NORMAL_FILE + @li wxART_TICK_MARK + @li wxART_CROSS_MARK + + @li wxART_MISSING_IMAGE + @li wxART_NEW + @li wxART_FILE_OPEN + @li wxART_FILE_SAVE + @li wxART_FILE_SAVE_AS + @li wxART_DELETE + @li wxART_COPY + @li wxART_CUT + @li wxART_PASTE + @li wxART_UNDO + @li wxART_REDO + @li wxART_QUIT + @li wxART_FIND + @li wxART_FIND_AND_REPLACE + @li wxART_HARDDISK + @li wxART_FLOPPY + @li wxART_CDROM + @li wxART_REMOVABLE +
+ + Additionally, any string recognized by custom art providers registered using + wxArtProvider::Push may be used. + + @note + When running under GTK+ 2, GTK+ stock item IDs (e.g. @c "gtk-cdrom") may be used + as well. Additionally, if wxGTK was compiled against GTK+ >= 2.4, then it is also + possible to load icons from current icon theme by specifying their name (without + extension and directory components). + Icon themes recognized by GTK+ follow the freedesktop.org Icon Themes specification + (see http://freedesktop.org/Standards/icon-theme-spec). + Note that themes are not guaranteed to contain all icons, so wxArtProvider may + return ::wxNullBitmap or ::wxNullIcon. + The default theme is typically installed in @c /usr/share/icons/hicolor. + + + @section wxartprovider_clients Clients + + Client is the entity that calls wxArtProvider's GetBitmap or GetIcon function. + It is represented by wxClientID type and can have one of these values: + + @li wxART_TOOLBAR + @li wxART_MENU + @li wxART_BUTTON + @li wxART_FRAME_ICON + @li wxART_CMN_DIALOG + @li wxART_HELP_BROWSER + @li wxART_MESSAGE_BOX + @li wxART_OTHER (used for all requests that don't fit into any of the + categories above) + + Client ID servers as a hint to wxArtProvider that is supposed to help it to + choose the best looking bitmap. For example it is often desirable to use + slightly different icons in menus and toolbars even though they represent + the same action (e.g. wxART_FILE_OPEN). Remember that this is really only a + hint for wxArtProvider -- it is common that wxArtProvider::GetBitmap returns + identical bitmap for different client values! + + @library{wxcore} + @category{misc,data} + + @see the @ref page_samples_artprovider for an example of wxArtProvider usage. +*/ +class wxArtProvider : public wxObject +{ +public: + /** + The destructor automatically removes the provider from the provider stack used + by GetBitmap(). + */ + virtual ~wxArtProvider(); + + /** + Delete the given @a provider. + */ + static bool Delete(wxArtProvider* provider); + + /** + Query registered providers for bitmap with given ID. + + @param id + wxArtID unique identifier of the bitmap. + @param client + wxArtClient identifier of the client (i.e. who is asking for the bitmap). + @param size + Size of the returned bitmap or wxDefaultSize if size doesn't matter. + + @return The bitmap if one of registered providers recognizes the ID or + wxNullBitmap otherwise. + */ + static wxBitmap GetBitmap(const wxArtID& id, + const wxArtClient& client = wxART_OTHER, + const wxSize& size = wxDefaultSize); + + /** + Same as wxArtProvider::GetBitmap, but return a wxIcon object + (or ::wxNullIcon on failure). + */ + static wxIcon GetIcon(const wxArtID& id, + const wxArtClient& client = wxART_OTHER, + const wxSize& size = wxDefaultSize); + + /** + Returns a suitable size hint for the given @e wxArtClient. If + @a platform_default is @true, return a size based on the current platform, + otherwise return the size from the topmost wxArtProvider. @e wxDefaultSize may + be returned if the client doesn't have a specified size, like wxART_OTHER for + example. + */ + static wxSize GetSizeHint(const wxArtClient& client, + bool platform_default = false); + + /** + Query registered providers for icon bundle with given ID. + + @param id + wxArtID unique identifier of the icon bundle. + @param client + wxArtClient identifier of the client (i.e. who is asking for the icon + bundle). + + @return The icon bundle if one of registered providers recognizes the ID + or wxNullIconBundle otherwise. + */ + static wxIconBundle GetIconBundle(const wxArtID& id, + const wxArtClient& client = wxART_OTHER); + + /** + Register new art provider and add it to the bottom of providers stack + (i.e. it will be queried as the last one). + + @see Push() + */ + static void Insert(wxArtProvider* provider); + + /** + Remove latest added provider and delete it. + */ + static bool Pop(); + + /** + Register new art provider and add it to the top of providers stack + (i.e. it will be queried as the first provider). + + @see Insert() + */ + static void Push(wxArtProvider* provider); + + /** + Remove a provider from the stack if it is on it. The provider is not + deleted, unlike when using Delete(). + */ + static bool Remove(wxArtProvider* provider); + +protected: + + /** + Derived art provider classes must override this method to create requested art + resource. Note that returned bitmaps are cached by wxArtProvider and it is + therefore not necessary to optimize CreateBitmap() for speed (e.g. you may + create wxBitmap objects from XPMs here). + + @param id + wxArtID unique identifier of the bitmap. + @param client + wxArtClient identifier of the client (i.e. who is asking for the bitmap). + This only servers as a hint. + @param size + Preferred size of the bitmap. The function may return a bitmap of different + dimensions, it will be automatically rescaled to meet client's request. + + @note + This is not part of wxArtProvider's public API, use wxArtProvider::GetBitmap + or wxArtProvider::GetIconBundle or wxArtProvider::GetIcon to query wxArtProvider + for a resource. + + @see CreateIconBundle() + */ + virtual wxBitmap CreateBitmap(const wxArtID& id, + const wxArtClient& client, + const wxSize& size); + + /** + This method is similar to CreateBitmap() but can be used when a bitmap + (or an icon) exists in several sizes. + */ + virtual wxIconBundle CreateIconBundle(const wxArtID& id, + const wxArtClient& client); +}; + diff --git a/interface/wx/atomic.h b/interface/wx/atomic.h new file mode 100644 index 0000000000..3767cd7f0b --- /dev/null +++ b/interface/wx/atomic.h @@ -0,0 +1,43 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: atomic.h +// Purpose: interface of global functions +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + + +// ============================================================================ +// Global functions/macros +// ============================================================================ + +/** @ingroup group_funcmacro_atomic */ +//@{ + +/** + This function increments @a value in an atomic manner. + + Whenever possible wxWidgets provides an efficient, CPU-specific, + implementation of this function. If such implementation is available, the + symbol wxHAS_ATOMIC_OPS is defined. Otherwise this function still exists + but is implemented in a generic way using a critical section which can be + prohibitively expensive for use in performance-sensitive code. + + @header{wx/atomic.h} +*/ +void wxAtomicInc(wxAtomicInt& value); + +/** + This function decrements value in an atomic manner. + + Returns 0 if value is 0 after decrement or any non-zero value (not + necessarily equal to the value of the variable) otherwise. + + @see wxAtomicInc + + @header{wx/atomic.h} +*/ +wxInt32 wxAtomicDec(wxAtomicInt& value); + +//@} + diff --git a/interface/wx/aui/auibook.h b/interface/wx/aui/auibook.h new file mode 100644 index 0000000000..b4d933eab3 --- /dev/null +++ b/interface/wx/aui/auibook.h @@ -0,0 +1,325 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: aui/auibook.h +// Purpose: interface of wxAuiNotebook +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxAuiNotebook + @headerfile auibook.h wx/aui/auibook.h + + wxAuiNotebook is part of the wxAUI class framework. + See also @ref overview_aui. + + wxAuiNotebook is a notebook control which implements many features common in + applications with dockable panes. + Specifically, wxAuiNotebook implements functionality which allows the user to + rearrange tab order via drag-and-drop, split the tab window into many different + splitter configurations, and toggle through different themes to customize + the control's look and feel. + + An effort has been made to try to maintain an API as similar to that of + wxNotebook. + + The default theme that is used is wxAuiDefaultTabArt, which provides a modern, + glossy look and feel. + The theme can be changed by calling wxAuiNotebook::SetArtProvider. + + @beginStyleTable + @style{wxAUI_NB_DEFAULT_STYLE} + Defined as wxAUI_NB_TOP | wxAUI_NB_TAB_SPLIT | wxAUI_NB_TAB_MOVE | + wxAUI_NB_SCROLL_BUTTONS | wxAUI_NB_CLOSE_ON_ACTIVE_TAB. + @style{wxAUI_NB_TAB_SPLIT} + Allows the tab control to be split by dragging a tab. + @style{wxAUI_NB_TAB_MOVE} + Allows a tab to be moved horizontally by dragging. + @style{wxAUI_NB_TAB_EXTERNAL_MOVE} + Allows a tab to be moved to another tab control. + @style{wxAUI_NB_TAB_FIXED_WIDTH} + With this style, all tabs have the same width. + @style{wxAUI_NB_SCROLL_BUTTONS} + With this style, left and right scroll buttons are displayed. + @style{wxAUI_NB_WINDOWLIST_BUTTON} + With this style, a drop-down list of windows is available. + @style{wxAUI_NB_CLOSE_BUTTON} + With this style, a close button is available on the tab bar. + @style{wxAUI_NB_CLOSE_ON_ACTIVE_TAB} + With this style, the close button is visible on the active tab. + @style{wxAUI_NB_CLOSE_ON_ALL_TABS} + With this style, the close button is visible on all tabs. + @style{wxAUI_NB_TOP} + With this style, tabs are drawn along the top of the notebook. + @style{wxAUI_NB_BOTTOM} + With this style, tabs are drawn along the bottom of the notebook. + @endStyleTable + + @library{wxaui} + @category{aui} +*/ +class wxAuiNotebook : public wxControl +{ +public: + wxAuiNotebook(); + + /** + Constructor. Creates a wxAuiNotebok control. + */ + wxAuiNotebook(wxWindow* parent, wxWindowID id = wxID_ANY, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxAUI_NB_DEFAULT_STYLE); + + /** + Adds a page. + If the @a select parameter is @true, calling this will generate a page change event. + */ + bool AddPage(wxWindow* page, const wxString& caption, + bool select = false, + const wxBitmap& bitmap = wxNullBitmap); + + /** + Sets the selection to the next or previous page. + */ + void AdvanceSelection(bool forward = true); + + /** + Creates the notebook window. + */ + bool Create(wxWindow* parent, wxWindowID id = wxID_ANY, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0); + + /** + Deletes a page at the given index. + Calling this method will generate a page change event. + */ + bool DeletePage(size_t page); + + /** + Returns the associated art provider. + */ + wxAuiTabArt* GetArtProvider() const; + + /** + Returns the desired height of the notebook for the given page height. + Use this to fit the notebook to a given page size. + */ + int GetHeightForPageHeight(int pageHeight); + + /** + Returns the page specified by the given index. + */ + wxWindow* GetPage(size_t page_idx) const; + + /** + Returns the tab bitmap for the page. + */ + wxBitmap GetPageBitmap(size_t page) const; + + /** + Returns the number of pages in the notebook. + */ + size_t GetPageCount() const; + + /** + Returns the page index for the specified window. + If the window is not found in the notebook, wxNOT_FOUND is returned. + */ + int GetPageIndex(wxWindow* page_wnd) const; + + /** + Returns the tab label for the page. + */ + wxString GetPageText(size_t page) const; + + /** + Returns the currently selected page. + */ + int GetSelection() const; + + /** + Returns the height of the tab control. + */ + int GetTabCtrlHeight() const; + + /** + InsertPage() is similar to AddPage, but allows the ability to specify the + insert location. + If the @a select parameter is @true, calling this will generate a page change + event. + */ + bool InsertPage(size_t page_idx, wxWindow* page, + const wxString& caption, + bool select = false, + const wxBitmap& bitmap = wxNullBitmap); + + /** + Removes a page, without deleting the window pointer. + */ + bool RemovePage(size_t page); + + /** + Sets the art provider to be used by the notebook. + */ + void SetArtProvider(wxAuiTabArt* art); + + /** + Sets the font for drawing the tab labels, using a bold version of the font for + selected tab labels. + */ + virtual bool SetFont(const wxFont& font); + + /** + Sets the font for measuring tab labels. + */ + void SetMeasuringFont(const wxFont& font); + + /** + Sets the font for drawing unselected tab labels. + */ + void SetNormalFont(const wxFont& font); + + /** + Sets the bitmap for the page. To remove a bitmap from the tab caption, pass + wxNullBitmap. + */ + bool SetPageBitmap(size_t page, const wxBitmap& bitmap); + + /** + Sets the tab label for the page. + */ + bool SetPageText(size_t page, const wxString& text); + + /** + Sets the font for drawing selected tab labels. + */ + void SetSelectedFont(const wxFont& font); + + /** + Sets the page selection. Calling this method will generate a page change event. + */ + size_t SetSelection(size_t new_page); + + /** + Sets the tab height. By default, the tab control height is calculated + by measuring the text height and bitmap sizes on the tab captions. Calling this + method will override that calculation and set the tab control to the specified + height parameter. A call to this method will override any call to + SetUniformBitmapSize(). + + Specifying -1 as the height will return the control to its default auto-sizing + behaviour. + */ + virtual void SetTabCtrlHeight(int height); + + //@{ + /** + Split performs a split operation programmatically. The argument @a page + indicates the page that will be split off. This page will also become the + active page after the split. + + The @a direction argument specifies where the pane should go, it should be one + of the following: wxTOP, wxBOTTOM, wxLEFT, or wxRIGHT. + */ + void SetUniformBitmapSize(const wxSize& size); + void Split(size_t page, int direction); + //@} + + /** + Shows the window menu for the active tab control associated with this notebook, + and returns @true if a selection was made. + */ + bool ShowWindowMenu(); +}; + + + +/** + @class wxAuiTabArt + @headerfile auibook.h wx/aui/auibook.h + + Tab art class. + + @todo BETTER DESCRIPTION NEEDED + + @library{wxaui} + @category{aui} +*/ +class wxAuiTabArt +{ +public: + /** + Constructor. + */ + wxAuiTabArt(); + + /** + Clones the art object. + */ + virtual wxAuiTabArt* Clone() = 0; + + /** + Draws a background on the given area. + */ + virtual void DrawBackground(wxDC& dc, wxWindow* wnd, const wxRect& rect) = 0; + + /** + Draws a button. + */ + virtual void DrawButton(wxDC& dc, wxWindow* wnd, const wxRect& in_rect, + int bitmap_id, int button_state, int orientation, + wxRect* out_rect) = 0; + + /** + Draws a tab. + */ + virtual void DrawTab(wxDC& dc, wxWindow* wnd, const wxAuiNotebookPage& page, + const wxRect& rect, int close_button_state, + wxRect* out_tab_rect, wxRect* out_button_rect, int* x_extent) = 0; + + /** + Returns the tab control size. + */ + virtual int GetBestTabCtrlSize(wxWindow*, const wxAuiNotebookPageArray&, const wxSize&) = 0; + + /** + Returns the indent size. + */ + virtual int GetIndentSize() = 0; + + /** + Returns the tab size for the given caption, bitmap and state. + */ + virtual wxSize GetTabSize(wxDC& dc, wxWindow* wnd, const wxString& caption, + const wxBitmap& bitmap, bool active, + int close_button_state, int* x_extent) = 0; + + /** + Sets flags. + */ + virtual void SetFlags(unsigned int flags) = 0; + + /** + Sets the font used for calculating measurements. + */ + virtual void SetMeasuringFont(const wxFont& font) = 0; + + /** + Sets the normal font for drawing labels. + */ + virtual void SetNormalFont(const wxFont& font) = 0; + + /** + Sets the font for drawing text for selected UI elements. + */ + virtual void SetSelectedFont(const wxFont& font) = 0; + + /** + Sets sizing information. + */ + virtual void SetSizingInfo(const wxSize& tab_ctrl_size, size_t tab_count) = 0; +}; + diff --git a/interface/wx/aui/dockart.h b/interface/wx/aui/dockart.h new file mode 100644 index 0000000000..34ae018422 --- /dev/null +++ b/interface/wx/aui/dockart.h @@ -0,0 +1,180 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: aui/dockart.h +// Purpose: interface of wxAuiDockArt +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + + +/** + @todo TOWRITE +*/ +enum wxAuiPaneDockArtSetting +{ + wxAUI_DOCKART_SASH_SIZE = 0, + wxAUI_DOCKART_CAPTION_SIZE = 1, + wxAUI_DOCKART_GRIPPER_SIZE = 2, + wxAUI_DOCKART_PANE_BORDER_SIZE = 3, + wxAUI_DOCKART_PANE_BUTTON_SIZE = 4, + wxAUI_DOCKART_BACKGROUND_COLOUR = 5, + wxAUI_DOCKART_SASH_COLOUR = 6, + wxAUI_DOCKART_ACTIVE_CAPTION_COLOUR = 7, + wxAUI_DOCKART_ACTIVE_CAPTION_GRADIENT_COLOUR = 8, + wxAUI_DOCKART_INACTIVE_CAPTION_COLOUR = 9, + wxAUI_DOCKART_INACTIVE_CAPTION_GRADIENT_COLOUR = 10, + wxAUI_DOCKART_ACTIVE_CAPTION_TEXT_COLOUR = 11, + wxAUI_DOCKART_INACTIVE_CAPTION_TEXT_COLOUR = 12, + wxAUI_DOCKART_BORDER_COLOUR = 13, + wxAUI_DOCKART_GRIPPER_COLOUR = 14, + wxAUI_DOCKART_CAPTION_FONT = 15, + wxAUI_DOCKART_GRADIENT_TYPE = 16 +}; + +/** + @todo TOWRITE +*/ +enum wxAuiPaneDockArtGradients +{ + wxAUI_GRADIENT_NONE = 0, + wxAUI_GRADIENT_VERTICAL = 1, + wxAUI_GRADIENT_HORIZONTAL = 2 +}; + +/** + @todo TOWRITE +*/ +enum wxAuiPaneButtonState +{ + wxAUI_BUTTON_STATE_NORMAL = 0, + wxAUI_BUTTON_STATE_HOVER = 1, + wxAUI_BUTTON_STATE_PRESSED = 2 +}; + +/** + @todo TOWRITE +*/ +enum wxAuiButtonId +{ + wxAUI_BUTTON_CLOSE = 101, + wxAUI_BUTTON_MAXIMIZE_RESTORE = 102, + wxAUI_BUTTON_MINIMIZE = 103, + wxAUI_BUTTON_PIN = 104, + wxAUI_BUTTON_OPTIONS = 105, + wxAUI_BUTTON_WINDOWLIST = 106, + wxAUI_BUTTON_LEFT = 107, + wxAUI_BUTTON_RIGHT = 108, + wxAUI_BUTTON_UP = 109, + wxAUI_BUTTON_DOWN = 110, + wxAUI_BUTTON_CUSTOM1 = 201, + wxAUI_BUTTON_CUSTOM2 = 202, + wxAUI_BUTTON_CUSTOM3 = 203 +}; + +/** + @class wxAuiDockArt + @headerfile dockart.h wx/aui/dockart.h + + wxAuiDockArt is part of the wxAUI class framework. + See also @ref overview_aui. + + wxAuiDockArt is the art provider: provides all drawing functionality to the + wxAui dock manager. This allows the dock manager to have a plugable look-and-feel. + + By default, a wxAuiManager uses an instance of this class called + wxAuiDefaultDockArt which provides bitmap art and a colour scheme that is + adapted to the major platforms' look. You can either derive from that class + to alter its behaviour or write a completely new dock art class. + Call wxAuiManager::SetArtProvider to force wxAUI to use your new dock art provider. + + @library{wxaui} + @category{aui} + + @see wxAuiManager, wxAuiPaneInfo +*/ +class wxAuiDockArt +{ +public: + /** + Constructor. + */ + wxAuiDockArt(); + + /** + Destructor. + */ + virtual ~wxAuiDockArt(); + + /** + Draws a background. + */ + virtual void DrawBackground(wxDC& dc, wxWindow* window, int orientation, + const wxRect& rect) = 0; + + /** + Draws a border. + */ + virtual void DrawBorder(wxDC& dc, wxWindow* window, const wxRect& rect, + wxAuiPaneInfo& pane) = 0; + + /** + Draws a caption. + */ + virtual void DrawCaption(wxDC& dc, wxWindow* window, const wxString& text, + const wxRect& rect, wxAuiPaneInfo& pane) = 0; + + /** + Draws a gripper. + */ + virtual void DrawGripper(wxDC& dc, wxWindow* window, const wxRect& rect, + wxAuiPaneInfo& pane) = 0; + + /** + Draws a button in the pane's title bar. + @a button can be one of the values of @b wxAuiButtonId. + @a button_state can be one of the values of @b wxAuiPaneButtonState. + */ + virtual void DrawPaneButton(wxDC& dc, wxWindow* window, int button, + int button_state, const wxRect& rect, + wxAuiPaneInfo& pane) = 0; + + /** + Draws a sash between two windows. + */ + virtual void DrawSash(wxDC& dc, wxWindow* window, int orientation, + const wxRect& rect) = 0; + /** + Get the colour of a certain setting. + @a id can be one of the colour values of @b wxAuiPaneDockArtSetting. + */ + virtual wxColour GetColour(int id) = 0; + + /** + Get a font setting. + */ + virtual wxFont GetFont(int id) = 0; + + /** + Get the value of a certain setting. + @a id can be one of the size values of @b wxAuiPaneDockArtSetting. + */ + virtual int GetMetric(int id) = 0; + + /** + Set a certain setting with the value @e colour. + @a id can be one of the colour values of @b wxAuiPaneDockArtSetting. + */ + virtual void SetColour(int id, const wxColour& colour) = 0; + + /** + Set a font setting. + */ + virtual void SetFont(int id, const wxFont& font) = 0; + + /** + Set a certain setting with the value @e new_val. + @a id can be one of the size values of @b wxAuiPaneDockArtSetting. + */ + virtual void SetMetric(int id, int new_val) = 0; +}; + diff --git a/interface/wx/aui/framemanager.h b/interface/wx/aui/framemanager.h new file mode 100644 index 0000000000..b95708e143 --- /dev/null +++ b/interface/wx/aui/framemanager.h @@ -0,0 +1,771 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: aui/aui.h +// Purpose: interface of wxAuiManager +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + + +/** + @todo TOWRITE +*/ +enum wxAuiManagerDock +{ + wxAUI_DOCK_NONE = 0, + wxAUI_DOCK_TOP = 1, + wxAUI_DOCK_RIGHT = 2, + wxAUI_DOCK_BOTTOM = 3, + wxAUI_DOCK_LEFT = 4, + wxAUI_DOCK_CENTER = 5, + wxAUI_DOCK_CENTRE = wxAUI_DOCK_CENTER +}; + + +/** + @todo TOWRITE +*/ +enum wxAuiManagerOption +{ + wxAUI_MGR_ALLOW_FLOATING = 1 << 0, + wxAUI_MGR_ALLOW_ACTIVE_PANE = 1 << 1, + wxAUI_MGR_TRANSPARENT_DRAG = 1 << 2, + wxAUI_MGR_TRANSPARENT_HINT = 1 << 3, + wxAUI_MGR_VENETIAN_BLINDS_HINT = 1 << 4, + wxAUI_MGR_RECTANGLE_HINT = 1 << 5, + wxAUI_MGR_HINT_FADE = 1 << 6, + wxAUI_MGR_NO_VENETIAN_BLINDS_FADE = 1 << 7, + + wxAUI_MGR_DEFAULT = wxAUI_MGR_ALLOW_FLOATING | + wxAUI_MGR_TRANSPARENT_HINT | + wxAUI_MGR_HINT_FADE | + wxAUI_MGR_NO_VENETIAN_BLINDS_FADE +}; + +/** + @class wxAuiManager + @headerfile aui.h wx/aui/aui.h + + wxAuiManager is the central class of the wxAUI class framework. + See also @ref overview_aui. + + wxAuiManager manages the panes associated with it for a particular wxFrame, + using a pane's wxAuiPaneInfo information to determine each pane's docking + and floating behavior. + + wxAuiManager uses wxWidgets' sizer mechanism to plan the layout of each frame. + It uses a replaceable dock art class to do all drawing, so all drawing is + localized in one area, and may be customized depending on an application's + specific needs. + + wxAuiManager works as follows: the programmer adds panes to the class, + or makes changes to existing pane properties (dock position, floating + state, show state, etc.). To apply these changes, wxAuiManager's + Update() function is called. This batch processing can be used to avoid + flicker, by modifying more than one pane at a time, and then "committing" + all of the changes at once by calling Update(). + + Panes can be added quite easily: + + @code + wxTextCtrl* text1 = new wxTextCtrl(this, -1); + wxTextCtrl* text2 = new wxTextCtrl(this, -1); + m_mgr.AddPane(text1, wxLEFT, wxT("Pane Caption")); + m_mgr.AddPane(text2, wxBOTTOM, wxT("Pane Caption")); + m_mgr.Update(); + @endcode + + Later on, the positions can be modified easily. The following will float + an existing pane in a tool window: + + @code + m_mgr.GetPane(text1).Float(); + @endcode + + + @section wxauimanager_layers Layers, Rows and Directions, Positions + + Inside wxAUI, the docking layout is figured out by checking several pane + parameters. Four of these are important for determining where a pane will end up: + + @li Direction: Each docked pane has a direction, Top, Bottom, Left, Right, or Center. + This is fairly self-explanatory. The pane will be placed in the location specified + by this variable. + @li Position: More than one pane can be placed inside of a dock. Imagine two panes + being docked on the left side of a window. One pane can be placed over another. + In proportionally managed docks, the pane position indicates its sequential position, + starting with zero. So, in our scenario with two panes docked on the left side, + the top pane in the dock would have position 0, and the second one would occupy + position 1. + @li Row: A row can allow for two docks to be placed next to each other. One of the + most common places for this to happen is in the toolbar. Multiple toolbar rows + are allowed, the first row being row 0, and the second row 1. Rows can also be + used on vertically docked panes. + @li Layer: A layer is akin to an onion. Layer 0 is the very center of the managed pane. + Thus, if a pane is in layer 0, it will be closest to the center window (also + sometimes known as the "content window"). Increasing layers "swallow up" all + layers of a lower value. This can look very similar to multiple rows, but is + different because all panes in a lower level yield to panes in higher levels. + The best way to understand layers is by running the wxAUI sample. + + + @library{wxbase} + @category{aui} + + @see wxAuiPaneInfo, wxAuiDockArt +*/ +class wxAuiManager : public wxEvtHandler +{ +public: + /** + Constructor. @a managed_wnd specifies the wxFrame which should be managed. + @a flags specifies options which allow the frame management behavior + to be modified. + */ + wxAuiManager(wxWindow* managed_wnd = NULL, + unsigned int flags = wxAUI_MGR_DEFAULT); + + /** + Dtor. + */ + virtual ~wxAuiManager(); + + //@{ + /** + AddPane() tells the frame manager to start managing a child window. + There are several versions of this function. The first version allows + the full spectrum of pane parameter possibilities. The second version is + used for simpler user interfaces which do not require as much configuration. + The last version allows a drop position to be specified, which will determine + where the pane will be added. + */ + bool AddPane(wxWindow* window, const wxAuiPaneInfo& pane_info); + bool AddPane(wxWindow* window, int direction = wxLEFT, + const wxString& caption = wxEmptyString); + bool AddPane(wxWindow* window, + const wxAuiPaneInfo& pane_info, + const wxPoint& drop_pos); + //@} + + /** + Tells the wxAuiManager to stop managing the pane specified by window. + The window, if in a floated frame, is reparented to the frame managed + by wxAuiManager. + */ + bool DetachPane(wxWindow* window); + + /** + Returns an array of all panes managed by the frame manager. + */ + wxAuiPaneInfoArray& GetAllPanes(); + + /** + Returns the current art provider being used. + @see wxAuiDockArt. + */ + wxAuiDockArt* GetArtProvider() const; + + /** + Returns the current dock constraint values. + See SetDockSizeConstraint() for more information. + */ + void GetDockSizeConstraint(double* widthpct, double* heightpct) const; + + /** + Returns the current manager's flags. + */ + unsigned int GetFlags() const; + + /** + Returns the frame currently being managed by wxAuiManager. + */ + wxWindow* GetManagedWindow() const; + + /** + Calling this method will return the wxAuiManager for a given window. + The @a window parameter should specify any child window or sub-child + window of the frame or window managed by wxAuiManager. + + The @a window parameter need not be managed by the manager itself, nor does it + even need to be a child or sub-child of a managed window. It must however + be inside the window hierarchy underneath the managed window. + */ + static wxAuiManager* GetManager(wxWindow* window); + + //@{ + /** + GetPane() is used to lookup a wxAuiPaneInfo object either by window pointer + or by pane name, which acts as a unique id for a window pane. + + The returned wxAuiPaneInfo object may then be modified to change a pane's + look, state or position. After one or more modifications to wxAuiPaneInfo, + wxAuiManager::Update() should be called to commit the changes to the user + interface. If the lookup failed (meaning the pane could not be found in the + manager), a call to the returned wxAuiPaneInfo's IsOk() method will return @false. + */ + wxAuiPaneInfo GetPane(wxWindow* window); + wxAuiPaneInfo GetPane(const wxString& name); + //@} + + /** + HideHint() hides any docking hint that may be visible. + */ + virtual void HideHint(); + + /** + This method is used to insert either a previously unmanaged pane window + into the frame manager, or to insert a currently managed pane somewhere + else. InsertPane() will push all panes, rows, or docks aside and + insert the window into the position specified by @a insert_location. + + Because @a insert_location can specify either a pane, dock row, or dock + layer, the @a insert_level parameter is used to disambiguate this. + The parameter @a insert_level can take a value of wxAUI_INSERT_PANE, + wxAUI_INSERT_ROW or wxAUI_INSERT_DOCK. + */ + bool InsertPane(wxWindow* window, + const wxAuiPaneInfo& insert_location, + int insert_level = wxAUI_INSERT_PANE); + + /** + LoadPaneInfo() is similar to to LoadPerspective, with the exception that it + only loads information about a single pane. It is used in combination with + SavePaneInfo(). + */ + void LoadPaneInfo(wxString pane_part, wxAuiPaneInfo& pane); + + /** + Loads a saved perspective. If update is @true, wxAuiManager::Update() + is automatically invoked, thus realizing the saved perspective on screen. + */ + bool LoadPerspective(const wxString& perspective, + bool update = true); + + /** + SavePaneInfo() is similar to SavePerspective, with the exception that it only + saves information about a single pane. It is used in combination with + LoadPaneInfo(). + */ + wxString SavePaneInfo(wxAuiPaneInfo& pane); + + /** + Saves the entire user interface layout into an encoded wxString, which + can then be stored by the application (probably using wxConfig). + + When a perspective is restored using LoadPerspective(), the entire user + interface will return to the state it was when the perspective was saved. + */ + wxString SavePerspective(); + + /** + Instructs wxAuiManager to use art provider specified by parameter + @a art_provider for all drawing calls. + This allows plugable look-and-feel features. The previous art provider object, + if any, will be deleted by wxAuiManager. + + @see wxAuiDockArt. + */ + void SetArtProvider(wxAuiDockArt* art_provider); + + /** + When a user creates a new dock by dragging a window into a docked position, + often times the large size of the window will create a dock that is unwieldly + large. wxAuiManager by default limits the size of any new dock to 1/3 of the + window size. For horizontal docks, this would be 1/3 of the window height. + For vertical docks, 1/3 of the width. + + Calling this function will adjust this constraint value. The numbers must be + between 0.0 and 1.0. For instance, calling SetDockSizeContraint with + 0.5, 0.5 will cause new docks to be limited to half of the size of the + entire managed window. + */ + void SetDockSizeConstraint(double widthpct, double heightpct); + + /** + This method is used to specify wxAuiManager's settings flags. @a flags + specifies options which allow the frame management behavior to be modified. + */ + void SetFlags(unsigned int flags); + + /** + Called to specify the frame or window which is to be managed by wxAuiManager. + Frame management is not restricted to just frames. Child windows or custom + controls are also allowed. + */ + void SetManagedWindow(wxWindow* managed_wnd); + + /** + This function is used by controls to explicitly show a hint window at the + specified rectangle. It is rarely called, and is mostly used by controls + implementing custom pane drag/drop behaviour. + The specified rectangle should be in screen coordinates. + */ + virtual void ShowHint(const wxRect& rect); + + /** + Uninitializes the framework and should be called before a managed frame or + window is destroyed. UnInit() is usually called in the managed wxFrame's + destructor. It is necessary to call this function before the managed frame + or window is destroyed, otherwise the manager cannot remove its custom event + handlers from a window. + */ + void UnInit(); + + /** + This method is called after any number of changes are + made to any of the managed panes. Update() must be invoked after + AddPane() or InsertPane() are called in order to "realize" or "commit" + the changes. In addition, any number of changes may be made to + wxAuiPaneInfo structures (retrieved with wxAuiManager::GetPane), but to + realize the changes, Update() must be called. This construction allows + pane flicker to be avoided by updating the whole layout at one time. + */ + void Update(); + +protected: + + /** + ProcessDockResult() is a protected member of the wxAUI layout manager. + It can be overridden by derived classes to provide custom docking calculations. + */ + virtual bool ProcessDockResult(wxAuiPaneInfo& target, + const wxAuiPaneInfo& new_pos); +}; + + + +/** + @class wxAuiPaneInfo + @headerfile aui.h wx/aui/aui.h + + wxAuiPaneInfo is part of the wxAUI class framework. + See also @ref overview_aui. + + wxAuiPaneInfo specifies all the parameters for a pane. + These parameters specify where the pane is on the screen, whether it is docked + or floating, or hidden. + In addition, these parameters specify the pane's docked position, floating + position, preferred size, minimum size, caption text among many other parameters. + + @library{wxbase} + @category{aui} + + @see wxAuiManager, wxAuiDockArt +*/ +class wxAuiPaneInfo +{ +public: + wxAuiPaneInfo(); + + /** + Copy constructor. + */ + wxAuiPaneInfo(const wxAuiPaneInfo& c); + + //@{ + /** + BestSize() sets the ideal size for the pane. The docking manager will attempt + to use this size as much as possible when docking or floating the pane. + */ + wxAuiPaneInfo BestSize(const wxSize& size); + wxAuiPaneInfo BestSize(int x, int y); + //@} + + /** + Bottom() sets the pane dock position to the bottom side of the frame. This is + the same thing as calling Direction(wxAUI_DOCK_BOTTOM). + */ + wxAuiPaneInfo& Bottom(); + + /** + BottomDockable() indicates whether a pane can be docked at the bottom of the + frame. + */ + wxAuiPaneInfo& BottomDockable(bool b = true); + + /** + Caption() sets the caption of the pane. + */ + wxAuiPaneInfo& Caption(const wxString& c); + + /** + CaptionVisible indicates that a pane caption should be visible. If @false, no + pane caption is drawn. + */ + wxAuiPaneInfo& CaptionVisible(bool visible = true); + + //@{ + /** + Center() sets the pane dock position to the left side of the frame. + The centre pane is the space in the middle after all border panes (left, top, + right, bottom) are subtracted from the layout. + This is the same thing as calling Direction(wxAUI_DOCK_CENTRE). + */ + wxAuiPaneInfo Centre(); + wxAuiPaneInfo Center(); + //@} + + //@{ + /** + CentrePane() specifies that the pane should adopt the default center pane + settings. Centre panes usually do not have caption bars. + This function provides an easy way of preparing a pane to be displayed in + the center dock position. + */ + wxAuiPaneInfo CentrePane(); + wxAuiPaneInfo CenterPane(); + //@} + + /** + CloseButton() indicates that a close button should be drawn for the pane. + */ + wxAuiPaneInfo& CloseButton(bool visible = true); + + /** + DefaultPane() specifies that the pane should adopt the default pane settings. + */ + wxAuiPaneInfo& DefaultPane(); + + /** + DestroyOnClose() indicates whether a pane should be detroyed when it is closed. + Normally a pane is simply hidden when the close button is clicked. + Setting DestroyOnClose to @true will cause the window to be destroyed when + the user clicks the pane's close button. + */ + wxAuiPaneInfo& DestroyOnClose(bool b = true); + + /** + Direction() determines the direction of the docked pane. It is functionally the + same as calling Left(), Right(), Top() or Bottom(), except that docking direction + may be specified programmatically via the parameter. + */ + wxAuiPaneInfo& Direction(int direction); + + /** + Dock() indicates that a pane should be docked. It is the opposite of Float(). + */ + wxAuiPaneInfo& Dock(); + + /** + DockFixed() causes the containing dock to have no resize sash. This is useful + for creating panes that span the entire width or height of a dock, but should + not be resizable in the other direction. + */ + wxAuiPaneInfo& DockFixed(bool b = true); + + /** + Dockable() specifies whether a frame can be docked or not. It is the same as + specifying TopDockable(b).BottomDockable(b).LeftDockable(b).RightDockable(b). + */ + wxAuiPaneInfo& Dockable(bool b = true); + + /** + Fixed() forces a pane to be fixed size so that it cannot be resized. After + calling Fixed(), IsFixed() will return @true. + */ + wxAuiPaneInfo& Fixed(); + + /** + Float() indicates that a pane should be floated. It is the opposite of Dock(). + */ + wxAuiPaneInfo& Float(); + + /** + Floatable() sets whether the user will be able to undock a pane and turn it + into a floating window. + */ + wxAuiPaneInfo& Floatable(bool b = true); + + //@{ + /** + FloatingPosition() sets the position of the floating pane. + */ + wxAuiPaneInfo FloatingPosition(const wxPoint& pos); + wxAuiPaneInfo FloatingPosition(int x, int y); + //@} + + //@{ + /** + FloatingSize() sets the size of the floating pane. + */ + wxAuiPaneInfo FloatingSize(const wxSize& size); + wxAuiPaneInfo FloatingSize(int x, int y); + //@} + + /** + Gripper() indicates that a gripper should be drawn for the pane. + */ + wxAuiPaneInfo& Gripper(bool visible = true); + + /** + GripperTop() indicates that a gripper should be drawn at the top of the pane. + */ + wxAuiPaneInfo& GripperTop(bool attop = true); + + /** + HasBorder() returns @true if the pane displays a border. + */ + bool HasBorder() const; + + /** + HasCaption() returns @true if the pane displays a caption. + */ + bool HasCaption() const; + + /** + HasCloseButton() returns @true if the pane displays a button to close the pane. + */ + bool HasCloseButton() const; + + /** + HasFlag() returns @true if the the property specified by flag is active for the + pane. + */ + bool HasFlag(unsigned int flag) const; + + /** + HasGripper() returns @true if the pane displays a gripper. + */ + bool HasGripper() const; + + /** + HasGripper() returns @true if the pane displays a gripper at the top. + */ + bool HasGripperTop() const; + + /** + HasMaximizeButton() returns @true if the pane displays a button to maximize the + pane. + */ + bool HasMaximizeButton() const; + + /** + HasMinimizeButton() returns @true if the pane displays a button to minimize the + pane. + */ + bool HasMinimizeButton() const; + + /** + HasPinButton() returns @true if the pane displays a button to float the pane. + */ + bool HasPinButton() const; + + /** + Hide() indicates that a pane should be hidden. + */ + wxAuiPaneInfo& Hide(); + + /** + IsBottomDockable() returns @true if the pane can be docked at the bottom of the + managed frame. + */ + bool IsBottomDockable() const; + + /** + IsDocked() returns @true if the pane is docked. + */ + bool IsDocked() const; + + /** + IsFixed() returns @true if the pane cannot be resized. + */ + bool IsFixed() const; + + /** + IsFloatable() returns @true if the pane can be undocked and displayed as a + floating window. + */ + bool IsFloatable() const; + + /** + IsFloating() returns @true if the pane is floating. + */ + bool IsFloating() const; + + /** + IsLeftDockable() returns @true if the pane can be docked on the left of the + managed frame. + */ + bool IsLeftDockable() const; + + /** + IsMoveable() returns @true if the docked frame can be undocked or moved to + another dock position. + */ + bool IsMovable() const; + + /** + IsOk() returns @true if the wxAuiPaneInfo structure is valid. A pane structure + is valid if it has an associated window. + */ + bool IsOk() const; + + /** + IsResizable() returns @true if the pane can be resized. + */ + bool IsResizable() const; + + /** + IsRightDockable() returns @true if the pane can be docked on the right of the + managed frame. + */ + bool IsRightDockable() const; + + /** + IsShown() returns @true if the pane is currently shown. + */ + bool IsShown() const; + + /** + IsToolbar() returns @true if the pane contains a toolbar. + */ + bool IsToolbar() const; + + /** + IsTopDockable() returns @true if the pane can be docked at the top of the + managed frame. + */ + bool IsTopDockable() const; + + /** + Layer() determines the layer of the docked pane. The dock layer is similar to + an onion, the inner-most layer being layer 0. Each shell moving in the outward + direction has a higher layer number. This allows for more complex docking layout + formation. + */ + wxAuiPaneInfo& Layer(int layer); + + /** + Left() sets the pane dock position to the left side of the frame. This is the + same thing as calling Direction(wxAUI_DOCK_LEFT). + */ + wxAuiPaneInfo& Left(); + + /** + LeftDockable() indicates whether a pane can be docked on the left of the frame. + */ + wxAuiPaneInfo& LeftDockable(bool b = true); + + //@{ + /** + MaxSize() sets the maximum size of the pane. + */ + wxAuiPaneInfo MaxSize(const wxSize& size); + wxAuiPaneInfo MaxSize(int x, int y); + //@} + + /** + MaximizeButton() indicates that a maximize button should be drawn for the pane. + */ + wxAuiPaneInfo& MaximizeButton(bool visible = true); + + //@{ + /** + MinSize() sets the minimum size of the pane. Please note that this is only + partially supported as of this writing. + */ + wxAuiPaneInfo MinSize(const wxSize& size); + wxAuiPaneInfo MinSize(int x, int y); + //@} + + /** + MinimizeButton() indicates that a minimize button should be drawn for the pane. + */ + wxAuiPaneInfo& MinimizeButton(bool visible = true); + + /** + Movable indicates whether a frame can be moved. + */ + wxAuiPaneInfo& Movable(bool b = true); + + /** + Name() sets the name of the pane so it can be referenced in lookup functions. + If a name is not specified by the user, a random name is assigned to the pane + when it is added to the manager. + */ + wxAuiPaneInfo& Name(const wxString& n); + + /** + PaneBorder indicates that a border should be drawn for the pane. + */ + wxAuiPaneInfo& PaneBorder(bool visible = true); + + /** + PinButton() indicates that a pin button should be drawn for the pane. + */ + wxAuiPaneInfo& PinButton(bool visible = true); + + /** + Position() determines the position of the docked pane. + */ + wxAuiPaneInfo& Position(int pos); + + /** + Resizable() allows a pane to be resized if the parameter is @true, and forces it + to be a fixed size if the parameter is @false. This is simply an antonym for Fixed(). + */ + wxAuiPaneInfo& Resizable(bool resizable = true); + + /** + Right() sets the pane dock position to the right side of the frame. + */ + wxAuiPaneInfo& Right(); + + /** + RightDockable() indicates whether a pane can be docked on the right of the + frame. + */ + wxAuiPaneInfo& RightDockable(bool b = true); + + /** + Row() determines the row of the docked pane. + */ + wxAuiPaneInfo& Row(int row); + + /** + Write the safe parts of a newly loaded PaneInfo structure "source" into "this" + used on loading perspectives etc. + */ + void SafeSet(wxAuiPaneInfo source); + + /** + SetFlag() turns the property given by flag on or off with the option_state + parameter. + */ + wxAuiPaneInfo& SetFlag(unsigned int flag, bool option_state); + + /** + Show() indicates that a pane should be shown. + */ + wxAuiPaneInfo& Show(bool show = true); + + /** + ToolbarPane() specifies that the pane should adopt the default toolbar pane + settings. + */ + wxAuiPaneInfo& ToolbarPane(); + + /** + Top() sets the pane dock position to the top of the frame. + */ + wxAuiPaneInfo& Top(); + + /** + TopDockable() indicates whether a pane can be docked at the top of the frame. + */ + wxAuiPaneInfo& TopDockable(bool b = true); + + /** + Window() assigns the window pointer that the wxAuiPaneInfo should use. + This normally does not need to be specified, as the window pointer is + automatically assigned to the wxAuiPaneInfo structure as soon as it is added + to the manager. + */ + wxAuiPaneInfo& Window(wxWindow* w); + + /** + Makes a copy of the wxAuiPaneInfo object. + */ + wxAuiPaneInfo& operator=(const wxAuiPaneInfo& c); +}; + diff --git a/interface/wx/base64.h b/interface/wx/base64.h new file mode 100644 index 0000000000..3967d697b9 --- /dev/null +++ b/interface/wx/base64.h @@ -0,0 +1,166 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: base64.h +// Purpose: interface of global functions +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + + +// ============================================================================ +// Global functions/macros +// ============================================================================ + +/** @ingroup group_funcmacro_misc */ +//@{ + +/** + This function encodes the given data using base64. + + To allocate the buffer of the correct size, use wxBase64EncodedSize() or + call this function with @a dst set to @NULL -- it will then return the + necessary buffer size. + + This raw encoding function overload writes the output string into the + provided buffer; the other overloads return it as a wxString. + + @param dst + The output buffer, may be @NULL to retrieve the needed buffer size. + @param dstLen + The output buffer size, ignored if dst is @NULL. + @param src + The input buffer, must not be @NULL. + @param srcLen + The length of the input data. + + @return @c wxCONV_FAILED if the output buffer is too small. + + @header{wx/base64.h} +*/ +size_t wxBase64Encode(char* dst, size_t dstLen, + const void* src, + size_t srcLen); + +/** + This function encodes the given data using base64 and returns the output as + a wxString. + + There is no error return. + + To allocate the buffer of the correct size, use wxBase64EncodedSize() or + call this function with @a dst set to @NULL -- it will then return the + necessary buffer size. + + @param src + The input buffer, must not be @NULL. + @param srcLen + The length of the input data. + + @header{wx/base64.h} +*/ +wxString wxBase64Encode(const void* src, size_t srcLen); + +/** + This function encodes the given data using base64 and returns the output as + a wxString. + + There is no error return. + + @header{wx/base64.h} +*/ +wxString wxBase64Encode(const wxMemoryBuffer& buf); + + +/** + Returns the size of the buffer necessary to contain the data encoded in a + base64 string of length @e srcLen. This can be useful for allocating a + buffer to be passed to wxBase64Decode(). + + @header{wx/base64.h} +*/ +size_t wxBase64DecodedSize(size_t srcLen); + +/** + Returns the length of the string with base64 representation of a buffer of + specified size @e len. This can be useful for allocating the buffer passed + to wxBase64Encode(). + + @header{wx/base64.h} +*/ +size_t wxBase64EncodedSize(size_t len); + +/** + This function decodes a Base64-encoded string. + + This overload is a raw decoding function and decodes the data into the + provided buffer @a dst of the given size @e dstLen. An error is returned if + the buffer is not large enough -- that is not at least + wxBase64DecodedSize(srcLen) bytes. + + This overload returns the number of bytes written to the buffer or the + necessary buffer size if @a dst was @NULL or @c wxCONV_FAILED on error, + e.g. if the output buffer is too small or invalid characters were + encountered in the input string. + + @param dst + Pointer to output buffer, may be @NULL to just compute the necessary + buffer size. + @param dstLen + The size of the output buffer, ignored if dst is @NULL. + @param src + The input string, must not be @NULL. For the version using wxString, + the input string should contain only ASCII characters. + @param srcLen + The length of the input string or special value wxNO_LEN if the string + is @NULL-terminated and the length should be computed by this function + itself. + @param mode + This parameter specifies the function behaviour when invalid characters + are encountered in input. By default, any such character stops the + decoding with error. If the mode is wxBase64DecodeMode_SkipWS, then the + white space characters are silently skipped instead. And if it is + wxBase64DecodeMode_Relaxed, then all invalid characters are skipped. + @param posErr + If this pointer is non-@NULL and an error occurs during decoding, it is + filled with the index of the invalid character. + + @header{wx/base64.h} +*/ +size_t wxBase64Decode(void* dst, size_t dstLen, + const char* src, + size_t srcLen = wxNO_LEN, + wxBase64DecodeMode mode = wxBase64DecodeMode_Strict, + size_t posErr = NULL); + +/** + See the wxBase64Decode(void*,size_t,const char*,size_t,wxBase64DecodeMode,size_t) + overload for more info about the parameters of this function. + + This overload allocates memory internally and returns it as wxMemoryBuffer + and is recommended for normal use. + + This overload returns a buffer with the base64 decoded binary equivalent + of the input string. In neither case is the buffer @NULL-terminated. + + @header{wx/base64.h} +*/ +wxMemoryBuffer wxBase64Decode(const char* src, + size_t srcLen = wxNO_LEN, + wxBase64DecodeMode mode = wxBase64DecodeMode_Strict, + size_t posErr = NULL); + +/** + See the wxBase64Decode(void*,size_t,const char*,size_t,wxBase64DecodeMode,size_t) + overload for more info about the parameters of this function. + + This overload takes as input a wxString and returns the internally-allocated + memory as a wxMemoryBuffer, containing the base64 decoded data. + + @header{wx/base64.h} +*/ +wxMemoryBuffer wxBase64Decode(const wxString& src, + wxBase64DecodeMode mode = wxBase64DecodeMode_Strict, + size_t posErr = NULL); + +//@} + diff --git a/interface/wx/bitmap.h b/interface/wx/bitmap.h new file mode 100644 index 0000000000..1bcf959e19 --- /dev/null +++ b/interface/wx/bitmap.h @@ -0,0 +1,687 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: bitmap.h +// Purpose: interface of wxBitmap* classes +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + + +/** + In wxBitmap and wxBitmapHandler context this value means: "use the screen depth". +*/ +#define wxBITMAP_SCREEN_DEPTH (-1) + +/** + @class wxBitmapHandler + @wxheader{bitmap.h} + + This is the base class for implementing bitmap file loading/saving, and + bitmap creation from data. + It is used within wxBitmap and is not normally seen by the application. + + If you wish to extend the capabilities of wxBitmap, derive a class from + wxBitmapHandler and add the handler using wxBitmap::AddHandler() in your + application initialisation. + + @library{wxcore} + @category{misc} + + @see @ref overview_bitmap, wxBitmap, wxIcon, wxCursor +*/ +class wxBitmapHandler : public wxObject +{ +public: + /** + Default constructor. + + In your own default constructor, initialise the members m_name, + m_extension and m_type. + */ + wxBitmapHandler(); + + /** + Destroys the wxBitmapHandler object. + */ + virtual ~wxBitmapHandler(); + + /** + Creates a bitmap from the given data, which can be of arbitrary type. + The wxBitmap object @a bitmap is manipulated by this function. + + @param bitmap + The wxBitmap object. + @param width + The width of the bitmap in pixels. + @param height + The height of the bitmap in pixels. + @param depth + The depth of the bitmap in pixels. + If this is ::wxBITMAP_SCREEN_DEPTH, the screen depth is used. + @param data + Data whose type depends on the value of type. + @param type + A bitmap type identifier - see ::wxBitmapType for a list + of possible values. + + @return @true if the call succeeded, @false otherwise (the default). + */ + virtual bool Create(wxBitmap* bitmap, const void* data, wxBitmapType type, + int width, int height, int depth = 1); + + /** + Gets the file extension associated with this handler. + */ + const wxString& GetExtension() const; + + /** + Gets the name of this handler. + */ + const wxString& GetName() const; + + /** + Gets the bitmap type associated with this handler. + */ + wxBitmapType GetType() const; + + /** + Loads a bitmap from a file or resource, putting the resulting data into + @a bitmap. + + @param bitmap + The bitmap object which is to be affected by this operation. + @param name + Either a filename or a Windows resource name. + The meaning of name is determined by the type parameter. + @param type + See ::wxBitmapType for values this can take. + @param desiredWidth + The desired width for the loaded bitmap. + @param desiredHeight + The desired height for the loaded bitmap. + + @return @true if the operation succeeded, @false otherwise. + + @see wxBitmap::LoadFile, wxBitmap::SaveFile, SaveFile() + */ + virtual bool LoadFile(wxBitmap* bitmap, const wxString& name, wxBitmapType type, + int desiredWidth, int desiredHeight); + + /** + Saves a bitmap in the named file. + + @param bitmap + The bitmap object which is to be affected by this operation. + @param name + A filename. The meaning of name is determined by the type parameter. + @param type + See ::wxBitmapType for values this can take. + @param palette + An optional palette used for saving the bitmap. + + @return @true if the operation succeeded, @false otherwise. + + @see wxBitmap::LoadFile, wxBitmap::SaveFile, LoadFile() + */ + virtual bool SaveFile(const wxBitmap* bitmap, const wxString& name, wxBitmapType type, + const wxPalette* palette = NULL) const; + + /** + Sets the handler extension. + + @param extension + Handler extension. + */ + void SetExtension(const wxString& extension); + + /** + Sets the handler name. + + @param name + Handler name. + */ + void SetName(const wxString& name); + + /** + Sets the handler type. + + @param type + Handler type. + */ + void SetType(wxBitmapType type); +}; + + +/** + @class wxBitmap + @wxheader{bitmap.h} + + This class encapsulates the concept of a platform-dependent bitmap, + either monochrome or colour or colour with alpha channel support. + + If you need direct access the bitmap data instead going through + drawing to it using wxMemoryDC you need to use the wxPixelData + class (either wxNativePixelData for RGB bitmaps or wxAlphaPixelData + for bitmaps with an additionaly alpha channel). + + @note + Many wxBitmap functions take a @e type parameter, which is a value of the + ::wxBitmapType enumeration. + The validity of those values depends however on the platform where your program + is running and from the wxWidgets configuration. + If all possible wxWidgets settings are used, the Windows platform supports BMP file, + BMP resource, XPM data, and XPM. + Under wxGTK, the available formats are BMP file, XPM data, XPM file, and PNG file. + Under wxMotif, the available formats are XBM data, XBM file, XPM data, XPM file. + In addition, wxBitmap can load and save all formats that wxImage; see wxImage for + more info. Of course, you must have wxImage handlers loaded. + + @library{wxcore} + @category{gdi} + + @stdobjects + ::wxNullBitmap + + @see @ref overview_bitmap, @ref overview_bitmap_supportedformats, + wxDC::Blit, wxIcon, wxCursor, wxMemoryDC, wxImage, wxPixelData +*/ +class wxBitmap : public wxGDIObject +{ +public: + /** + Default constructor. + + Constructs a bitmap object with no data; an assignment or another member + function such as Create() or LoadFile() must be called subsequently. + */ + wxBitmap(); + + /** + Copy constructor, uses @ref overview_refcount "reference counting". + To make a real copy, you can use: + + @code + wxBitmap newBitmap = oldBitmap.GetSubBitmap( + wxRect(0, 0, oldBitmap.GetWidth(), oldBitmap.GetHeight())); + @endcode + */ + wxBitmap(const wxBitmap& bitmap); + + + /* + Creates a bitmap from the given @a data which is interpreted in + platform-dependent manner. + + @param data + Specifies the bitmap data in a platform-dependent format. + @param type + May be one of the ::wxBitmapType values and indicates which type of + bitmap does @a data contains. See the note in the class + detailed description. + @param width + Specifies the width of the bitmap. + @param height + Specifies the height of the bitmap. + @param depth + Specifies the depth of the bitmap. + If this is omitted, the display depth of the screen is used. + wxBitmap(const void* data, int type, int width, int height, int depth = -1); + + + NOTE: this ctor is not implemented by all ports, is somewhat useless + without further description of the "data" supported formats and + uses 'int type' instead of wxBitmapType, so don't document it. + */ + + /** + Creates a bitmap from the given array @a bits. + You should only use this function for monochrome bitmaps (depth 1) in + portable programs: in this case the bits parameter should contain an XBM image. + + For other bit depths, the behaviour is platform dependent: under Windows, + the data is passed without any changes to the underlying CreateBitmap() API. + Under other platforms, only monochrome bitmaps may be created using this + constructor and wxImage should be used for creating colour bitmaps from + static data. + + @param bits + Specifies an array of pixel values. + @param width + Specifies the width of the bitmap. + @param height + Specifies the height of the bitmap. + @param depth + Specifies the depth of the bitmap. + If this is omitted, then a value of 1 (monochrome bitmap) is used. + */ + wxBitmap(const char bits[], int width, int height, int depth = 1); + + /** + Creates a new bitmap. A depth of ::wxBITMAP_SCREEN_DEPTH indicates the + depth of the current screen or visual. + + Some platforms only support 1 for monochrome and ::wxBITMAP_SCREEN_DEPTH for + the current colour setting. + + A depth of 32 including an alpha channel is supported under MSW, Mac and GTK+. + */ + wxBitmap(int width, int height, int depth = wxBITMAP_SCREEN_DEPTH); + + /** + Creates a bitmap from XPM data. + */ + wxBitmap(const char* const* bits); + + /** + Loads a bitmap from a file or resource. + + @param name + This can refer to a resource name or a filename under MS Windows and X. + Its meaning is determined by the @a type parameter. + @param type + May be one of the ::wxBitmapType values and indicates which type of + bitmap should be loaded. See the note in the class detailed description. + + @see LoadFile() + */ + wxBitmap(const wxString& name, wxBitmapType type = wxBITMAP_TYPE_XPM); + + /** + Creates this bitmap object from the given image. + This has to be done to actually display an image as you cannot draw an + image directly on a window. + + The resulting bitmap will use the provided colour depth (or that of the + current system if depth is ::wxBITMAP_SCREEN_DEPTH) which entails that a + colour reduction may take place. + + When in 8-bit mode (PseudoColour mode), the GTK port will use a color cube + created on program start-up to look up colors. This ensures a very fast conversion, + but the image quality won't be perfect (and could be better for photo images using + more sophisticated dithering algorithms). + + On Windows, if there is a palette present (set with SetPalette), it will be + used when creating the wxBitmap (most useful in 8-bit display mode). + On other platforms, the palette is currently ignored. + + @param img + Platform-independent wxImage object. + @param depth + Specifies the depth of the bitmap. + If this is omitted, the display depth of the screen is used. + */ + wxBitmap(const wxImage& img, int depth = wxBITMAP_SCREEN_DEPTH); + + /** + Destructor. + See @ref overview_refcount_destruct for more info. + + If the application omits to delete the bitmap explicitly, the bitmap will be + destroyed automatically by wxWidgets when the application exits. + + @warning + Do not delete a bitmap that is selected into a memory device context. + */ + virtual ~wxBitmap(); + + /** + Adds a handler to the end of the static list of format handlers. + + @param handler + A new bitmap format handler object. There is usually only one instance + of a given handler class in an application session. + + @see wxBitmapHandler + */ + static void AddHandler(wxBitmapHandler* handler); + + /** + Deletes all bitmap handlers. + This function is called by wxWidgets on exit. + */ + static void CleanUpHandlers(); + + /** + Creates an image from a platform-dependent bitmap. This preserves + mask information so that bitmaps and images can be converted back + and forth without loss in that respect. + */ + virtual wxImage ConvertToImage() const; + + /** + Creates the bitmap from an icon. + */ + virtual bool CopyFromIcon(const wxIcon& icon); + + /** + Creates a fresh bitmap. + If the final argument is omitted, the display depth of the screen is used. + + This overload works on all platforms. + */ + virtual bool Create(int width, int height, int depth = wxBITMAP_SCREEN_DEPTH); + + /* + Creates a bitmap from the given data, which can be of arbitrary type. + + @param data + Data whose type depends on the value of type. + @param type + A bitmap type identifier; see ::wxBitmapType for the list of values. + See the note in the class detailed description for more info. + @param width + The width of the bitmap in pixels. + @param height + The height of the bitmap in pixels. + @param depth + The depth of the bitmap in pixels. If this is -1, the screen depth is used. + + @return @true if the call succeeded, @false otherwise. + + This overload depends on the @a type of data. + + virtual bool Create(const void* data, int type, int width, + int height, int depth = -1); + + NOTE: leave this undoc for the same reason of the relative ctor. + */ + + /** + Finds the handler with the given @a name. + + @return A pointer to the handler if found, @NULL otherwise. + */ + static wxBitmapHandler* FindHandler(const wxString& name); + + /** + Finds the handler associated with the given @a extension and @a type. + + @param extension + The file extension, such as "bmp" (without the dot). + @param bitmapType + The bitmap type managed by the handler, see ::wxBitmapType. + + @return A pointer to the handler if found, @NULL otherwise. + */ + static wxBitmapHandler* FindHandler(const wxString& extension, + wxBitmapType bitmapType); + + /** + Finds the handler associated with the given bitmap type. + + @param bitmapType + The bitmap type managed by the handler, see ::wxBitmapType. + + @return A pointer to the handler if found, @NULL otherwise. + + @see wxBitmapHandler + */ + + static wxBitmapHandler* FindHandler(wxBitmapType bitmapType); + + /** + Gets the colour depth of the bitmap. + A value of 1 indicates a monochrome bitmap. + */ + virtual int GetDepth() const; + + /** + Returns the static list of bitmap format handlers. + + @see wxBitmapHandler + */ + static wxList GetHandlers(); + + /** + Gets the height of the bitmap in pixels. + */ + virtual int GetHeight() const; + + /** + Gets the associated mask (if any) which may have been loaded from a file + or set for the bitmap. + + @see SetMask(), wxMask + */ + virtual wxMask* GetMask() const; + + /** + Gets the associated palette (if any) which may have been loaded from a file + or set for the bitmap. + + @see wxPalette + */ + virtual wxPalette* GetPalette() const; + + /** + Returns a sub bitmap of the current one as long as the rect belongs entirely to + the bitmap. This function preserves bit depth and mask information. + */ + virtual wxBitmap GetSubBitmap(const wxRect& rect) const; + + /** + Gets the width of the bitmap in pixels. + + @see GetHeight() + */ + virtual int GetWidth() const; + + /** + Adds the standard bitmap format handlers, which, depending on wxWidgets + configuration, can be handlers for Windows bitmap, Windows bitmap resource, + and XPM. + + This function is called by wxWidgets on startup. + + @see wxBitmapHandler + */ + static void InitStandardHandlers(); + + /** + Adds a handler at the start of the static list of format handlers. + + @param handler + A new bitmap format handler object. There is usually only one instance + of a given handler class in an application session. + + @see wxBitmapHandler + */ + static void InsertHandler(wxBitmapHandler* handler); + + /** + Returns @true if bitmap data is present. + */ + bool IsOk() const; + + /** + Loads a bitmap from a file or resource. + + @param name + Either a filename or a Windows resource name. + The meaning of name is determined by the @a type parameter. + @param type + One of the ::wxBitmapType values; see the note in the class + detailed description. + + @return @true if the operation succeeded, @false otherwise. + + @remarks A palette may be associated with the bitmap if one exists + (especially for colour Windows bitmaps), and if the + code supports it. You can check if one has been created + by using the GetPalette() member. + + @see SaveFile() + */ + virtual bool LoadFile(const wxString& name, wxBitmapType type); + + /** + Finds the handler with the given name, and removes it. + The handler is not deleted. + + @param name + The handler name. + + @return @true if the handler was found and removed, @false otherwise. + + @see wxBitmapHandler + */ + static bool RemoveHandler(const wxString& name); + + /** + Saves a bitmap in the named file. + + @param name + A filename. The meaning of name is determined by the type parameter. + @param type + One of the ::wxBitmapType values; see the note in the class + detailed description. + @param palette + An optional palette used for saving the bitmap. + + @return @true if the operation succeeded, @false otherwise. + + @remarks Depending on how wxWidgets has been configured, not all formats + may be available. + + @see LoadFile() + */ + virtual bool SaveFile(const wxString& name, wxBitmapType type, + const wxPalette* palette = NULL) const; + + /** + Sets the depth member (does not affect the bitmap data). + + @todo since these functions do not affect the bitmap data, + why they exist?? + + @param depth + Bitmap depth. + */ + virtual void SetDepth(int depth); + + /** + Sets the height member (does not affect the bitmap data). + + @param height + Bitmap height in pixels. + */ + virtual void SetHeight(int height); + + /** + Sets the mask for this bitmap. + + @remarks The bitmap object owns the mask once this has been called. + + @see GetMask(), wxMask + */ + virtual void SetMask(wxMask* mask); + + /** + Sets the associated palette. (Not implemented under GTK+). + + @param palette + The palette to set. + + @see wxPalette + */ + virtual void SetPalette(const wxPalette& palette); + + /** + Sets the width member (does not affect the bitmap data). + + @param width + Bitmap width in pixels. + */ + virtual void SetWidth(int width); +}; + +/** + An empty wxBitmap object. +*/ +wxBitmap wxNullBitmap; + + + + +/** + @class wxMask + @wxheader{bitmap.h} + + This class encapsulates a monochrome mask bitmap, where the masked area is + black and the unmasked area is white. + + When associated with a bitmap and drawn in a device context, the unmasked + area of the bitmap will be drawn, and the masked area will not be drawn. + + @library{wxcore} + @category{gdi} + + @see wxBitmap, wxDC::Blit, wxMemoryDC +*/ +class wxMask : public wxObject +{ +public: + + /** + Default constructor. + */ + wxMask(); + + /** + Constructs a mask from a bitmap and a palette index that indicates the + background. + Not yet implemented for GTK. + + @param bitmap + A valid bitmap. + @param index + Index into a palette, specifying the transparency colour. + */ + wxMask(const wxBitmap& bitmap, int index); + + /** + Constructs a mask from a monochrome bitmap. + + @beginWxPythonOnly + This is the default constructor for wxMask in wxPython. + @endWxPythonOnly + */ + wxMask(const wxBitmap& bitmap); + + /** + Constructs a mask from a bitmap and a colour that indicates the background. + + @beginWxPythonOnly + wxPython has an alternate wxMask constructor matching this form called wxMaskColour. + @endWxPythonOnly + */ + wxMask(const wxBitmap& bitmap, const wxColour& colour); + + /** + Destroys the wxMask object and the underlying bitmap data. + */ + virtual ~wxMask(); + + /** + Constructs a mask from a bitmap and a palette index that indicates the + background. + Not yet implemented for GTK. + + @param bitmap + A valid bitmap. + @param index + Index into a palette, specifying the transparency colour. + */ + bool Create(const wxBitmap& bitmap, int index); + + /** + Constructs a mask from a monochrome bitmap. + */ + bool Create(const wxBitmap& bitmap); + + /** + Constructs a mask from a bitmap and a colour that indicates the background. + */ + bool Create(const wxBitmap& bitmap, const wxColour& colour); +}; + diff --git a/interface/wx/bmpbuttn.h b/interface/wx/bmpbuttn.h new file mode 100644 index 0000000000..89dcca9677 --- /dev/null +++ b/interface/wx/bmpbuttn.h @@ -0,0 +1,239 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: bmpbuttn.h +// Purpose: interface of wxBitmapButton +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxBitmapButton + @wxheader{bmpbuttn.h} + + A bitmap button is a control that contains a bitmap. + It may be placed on a wxDialog or a wxPanel, or indeed almost any other window. + + @remarks + A bitmap button can be supplied with a single bitmap, and wxWidgets will draw + all button states using this bitmap. If the application needs more control, + additional bitmaps for the selected state, unpressed focused state, and greyed-out + state may be supplied. + + @section wxbitmapbutton_states Button states + This class supports bitmaps for several different states: + + @li @b normal: this is the bitmap shown in the default state, it must be always + valid while all the other bitmaps are optional and don't have to be set. + @li @b disabled: bitmap shown when the button is disabled. + @li @b selected: bitmap shown when the button is pushed (e.g. while the user + keeps the mouse button pressed on it) + @li @b focus: bitmap shown when the button has keyboard focus but is not pressed. + @li @b hover: bitmap shown when the mouse is over the button (but it is not pressed). + Notice that if hover bitmap is not specified but the current platform UI uses + hover images for the buttons (such as Windows XP or GTK+), then the focus bitmap + is used for hover state as well. This makes it possible to set focus bitmap only + to get reasonably good behaviour on all platforms. + + @beginStyleTable + @style{wxBU_AUTODRAW} + If this is specified, the button will be drawn automatically using + the label bitmap only, providing a 3D-look border. If this style is + not specified, the button will be drawn without borders and using + all provided bitmaps. Has effect only under MS Windows. + @style{wxBU_LEFT} + Left-justifies the bitmap label. Has effect only under MS Windows. + @style{wxBU_TOP} + Aligns the bitmap label to the top of the button. + Has effect only under MS Windows. + @style{wxBU_RIGHT} + Right-justifies the bitmap label. Has effect only under MS Windows. + @style{wxBU_BOTTOM} + Aligns the bitmap label to the bottom of the button. + Has effect only under MS Windows. + @endStyleTable + + Note that the wxBU_EXACTFIT style supported by wxButton is not used by this + class as bitmap buttons don't have any minimal standard size by default. + + @beginEventTable{wxCommandEvent} + @event{EVT_BUTTON(id, func)} + Process a wxEVT_COMMAND_BUTTON_CLICKED event, when the button is clicked. + @endEventTable + + @library{wxcore} + @category{ctrl} + + + @see wxButton +*/ +class wxBitmapButton : public wxButton +{ +public: + /** + Default ctor. + */ + wxBitmapButton(); + + /** + Constructor, creating and showing a button. + + @param parent + Parent window. Must not be @NULL. + @param id + Button identifier. The value wxID_ANY indicates a default value. + @param bitmap + Bitmap to be displayed. + @param pos + Button position. + @param size + Button size. If wxDefaultSize is specified then the button is sized + appropriately for the bitmap. + @param style + Window style. See wxBitmapButton. + @param validator + Window validator. + @param name + Window name. + + @remarks The bitmap parameter is normally the only bitmap you need to provide, + and wxWidgets will draw the button correctly in its different states. + If you want more control, call any of the functions SetBitmapSelected(), + SetBitmapFocus(), SetBitmapDisabled(). + + @see Create(), wxValidator + */ + wxBitmapButton(wxWindow* parent, wxWindowID id, + const wxBitmap& bitmap, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxBU_AUTODRAW, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = wxButtonNameStr); + + /** + Destructor, destroying the button. + */ + virtual ~wxBitmapButton(); + + /** + Button creation function for two-step creation. + For more details, see wxBitmapButton(). + */ + bool Create(wxWindow* parent, wxWindowID id, + const wxBitmap& bitmap, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxBU_AUTODRAW, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = wxButtonNameStr); + + //@{ + /** + Returns the bitmap for the disabled state, which may be invalid. + + @return A reference to the disabled state bitmap. + + @see SetBitmapDisabled() + */ + const wxBitmap& GetBitmapDisabled() const; + wxBitmap& GetBitmapDisabled(); + //@} + + //@{ + /** + Returns the bitmap for the focused state, which may be invalid. + + @return A reference to the focused state bitmap. + + @see SetBitmapFocus() + */ + const wxBitmap& GetBitmapFocus() const; + wxBitmap& GetBitmapFocus(); + //@} + + //@{ + /** + Returns the bitmap used when the mouse is over the button, which may be invalid. + + @see SetBitmapHover() + */ + const wxBitmap& GetBitmapHover(); + wxBitmap& GetBitmapHover(); + //@} + + //@{ + /** + Returns the label bitmap (the one passed to the constructor), always valid. + + @return A reference to the button's label bitmap. + + @see SetBitmapLabel() + */ + const wxBitmap& GetBitmapLabel(); + wxBitmap& GetBitmapLabel(); + //@} + + /** + Returns the bitmap for the selected state. + + @return A reference to the selected state bitmap. + + @see SetBitmapSelected() + */ + const wxBitmap& GetBitmapSelected() const; + + /** + Sets the bitmap for the disabled button appearance. + + @param bitmap + The bitmap to set. + + @see GetBitmapDisabled(), SetBitmapLabel(), + SetBitmapSelected(), SetBitmapFocus() + */ + virtual void SetBitmapDisabled(const wxBitmap& bitmap); + + /** + Sets the bitmap for the button appearance when it has the keyboard focus. + + @param bitmap + The bitmap to set. + + @see GetBitmapFocus(), SetBitmapLabel(), + SetBitmapSelected(), SetBitmapDisabled() + */ + virtual void SetBitmapFocus(const wxBitmap& bitmap); + + /** + Sets the bitmap to be shown when the mouse is over the button. + + @since 2.7.0 + + The hover bitmap is currently only supported in wxMSW. + + @see GetBitmapHover() + */ + virtual void SetBitmapHover(const wxBitmap& bitmap); + + /** + Sets the bitmap label for the button. + + @param bitmap + The bitmap label to set. + + @remarks This is the bitmap used for the unselected state, and for all + other states if no other bitmaps are provided. + + @see GetBitmapLabel() + */ + virtual void SetBitmapLabel(const wxBitmap& bitmap); + + /** + Sets the bitmap for the selected (depressed) button appearance. + + @param bitmap + The bitmap to set. + */ + virtual void SetBitmapSelected(const wxBitmap& bitmap); +}; + diff --git a/interface/wx/bmpcbox.h b/interface/wx/bmpcbox.h new file mode 100644 index 0000000000..3e7b6d87e1 --- /dev/null +++ b/interface/wx/bmpcbox.h @@ -0,0 +1,203 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: bmpcbox.h +// Purpose: interface of wxBitmapComboBox +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxBitmapComboBox + @wxheader{bmpcbox.h} + + A combobox that displays bitmap in front of the list items. + It currently only allows using bitmaps of one size, and resizes itself + so that a bitmap can be shown next to the text field. + + @remarks + While wxBitmapComboBox contains the wxComboBox API, but it might not actually + be derived from that class. In fact, if the platform does not have a native + implementation, wxBitmapComboBox will inherit from wxOwnerDrawnComboBox. + You can determine if the implementation is generic by checking whether + @c wxGENERIC_BITMAPCOMBOBOX is defined. Currently wxBitmapComboBox is + implemented natively for MSW and GTK+. + + @beginStyleTable + @style{wxCB_READONLY} + Creates a combobox without a text editor. On some platforms the + control may appear very different when this style is used. + @style{wxCB_SORT} + Sorts the entries in the list alphabetically. + @style{wxTE_PROCESS_ENTER} + The control will generate the event wxEVT_COMMAND_TEXT_ENTER + (otherwise pressing Enter key is either processed internally by the + control or used for navigation between dialog controls). + Windows only. + @endStyleTable + + @todo create wxCB_PROCESS_ENTER rather than reusing wxTE_PROCESS_ENTER! + + @beginEventTable{wxCommandEvent} + @event{EVT_COMBOBOX(id, func)} + Process a wxEVT_COMMAND_COMBOBOX_SELECTED event, when an item on + the list is selected. + @event{EVT_TEXT(id, func)} + Process a wxEVT_COMMAND_TEXT_UPDATED event, when the combobox text changes. + @event{EVT_TEXT_ENTER(id, func)} + Process a wxEVT_COMMAND_TEXT_ENTER event, when RETURN is pressed in + the combobox. + @endEventTable + + @library{wxadv} + @category{ctrl} + + + @see wxComboBox, wxChoice, wxOwnerDrawnComboBox, wxCommandEvent +*/ +class wxBitmapComboBox : public wxComboBox +{ +public: + /** + Default ctor. + */ + wxBitmapComboBox(); + + /** + Constructor, creating and showing a combobox. + + @param parent + Parent window. Must not be @NULL. + @param id + Window identifier. The value wxID_ANY indicates a default value. + @param value + Initial selection string. An empty string indicates no selection. + @param n + Number of strings with which to initialise the control. + @param choices + An array of strings with which to initialise the control. + + @see Create(), wxValidator + */ + wxBitmapComboBox(wxWindow* parent, wxWindowID id, + const wxString& value = "", + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + int n = 0, + const wxString choices[] = NULL, + long style = 0, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "comboBox"); + + /** + Constructor, creating and showing a combobox. + + @param parent + Parent window. Must not be @NULL. + @param id + Window identifier. The value wxID_ANY indicates a default value. + @param value + Initial selection string. An empty string indicates no selection. + @param choices + An wxArrayString with which to initialise the control. + + @see Create(), wxValidator + */ + wxBitmapComboBox(wxWindow* parent, wxWindowID id, + const wxString& value, + const wxPoint& pos, + const wxSize& size, + const wxArrayString& choices, + long style = 0, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "comboBox"); + + /** + Destructor, destroying the combobox. + */ + virtual ~wxBitmapComboBox(); + + /** + Adds the item to the end of the combo box. + */ + int Append(const wxString& item, + const wxBitmap& bitmap = wxNullBitmap); + + /** + Adds the item to the end of the combo box, associating the given + untyped, client data pointer @a clientData with the item. + */ + int Append(const wxString& item, const wxBitmap& bitmap, + void* clientData); + + /** + Adds the item to the end of the combo box, associating the given typed + client data pointer @a clientData with the item. + */ + int Append(const wxString& item, const wxBitmap& bitmap, + wxClientData* clientData); + + /** + Creates the combobox for two-step construction. + */ + bool Create(wxWindow* parent, wxWindowID id, + const wxString& value = "", + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + int n, const wxString choices[], + long style = 0, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "comboBox"); + + /** + Creates the combobox for two-step construction. + */ + bool Create(wxWindow* parent, wxWindowID id, + const wxString& value, + const wxPoint& pos, + const wxSize& size, + const wxArrayString& choices, + long style = 0, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "comboBox"); + + /** + Returns size of bitmaps used in the list. + */ + virtual wxSize GetBitmapSize() const; + + /** + Returns the bitmap of the item with the given index. + */ + virtual wxBitmap GetItemBitmap(unsigned int n) const; + + /** + Inserts the item into the list before @a pos. + Not valid for @c wxCB_SORT style, use Append() instead. + */ + int Insert(const wxString& item, const wxBitmap& bitmap, + unsigned int pos); + + /** + Inserts the item into the list before pos, associating the given + untyped, client data pointer with the item. + Not valid for @c wxCB_SORT style, use Append() instead. + */ + int Insert(const wxString& item, const wxBitmap& bitmap, + unsigned int pos, + void* clientData); + + /** + Inserts the item into the list before pos, associating the given typed + client data pointer with the item. + Not valid for @c wxCB_SORT style, use Append() instead. + */ + int Insert(const wxString& item, const wxBitmap& bitmap, + unsigned int pos, + wxClientData* clientData); + + /** + Sets the bitmap for the given item. + */ + virtual void SetItemBitmap(unsigned int n, const wxBitmap& bitmap); +}; + diff --git a/interface/wx/bookctrl.h b/interface/wx/bookctrl.h new file mode 100644 index 0000000000..c4d68d7bdf --- /dev/null +++ b/interface/wx/bookctrl.h @@ -0,0 +1,25 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: bookctrl.h +// Purpose: interface of wxBookCtrlBase +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxBookCtrlBase + @wxheader{bookctrl.h} + + @todo Document this class. + + @library{wxcore} + @category{miscwnd} + + @see @ref overview_bookctrl +*/ +class wxBookCtrlBase : public wxControl +{ +public: + +}; + diff --git a/interface/wx/brush.h b/interface/wx/brush.h new file mode 100644 index 0000000000..f98b98525f --- /dev/null +++ b/interface/wx/brush.h @@ -0,0 +1,308 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: brush.h +// Purpose: interface of wxBrush +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + The possible brush styles. +*/ +enum wxBrushStyle +{ + wxBRUSHSTYLE_INVALID = -1, + + wxBRUSHSTYLE_SOLID = wxSOLID, + /**< Solid. */ + + wxBRUSHSTYLE_TRANSPARENT = wxTRANSPARENT, + /**< Transparent (no fill). */ + + wxBRUSHSTYLE_STIPPLE_MASK_OPAQUE = wxSTIPPLE_MASK_OPAQUE, + /**< @todo WHAT's THIS?? */ + + wxBRUSHSTYLE_STIPPLE_MASK = wxSTIPPLE_MASK, + /**< @todo WHAT's THIS?? */ + + wxBRUSHSTYLE_STIPPLE = wxSTIPPLE, + /**< Uses a bitmap as a stipple. */ + + wxBRUSHSTYLE_BDIAGONAL_HATCH = wxBDIAGONAL_HATCH, + /**< Backward diagonal hatch. */ + + wxBRUSHSTYLE_CROSSDIAG_HATCH = wxCROSSDIAG_HATCH, + /**< Cross-diagonal hatch. */ + + wxBRUSHSTYLE_FDIAGONAL_HATCH = wxFDIAGONAL_HATCH, + /**< Forward diagonal hatch. */ + + wxBRUSHSTYLE_CROSS_HATCH = wxCROSS_HATCH, + /**< Cross hatch. */ + + wxBRUSHSTYLE_HORIZONTAL_HATCH = wxHORIZONTAL_HATCH, + /**< Horizontal hatch. */ + + wxBRUSHSTYLE_VERTICAL_HATCH = wxVERTICAL_HATCH, + /**< Vertical hatch. */ + + wxBRUSHSTYLE_FIRST_HATCH = wxFIRST_HATCH, + wxBRUSHSTYLE_LAST_HATCH = wxLAST_HATCH, +}; + + + +/** + @class wxBrush + @wxheader{brush.h} + + A brush is a drawing tool for filling in areas. It is used for painting + the background of rectangles, ellipses, etc. It has a colour and a style. + + On a monochrome display, wxWidgets shows all brushes as white unless the + colour is really 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 or when required. + + An application may wish to create brushes with different characteristics + dynamically, and there is the consequent danger that a large number of + duplicate brushes will be created. Therefore an application may wish to + get a pointer to a brush by using the global list of brushes ::wxTheBrushList, + and calling the member function wxBrushList::FindOrCreateBrush(). + + This class uses 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 + counting, are not affected. + + @library{wxcore} + @category{gdi} + + @stdobjects + ::wxNullBrush, ::wxBLUE_BRUSH, ::wxGREEN_BRUSH, ::wxWHITE_BRUSH, + ::wxBLACK_BRUSH, ::wxGREY_BRUSH, ::wxMEDIUM_GREY_BRUSH, ::wxLIGHT_GREY_BRUSH, + ::wxTRANSPARENT_BRUSH, ::wxCYAN_BRUSH, ::wxRED_BRUSH + + @see wxBrushList, wxDC, wxDC::SetBrush +*/ +class wxBrush : public wxGDIObject +{ +public: + /** + Default constructor. + The brush will be uninitialised, and wxBrush:IsOk() will return @false. + */ + wxBrush(); + + /** + Constructs a brush from a colour object and @a style. + + @param colour + Colour object. + @param style + One of the ::wxBrushStyle enumeration values. + */ + wxBrush(const wxColour& colour, wxBrushStyle style = wxBRUSHSTYLE_SOLID); + + /** + Constructs a stippled brush using a bitmap. + The brush style will be set to wxBRUSHSTYLE_STIPPLE. + */ + wxBrush(const wxBitmap& stippleBitmap); + + /** + Copy constructor, uses @ref overview_refcount "reference counting". + */ + wxBrush(const wxBrush& brush); + + /** + Destructor. + + See @ref overview_refcount_destruct for more info. + + @remarks Although all remaining brushes are deleted when the application + exits, the application should try to clean up all brushes itself. + This is because wxWidgets cannot know if a pointer to the brush + object is stored in an application data structure, and there is + a risk of double deletion. + */ + virtual ~wxBrush(); + + /** + Returns a reference to the brush colour. + + @see SetColour() + */ + virtual wxColour GetColour() const; + + /** + Gets a pointer to the stipple bitmap. If the brush does not have a wxBRUSHSTYLE_STIPPLE + style, this bitmap may be non-@NULL but uninitialised (i.e. wxBitmap:IsOk() returns @false). + + @see SetStipple() + */ + virtual wxBitmap* GetStipple() const; + + /** + Returns the brush style, one of the ::wxBrushStyle values. + + @see SetStyle(), SetColour(), SetStipple() + */ + virtual wxBrushStyle GetStyle() const; + + /** + Returns @true if the style of the brush is any of hatched fills. + + @see GetStyle() + */ + virtual bool IsHatch() const; + + /** + Returns @true if the brush is initialised. It will return @false if the default + constructor has been used (for example, the brush is a member of a class, or + @NULL has been assigned to it). + */ + bool IsOk() const; + + //@{ + /** + Sets the brush colour using red, green and blue values. + + @see GetColour() + */ + virtual void SetColour(wxColour& colour); + virtual void SetColour(unsigned char red, unsigned char green, unsigned char blue); + //@} + + /** + Sets the stipple bitmap. + + @param bitmap + The bitmap to use for stippling. + + @remarks The style will be set to wxBRUSHSTYLE_STIPPLE, unless the bitmap + has a mask associated to it, in which case the style will be set + to wxBRUSHSTYLE_STIPPLE_MASK_OPAQUE. + + @see wxBitmap + */ + virtual void SetStipple(const wxBitmap& bitmap); + + /** + Sets the brush style. + + @param style + One of the ::wxBrushStyle values. + + @see GetStyle() + */ + virtual void SetStyle(wxBrushStyle style); + + /** + Inequality operator. + See @ref overview_refcount_equality for more info. + */ + bool operator !=(const wxBrush& brush) const; + + /** + Equality operator. + See @ref overview_refcount_equality for more info. + */ + bool operator ==(const wxBrush& brush) const; +}; + +/** + An empty brush. +*/ +wxBrush wxNullBrush; + +/** + Blue brush. +*/ +wxBrush* wxBLUE_BRUSH; + +/** + Green brush. +*/ +wxBrush* wxGREEN_BRUSH; + +/** + White brush. +*/ +wxBrush* wxWHITE_BRUSH; + +/** + Black brush. +*/ +wxBrush* wxBLACK_BRUSH; + +/** + Grey brush. +*/ +wxBrush* wxGREY_BRUSH; + +/** + Medium grey brush. +*/ +wxBrush* wxMEDIUM_GREY_BRUSH; + +/** + Light grey brush. +*/ +wxBrush* wxLIGHT_GREY_BRUSH; + +/** + Transparent brush. +*/ +wxBrush* wxTRANSPARENT_BRUSH; + +/** + Cyan brush. +*/ +wxBrush* wxCYAN_BRUSH; + +/** + Red brush. +*/ +wxBrush* wxRED_BRUSH; + + + +/** + @class wxBrushList + @wxheader{gdicmn.h} + + A brush list is a list containing all brushes which have been created. + + The application should not construct its own brush list: it should use the + object pointer ::wxTheBrushList. + + @library{wxcore} + @category{gdi} + + @see wxBrush +*/ +class wxBrushList : public wxList +{ +public: + /** + Finds a brush with the specified attributes and returns it, else creates a new + brush, adds it to the brush list, and returns it. + + @param colour + Colour object. + @param style + Brush style. See ::wxBrushStyle for a list of styles. + */ + wxBrush* FindOrCreateBrush(const wxColour& colour, + wxBrushStyle style = wxBRUSHSTYLE_SOLID); +}; + +/** + The global wxBrushList instance. +*/ +wxBrushList* wxTheBrushList; diff --git a/interface/wx/buffer.h b/interface/wx/buffer.h new file mode 100644 index 0000000000..6de1c83f15 --- /dev/null +++ b/interface/wx/buffer.h @@ -0,0 +1,117 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: buffer.h +// Purpose: interface of wxMemoryBuffer +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxMemoryBuffer + @wxheader{buffer.h} + + A @b wxMemoryBuffer is a useful data structure for storing arbitrary sized + blocks of memory. wxMemoryBuffer guarantees deletion of the memory block when + the object is destroyed. + + @library{wxbase} + @category{data} +*/ +class wxMemoryBuffer +{ +public: + /** + Copy constructor, refcounting is used for performance, but wxMemoryBuffer + is not a copy-on-write structure so changes made to one buffer effect all + copies made from it. + + @see @ref overview_refcount + */ + wxMemoryBuffer(const wxMemoryBuffer& src); + + /** + Create a new buffer. + + @param size + size of the new buffer. + */ + wxMemoryBuffer(size_t size); + + /** + Append a single byte to the buffer. + + @param data + New byte to append to the buffer. + */ + void AppendByte(char data); + + /** + Ensure that the buffer is big enough and return a pointer to the start + of the empty space in the buffer. This pointer can be used to directly + write data into the buffer, this new data will be appended to the + existing data. + + @param sizeNeeded + Amount of extra space required in the buffer for + the append operation + */ + void* GetAppendBuf(size_t sizeNeeded); + + /** + Returns the size of the buffer. + */ + size_t GetBufSize() const; + + /** + Return a pointer to the data in the buffer. + */ + void* GetData() const; + + /** + Returns the length of the valid data in the buffer. + */ + size_t GetDataLen() const; + + /** + Ensure the buffer is big enough and return a pointer to the + buffer which can be used to directly write into the buffer + up to @a sizeNeeded bytes. + */ + void* GetWriteBuf(size_t sizeNeeded); + + /** + Ensures the buffer has at least @a size bytes available. + */ + void SetBufSize(size_t size); + + /** + Sets the length of the data stored in the buffer. + Mainly useful for truncating existing data. + + @param size + New length of the valid data in the buffer. This is + distinct from the allocated size + */ + void SetDataLen(size_t size); + + /** + Update the length after completing a direct append, which + you must have used GetAppendBuf() to initialise. + + @param sizeUsed + This is the amount of new data that has been + appended. + */ + void UngetAppendBuf(size_t sizeUsed); + + /** + Update the buffer after completing a direct write, which + you must have used GetWriteBuf() to initialise. + + @param sizeUsed + The amount of data written in to buffer + by the direct write + */ + void UngetWriteBuf(size_t sizeUsed); +}; + diff --git a/interface/wx/busyinfo.h b/interface/wx/busyinfo.h new file mode 100644 index 0000000000..88c88810e3 --- /dev/null +++ b/interface/wx/busyinfo.h @@ -0,0 +1,72 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: busyinfo.h +// Purpose: interface of wxBusyInfo +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxBusyInfo + @wxheader{busyinfo.h} + + This class makes it easy to tell your user that the program is temporarily busy. + Just create a wxBusyInfo object on the stack, and within the current scope, + a message window will be shown. + + For example: + + @code + wxBusyInfo wait("Please wait, working..."); + + for (int i = 0; i < 100000; i++) + { + DoACalculation(); + } + @endcode + + It works by creating a window in the constructor, and deleting it + in the destructor. + + You may also want to call wxTheApp-Yield() to refresh the window + periodically (in case it had been obscured by other windows, for + example) like this: + + @code + wxWindowDisabler disableAll; + + wxBusyInfo wait("Please wait, working..."); + + for (int i = 0; i < 100000; i++) + { + DoACalculation(); + + if ( !(i % 1000) ) + wxTheApp-Yield(); + } + @endcode + + but take care to not cause undesirable reentrancies when doing it (see + wxApp::Yield for more details). The simplest way to do it is to use + wxWindowDisabler class as illustrated in the above example. + + @library{wxcore} + @category{cmndlg} +*/ +class wxBusyInfo +{ +public: + /** + Constructs a busy info window as child of @a parent and displays @e msg in it. + + @note If @a parent is not @NULL you must ensure that it is not + closed while the busy info is shown. + */ + wxBusyInfo(const wxString& msg, wxWindow* parent = NULL); + + /** + Hides and closes the window containing the information text. + */ + virtual ~wxBusyInfo(); +}; + diff --git a/interface/wx/button.h b/interface/wx/button.h new file mode 100644 index 0000000000..67e13cc77f --- /dev/null +++ b/interface/wx/button.h @@ -0,0 +1,146 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: button.h +// Purpose: interface of wxButton +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxButton + @wxheader{button.h} + + A button is a control that contains a text string, and is one of the most + common elements of a GUI. + + It may be placed on a @ref wxDialog "dialog box" or on a @ref wxPanel panel, + or indeed on almost any other window. + + @beginStyleTable + @style{wxBU_LEFT} + Left-justifies the label. Windows and GTK+ only. + @style{wxBU_TOP} + Aligns the label to the top of the button. Windows and GTK+ only. + @style{wxBU_RIGHT} + Right-justifies the bitmap label. Windows and GTK+ only. + @style{wxBU_BOTTOM} + Aligns the label to the bottom of the button. Windows and GTK+ only. + @style{wxBU_EXACTFIT} + Creates the button as small as possible instead of making it of the + standard size (which is the default behaviour ). + @style{wxBORDER_NONE} + Creates a flat button. Windows and GTK+ only. + @endStyleTable + + @beginEventTable{wxCommandEvent} + @event{EVT_BUTTON(id, func)} + Process a wxEVT_COMMAND_BUTTON_CLICKED event, when the button is clicked. + @endEventTable + + @library{wxcore} + @category{ctrl} + + + @see wxBitmapButton +*/ +class wxButton : public wxControl +{ +public: + /** + Default ctor. + */ + wxButton(); + + /** + Constructor, creating and showing a button. + + The preferred way to create standard buttons is to use default value of + @a label. If no label is supplied and @a id is one of standard IDs from + @ref page_stockitems "this list", a standard label will be used. + + In addition to that, the button will be decorated with stock icons under GTK+ 2. + + @param parent + Parent window. Must not be @NULL. + @param id + Button identifier. A value of wxID_ANY indicates a default value. + @param label + Text to be displayed on the button. + @param pos + Button position. + @param size + Button size. If the default size is specified then the button is sized + appropriately for the text. + @param style + Window style. See wxButton class description. + @param validator + Window validator. + @param name + Window name. + + @see Create(), wxValidator + */ + wxButton(wxWindow* parent, wxWindowID id, + const wxString& label = wxEmptyString, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = wxButtonNameStr); + + /** + Destructor, destroying the button. + */ + virtual ~wxButton(); + + /** + Button creation function for two-step creation. + For more details, see wxButton(). + */ + bool Create(wxWindow* parent, wxWindowID id, + const wxString& label = wxEmptyString, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = wxButtonNameStr); + + /** + Returns the default size for the buttons. It is advised to make all the dialog + buttons of the same size and this function allows to retrieve the (platform and + current font dependent size) which should be the best suited for this. + */ + static wxSize GetDefaultSize(); + + /** + Returns the string label for the button. + + @see SetLabel() + */ + wxString GetLabel() const; + + /** + This sets the button to be the default item in its top-level window + (e.g. the panel or the dialog box containing it). + + As normal, pressing return causes the default button to be depressed when + the return key is pressed. + + See also wxWindow::SetFocus() which sets the keyboard focus for windows + and text panel items, and wxTopLevelWindow::SetDefaultItem(). + + @remarks Under Windows, only dialog box buttons respond to this function. + + @return the old default item (possibly NULL) + */ + virtual wxWindow* SetDefault(); + + /** + Sets the string label for the button. + + @param label + The label to set. + */ + void SetLabel(const wxString& label); +}; + diff --git a/interface/wx/calctrl.h b/interface/wx/calctrl.h new file mode 100644 index 0000000000..397b4760ef --- /dev/null +++ b/interface/wx/calctrl.h @@ -0,0 +1,529 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: calctrl.h +// Purpose: interface of wxCalendarCtrl +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxCalendarEvent + @wxheader{calctrl.h} + + The wxCalendarEvent class is used together with wxCalendarCtrl. + + @library{wxadv} + @category{events} + + @see wxCalendarCtrl +*/ +class wxCalendarEvent : public wxDateEvent +{ +public: + /** + Returns the week day on which the user clicked in + @c EVT_CALENDAR_WEEKDAY_CLICKED handler. It doesn't make sense to call + this function in other handlers. + */ + wxDateTime::WeekDay GetWeekDay() const; + + /** + Sets the week day carried by the event, normally only used by the + library internally. + */ + void SetWeekDay(wxDateTime::WeekDay day); +}; + + + +/** + Possible kinds of borders which may be used to decorate a date using + wxCalendarDateAttr. +*/ +enum wxCalendarDateBorder +{ + wxCAL_BORDER_NONE, ///< No Border (Default) + wxCAL_BORDER_SQUARE, ///< Rectangular Border + wxCAL_BORDER_ROUND ///< Round Border +}; + +/** + @class wxCalendarDateAttr + @wxheader{calctrl.h} + + wxCalendarDateAttr is a custom attributes for a calendar date. The objects + of this class are used with wxCalendarCtrl. + + @library{wxadv} + @category{misc} + + @see wxCalendarCtrl +*/ +class wxCalendarDateAttr +{ +public: + /** + Default constructor. + */ + wxCalendarDateAttr(); + + /** + Constructor for specifying all wxCalendarDateAttr properties. + */ + wxCalendarDateAttr(const wxColour& colText, + const wxColour& colBack = wxNullColour, + const wxColour& colBorder = wxNullColour, + const wxFont& font = wxNullFont, + wxCalendarDateBorder border = wxCAL_BORDER_NONE); + + /** + Constructor using default properties except the given border. + */ + wxCalendarDateAttr(wxCalendarDateBorder border, + const wxColour& colBorder = wxNullColour); + + /** + Returns the background colour set for the calendar date. + */ + const wxColour GetBackgroundColour() const; + + /** + Returns the border set for the calendar date. + */ + wxCalendarDateBorder GetBorder() const; + + /** + Returns the border colour set for the calendar date. + */ + const wxColour GetBorderColour() const; + + /** + Returns the font set for the calendar date. + */ + const wxFont GetFont() const; + + /** + Returns the text colour set for the calendar date. + */ + const wxColour GetTextColour() const; + + /** + Returns @true if a non-default text background colour is set. + */ + bool HasBackgroundColour() const; + + /** + Returns @true if a non-default (i.e. any) border is set. + */ + bool HasBorder() const; + + /** + Returns @true if a non-default border colour is set. + */ + bool HasBorderColour() const; + + /** + Returns @true if a non-default font is set. + */ + bool HasFont() const; + + /** + Returns @true if a non-default text foreground colour is set. + */ + bool HasTextColour() const; + + /** + Returns @true if this calendar day is displayed as a holiday. + */ + bool IsHoliday() const; + + /** + Sets the text background colour to use. + */ + void SetBackgroundColour(const wxColour& colBack); + + /** + Sets the border to use. + */ + void SetBorder(wxCalendarDateBorder border); + + /** + Sets the border colour to use. + */ + void SetBorderColour(const wxColour& col); + + /** + Sets the font to use. + */ + void SetFont(const wxFont& font); + + /** + If @a holiday is @true, this calendar day will be displayed as a + holiday. + */ + void SetHoliday(bool holiday); + + /** + Sets the text (foreground) colour to use. + */ + void SetTextColour(const wxColour& colText); + + /** + Used (internally) by the generic wxCalendarCtrl::Mark(). + */ + static const wxCalendarDateAttr& GetMark(); + + /** + Set the attributes that will be used to Mark() days on the generic + wxCalendarCtrl. + */ + static void SetMark(wxCalendarDateAttr const& m); +}; + + + +/** + Possible return values from wxCalendarCtrl::HitTest(). +*/ +enum wxCalendarHitTestResult +{ + wxCAL_HITTEST_NOWHERE, ///< Hit outside of anything. + wxCAL_HITTEST_HEADER, ///< Hit on the header (weekdays). + wxCAL_HITTEST_DAY ///< Hit on a day in the calendar. +}; + +/** + @class wxCalendarCtrl + @wxheader{calctrl.h} + + The calendar control allows the user to pick a date. The user can move the + current selection using the keyboard and select the date (generating + @c EVT_CALENDAR event) by pressing @c @ or double clicking it. + + Generic calendar has advanced possibilities for the customization of its + display, described below. If you want to use these possibilities on every + platform, use wxGenericCalendarCtrl instead of wxCalendarCtrl. + + All global settings (such as colours and fonts used) can, of course, be + changed. But also, the display style for each day in the month can be set + independently using wxCalendarDateAttr class. + + An item without custom attributes is drawn with the default colours and + font and without border, but setting custom attributes with SetAttr() + allows to modify its appearance. Just create a custom attribute object and + set it for the day you want to be displayed specially (note that the + control will take ownership of the pointer, i.e. it will delete it itself). + A day may be marked as being a holiday, even if it is not recognized as + one by wxDateTime using the wxCalendarDateAttr::SetHoliday() method. + + As the attributes are specified for each day, they may change when the + month is changed, so you will often want to update them in + @c EVT_CALENDAR_PAGE_CHANGED event handler. + + @beginStyleTable + @style{wxCAL_SUNDAY_FIRST} + Show Sunday as the first day in the week (not in wxGTK) + @style{wxCAL_MONDAY_FIRST} + Show Monday as the first day in the week (not in wxGTK) + @style{wxCAL_SHOW_HOLIDAYS} + Highlight holidays in the calendar (only generic) + @style{wxCAL_NO_YEAR_CHANGE} + Disable the year changing (deprecated, only generic) + @style{wxCAL_NO_MONTH_CHANGE} + Disable the month (and, implicitly, the year) changing + @style{wxCAL_SHOW_SURROUNDING_WEEKS} + Show the neighbouring weeks in the previous and next months + (only generic, always on for the native controls) + @style{wxCAL_SEQUENTIAL_MONTH_SELECTION} + Use alternative, more compact, style for the month and year + selection controls. (only generic) + @style{wxCAL_SHOW_WEEK_NUMBERS} + Show week numbers on the left side of the calendar. (not in generic) + @endStyleTable + + @beginEventTable{wxCalendarEvent} + @event{EVT_CALENDAR(id, func)} + A day was double clicked in the calendar. + @event{EVT_CALENDAR_SEL_CHANGED(id, func)} + The selected date changed. + @event{EVT_CALENDAR_PAGE_CHANGED(id, func)} + The selected month (and/or year) changed. + @event{EVT_CALENDAR_WEEKDAY_CLICKED(id, func)} + User clicked on the week day header (only generic). + @endEventTable + + @note Changing the selected date will trigger an EVT_CALENDAR_DAY, MONTH or + YEAR event as well as an EVT_CALENDAR_SEL_CHANGED event. + + @library{wxadv} + @category{ctrl} + + + @nativeimpl{wxgtk,wxmsw} + + @see @ref page_samples_calendar, wxCalendarDateAttr, wxCalendarEvent, + wxDatePickerCtrl +*/ +class wxCalendarCtrl : public wxControl +{ +public: + /** + Default constructor. + */ + wxCalendarCtrl(); + + /** + Does the same as Create() method. + */ + wxCalendarCtrl(wxWindow* parent, wxWindowID id, + const wxDateTime& date = wxDefaultDateTime, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxCAL_SHOW_HOLIDAYS, + const wxString& name = wxCalendarNameStr); + + /** + Destroys the control. + */ + ~wxCalendarCtrl(); + + /** + Creates the control. See wxWindow::wxWindow() for the meaning of the + parameters and the control overview for the possible styles. + */ + bool Create(wxWindow* parent, wxWindowID id, + const wxDateTime& date = wxDefaultDateTime, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxCAL_SHOW_HOLIDAYS, + const wxString& name = wxCalendarNameStr); + + /** + This function should be used instead of changing @c wxCAL_SHOW_HOLIDAYS + style bit directly. It enables or disables the special highlighting of + the holidays. + */ + void EnableHolidayDisplay(bool display = true); + + /** + This function should be used instead of changing + @c wxCAL_NO_MONTH_CHANGE style bit. It allows or disallows the user to + change the month interactively. Note that if the month can not be + changed, the year can not be changed neither. + + @return @true if the value of this option really changed or @false if + it was already set to the requested value. + */ + bool EnableMonthChange(bool enable = true); + + /** + @deprecated + + This function should be used instead of changing + @c wxCAL_NO_YEAR_CHANGE style bit directly. It allows or disallows the + user to change the year interactively. Only in generic wxCalendarCtrl. + */ + void EnableYearChange(bool enable = true); + + /** + Returns the attribute for the given date (should be in the range + 1...31). The returned pointer may be @NULL. Only in generic + wxCalendarCtrl. + */ + wxCalendarDateAttr* GetAttr(size_t day) const; + + /** + Gets the currently selected date. + */ + const wxDateTime GetDate() const; + + /** + Gets the background colour of the header part of the calendar window. + + This method is currently only implemented in generic wxCalendarCtrl and + always returns @c wxNullColour in the native versions. + + @see SetHeaderColours() + */ + const wxColour GetHeaderColourBg() const; + + /** + Gets the foreground colour of the header part of the calendar window. + + This method is currently only implemented in generic wxCalendarCtrl and + always returns @c wxNullColour in the native versions. + + @see SetHeaderColours() + */ + const wxColour GetHeaderColourFg() const; + + /** + Gets the background highlight colour. Only in generic wxCalendarCtrl. + + This method is currently only implemented in generic wxCalendarCtrl and + always returns @c wxNullColour in the native versions. + + @see SetHighlightColours() + */ + const wxColour GetHighlightColourBg() const; + + /** + Gets the foreground highlight colour. Only in generic wxCalendarCtrl. + + This method is currently only implemented in generic wxCalendarCtrl and + always returns @c wxNullColour in the native versions. + + @see SetHighlightColours() + */ + const wxColour GetHighlightColourFg() const; + + /** + Return the background colour currently used for holiday highlighting. + + Only useful with generic wxCalendarCtrl as native versions currently + don't support holidays display at all and always return + @c wxNullColour. + + @see SetHolidayColours() + */ + const wxColour GetHolidayColourBg() const; + + /** + Return the foreground colour currently used for holiday highlighting. + + Only useful with generic wxCalendarCtrl as native versions currently + don't support holidays display at all and always return + @c wxNullColour. + + @see SetHolidayColours() + */ + const wxColour GetHolidayColourFg() const; + + /** + Returns one of wxCalendarHitTestResult constants and fills either + @a date or @a wd pointer with the corresponding value depending on the + hit test code. + + Not implemented in wxGTK currently. + */ + wxCalendarHitTestResult HitTest(const wxPoint& pos, + wxDateTime* date = NULL, + wxDateTime::WeekDay* wd = NULL); + + /** + Clears any attributes associated with the given day (in the range + 1...31). Only in generic wxCalendarCtrl. + */ + void ResetAttr(size_t day); + + /** + Associates the attribute with the specified date (in the range 1...31). + If the pointer is @NULL, the items attribute is cleared. Only in + generic wxCalendarCtrl. + */ + void SetAttr(size_t day, wxCalendarDateAttr* attr); + + /** + Sets the current date. + + The @a date parameter must be valid. + */ + void SetDate(const wxDateTime& date); + + /** + Set the colours used for painting the weekdays at the top of the + control. + + This method is currently only implemented in generic wxCalendarCtrl and + does nothing in the native versions. + */ + void SetHeaderColours(const wxColour& colFg, + const wxColour& colBg); + + /** + Set the colours to be used for highlighting the currently selected + date. + + This method is currently only implemented in generic wxCalendarCtrl and + does nothing in the native versions. + */ + void SetHighlightColours(const wxColour& colFg, + const wxColour& colBg); + + /** + Marks the specified day as being a holiday in the current month. + + This method is only implemented in the generic version of the control + and does nothing in the native ones. + */ + void SetHoliday(size_t day); + + /** + Sets the colours to be used for the holidays highlighting. + + This method is only implemented in the generic version of the control + and does nothing in the native ones. It should also only be called if + the window style includes @c wxCAL_SHOW_HOLIDAYS flag or + EnableHolidayDisplay() had been called. + + */ + void SetHolidayColours(const wxColour& colFg, + const wxColour& colBg); + + /** + Mark or unmark the day. This day of month will be marked in every + month. In generic wxCalendarCtrl, + */ + void Mark(size_t day, bool mark); + + /** + @name Date Range Functions + + The functions in this section are currently implemented in the generic + and MSW versions and do nothing in the native GTK implementation. + */ + //@{ + + /** + Restrict the dates shown by the control to the specified range. + + If either date is set, the corresponding limit will be enforced and + @true returned. If none are set, the existing restrictions are removed + and @false is returned. + + @see GetDateRange() + + @param lowerdate + The low limit for the dates shown by the control or + @c wxDefaultDateTime. + @param highlighting + The high limit for the dates shown by the control or + @c wxDefaultDateTime. + @return + @true if either limit is valid, @false otherwise + */ + virtual bool SetDateRange(const wxDateTime& lowerdate = wxDefaultDateTime, + const wxDateTime& upperdate = wxDefaultDateTime); + + /** + Returns the limits currently being used. + + @see SetDateRange() + + @param lowerdate + If non-@NULL, the value of the low limit for the dates shown by the + control is returned (which may be @c wxDefaultDateTime if no limit + is set). + @param upperdate + If non-@NULL, the value of the upper limit for the dates shown by + the control is returned (which may be @c wxDefaultDateTime if no + limit is set). + @return + @true if either limit is set, @false otherwise + */ + virtual bool GetDateRange(wxDateTime *lowerdate, + wxDateTime *upperdate) const; + + //@} +}; + diff --git a/interface/wx/caret.h b/interface/wx/caret.h new file mode 100644 index 0000000000..4182c41f60 --- /dev/null +++ b/interface/wx/caret.h @@ -0,0 +1,132 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: caret.h +// Purpose: interface of wxCaret +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxCaret + @wxheader{caret.h} + + A caret is a blinking cursor showing the position where the typed text will + appear. Text controls usually have their own caret but wxCaret provides a + way to use a caret in other windows. + + Currently, the caret appears as a rectangle of the given size. In the + future, it will be possible to specify a bitmap to be used for the caret + shape. + + A caret is always associated with a window and the current caret can be + retrieved using wxWindow::GetCaret(). The same caret can't be reused in two + different windows. + + @library{wxcore} + @category{misc} +*/ +class wxCaret +{ +public: + /** + Default constructor. + */ + wxCaret(); + + //@{ + /** + Creates a caret with the given size (in pixels) and associates it with + the @a window. + */ + wxCaret(wxWindow* window, int width, int height); + wxCaret(wxWindowBase* window, const wxSize& size); + //@} + + //@{ + /** + Creates a caret with the given size (in pixels) and associates it with + the @a window (same as the equivalent constructors). + */ + bool Create(wxWindowBase* window, int width, int height); + bool Create(wxWindowBase* window, const wxSize& size); + //@} + + /** + Returns the blink time which is measured in milliseconds and is the + time elapsed between 2 inversions of the caret (blink time of the caret + is the same for all carets, so this functions is static). + */ + static int GetBlinkTime(); + + //@{ + /** + Get the caret position (in pixels). + */ + void GetPosition(int* x, int* y) const; + const wxPoint GetPosition() const; + //@} + + //@{ + /** + Get the caret size. + */ + void GetSize(int* width, int* height) const; + const wxSize GetSize() const; + //@} + + /** + Get the window the caret is associated with. + */ + wxWindow* GetWindow() const; + + /** + Hides the caret, same as Show(@false). + */ + void Hide(); + + /** + Returns @true if the caret was created successfully. + */ + bool IsOk() const; + + /** + Returns @true if the caret is visible and @false if it is permanently + hidden (if it is is blinking and not shown currently but will be after + the next blink, this method still returns @true). + */ + bool IsVisible() const; + + //@{ + /** + Move the caret to given position (in logical coordinates). + */ + void Move(int x, int y); + void Move(const wxPoint& pt); + //@} + + /** + Sets the blink time for all the carets. + + @warning Under Windows, this function will change the blink time for + all carets permanently (until the next time it is called), + even for carets in other applications. + + @see GetBlinkTime() + */ + static void SetBlinkTime(int milliseconds); + + //@{ + /** + Changes the size of the caret. + */ + void SetSize(int width, int height); + void SetSize(const wxSize& size); + //@} + + /** + Shows or hides the caret. Notice that if the caret was hidden N times, + it must be shown N times as well to reappear on the screen. + */ + void Show(bool show = true); +}; + diff --git a/interface/wx/chartype.h b/interface/wx/chartype.h new file mode 100644 index 0000000000..af71092399 --- /dev/null +++ b/interface/wx/chartype.h @@ -0,0 +1,59 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: chartype.h +// Purpose: interface of global functions +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** @ingroup group_funcmacro_string */ +//@{ + +/** + This macro can be used with character and string literals (in other words, + @c 'x' or @c "foo") to automatically convert them to Unicode in Unicode + builds of wxWidgets. This macro is simply returns the value passed to it + without changes in ASCII build. In fact, its definition is: + +@code +#ifdef UNICODE +# define wxT(x) L ## x +#else // !Unicode +# define wxT(x) x +#endif +@endcode + + @see @ref overview_unicode + + @header{wx/chartype.h} +*/ +#define wxT(string) + +/** + wxS is macro which can be used with character and string literals to either + convert them to wide characters or strings in @c wchar_t-based Unicode + builds or keep them unchanged in UTF-8 builds. The use of this macro is + optional as the translation will always be done at run-time even if there + is a mismatch between the kind of the literal used and string or character + type used in the current build, but using it can be beneficial in + performance-sensitive code to do the conversion at compile-time instead. + + @see wxT() + + @header{wx/chartype.h} +*/ +#define wxS(string) + +/** + This macro is exactly the same as wxT() and is defined in wxWidgets simply + because it may be more intuitive for Windows programmers as the standard + Win32 headers also define it (as well as yet another name for the same + macro which is _TEXT()). + + Don't confuse this macro with _()! + + @header{wx/chartype.h} +*/ +#define _T(string) + +//@} diff --git a/interface/wx/checkbox.h b/interface/wx/checkbox.h new file mode 100644 index 0000000000..e0f584b3b6 --- /dev/null +++ b/interface/wx/checkbox.h @@ -0,0 +1,170 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: checkbox.h +// Purpose: interface of wxCheckBox +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + The possible states of a 3-state wxCheckBox (Compatible with the 2-state + wxCheckBox). +*/ +enum wxCheckBoxState +{ + wxCHK_UNCHECKED, + wxCHK_CHECKED, + wxCHK_UNDETERMINED ///< 3-state checkbox only +}; + +/** + @class wxCheckBox + @wxheader{checkbox.h} + + A checkbox is a labelled box which by default is either on (checkmark is + visible) or off (no checkmark). Optionally (when the wxCHK_3STATE style + flag is set) it can have a third state, called the mixed or undetermined + state. Often this is used as a "Does Not Apply" state. + + @beginStyleTable + @style{wxCHK_2STATE} + Create a 2-state checkbox. This is the default. + @style{wxCHK_3STATE} + Create a 3-state checkbox. Not implemented in wxMGL, wxOS2 and + wxGTK built against GTK+ 1.2. + @style{wxCHK_ALLOW_3RD_STATE_FOR_USER} + By default a user can't set a 3-state checkbox to the third state. + It can only be done from code. Using this flags allows the user to + set the checkbox to the third state by clicking. + @style{wxALIGN_RIGHT} + Makes the text appear on the left of the checkbox. + @endStyleTable + + @beginEventTable{wxCommandEvent} + @event{EVT_CHECKBOX(id, func)} + Process a wxEVT_COMMAND_CHECKBOX_CLICKED event, when the checkbox + is clicked. + @endEventTable + + @library{wxcore} + @category{ctrl} + + + @see wxRadioButton, wxCommandEvent +*/ +class wxCheckBox : public wxControl +{ +public: + /** + Default constructor. + + @see Create(), wxValidator + */ + wxCheckBox(); + + /** + Constructor, creating and showing a checkbox. + + @param parent + Parent window. Must not be @NULL. + @param id + Checkbox identifier. The value wxID_ANY indicates a default value. + @param label + Text to be displayed next to the checkbox. + @param pos + Checkbox position. If wxDefaultPosition is specified then a default + position is chosen. + @param size + Checkbox size. If wxDefaultSize is specified then a default size is + chosen. + @param style + Window style. See wxCheckBox. + @param validator + Window validator. + @param name + Window name. + + @see Create(), wxValidator + */ + wxCheckBox(wxWindow* parent, wxWindowID id, + const wxString& label, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0, + const wxValidator& val = wxDefaultValidator, + const wxString& name = "checkBox"); + + /** + Destructor, destroying the checkbox. + */ + ~wxCheckBox(); + + /** + Creates the checkbox for two-step construction. See wxCheckBox() + for details. + */ + bool Create(wxWindow* parent, wxWindowID id, + const wxString& label, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0, + const wxValidator& val = wxDefaultValidator, + const wxString& name = "checkBox"); + + /** + Gets the state of a 2-state checkbox. + + @return Returns @true if it is checked, @false otherwise. + */ + bool GetValue() const; + + /** + Gets the state of a 3-state checkbox. Asserts when the function is used + with a 2-state checkbox. + */ + wxCheckBoxState Get3StateValue() const; + + /** + Returns whether or not the checkbox is a 3-state checkbox. + + @return @true if this checkbox is a 3-state checkbox, @false if it's + a 2-state checkbox. + */ + bool Is3State() const; + + /** + Returns whether or not the user can set the checkbox to the third + state. + + @return @true if the user can set the third state of this checkbox, + @false if it can only be set programmatically or if it's a + 2-state checkbox. + */ + bool Is3rdStateAllowedForUser() const; + + /** + This is just a maybe more readable synonym for GetValue(): just as the + latter, it returns @true if the checkbox is checked and @false + otherwise. + */ + bool IsChecked() const; + + /** + Sets the checkbox to the given state. This does not cause a + wxEVT_COMMAND_CHECKBOX_CLICKED event to get emitted. + + @param state + If @true, the check is on, otherwise it is off. + */ + void SetValue(bool state); + + /** + Sets the checkbox to the given state. This does not cause a + wxEVT_COMMAND_CHECKBOX_CLICKED event to get emitted. + + Asserts when the checkbox is a 2-state checkbox and setting the state + to wxCHK_UNDETERMINED. + */ + void Set3StateValue(const wxCheckBoxState state); +}; + diff --git a/interface/wx/checklst.h b/interface/wx/checklst.h new file mode 100644 index 0000000000..c8a6ee6073 --- /dev/null +++ b/interface/wx/checklst.h @@ -0,0 +1,109 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: checklst.h +// Purpose: interface of wxCheckListBox +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxCheckListBox + @wxheader{checklst.h} + + A wxCheckListBox is like a wxListBox, but allows items to be checked or + unchecked. + + When using this class under Windows wxWidgets must be compiled with + wxUSE_OWNER_DRAWN set to 1. + + Only the new functions for this class are documented; see also wxListBox. + + Please note that wxCheckListBox uses client data in its implementation, + and therefore this is not available to the application. + + @beginEventTable{wxCommandEvent} + @event{EVT_CHECKLISTBOX(id, func)} + Process a wxEVT_COMMAND_CHECKLISTBOX_TOGGLED event, when an item in + the check list box is checked or unchecked. + @endEventTable + + @library{wxcore} + @category{ctrl} + + + @see wxListBox, wxChoice, wxComboBox, wxListCtrl, wxCommandEvent +*/ +class wxCheckListBox : public wxListBox +{ +public: + /** + Default constructor. + */ + wxCheckListBox(); + + //@{ + /** + Constructor, creating and showing a list box. + + @param parent + Parent window. Must not be @NULL. + @param id + Window identifier. The value wxID_ANY indicates a default value. + @param pos + Window position. + @param size + Window size. If wxDefaultSize is specified then the window is sized + appropriately. + @param n + Number of strings with which to initialise the control. + @param choices + An array of strings with which to initialise the control. + @param style + Window style. See wxCheckListBox. + @param validator + Window validator. + @param name + Window name. + */ + wxCheckListBox(wxWindow* parent, wxWindowID id, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + int n, + const wxString choices[] = NULL, + long style = 0, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "listBox"); + wxCheckListBox(wxWindow* parent, wxWindowID id, + const wxPoint& pos, + const wxSize& size, + const wxArrayString& choices, + long style = 0, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "listBox"); + //@} + + /** + Destructor, destroying the list box. + */ + ~wxCheckListBox(); + + /** + Checks the given item. Note that calling this method does not result in + a wxEVT_COMMAND_CHECKLISTBOX_TOGGLE event being emitted. + + @param item + Index of item to check. + @param check + @true if the item is to be checked, @false otherwise. + */ + void Check(int item, bool check = true); + + /** + Returns @true if the given item is checked, @false otherwise. + + @param item + Index of item whose check status is to be returned. + */ + bool IsChecked(unsigned int item) const; +}; + diff --git a/interface/wx/choicdlg.h b/interface/wx/choicdlg.h new file mode 100644 index 0000000000..734cecc83c --- /dev/null +++ b/interface/wx/choicdlg.h @@ -0,0 +1,353 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: choicdlg.h +// Purpose: interface of wx[Multi|Single]ChoiceDialog +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxMultiChoiceDialog + @wxheader{choicdlg.h} + + This class represents a dialog that shows a list of strings, and allows the + user to select one or more. + + @library{wxbase} + @category{cmndlg} + + @see @ref overview_cmndlg_multichoice, wxSingleChoiceDialog +*/ +class wxMultiChoiceDialog : public wxDialog +{ +public: + //@{ + /** + Constructor taking an array of wxString choices. + + @param parent + Parent window. + @param message + Message to show on the dialog. + @param caption + The dialog caption. + @param n + The number of choices. + @param choices + An array of strings, or a string list, containing the choices. + @param style + A dialog style (bitlist) containing flags chosen from standard + dialog style and the ones listed below. The default value is + equivalent to wxDEFAULT_DIALOG_STYLE | wxRESIZE_BORDER | wxOK | + wxCANCEL | wxCENTRE. + @param pos + Dialog position. Not Windows. + + @beginStyleTable + @style{wxOK} + Show an OK button. + @style{wxCANCEL} + Show a Cancel button. + @style{wxCENTRE} + Centre the message. Not Windows. + @endStyleTable + + @remarks Use ShowModal() to show the dialog. + + @beginWxPythonOnly + + For Python the two parameters @a n and @a choices are collapsed into a + multi parameter @a choices which is expected to be a Python list of + strings. + + @endWxPythonOnly + */ + wxMultiChoiceDialog(wxWindow* parent, const wxString& message, + const wxString& caption, + int n, const wxString* choices, + long style = wxCHOICEDLG_STYLE, + const wxPoint& pos = wxDefaultPosition); + wxMultiChoiceDialog(wxWindow* parent, + const wxString& message, + const wxString& caption, + const wxArrayString& choices, + long style = wxCHOICEDLG_STYLE, + const wxPoint& pos = wxDefaultPosition); + //@} + + /** + Returns array with indexes of selected items. + */ + wxArrayInt GetSelection() const; + + /** + Sets selected items from the array of selected items' indexes. + */ + void SetSelections(const wxArrayInt& selections) const; + + /** + Shows the dialog, returning either wxID_OK or wxID_CANCEL. + */ + int ShowModal(); +}; + + + +/** + @class wxSingleChoiceDialog + @wxheader{choicdlg.h} + + This class represents a dialog that shows a list of strings, and allows the + user to select one. Double-clicking on a list item is equivalent to + single-clicking and then pressing OK. + + @library{wxbase} + @category{cmndlg} + + @see @ref overview_cmndlg_singlechoice, wxMultiChoiceDialog +*/ +class wxSingleChoiceDialog : public wxDialog +{ +public: + //@{ + /** + Constructor, taking an array of wxString choices and optional client + data. + + @param parent + Parent window. + @param message + Message to show on the dialog. + @param caption + The dialog caption. + @param n + The number of choices. + @param choices + An array of strings, or a string list, containing the choices. + @param clientData + An array of client data to be associated with the items. See + GetSelectionClientData(). + @param style + A dialog style (bitlist) containing flags chosen from standard + dialog styles and the ones listed below. The default value is + equivalent to wxDEFAULT_DIALOG_STYLE | wxRESIZE_BORDER | wxOK | + wxCANCEL | wxCENTRE. + @param pos + Dialog position. Not Windows. + + @beginStyleTable + @style{wxOK} + Show an OK button. + @style{wxCANCEL} + Show a Cancel button. + @style{wxCENTRE} + Centre the message. Not Windows. + @endStyleTable + + @remarks Use ShowModal() to show the dialog. + + @beginWxPythonOnly + + For Python the two parameters @a n and @a choices are collapsed into a + multi parameter @a choices which is expected to be a Python list of + strings. + + @endWxPythonOnly + */ + wxSingleChoiceDialog(wxWindow* parent, const wxString& message, + const wxString& caption, + int n, const wxString* choices, + void** clientData = NULL, + long style = wxCHOICEDLG_STYLE, + const wxPoint& pos = wxDefaultPosition); + wxSingleChoiceDialog(wxWindow* parent, + const wxString& message, + const wxString& caption, + const wxArrayString& choices, + void** clientData = NULL, + long style = wxCHOICEDLG_STYLE, + const wxPoint& pos = wxDefaultPosition); + //@} + + /** + Returns the index of selected item. + */ + int GetSelection() const; + + /** + Returns the client data associated with the selection. + */ + char* GetSelectionClientData() const; + + /** + Returns the selected string. + */ + wxString GetStringSelection() const; + + /** + Sets the index of the initially selected item. + */ + void SetSelection(int selection) const; + + /** + Shows the dialog, returning either wxID_OK or wxID_CANCEL. + */ + int ShowModal(); +}; + + + +// ============================================================================ +// Global functions/macros +// ============================================================================ + +/** @ingroup group_funcmacro_dialog */ +//@{ + +/** + Same as wxGetSingleChoice() but returns the index representing the + selected string. If the user pressed cancel, -1 is returned. + + @header{wx/choicdlg.h} +*/ +int wxGetSingleChoiceIndex(const wxString& message, + const wxString& caption, + const wxArrayString& aChoices, + wxWindow* parent = NULL, + int x = -1, + int y = -1, + bool centre = true, + int width = 150, + int height = 200); +int wxGetSingleChoiceIndex(const wxString& message, + const wxString& caption, + int n, + const wxString& choices[], + wxWindow* parent = NULL, + int x = -1, + int y = -1, + bool centre = true, + int width = 150, + int height = 200); + +//@} + +/** @ingroup group_funcmacro_dialog */ +//@{ + +/** + Pops up a dialog box containing a message, OK/Cancel buttons and a + single-selection listbox. The user may choose an item and press OK to + return a string or Cancel to return the empty string. Use + wxGetSingleChoiceIndex() if empty string is a valid choice and if you want + to be able to detect pressing Cancel reliably. + + You may pass the list of strings to choose from either using @c choices + which is an array of @a n strings for the listbox or by using a single + @c aChoices parameter of type wxArrayString. + + If @c centre is @true, the message text (which may include new line + characters) is centred; if @false, the message is left-justified. + + @header{wx/choicdlg.h} +*/ +wxString wxGetSingleChoice(const wxString& message, + const wxString& caption, + const wxArrayString& aChoices, + wxWindow* parent = NULL, + int x = -1, + int y = -1, + bool centre = true, + int width = 150, + int height = 200); +wxString wxGetSingleChoice(const wxString& message, + const wxString& caption, + int n, + const wxString& choices[], + wxWindow* parent = NULL, + int x = -1, + int y = -1, + bool centre = true, + int width = 150, + int height = 200); + +//@} + +/** @ingroup group_funcmacro_dialog */ +//@{ + +/** + Same as wxGetSingleChoice but takes an array of client data pointers + corresponding to the strings, and returns one of these pointers or @NULL + if Cancel was pressed. The @c client_data array must have the same number + of elements as @c choices or @c aChoices! + + @header{wx/choicdlg.h} +*/ +wxString wxGetSingleChoiceData(const wxString& message, + const wxString& caption, + const wxArrayString& aChoices, + const wxString& client_data[], + wxWindow* parent = NULL, + int x = -1, + int y = -1, + bool centre = true, + int width = 150, + int height = 200); +wxString wxGetSingleChoiceData(const wxString& message, + const wxString& caption, + int n, + const wxString& choices[], + const wxString& client_data[], + wxWindow* parent = NULL, + int x = -1, + int y = -1, + bool centre = true, + int width = 150, + int height = 200); + +//@} + +/** @ingroup group_funcmacro_dialog */ +//@{ + +/** + Pops up a dialog box containing a message, OK/Cancel buttons and a + multiple-selection listbox. The user may choose an arbitrary (including 0) + number of items in the listbox whose indices will be returned in + @c selections array. The initial contents of this array will be used to + select the items when the dialog is shown. + + You may pass the list of strings to choose from either using @c choices + which is an array of @a n strings for the listbox or by using a single + @c aChoices parameter of type wxArrayString. + + If @c centre is @true, the message text (which may include new line + characters) is centred; if @false, the message is left-justified. + + @header{wx/choicdlg.h} +*/ +size_t wxGetMultipleChoices(wxArrayInt& selections, + const wxString& message, + const wxString& caption, + const wxArrayString& aChoices, + wxWindow* parent = NULL, + int x = -1, + int y = -1, + bool centre = true, + int width = 150, + int height = 200); +size_t wxGetMultipleChoices(wxArrayInt& selections, + const wxString& message, + const wxString& caption, + int n, + const wxString& choices[], + wxWindow* parent = NULL, + int x = -1, + int y = -1, + bool centre = true, + int width = 150, + int height = 200); + +//@} + diff --git a/interface/wx/choice.h b/interface/wx/choice.h new file mode 100644 index 0000000000..acb6033101 --- /dev/null +++ b/interface/wx/choice.h @@ -0,0 +1,150 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: choice.h +// Purpose: interface of wxChoice +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxChoice + @wxheader{choice.h} + + A choice item is used to select one of a list of strings. Unlike a + wxListBox, only the selection is visible until the user pulls down the + menu of choices. + + @beginStyleTable + @style{wxCB_SORT} + Sorts the entries alphabetically. + @endStyleTable + + @beginEventTable{wxCommandEvent} + @event{EVT_CHOICE(id, func)} + Process a wxEVT_COMMAND_CHOICE_SELECTED event, when an item on the + list is selected. + @endEventTable + + @library{wxcore} + @category{ctrl} + + + @see wxListBox, wxComboBox, wxCommandEvent +*/ +class wxChoice : public wxControlWithItems +{ +public: + /** + Default constructor. + + @see Create(), wxValidator + */ + wxChoice(); + + //@{ + /** + Constructor, creating and showing a choice. + + @param parent + Parent window. Must not be @NULL. + @param id + Window identifier. The value wxID_ANY indicates a default value. + @param pos + Window position. + @param size + Window size. If wxDefaultSize is specified then the choice is sized + appropriately. + @param n + Number of strings with which to initialise the choice control. + @param choices + An array of strings with which to initialise the choice control. + @param style + Window style. See wxChoice. + @param validator + Window validator. + @param name + Window name. + + @see Create(), wxValidator + + @beginWxPythonOnly + + The wxChoice constructor in wxPython reduces the @a n and @a choices + arguments to a single argument, which is a list of strings. + + @endWxPythonOnly + */ + wxChoice(wxWindow* parent, wxWindowID id, + const wxPoint& pos, + const wxSize& size, int n, + const wxString choices[], + long style = 0, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "choice"); + wxChoice(wxWindow* parent, wxWindowID id, + const wxPoint& pos, + const wxSize& size, + const wxArrayString& choices, + long style = 0, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "choice"); + //@} + + /** + Destructor, destroying the choice item. + */ + ~wxChoice(); + + //@{ + /** + Creates the choice for two-step construction. See wxChoice(). + */ + bool Create(wxWindow* parent, wxWindowID id, const wxPoint& pos, + const wxSize& size, int n, + const wxString choices[], + long style = 0, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "choice"); + bool Create(wxWindow* parent, wxWindowID id, + const wxPoint& pos, + const wxSize& size, + const wxArrayString& choices, + long style = 0, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "choice"); + //@} + + /** + Gets the number of columns in this choice item. + + @remarks This is implemented for GTK and Motif only and always + returns 1 for the other platforms. + */ + int GetColumns() const; + + /** + Unlike wxControlWithItems::GetSelection() which only returns the + accepted selection value, i.e. the selection in the control once the + user closes the dropdown list, this function returns the current + selection. That is, while the dropdown list is shown, it returns the + currently selected item in it. When it is not shown, its result is the + same as for the other function. + + @since 2.6.2. + In older versions, wxControlWithItems::GetSelection() itself + behaved like this. + */ + int GetCurrentSelection() const; + + /** + Sets the number of columns in this choice item. + + @param n + Number of columns. + + @remarks This is implemented for GTK and Motif only and doesn’t do + anything under other platforms. + */ + void SetColumns(int n = 1); +}; + diff --git a/interface/wx/choicebk.h b/interface/wx/choicebk.h new file mode 100644 index 0000000000..879e4e024d --- /dev/null +++ b/interface/wx/choicebk.h @@ -0,0 +1,78 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: choicebk.h +// Purpose: interface of wxChoicebook +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxChoicebook + @wxheader{choicebk.h} + + wxChoicebook is a class similar to wxNotebook, but uses a wxChoice control + to show the labels instead of the tabs. + + There is no documentation for this class yet but its usage is identical to + wxNotebook (except for the features clearly related to tabs only), so + please refer to that class documentation for now. You can also use the + @ref page_samples_notebook to see wxChoicebook in action. + + wxChoicebook allows the use of wxBookCtrlBase::GetControlSizer(), allowing + a program to add other controls next to the choice control. This is + particularly useful when screen space is restricted, as it often is when + wxChoicebook is being employed. + + @beginStyleTable + @style{wxCHB_DEFAULT} + Choose the default location for the labels depending on the current + platform (left everywhere except Mac where it is top). + @style{wxCHB_TOP} + Place labels above the page area. + @style{wxCHB_LEFT} + Place labels on the left side. + @style{wxCHB_RIGHT} + Place labels on the right side. + @style{wxCHB_BOTTOM} + Place labels below the page area. + @endStyleTable + + @beginEventTable{wxChoicebookEvent} + @event{EVT_CHOICEBOOK_PAGE_CHANGED(id, func)} + The page selection was changed. Processes a + wxEVT_COMMAND_LISTBOOK_PAGE_CHANGED event. + @event{EVT_CHOICEBOOK_PAGE_CHANGING(id, func)} + The page selection is about to be changed. Processes a + wxEVT_COMMAND_CHOICEBOOK_PAGE_CHANGING event. This event can be + vetoed (using wxNotifyEvent::Veto()). + @endEventTable + + @library{wxcore} + @category{miscwnd} + + @see @ref overview_bookctrl, wxNotebook, @ref page_samples_notebook + + @todo Write up wxBookCtrlBase documentation, where most of this class' + functionality comes from. +*/ +class wxChoicebook : public wxBookCtrlBase +{ +public: + //@{ + /** + Constructs a choicebook control. + */ + wxChoicebook(); + wxChoicebook(wxWindow* parent, wxWindowID id, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0, + const wxString& name = wxEmptyStr); + //@} + + /** + Returns the wxChoice associated with the control. + */ + wxChoice * GetChoiceCtrl() const; +}; + diff --git a/interface/wx/clipbrd.h b/interface/wx/clipbrd.h new file mode 100644 index 0000000000..307793295c --- /dev/null +++ b/interface/wx/clipbrd.h @@ -0,0 +1,179 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: clipbrd.h +// Purpose: interface of wxClipboard +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + The backwards compatible access macro that returns the global clipboard + object pointer. +*/ +#define wxTheClipboard + +/** + @class wxClipboard + @wxheader{clipbrd.h} + + A class for manipulating the clipboard. + + To use the clipboard, you call member functions of the global + ::wxTheClipboard object. + + See the @ref overview_dataobject for further information. + + Call wxClipboard::Open() to get ownership of the clipboard. If this + operation returns @true, you now own the clipboard. Call + wxClipboard::SetData() to put data on the clipboard, or + wxClipboard::GetData() to retrieve data from the clipboard. Call + wxClipboard::Close() to close the clipboard and relinquish ownership. You + should keep the clipboard open only momentarily. + + For example: + + @code + // Write some text to the clipboard + if (wxTheClipboard->Open()) + { + // This data objects are held by the clipboard, + // so do not delete them in the app. + wxTheClipboard->SetData( new wxTextDataObject("Some text") ); + wxTheClipboard->Close(); + } + + // Read some text + if (wxTheClipboard->Open()) + { + if (wxTheClipboard->IsSupported( wxDF_TEXT )) + { + wxTextDataObject data; + wxTheClipboard->GetData( data ); + wxMessageBox( data.GetText() ); + } + wxTheClipboard->Close(); + } + @endcode + + @library{wxcore} + @category{dnd} + + @see @ref overview_dnd, @ref overview_dataobject, wxDataObject +*/ +class wxClipboard : public wxObject +{ +public: + /** + Default constructor. + */ + wxClipboard(); + + /** + Destructor. + */ + ~wxClipboard(); + + /** + Call this function to add the data object to the clipboard. You may + call this function repeatedly after having cleared the clipboard using + Clear(). + + After this function has been called, the clipboard owns the data, so do + not delete the data explicitly. + + @see SetData() + */ + bool AddData(wxDataObject* data); + + /** + Clears the global clipboard object and the system's clipboard if + possible. + */ + void Clear(); + + /** + Call this function to close the clipboard, having opened it with + Open(). + */ + void Close(); + + /** + Flushes the clipboard: this means that the data which is currently on + clipboard will stay available even after the application exits + (possibly eating memory), otherwise the clipboard will be emptied on + exit. + + @return @false if the operation is unsuccessful for any reason. + */ + bool Flush(); + + /** + Call this function to fill @a data with data on the clipboard, if + available in the required format. Returns @true on success. + */ + bool GetData(wxDataObject& data); + + /** + Returns @true if the clipboard has been opened. + */ + bool IsOpened() const; + + /** + Returns @true if there is data which matches the data format of the + given data object currently @b available on the clipboard. + + @todo The name of this function is misleading. This should be renamed + to something that more accurately indicates what it does. + */ + bool IsSupported(const wxDataFormat& format); + + /** + Returns @true if we are using the primary selection, @false if + clipboard one. + + @see UsePrimarySelection() + */ + bool IsUsingPrimarySelection() const; + + /** + Call this function to open the clipboard before calling SetData() and + GetData(). + + Call Close() when you have finished with the clipboard. You should keep + the clipboard open for only a very short time. + + @return @true on success. This should be tested (as in the sample + shown above). + */ + bool Open(); + + /** + Call this function to set the data object to the clipboard. This + function will clear all previous contents in the clipboard, so calling + it several times does not make any sense. + + After this function has been called, the clipboard owns the data, so do + not delete the data explicitly. + + @see AddData() + */ + bool SetData(wxDataObject* data); + + /** + On platforms supporting it (all X11-based ports), wxClipboard uses the + CLIPBOARD X11 selection by default. When this function is called with + @true, all subsequent clipboard operations will use PRIMARY selection + until this function is called again with @false. + + On the other platforms, there is no PRIMARY selection and so all + clipboard operations will fail. This allows to implement the standard + X11 handling of the clipboard which consists in copying data to the + CLIPBOARD selection only when the user explicitly requests it (i.e. by + selecting the "Copy" menu command) but putting the currently selected + text into the PRIMARY selection automatically, without overwriting the + normal clipboard contents with the currently selected text on the other + platforms. + */ + void UsePrimarySelection(bool primary = true); +}; + diff --git a/interface/wx/clntdata.h b/interface/wx/clntdata.h new file mode 100644 index 0000000000..62d7a86429 --- /dev/null +++ b/interface/wx/clntdata.h @@ -0,0 +1,141 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: clntdata.h +// Purpose: interface of wxClientData[Container] and wxStringClientData +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxClientDataContainer + @wxheader{clntdata.h} + + This class is a mixin that provides storage and management of "client + data." This data can either be of type void - in which case the data + @e container does not take care of freeing the data again or it is of + type wxClientData or its derivatives. In that case the container will free + the memory itself later. Note that you @e must not assign both void data + and data derived from the wxClientData class to a container. + + @note This functionality is currently duplicated in wxEvtHandler in order + to avoid having more than one vtable in that class hierarchy. + + @library{wxbase} + @category{containers} + + @see wxEvtHandler, wxClientData +*/ +class wxClientDataContainer +{ +public: + /** + Default constructor. + */ + wxClientDataContainer(); + + /** + Destructor. + */ + ~wxClientDataContainer(); + + /** + Get the untyped client data. + */ + void* GetClientData() const; + + /** + Get a pointer to the client data object. + */ + wxClientData* GetClientObject() const; + + /** + Set the untyped client data. + */ + void SetClientData(void* data); + + /** + Set the client data object. Any previous object will be deleted. + */ + void SetClientObject(wxClientData* data); +}; + + + +/** + @class wxClientData + @wxheader{clntdata.h} + + All classes deriving from wxEvtHandler (such as all controls and wxApp) can + hold arbitrary data which is here referred to as "client data". This is + useful e.g. for scripting languages which need to handle shadow objects for + most of wxWidgets' classes and which store a handle to such a shadow class + as client data in that class. This data can either be of type void - in + which case the data @e container does not take care of freeing the data + again or it is of type wxClientData or its derivatives. In that case the + container (e.g. a control) will free the memory itself later. Note that you + @e must not assign both void data and data derived from the wxClientData + class to a container. + + Some controls can hold various items and these controls can additionally + hold client data for each item. This is the case for wxChoice, wxComboBox + and wxListBox. wxTreeCtrl has a specialized class wxTreeItemData for each + item in the tree. + + If you want to add client data to your own classes, you may use the mix-in + class wxClientDataContainer. + + @library{wxbase} + @category{containers} + + @see wxEvtHandler, wxTreeItemData, wxStringClientData, + wxClientDataContainer +*/ +class wxClientData +{ +public: + /** + Constructor. + */ + wxClientData(); + + /** + Virtual destructor. + */ + ~wxClientData(); +}; + + + +/** + @class wxStringClientData + @wxheader{clntdata.h} + + Predefined client data class for holding a string. + + @library{wxbase} + @category{containers} +*/ +class wxStringClientData : public wxClientData +{ +public: + /** + Default constructor. + */ + wxStringClientData(); + + /** + Create client data with string. + */ + wxStringClientData(const wxString& data); + + /** + Get string client data. + */ + const wxString GetData() const; + + /** + Set string client data. + */ + void SetData(const wxString& data); +}; + diff --git a/interface/wx/clrpicker.h b/interface/wx/clrpicker.h new file mode 100644 index 0000000000..062c134d13 --- /dev/null +++ b/interface/wx/clrpicker.h @@ -0,0 +1,143 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: clrpicker.h +// Purpose: interface of wxColourPickerCtrl +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxColourPickerCtrl + @wxheader{clrpicker.h} + + This control allows the user to select a colour. The generic implementation + is a button which brings up a wxColourDialog when clicked. Native + implementation may differ but this is usually a (small) widget which give + access to the colour-chooser dialog. It is only available if + @c wxUSE_COLOURPICKERCTRL is set to 1 (the default). + + @beginStyleTable + @style{wxCLRP_DEFAULT_STYLE} + The default style: 0. + @style{wxCLRP_USE_TEXTCTRL} + Creates a text control to the left of the picker button which is + completely managed by the wxColourPickerCtrl and which can be used + by the user to specify a colour (see SetColour). The text control + is automatically synchronized with button's value. Use functions + defined in wxPickerBase to modify the text control. + @style{wxCLRP_SHOW_LABEL} + Shows the colour in HTML form (AABBCC) as colour button label + (instead of no label at all). + @endStyleTable + + @beginEventTable{wxColourPickerEvent} + @event{EVT_COLOURPICKER_CHANGED(id, func)} + The user changed the colour selected in the control either using the + button or using text control (see @c wxCLRP_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} + + + @see wxColourDialog, wxColourPickerEvent +*/ +class wxColourPickerCtrl : public wxPickerBase +{ +public: + /** + Initializes the object and calls Create() with all the parameters. + */ + wxColourPickerCtrl(wxWindow* parent, wxWindowID id, + const wxColour& colour = wxBLACK, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxCLRP_DEFAULT_STYLE, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "colourpickerctrl"); + + /** + Creates a colour picker with the given arguments. + + @param parent + Parent window, must not be non-@NULL. + @param id + The identifier for the control. + @param colour + The initial colour shown in the control. + @param pos + Initial position. + @param size + Initial size. + @param style + The window style, see wxCRLP_* flags. + @param validator + Validator which can be used for additional date checks. + @param name + Control name. + + @return @true if the control was successfully created or @false if + creation failed. + */ + bool Create(wxWindow* parent, wxWindowID id, + const wxColour& colour = wxBLACK, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxCLRP_DEFAULT_STYLE, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "colourpickerctrl"); + + /** + Returns the currently selected colour. + */ + wxColour GetColour() const; + + //@{ + /** + Sets the currently selected colour. See wxColour::Set(). + */ + void SetColour(const wxColour& col); + void SetColour(const wxString& colname); + //@} +}; + + + +/** + @class wxColourPickerEvent + @wxheader{clrpicker.h} + + This event class is used for the events generated by wxColourPickerCtrl. + + @beginEventTable{wxColourPickerEvent} + @event{EVT_COLOURPICKER_CHANGED(id, func)} + Generated whenever the selected colour changes. + @endEventTable + + @library{wxcore} + @category{events} + + @see wxColourPickerCtrl +*/ +class wxColourPickerEvent : public wxCommandEvent +{ +public: + /** + The constructor is not normally used by the user code. + */ + wxColourPickerEvent(wxObject* generator, int id, + const wxColour& colour); + + /** + Retrieve the colour the user has just selected. + */ + wxColour GetColour() const; + + /** + Set the colour associated with the event. + */ + void SetColour(const wxColour& pos); +}; + diff --git a/interface/wx/cmdline.h b/interface/wx/cmdline.h new file mode 100644 index 0000000000..2196edb66a --- /dev/null +++ b/interface/wx/cmdline.h @@ -0,0 +1,450 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: cmdline.h +// Purpose: interface of wxCmdLineParser +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + wxCmdLineEntryDesc::flags field is a combination of these bit masks. + + Notice that by default (i.e. if flags are just 0), options are optional + (sic) and each call to wxCmdLineEntryDesc::AddParam() allows one more + parameter - this may be changed by giving non-default flags to it, i.e. use + wxCMD_LINE_OPTION_MANDATORY to require that the option is given and + wxCMD_LINE_PARAM_OPTIONAL to make a parameter optional. Also, + wxCMD_LINE_PARAM_MULTIPLE may be specified if the programs accepts a + variable number of parameters - but it only can be given for the last + parameter in the command line description. If you use this flag, you will + probably need to use wxCmdLineEntryDesc::GetParamCount() to retrieve the + number of parameters effectively specified after calling + wxCmdLineEntryDesc::Parse(). + + wxCMD_LINE_NEEDS_SEPARATOR can be specified to require a separator (either + a colon, an equal sign or white space) between the option name and its + value. By default, no separator is required. +*/ +enum +{ + wxCMD_LINE_OPTION_MANDATORY = 0x01, ///< This option must be given. + wxCMD_LINE_PARAM_OPTIONAL = 0x02, ///< The parameter may be omitted. + wxCMD_LINE_PARAM_MULTIPLE = 0x04, ///< The parameter may be repeated. + wxCMD_LINE_OPTION_HELP = 0x08, ///< This option is a help request. + wxCMD_LINE_NEEDS_SEPARATOR = 0x10 ///< Must have a separator before the value. +}; + +/** + The possible values of wxCmdLineEntryDesc::type which specifies the type of + the value accepted by an option. +*/ +enum wxCmdLineParamType +{ + wxCMD_LINE_VAL_STRING, + wxCMD_LINE_VAL_NUMBER, + wxCMD_LINE_VAL_DATE, + wxCMD_LINE_VAL_DOUBLE, + wxCMD_LINE_VAL_NONE +}; + +/** + The type of a command line entity used for wxCmdLineEntryDesc::kind. +*/ +enum wxCmdLineEntryType +{ + wxCMD_LINE_SWITCH, + wxCMD_LINE_OPTION, + wxCMD_LINE_PARAM, + wxCMD_LINE_USAGE_TEXT, + wxCMD_LINE_NONE ///< Use this to terminate the list. +}; + +/** + The structure wxCmdLineEntryDesc is used to describe the one command line + switch, option or parameter. An array of such structures should be passed + to wxCmdLineParser::SetDesc(). Also, the meanings of parameters of the + wxCmdLineParser::AddXXX() functions are the same as of the corresponding + fields in this structure. + + The field @c shortName is the usual, short, name of the switch or the + option. @c longName is the corresponding long name or empty if the option + has no long name. Both of these fields are unused for the parameters. Both + the short and long option names can contain only letters, digits and the + underscores. + + @c description is used by the wxCmdLineEntryDesc::Usage() method to + construct a help message explaining the syntax of the program. +*/ +struct wxCmdLineEntryDesc +{ + wxCmdLineEntryType kind; + const char *shortName; + const char *longName; + const char *description; + wxCmdLineParamType type; + int flags; +}; + +/** + @class wxCmdLineParser + @wxheader{cmdline.h} + + wxCmdLineParser is a class for parsing the command line. + + It has the following features: + + - distinguishes options, switches and parameters + - allows option grouping + - allows both short and long options + - automatically generates the usage message from the command line description + - checks types of the options values (number, date, ...). + + To use it you should follow these steps: + + -# @ref cmdlineparser_construction "Construct" an object of this class + giving it the command line to parse and optionally its description or + use the @c AddXXX() functions later. + -# Call Parse(). + -# Use Found() to retrieve the results. + + In the documentation below the following terminology is used: + + - @b switch: This is a boolean option which can be given or not, but which + doesn't have any value. We use the word switch to distinguish + such boolean options from more generic options like those + described below. For example, @c "-v" might be a switch + meaning "enable verbose mode". + - @b option: Option for us here is something which comes with a value 0 + unlike a switch. For example, @c -o: @c filename might be an + option for specifying the name of the output file. + - @b parameter: This is a required program argument. + - @b text: This is a text which can be shown in usage information. + + + @section cmdlineparser_construction Construction + + Before Parse() can be called, the command line parser object must have the + command line to parse and also the rules saying which switches, options and + parameters are valid - this is called command line description in what + follows. + + You have complete freedom of choice as to when specify the required + information, the only restriction is that it must be done before calling + Parse(). + + To specify the command line to parse you may use either one of constructors + accepting it (wxCmdLineParser(int, char**) or + wxCmdLineParser(const wxString&) usually) or, if you use the default + constructor, you can do it later by calling SetCmdLine(). + + The same holds for command line description: it can be specified either in + the constructor (with or without the command line itself) or constructed + later using either SetDesc() or combination of AddSwitch(), AddOption(), + AddParam() and AddUsageText() methods. + + Using constructors or SetDesc() uses a (usually const static) table + containing the command line description. If you want to decide which + options to accept during the run-time, using one of the AddXXX() functions + above might be preferable. + + + @section cmdlineparser_customization Customization + + wxCmdLineParser has several global options which may be changed by the + application. All of the functions described in this section should be + called before Parse(). + + First global option is the support for long (also known as GNU-style) + options. The long options are the ones which start with two dashes and look + like "--verbose", i.e. they generally are complete words and not some + abbreviations of them. As long options are used by more and more + applications, they are enabled by default, but may be disabled with + DisableLongOptions(). + + Another global option is the set of characters which may be used to start + an option (otherwise, the word on the command line is assumed to be a + parameter). Under Unix, @c "-" is always used, but Windows has at least two + common choices for this: @c "-" and @c "/". Some programs also use "+". The + default is to use what suits most the current platform, but may be changed + with SetSwitchChars() method. + + Finally, SetLogo() can be used to show some application-specific text + before the explanation given by Usage() function. + + + @section cmdlineparser_parsing Parsing the Command Line + + After the command line description was constructed and the desired options + were set, you can finally call Parse() method. It returns 0 if the command + line was correct and was parsed, -1 if the help option was specified (this + is a separate case as, normally, the program will terminate after this) or + a positive number if there was an error during the command line parsing. + + In the latter case, the appropriate error message and usage information are + logged by wxCmdLineParser itself using the standard wxWidgets logging + functions. + + + @section cmdlineparser_results Getting Results + + After calling Parse() (and if it returned 0), you may access the results of + parsing using one of overloaded Found() methods. + + For a simple switch, you will simply call Found to determine if the switch + was given or not, for an option or a parameter, you will call a version of + Found() which also returns the associated value in the provided variable. + All Found() functions return true if the switch or option were found in the + command line or false if they were not specified. + + + @library{wxbase} + @category{appmanagement} + + @see wxApp::argc, wxApp::argv, @ref page_samples_console "Console Sample" +*/ +class wxCmdLineParser +{ +public: + /** + Default constructor, you must use SetCmdLine() later. + */ + wxCmdLineParser(); + + //@{ + /** + Constructor which specifies the command line to parse. This is the + traditional (Unix) command line format. The parameters @a argc and + @a argv have the same meaning as the typical @c main() function. + + The second overloaded constructor is only available in Unicode build. + The first one is available in both ANSI and Unicode modes because under + some platforms the command line arguments are passed as ASCII strings + even to Unicode programs. + */ + wxCmdLineParser(int argc, char** argv); + wxCmdLineParser(int argc, wchar_t** argv); + //@} + + /** + Constructor which specify the command line to parse in Windows format. + The parameter cmdline has the same meaning as the corresponding + parameter of @c WinMain(). + */ + wxCmdLineParser(const wxString& cmdline); + + /** + Specifies the @ref SetDesc() "command line description" but not the + command line. You must use SetCmdLine() later. + */ + wxCmdLineParser(const wxCmdLineEntryDesc* desc); + + /** + Specifies both the command line (in Unix format) and the + @ref SetDesc() "command line description". + */ + wxCmdLineParser(const wxCmdLineEntryDesc* desc, int argc, char** argv); + + /** + Specifies both the command line (in Windows format) and the + @ref SetDesc() "command line description". + */ + wxCmdLineParser(const wxCmdLineEntryDesc* desc, + const wxString& cmdline); + + /** + Frees resources allocated by the object. + + @note This destructor is not virtual, don't use this class + polymorphically. + */ + ~wxCmdLineParser(); + + /** + Add an option @a name with an optional long name @a lng (no long name + if it is empty, which is default) taking a value of the given type + (string by default) to the command line description. + */ + void AddOption(const wxString& name, + const wxString& lng = wxEmptyString, + const wxString& desc = wxEmptyString, + wxCmdLineParamType type = wxCMD_LINE_VAL_STRING, + int flags = 0); + + /** + Add a parameter of the given @a type to the command line description. + */ + void AddParam(const wxString& desc = wxEmptyString, + wxCmdLineParamType type = wxCMD_LINE_VAL_STRING, + int flags = 0); + + /** + Add a switch @a name with an optional long name @a lng (no long name if + it is empty, which is default), description @a desc and flags @a flags + to the command line description. + */ + void AddSwitch(const wxString& name, + const wxString& lng = wxEmptyString, + const wxString& desc = wxEmptyString, + int flags = 0); + + /** + Add a string @a text to the command line description shown by Usage(). + + @since 2.9.0 + */ + void AddUsageText(const wxString& text); + + /** + Returns @true if long options are enabled, otherwise @false. + + @see EnableLongOptions() + */ + bool AreLongOptionsEnabled() const; + + /** + Breaks down the string containing the full command line in words. The + words are separated by whitespace. The quotes can be used in the input + string to quote the white space and the back slashes can be used to + quote the quotes. + */ + static wxArrayString ConvertStringToArgs(const wxChar cmdline); + + /** + Identical to EnableLongOptions(@false). + */ + void DisableLongOptions(); + + /** + Enable or disable support for the long options. + + As long options are not (yet) POSIX-compliant, this option allows to + disable them. + + @see @ref cmdlineparser_customization and AreLongOptionsEnabled() + */ + void EnableLongOptions(bool enable = true); + + /** + Returns @true if the given switch was found, @false otherwise. + */ + bool Found(const wxString& name) const; + + /** + Returns true if an option taking a string value was found and stores + the value in the provided pointer (which should not be @NULL). + */ + bool Found(const wxString& name, wxString* value) const; + + /** + Returns @true if an option taking an integer value was found and stores + the value in the provided pointer (which should not be @NULL). + */ + bool Found(const wxString& name, long* value) const; + + /** + Returns @true if an option taking a float value was found and stores + the value in the provided pointer (which should not be @NULL). + */ + bool Found(const wxString& name, double* value) const; + + /** + Returns @true if an option taking a date value was found and stores the + value in the provided pointer (which should not be @NULL). + */ + bool Found(const wxString& name, wxDateTime* value) const; + + /** + Returns the value of Nth parameter (as string only). + */ + wxString GetParam(size_t n = 0) const; + + /** + Returns the number of parameters found. This function makes sense + mostly if you had used @c wxCMD_LINE_PARAM_MULTIPLE flag. + */ + size_t GetParamCount() const; + + /** + Parse the command line, return 0 if ok, -1 if @c "-h" or @c "--help" + option was encountered and the help message was given or a positive + value if a syntax error occurred. + + @param giveUsage + If @true (default), the usage message is given if a syntax error + was encountered while parsing the command line or if help was + requested. If @false, only error messages about possible syntax + errors are given, use Usage to show the usage message from the + caller if needed. + */ + int Parse(bool giveUsage = true); + + //@{ + /** + Set the command line to parse after using one of the constructors which + don't do it. + */ + void SetCmdLine(int argc, char** argv); + void SetCmdLine(int argc, wchar_t** argv); + void SetCmdLine(const wxString& cmdline); + //@} + + /** + Constructs the command line description. + + Take the command line description from the wxCMD_LINE_NONE terminated + table. + + Example of usage: + + @code + static const wxCmdLineEntryDesc cmdLineDesc[] = + { + { wxCMD_LINE_SWITCH, "v", "verbose", "be verbose" }, + { wxCMD_LINE_SWITCH, "q", "quiet", "be quiet" }, + + { wxCMD_LINE_OPTION, "o", "output", "output file" }, + { wxCMD_LINE_OPTION, "i", "input", "input dir" }, + { wxCMD_LINE_OPTION, "s", "size", "output block size", wxCMD_LINE_VAL_NUMBER }, + { wxCMD_LINE_OPTION, "d", "date", "output file date", wxCMD_LINE_VAL_DATE }, + + { wxCMD_LINE_PARAM, NULL, NULL, "input file", wxCMD_LINE_VAL_STRING, wxCMD_LINE_PARAM_MULTIPLE }, + + { wxCMD_LINE_NONE } + }; + + wxCmdLineParser parser; + + parser.SetDesc(cmdLineDesc); + @endcode + */ + void SetDesc(const wxCmdLineEntryDesc* desc); + + /** + The @a logo is some extra text which will be shown by Usage() method. + */ + void SetLogo(const wxString& logo); + + /** + @a switchChars contains all characters with which an option or switch + may start. Default is @c "-" for Unix, @c "-/" for Windows. + */ + void SetSwitchChars(const wxString& switchChars); + + /** + Give the standard usage message describing all program options. It will + use the options and parameters descriptions specified earlier, so the + resulting message will not be helpful to the user unless the + descriptions were indeed specified. + + @see SetLogo() + */ + void Usage() const; + + /** + Return the string containing the program usage description. + + Call Usage() to directly show this string to the user. + */ + wxString GetUsageString() const; +}; + diff --git a/interface/wx/cmdproc.h b/interface/wx/cmdproc.h new file mode 100644 index 0000000000..a0bd1d0a2f --- /dev/null +++ b/interface/wx/cmdproc.h @@ -0,0 +1,242 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: cmdproc.h +// Purpose: interface of wxCommandProcessor and wxCommand +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxCommand + @wxheader{cmdproc.h} + + wxCommand is a base class for modelling an application command, which is an + action usually performed by selecting a menu item, pressing a toolbar + button or any other means provided by the application to change the data or + view. + + @library{wxcore} + @category{docview} + + @see @ref overview_docview_wxcommand +*/ +class wxCommand : public wxObject +{ +public: + /** + Constructor. wxCommand is an abstract class, so you will need to derive + a new class and call this constructor from your own constructor. + + @param canUndo + Tells the command processor whether this command is undo-able. You + can achieve the same functionality by overriding the CanUndo() + member function (if for example the criteria for undoability is + context-dependent). + @param name + Must be supplied for the command processor to display the command + name in the application's edit menu. + */ + wxCommand(bool canUndo = false, const wxString& name = NULL); + + /** + Destructor. + */ + ~wxCommand(); + + /** + Returns @true if the command can be undone, @false otherwise. + */ + bool CanUndo(); + + /** + Override this member function to execute the appropriate action when + called. + + @return @true to indicate that the action has taken place, @false + otherwise. Returning @false will indicate to the command + processor that the action is not undoable and should not be + added to the command history. + */ + bool Do(); + + /** + Returns the command name. + */ + wxString GetName(); + + /** + Override this member function to un-execute a previous Do. + + How you implement this command is totally application dependent, but + typical strategies include: + + - Perform an inverse operation on the last modified piece of data in + the document. When redone, a copy of data stored in command is pasted + back or some operation reapplied. This relies on the fact that you + know the ordering of Undos; the user can never Undo at an arbitrary + position in the command history. + - Restore the entire document state (perhaps using document + transactioning). Potentially very inefficient, but possibly easier to + code if the user interface and data are complex, and an "inverse + execute" operation is hard to write. The docview sample uses the + first method, to remove or restore segments in the drawing. + + @return @true to indicate that the action has taken place, @false + otherwise. Returning @false will indicate to the command + processor that the action is not redoable and no change should + be made to the command history. + */ + bool Undo(); +}; + + + +/** + @class wxCommandProcessor + @wxheader{cmdproc.h} + + wxCommandProcessor is a class that maintains a history of wxCommands, with + undo/redo functionality built-in. Derive a new class from this if you want + different behaviour. + + @library{wxcore} + @category{docview} + + @see @ref overview_docview_wxcommandproc, wxCommand +*/ +class wxCommandProcessor : public wxObject +{ +public: + /** + Constructor. + + @param maxCommands + May be set to a positive integer to limit the number of commands + stored to it, otherwise (and by default) the list of commands can + grow arbitrarily. + */ + wxCommandProcessor(int maxCommands = -1); + + /** + Destructor. + */ + ~wxCommandProcessor(); + + /** + Returns @true if the currently-active command can be undone, @false + otherwise. + */ + virtual bool CanUndo(); + + /** + Deletes all commands in the list and sets the current command pointer + to @NULL. + */ + virtual void ClearCommands(); + + /** + Returns the list of commands. + */ + wxList& GetCommands() const; + + /** + Returns the edit menu associated with the command processor. + */ + wxMenu* GetEditMenu() const; + + /** + Returns the maximum number of commands that the command processor + stores. + */ + int GetMaxCommands() const; + + /** + Returns the string that will be appended to the Redo menu item. + */ + const wxString& GetRedoAccelerator() const; + + /** + Returns the string that will be shown for the redo menu item. + */ + wxString GetRedoMenuLabel() const; + + /** + Returns the string that will be appended to the Undo menu item. + */ + const wxString& GetUndoAccelerator() const; + + /** + Returns the string that will be shown for the undo menu item. + */ + wxString GetUndoMenuLabel() const; + + /** + Initializes the command processor, setting the current command to the + last in the list (if any), and updating the edit menu (if one has been + specified). + */ + virtual void Initialize(); + + /** + Returns a boolean value that indicates if changes have been made since + the last save operation. This only works if MarkAsSaved() is called + whenever the project is saved. + */ + virtual bool IsDirty(); + + /** + You must call this method whenever the project is saved if you plan to + use IsDirty(). + */ + virtual void MarkAsSaved(); + + /** + Executes (redoes) the current command (the command that has just been + undone if any). + */ + virtual bool Redo(); + + /** + Tells the command processor to update the Undo and Redo items on this + menu as appropriate. Set this to @NULL if the menu is about to be + destroyed and command operations may still be performed, or the command + processor may try to access an invalid pointer. + */ + void SetEditMenu(wxMenu* menu); + + /** + Sets the menu labels according to the currently set menu and the + current command state. + */ + void SetMenuStrings(); + + /** + Sets the string that will be appended to the Redo menu item. + */ + void SetRedoAccelerator(const wxString& accel); + + /** + Sets the string that will be appended to the Undo menu item. + */ + void SetUndoAccelerator(const wxString& accel); + + /** + Submits a new command to the command processor. The command processor + calls wxCommand::Do() to execute the command; if it succeeds, the + command is stored in the history list, and the associated edit menu (if + any) updated appropriately. If it fails, the command is deleted + immediately. Once Submit() has been called, the passed command should + not be deleted directly by the application. + + @param storeIt + Indicates whether the successful command should be stored in the + history list. + */ + virtual bool Submit(wxCommand* command, bool storeIt = true); + + /** + Undoes the last command executed. + */ + virtual bool Undo(); +}; + diff --git a/interface/wx/cmndata.h b/interface/wx/cmndata.h new file mode 100644 index 0000000000..70c26781d1 --- /dev/null +++ b/interface/wx/cmndata.h @@ -0,0 +1,846 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: cmndata.h +// Purpose: interface of common wx*Data classes (font, colour, print) +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxFontData + @wxheader{cmndata.h} + + This class holds a variety of information related to font dialogs. + + @library{wxcore} + @category{cmndlg} + + @see @ref overview_cmndlg_font, wxFont, wxFontDialog +*/ +class wxFontData : public wxObject +{ +public: + /** + Constructor. Initializes @e fontColour to black, @e showHelp to @false, + @e allowSymbols to @true, @e enableEffects to @true, @e minSize to 0 + and @e maxSize to 0. + */ + wxFontData(); + + /** + Enables or disables "effects" under Windows or generic only. This + refers to the controls for manipulating colour, strikeout and underline + properties. + + The default value is @true. + */ + void EnableEffects(bool enable); + + /** + Under Windows, returns a flag determining whether symbol fonts can be + selected. Has no effect on other platforms. + + The default value is @true. + */ + bool GetAllowSymbols(); + + /** + Gets the font chosen by the user if the user pressed OK + (wxFontDialog::ShowModal() returned wxID_OK). + */ + wxFont GetChosenFont(); + + /** + Gets the colour associated with the font dialog. + + The default value is black. + */ + wxColour& GetColour(); + + /** + Determines whether "effects" are enabled under Windows. This refers to + the controls for manipulating colour, strikeout and underline + properties. + + The default value is @true. + */ + bool GetEnableEffects(); + + /** + Gets the font that will be initially used by the font dialog. This + should have previously been set by the application. + */ + wxFont GetInitialFont(); + + /** + Returns @true if the Help button will be shown (Windows only). + + The default value is @false. + */ + bool GetShowHelp(); + + /** + Under Windows, determines whether symbol fonts can be selected. Has no + effect on other platforms. + + The default value is @true. + */ + void SetAllowSymbols(bool allowSymbols); + + /** + Sets the font that will be returned to the user (for internal use + only). + */ + void SetChosenFont(const wxFont& font); + + /** + Sets the colour that will be used for the font foreground colour. + + The default colour is black. + */ + void SetColour(const wxColour& colour); + + /** + Sets the font that will be initially used by the font dialog. + */ + void SetInitialFont(const wxFont& font); + + /** + Sets the valid range for the font point size (Windows only). + + The default is 0, 0 (unrestricted range). + */ + void SetRange(int min, int max); + + /** + Determines whether the Help button will be displayed in the font dialog + (Windows only). + + The default value is @false. + */ + void SetShowHelp(bool showHelp); + + /** + Assignment operator for the font data. + */ + void operator =(const wxFontData& data); +}; + + + +/** + @class wxPageSetupDialogData + @wxheader{cmndata.h} + + This class holds a variety of information related to wxPageSetupDialog. + + It contains a wxPrintData member which is used to hold basic printer + configuration data (as opposed to the user-interface configuration settings + stored by wxPageSetupDialogData). + + @library{wxcore} + @category{printing} + + @see @ref overview_printing, wxPageSetupDialog +*/ +class wxPageSetupDialogData : public wxObject +{ +public: + /** + Default constructor. + */ + wxPageSetupDialogData(); + + /** + Copy constructor. + */ + wxPageSetupDialogData(wxPageSetupDialogData& data); + + /** + Construct an object from a print data object. + */ + wxPageSetupDialogData(wxPrintData& printData); + + /** + Destructor. + */ + ~wxPageSetupDialogData(); + + /** + Enables or disables the "Help" button (Windows only). + */ + void EnableHelp(bool flag); + + /** + Enables or disables the margin controls (Windows only). + */ + void EnableMargins(bool flag); + + /** + Enables or disables the orientation control (Windows only). + */ + void EnableOrientation(bool flag); + + /** + Enables or disables the paper size control (Windows only). + */ + void EnablePaper(bool flag); + + /** + Enables or disables the "Printer" button, which invokes a printer setup + dialog. + */ + void EnablePrinter(bool flag); + + /** + Returns @true if the dialog will simply return default printer + information (such as orientation) instead of showing a dialog (Windows + only). + */ + bool GetDefaultInfo() const; + + /** + Returns @true if the page setup dialog will take its minimum margin + values from the currently selected printer properties (Windows only). + */ + bool GetDefaultMinMargins() const; + + /** + Returns @true if the printer setup button is enabled. + */ + bool GetEnableHelp() const; + + /** + Returns @true if the margin controls are enabled (Windows only). + */ + bool GetEnableMargins() const; + + /** + Returns @true if the orientation control is enabled (Windows only). + */ + bool GetEnableOrientation() const; + + /** + Returns @true if the paper size control is enabled (Windows only). + */ + bool GetEnablePaper() const; + + /** + Returns @true if the printer setup button is enabled. + */ + bool GetEnablePrinter() const; + + /** + Returns the right (x) and bottom (y) margins in millimetres. + */ + wxPoint GetMarginBottomRight() const; + + /** + Returns the left (x) and top (y) margins in millimetres. + */ + wxPoint GetMarginTopLeft() const; + + /** + Returns the right (x) and bottom (y) minimum margins the user can enter + (Windows only). Units are in millimetres. + */ + wxPoint GetMinMarginBottomRight() const; + + /** + Returns the left (x) and top (y) minimum margins the user can enter + (Windows only). Units are in millimetres. + */ + wxPoint GetMinMarginTopLeft() const; + + /** + Returns the paper id (stored in the internal wxPrintData object). + + @see wxPrintData::SetPaperId() + */ + wxPaperSize GetPaperId() const; + + /** + Returns the paper size in millimetres. + */ + wxSize GetPaperSize() const; + + /** + Returns a reference to the print data associated with this object. + */ + wxPrintData GetPrintData(); + + /** + Returns @true if the print data associated with the dialog data is + valid. This can return @false on Windows if the current printer is not + set, for example. On all other platforms, it returns @true. + */ + bool IsOk() const; + + /** + Pass @true if the dialog will simply return default printer information + (such as orientation) instead of showing a dialog (Windows only). + */ + void SetDefaultInfo(bool flag); + + /** + Pass @true if the page setup dialog will take its minimum margin values + from the currently selected printer properties (Windows only). Units + are in millimetres. + */ + void SetDefaultMinMargins(bool flag); + + /** + Sets the right (x) and bottom (y) margins in millimetres. + */ + void SetMarginBottomRight(const wxPoint& pt); + + /** + Sets the left (x) and top (y) margins in millimetres. + */ + void SetMarginTopLeft(const wxPoint& pt); + + /** + Sets the right (x) and bottom (y) minimum margins the user can enter + (Windows only). Units are in millimetres. + */ + void SetMinMarginBottomRight(const wxPoint& pt); + + /** + Sets the left (x) and top (y) minimum margins the user can enter + (Windows only). Units are in millimetres. + */ + void SetMinMarginTopLeft(const wxPoint& pt); + + /** + Sets the paper size id. Calling this function overrides the explicit + paper dimensions passed in SetPaperSize(). + + @see wxPrintData::SetPaperId() + */ + void SetPaperId(wxPaperSize& id); + + /** + Sets the paper size in millimetres. If a corresponding paper id is + found, it will be set in the internal wxPrintData object, otherwise the + paper size overrides the paper id. + */ + void SetPaperSize(const wxSize& size); + + /** + Sets the print data associated with this object. + */ + void SetPrintData(const wxPrintData& printData); + + /** + Assigns print data to this object. + */ + void operator =(const wxPrintData& data); + + /** + Assigns page setup data to this object. + */ + void operator =(const wxPageSetupDialogData& data); +}; + + + +/** + @class wxColourData + @wxheader{cmndata.h} + + This class holds a variety of information related to colour dialogs. + + @library{wxcore} + @category{cmndlg} + + @see wxColour, wxColourDialog, @ref overview_cmndlg_colour +*/ +class wxColourData : public wxObject +{ +public: + /** + Constructor. Initializes the custom colours to @c wxNullColour, the + @e data colour setting to black, and the @e choose full setting to + @true. + */ + wxColourData(); + + /** + Destructor. + */ + ~wxColourData(); + + /** + Under Windows, determines whether the Windows colour dialog will + display the full dialog with custom colour selection controls. Under + PalmOS, determines whether colour dialog will display full rgb colour + picker or only available palette indexer. Has no meaning under other + platforms. + + The default value is @true. + */ + bool GetChooseFull() const; + + /** + Gets the current colour associated with the colour dialog. + + The default colour is black. + */ + wxColour& GetColour() const; + + /** + Returns custom colours associated with the colour dialog. + + @param i + An integer between 0 and 15, being any of the 15 custom colours + that the user has saved. The default custom colours are invalid + colours. + */ + wxColour& GetCustomColour(int i) const; + + /** + Under Windows, tells the Windows colour dialog to display the full + dialog with custom colour selection controls. Under other platforms, + has no effect. + + The default value is @true. + */ + void SetChooseFull(const bool flag); + + /** + Sets the default colour for the colour dialog. + + The default colour is black. + */ + void SetColour(const wxColour& colour); + + /** + Sets custom colours for the colour dialog. + + @param i + An integer between 0 and 15 for whatever custom colour you want to + set. The default custom colours are invalid colours. + */ + void SetCustomColour(int i, const wxColour& colour); + + /** + Assignment operator for the colour data. + */ + void operator =(const wxColourData& data); +}; + + + +/** + Enumeration of various printer bin sources. + + @see wxPrintData::SetBin() +*/ +enum wxPrintBin +{ + wxPRINTBIN_DEFAULT, + + wxPRINTBIN_ONLYONE, + wxPRINTBIN_LOWER, + wxPRINTBIN_MIDDLE, + wxPRINTBIN_MANUAL, + wxPRINTBIN_ENVELOPE, + wxPRINTBIN_ENVMANUAL, + wxPRINTBIN_AUTO, + wxPRINTBIN_TRACTOR, + wxPRINTBIN_SMALLFMT, + wxPRINTBIN_LARGEFMT, + wxPRINTBIN_LARGECAPACITY, + wxPRINTBIN_CASSETTE, + wxPRINTBIN_FORMSOURCE, + + wxPRINTBIN_USER, +}; + +/** + @class wxPrintData + @wxheader{cmndata.h} + + This class holds a variety of information related to printers and printer + device contexts. This class is used to create a wxPrinterDC and a + wxPostScriptDC. It is also used as a data member of wxPrintDialogData and + wxPageSetupDialogData, as part of the mechanism for transferring data + between the print dialogs and the application. + + @remarks + + The following functions are specific to PostScript printing and have not + yet been documented: + + @code + const wxString& GetPrinterCommand() const ; + const wxString& GetPrinterOptions() const ; + const wxString& GetPreviewCommand() const ; + const wxString& GetFilename() const ; + const wxString& GetFontMetricPath() const ; + double GetPrinterScaleX() const ; + double GetPrinterScaleY() const ; + long GetPrinterTranslateX() const ; + long GetPrinterTranslateY() const ; + // wxPRINT_MODE_PREVIEW, wxPRINT_MODE_FILE, wxPRINT_MODE_PRINTER + wxPrintMode GetPrintMode() const ; + + void SetPrinterCommand(const wxString& command) ; + void SetPrinterOptions(const wxString& options) ; + void SetPreviewCommand(const wxString& command) ; + void SetFilename(const wxString& filename) ; + void SetFontMetricPath(const wxString& path) ; + void SetPrinterScaleX(double x) ; + void SetPrinterScaleY(double y) ; + void SetPrinterScaling(double x, double y) ; + void SetPrinterTranslateX(long x) ; + void SetPrinterTranslateY(long y) ; + void SetPrinterTranslation(long x, long y) ; + void SetPrintMode(wxPrintMode printMode) ; + @endcode + + @library{wxcore} + @category{printing} + + @see @ref overview_printing, wxPrintDialog, wxPageSetupDialog, + wxPrintDialogData, wxPageSetupDialogData, @ref overview_cmndlg_print, + wxPrinterDC, wxPostScriptDC +*/ +class wxPrintData : public wxObject +{ +public: + /** + Default constructor. + */ + wxPrintData(); + + /** + Copy constructor. + */ + wxPrintData(const wxPrintData& data); + + /** + Destructor. + */ + ~wxPrintData(); + + /** + Returns the current bin (papersource). By default, the system is left + to select the bin (@c wxPRINTBIN_DEFAULT is returned). + + See SetBin() for the full list of bin values. + */ + wxPrintBin GetBin() const; + + /** + Returns @true if collation is on. + */ + bool GetCollate() const; + + /** + Returns @true if colour printing is on. + */ + bool GetColour() const; + + /** + Returns the duplex mode. One of wxDUPLEX_SIMPLEX, wxDUPLEX_HORIZONTAL, + wxDUPLEX_VERTICAL. + */ + wxDuplexMode GetDuplex() const; + + /** + Returns the number of copies requested by the user. + */ + int GetNoCopies() const; + + /** + Gets the orientation. This can be wxLANDSCAPE or wxPORTRAIT. + */ + int GetOrientation() const; + + /** + Returns the paper size id. + + @see SetPaperId() + */ + wxPaperSize GetPaperId() const; + + /** + Returns the printer name. If the printer name is the empty string, it + indicates that the default printer should be used. + */ + const wxString GetPrinterName() const; + + /** + Returns the current print quality. This can be a positive integer, + denoting the number of dots per inch, or one of the following + identifiers: + + - wxPRINT_QUALITY_HIGH + - wxPRINT_QUALITY_MEDIUM + - wxPRINT_QUALITY_LOW + - wxPRINT_QUALITY_DRAFT + + On input you should pass one of these identifiers, but on return you + may get back a positive integer indicating the current resolution + setting. + */ + wxPrintQuality GetQuality() const; + + /** + Returns @true if the print data is valid for using in print dialogs. + This can return @false on Windows if the current printer is not set, + for example. On all other platforms, it returns @true. + */ + bool IsOk() const; + + /** + Sets the current bin. + */ + void SetBin(wxPrintBin flag); + + /** + Sets collation to on or off. + */ + void SetCollate(bool flag); + + /** + Sets colour printing on or off. + */ + void SetColour(bool flag); + + /** + Returns the duplex mode. One of wxDUPLEX_SIMPLEX, wxDUPLEX_HORIZONTAL, + wxDUPLEX_VERTICAL. + */ + void SetDuplex(wxDuplexMode mode); + + /** + Sets the default number of copies to be printed out. + */ + void SetNoCopies(int n); + + /** + Sets the orientation. This can be wxLANDSCAPE or wxPORTRAIT. + */ + void SetOrientation(int orientation); + + /** + Sets the paper id. This indicates the type of paper to be used. For a + mapping between paper id, paper size and string name, see + wxPrintPaperDatabase in @c "paper.h" (not yet documented). + */ + void SetPaperId(wxPaperSize paperId); + + /** + Sets the printer name. This can be the empty string to indicate that + the default printer should be used. + */ + void SetPrinterName(const wxString& printerName); + + /** + Sets the desired print quality. This can be a positive integer, + denoting the number of dots per inch, or one of the following + identifiers: + + - wxPRINT_QUALITY_HIGH + - wxPRINT_QUALITY_MEDIUM + - wxPRINT_QUALITY_LOW + - wxPRINT_QUALITY_DRAFT + + On input you should pass one of these identifiers, but on return you + may get back a positive integer indicating the current resolution + setting. + */ + void SetQuality(wxPrintQuality quality); + + /** + Assigns print data to this object. + */ + void operator =(const wxPrintData& data); +}; + + + +/** + @class wxPrintDialogData + @wxheader{cmndata.h} + + This class holds information related to the visual characteristics of + wxPrintDialog. It contains a wxPrintData object with underlying printing + settings. + + @library{wxcore} + @category{printing} + + @see @ref overview_printing, wxPrintDialog, @ref overview_cmndlg_print +*/ +class wxPrintDialogData : public wxObject +{ +public: + /** + Default constructor. + */ + wxPrintDialogData(); + + /** + Copy constructor. + */ + wxPrintDialogData(wxPrintDialogData& dialogData); + + /** + Construct an object from a print dialog data object. + */ + wxPrintDialogData(wxPrintData& printData); + + /** + Destructor. + */ + ~wxPrintDialogData(); + + /** + Enables or disables the "Help" button. + */ + void EnableHelp(bool flag); + + /** + Enables or disables the "Page numbers" controls. + */ + void EnablePageNumbers(bool flag); + + /** + Enables or disables the "Print to file" checkbox. + */ + void EnablePrintToFile(bool flag); + + /** + Enables or disables the "Selection" radio button. + */ + void EnableSelection(bool flag); + + /** + Returns @true if the user requested that all pages be printed. + */ + bool GetAllPages() const; + + /** + Returns @true if the user requested that the document(s) be collated. + */ + bool GetCollate() const; + + /** + Returns the @e from page number, as entered by the user. + */ + int GetFromPage() const; + + /** + Returns the @e maximum page number. + */ + int GetMaxPage() const; + + /** + Returns the @e minimum page number. + */ + int GetMinPage() const; + + /** + Returns the number of copies requested by the user. + */ + int GetNoCopies() const; + + /** + Returns a reference to the internal wxPrintData object. + */ + wxPrintData& GetPrintData(); + + /** + Returns @true if the user has selected printing to a file. + */ + bool GetPrintToFile() const; + + /** + Returns @true if the user requested that the selection be printed + (where "selection" is a concept specific to the application). + */ + bool GetSelection() const; + + /** + Returns the @e "print to" page number, as entered by the user. + */ + int GetToPage() const; + + /** + Returns @true if the print data is valid for using in print dialogs. + This can return @false on Windows if the current printer is not set, + for example. On all other platforms, it returns @true. + */ + bool IsOk() const; + + /** + Sets the "Collate" checkbox to @true or @false. + */ + void SetCollate(bool flag); + + /** + Sets the @e from page number. + */ + void SetFromPage(int page); + + /** + Sets the @e maximum page number. + */ + void SetMaxPage(int page); + + /** + Sets the @e minimum page number. + */ + void SetMinPage(int page); + + /** + Sets the default number of copies the user has requested to be printed + out. + */ + void SetNoCopies(int n); + + /** + Sets the internal wxPrintData. + */ + void SetPrintData(const wxPrintData& printData); + + /** + Sets the "Print to file" checkbox to @true or @false. + */ + void SetPrintToFile(bool flag); + + /** + Selects the "Selection" radio button. The effect of printing the + selection depends on how the application implements this command, if at + all. + */ + void SetSelection(bool flag); + + /** + @deprecated This function has been deprecated since version 2.5.4. + + Determines whether the dialog to be shown will be the Print dialog + (pass @false) or Print Setup dialog (pass @true). + + */ + void SetSetupDialog(bool flag); + + /** + Sets the @e "print to" page number. + */ + void SetToPage(int page); + + /** + Assigns print data to this object. + */ + void operator =(const wxPrintData& data); + + /** + Assigns another print dialog data object to this object. + */ + void operator =(const wxPrintDialogData& data); +}; + diff --git a/interface/wx/collpane.h b/interface/wx/collpane.h new file mode 100644 index 0000000000..161eff344d --- /dev/null +++ b/interface/wx/collpane.h @@ -0,0 +1,176 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: collpane.h +// Purpose: interface of wxCollapsiblePane +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxCollapsiblePaneEvent + @wxheader{collpane.h} + + This event class is used for the events generated by wxCollapsiblePane. + + @beginEventTable{wxCollapsiblePaneEvent} + @event{EVT_COLLAPSIBLEPANE_CHANGED(id, func)} + The user expanded or collapsed the collapsible pane. + @endEventTable + + @library{wxcore} + @category{events} + + @see wxCollapsiblePane +*/ +class wxCollapsiblePaneEvent : public wxCommandEvent +{ +public: + /** + The constructor is not normally used by the user code. + */ + wxCollapsiblePaneEvent(wxObject* generator, int id, bool collapsed); + + /** + Returns @true if the pane has been collapsed. + */ + bool GetCollapsed() const; + + /** + Sets this as a collapsed pane event (if @a collapsed is @true) or as an + expanded pane event (if @a collapsed is @false). + */ + void SetCollapsed(bool collapsed); +}; + + + +/** + @class wxCollapsiblePane + @wxheader{collpane.h} + + A collapsible pane is a container with an embedded button-like control + which can be used by the user to collapse or expand the pane's contents. + + Once constructed you should use the GetPane() function to access the pane + and add your controls inside it (i.e. use the returned pointer from + GetPane() as parent for the controls which must go in the pane, @b not the + wxCollapsiblePane itself!). + + Note that because of its nature of control which can dynamically (and + drastically) change its size at run-time under user-input, when putting + wxCollapsiblePane inside a wxSizer you should be careful to add it with a + proportion value of zero; this is because otherwise all other windows with + non-null proportion values will automatically resize each time the user + expands or collapse the pane window usually resulting in a weird, + flickering effect. + + Usage sample: + + @code + wxCollapsiblePane *collpane = new wxCollapsiblePane(this, wxID_ANY, wxT("Details:")); + + // add the pane with a zero proportion value to the 'sz' sizer which contains it + sz->Add(collpane, 0, wxGROW|wxALL, 5); + + // now add a test label in the collapsible pane using a sizer to layout it: + wxWindow *win = collpane->GetPane(); + wxSizer *paneSz = new wxBoxSizer(wxVERTICAL); + paneSz->Add(new wxStaticText(win, wxID_ANY, wxT("test!")), 1, wxGROW|wxALL, 2); + win->SetSizer(paneSz); + paneSz->SetSizeHints(win); + @endcode + + It is only available if @c wxUSE_COLLPANE is set to 1 (the default). + + @beginStyleTable + @style{wxCP_DEFAULT_STYLE} + The default style: 0. + @endStyleTable + + @beginEventTable{wxCollapsiblePaneEvent} + @event{EVT_COLLAPSIBLEPANE_CHANGED(id, func)} + The user expanded or collapsed the collapsible pane. + @endEventTable + + @library{wxcore} + @category{ctrl} + + + @see wxPanel, wxCollapsiblePaneEvent +*/ +class wxCollapsiblePane : public wxControl +{ +public: + /** + Default constructor. + */ + wxCollapsiblePane(); + + /** + Initializes the object and calls Create() with all the parameters. + */ + wxCollapsiblePane(wxWindow* parent, wxWindowID id, + const wxString& label, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxCP_DEFAULT_STYLE, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "collapsiblePane"); + + /** + @param parent + Parent window, must not be non-@NULL. + @param id + The identifier for the control. + @param label + The initial label shown in the button which allows the user to + expand or collapse the pane window. + @param pos + Initial position. + @param size + Initial size. + @param style + The window style, see wxCP_* flags. + @param validator + Validator which can be used for additional date checks. + @param name + Control name. + + @return @true if the control was successfully created or @false if + creation failed. + */ + bool Create(wxWindow* parent, wxWindowID id, + const wxString& label, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxCP_DEFAULT_STYLE, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "collapsiblePane"); + + /** + Collapses or expands the pane window. + */ + void Collapse(bool collapse = true); + + /** + Same as calling Collapse(@false). + */ + void Expand(); + + /** + Returns a pointer to the pane window. Add controls to the returned + wxWindow to make them collapsible. + */ + wxWindow* GetPane() const; + + /** + Returns @true if the pane window is currently hidden. + */ + bool IsCollapsed() const; + + /** + Returns @true if the pane window is currently shown. + */ + bool IsExpanded() const; +}; + diff --git a/interface/wx/colordlg.h b/interface/wx/colordlg.h new file mode 100644 index 0000000000..1ed5b25cb8 --- /dev/null +++ b/interface/wx/colordlg.h @@ -0,0 +1,93 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: colordlg.h +// Purpose: interface of wxColourDialog +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxColourDialog + @wxheader{colordlg.h} + + This class represents the colour chooser dialog. + + @library{wxcore} + @category{cmndlg} + + @see @ref overview_cmndlg_colour, wxColour, wxColourData, + wxGetColourFromUser() +*/ +class wxColourDialog : public wxDialog +{ +public: + /** + Constructor. Pass a parent window, and optionally a pointer to a block + of colour data, which will be copied to the colour dialog's colour + data. + + Custom colours from colour data object will be be used in the dialog's + colour palette. Invalid entries in custom colours list will be ignored + on some platforms(GTK) or replaced with white colour on platforms where + custom colours palette has fixed size (MSW). + + @see wxColourData + */ + wxColourDialog(wxWindow* parent, wxColourData* data = NULL); + + /** + Destructor. + */ + ~wxColourDialog(); + + /** + Same as wxColourDialog(). + */ + bool Create(wxWindow* parent, wxColourData* data = NULL); + + /** + Returns the colour data associated with the colour dialog. + */ + wxColourData GetColourData(); + + /** + Shows the dialog, returning wxID_OK if the user pressed OK, and + wxID_CANCEL otherwise. + */ + int ShowModal(); +}; + + + +// ============================================================================ +// Global functions/macros +// ============================================================================ + +/** @ingroup group_funcmacro_dialog */ +//@{ + +/** + Shows the colour selection dialog and returns the colour selected by user + or invalid colour (use wxColour::IsOk() to test whether a colour is valid) + if the dialog was cancelled. + + @param parent + The parent window for the colour selection dialog. + @param colInit + If given, this will be the colour initially selected in the dialog. + @param caption + If given, this will be used for the dialog caption. + @param data + Optional object storing additional colour dialog settings, such as + custom colours. If none is provided the same settings as the last time + are used. + + @header{wx/colordlg.h} +*/ +wxColour wxGetColourFromUser(wxWindow* parent, + const wxColour& colInit, + const wxString& caption = wxEmptyString, + wxColourData* data = NULL); + +//@} + diff --git a/interface/wx/colour.h b/interface/wx/colour.h new file mode 100644 index 0000000000..52bc2f28d1 --- /dev/null +++ b/interface/wx/colour.h @@ -0,0 +1,213 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: colour.h +// Purpose: interface of wxColour +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxColour + @wxheader{colour.h} + + A colour is an object representing a combination of Red, Green, and Blue + (RGB) intensity values, and is used to determine drawing colours. See the + entry for wxColourDatabase for how a pointer to a predefined, named colour + may be returned instead of creating a new colour. + + Valid RGB values are in the range 0 to 255. + + You can retrieve the current system colour settings with wxSystemSettings. + + @library{wxcore} + @category{gdi} + + @stdobjects + - ::wxNullColour - An empty, invalid colour. + - ::wxBLACK + - ::wxBLUE + - ::wxCYAN + - ::wxGREEN + - ::wxLIGHT_GREY + - ::wxRED + - ::wxWHITE + + @see wxColourDatabase, wxPen, wxBrush, wxColourDialog, wxSystemSettings +*/ +class wxColour : public wxObject +{ +public: + + /** + Default constructor. + */ + wxColour(); + + /** + @param red + The red value. + @param green + The green value. + @param blue + The blue value. + @param alpha + The alpha value. Alpha values range from 0 (wxALPHA_TRANSPARENT) to + 255 (wxALPHA_OPAQUE). + */ + wxColour(unsigned char red, unsigned char green, unsigned char blue, + unsigned char alpha = wxALPHA_OPAQUE); + + /** + @param colourName + The colour name. + */ + wxColour(const wxString& colourName); + + /** + Copy constructor. + */ + wxColour(const wxColour& colour); + + /** + Returns the alpha value, on platforms where alpha is not yet supported, this + always returns wxALPHA_OPAQUE. + */ + unsigned char Alpha() const; + + /** + Returns the blue intensity. + */ + unsigned char Blue() const; + + /** + Converts this colour to a wxString using the given flags. + + The supported flags are wxC2S_NAME, to obtain the colour name (e.g. + wxColour(255,0,0) == "red"), wxC2S_CSS_SYNTAX, to obtain the colour in + the "rgb(r,g,b)" or "rgba(r,g,b,a)" syntax (e.g. + wxColour(255,0,0,85) == "rgba(255,0,0,0.333)"), and wxC2S_HTML_SYNTAX, + to obtain the colour as "#" followed by 6 hexadecimal digits (e.g. + wxColour(255,0,0) == "#FF0000"). + + This function never fails and always returns a non-empty string but + asserts if the colour has alpha channel (i.e. is non opaque) but + wxC2S_CSS_SYNTAX (which is the only one supporting alpha) is not + specified in flags. + + @since 2.7.0 + */ + wxString GetAsString(long flags); + + /** + Returns a pixel value which is platform-dependent. On Windows, a COLORREF is + returned. + On X, an allocated pixel value is returned. + -1 is returned if the pixel is invalid (on X, unallocated). + */ + long GetPixel() const; + + /** + Returns the green intensity. + */ + unsigned char Green() const; + + /** + Returns @true if the colour object is valid (the colour has been initialised + with RGB values). + */ + bool IsOk() const; + + /** + Returns the red intensity. + */ + unsigned char Red() const; + + //@{ + /** + Sets the RGB intensity values using the given values (first overload), + extracting them from the packed long (second overload), using the given + string (third overloard). + + When using third form, Set() accepts: colour names (those listed in + wxTheColourDatabase()), the CSS-like @c "rgb(r,g,b)" or + @c "rgba(r,g,b,a)" syntax (case insensitive) and the HTML-like syntax + (i.e. @c "#" followed by 6 hexadecimal digits for red, green, blue + components). + + Returns @true if the conversion was successful, @false otherwise. + + @since 2.7.0 + */ + void Set(unsigned char red, unsigned char green, + unsigned char blue, + unsigned char alpha = wxALPHA_OPAQUE); + void Set(unsigned long RGB); + bool Set(const wxString& str); + //@} + + /** + Tests the inequality of two colours by comparing individual red, green, blue + colours and alpha values. + */ + bool operator !=(const wxColour& colour); + + //@{ + /** + Assignment operator, using a colour name to be found in the colour database. + + @see wxColourDatabase + */ + wxColour operator =(const wxColour& colour); + wxColour operator =(const wxString& colourName); + //@} + + /** + Tests the equality of two colours by comparing individual red, green, blue + colours and alpha values. + */ + bool operator ==(const wxColour& colour); +}; + + +/** @name Predefined colors. */ +//@{ +wxColour wxNullColour; +wxColour* wxBLACK; +wxColour* wxBLUE; +wxColour* wxCYAN; +wxColour* wxGREEN; +wxColour* wxLIGHT_GREY; +wxColour* wxRED; +wxColour* wxWHITE; +//@} + + + +// ============================================================================ +// Global functions/macros +// ============================================================================ + +/** @ingroup group_funcmacro_misc */ +//@{ + +/** + Converts string to a wxColour best represented by the given string. Returns + @true on success. + + @see wxToString(const wxColour&) + + @header{wx/colour.h} +*/ +bool wxFromString(const wxString& string, wxColour* colour); + +/** + Converts the given wxColour into a string. + + @see wxFromString(const wxString&, wxColour*) + + @header{wx/colour.h} +*/ +wxString wxToString(const wxColour& colour); + +//@} + diff --git a/interface/wx/combo.h b/interface/wx/combo.h new file mode 100644 index 0000000000..353daaf8f5 --- /dev/null +++ b/interface/wx/combo.h @@ -0,0 +1,755 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: combo.h +// Purpose: interface of wxComboCtrl and wxComboPopup +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxComboPopup + @wxheader{combo.h} + + In order to use a custom popup with wxComboCtrl, an interface class must be + derived from wxComboPopup. + + For more information on how to use it, see @ref comboctrl_custompopup. + + @library{wxcore} + @category{ctrl} + + @see wxComboCtrl +*/ +class wxComboPopup +{ +public: + /** + Default constructor. It is recommended that internal variables are + prepared in Init() instead (because m_combo is not valid in + constructor). + */ + wxComboPopup(); + + /** + The derived class must implement this to create the popup control. + + @return @true if the call succeeded, @false otherwise. + */ + virtual bool Create(wxWindow* parent); + + /** + Utility function that hides the popup. + */ + void Dismiss(); + + /** + The derived class may implement this to return adjusted size for the + popup control, according to the variables given. + + @param minWidth + Preferred minimum width. + @param prefHeight + Preferred height. May be -1 to indicate no preference. + @param maxWidth + Max height for window, as limited by screen size. + + @remarks This function is called each time popup is about to be shown. + */ + virtual wxSize GetAdjustedSize(int minWidth, int prefHeight, int maxHeight); + + /** + The derived class must implement this to return pointer to the + associated control created in Create(). + */ + virtual wxWindow* GetControl(); + + /** + The derived class must implement this to return string representation + of the value. + */ + virtual wxString GetStringValue() const; + + /** + The derived class must implement this to initialize its internal + variables. This method is called immediately after construction + finishes. m_combo member variable has been initialized before the call. + */ + virtual void Init(); + + /** + Utility method that returns @true if Create has been called. + + Useful in conjunction with LazyCreate(). + */ + bool IsCreated() const; + + /** + The derived class may implement this to return @true if it wants to + delay call to Create() until the popup is shown for the first time. It + is more efficient, but on the other hand it is often more convenient to + have the control created immediately. + + @remarks Base implementation returns @false. + */ + virtual bool LazyCreate(); + + /** + The derived class may implement this to do something when the parent + wxComboCtrl gets double-clicked. + */ + virtual void OnComboDoubleClick(); + + /** + The derived class may implement this to receive key events from the + parent wxComboCtrl. + + Events not handled should be skipped, as usual. + */ + virtual void OnComboKeyEvent(wxKeyEvent& event); + + /** + The derived class may implement this to do special processing when + popup is hidden. + */ + virtual void OnDismiss(); + + /** + The derived class may implement this to do special processing when + popup is shown. + */ + virtual void OnPopup(); + + /** + The derived class may implement this to paint the parent wxComboCtrl. + + Default implementation draws value as string. + */ + virtual void PaintComboControl(wxDC& dc, const wxRect& rect); + + /** + The derived class must implement this to receive string value changes + from wxComboCtrl. + */ + virtual void SetStringValue(const wxString& value); + + /** + Parent wxComboCtrl. This is parameter has been prepared before Init() + is called. + */ + wxComboCtrl m_combo; +}; + + + +/** + Features enabled for wxComboCtrl. + + @see wxComboCtrl::GetFeatures() +*/ +struct wxComboCtrlFeatures +{ + enum + { + MovableButton = 0x0001, ///< Button can be on either side of control. + BitmapButton = 0x0002, ///< Button may be replaced with bitmap. + ButtonSpacing = 0x0004, ///< Button can have spacing from the edge + ///< of the control. + TextIndent = 0x0008, ///< wxComboCtrl::SetTextIndent() can be used. + PaintControl = 0x0010, ///< Combo control itself can be custom painted. + PaintWritable = 0x0020, ///< A variable-width area in front of writable + ///< combo control's textctrl can be custom + ///< painted. + Borderless = 0x0040, ///< wxNO_BORDER window style works. + + All = MovableButton | BitmapButton | ButtonSpacing | + TextIndent | PaintControl | PaintWritable | + Borderless ///< All features. + }; +}; + + +/** + @class wxComboCtrl + @wxheader{combo.h} + + A combo control is a generic combobox that allows totally custom popup. In + addition it has other customization features. For instance, position and + size of the dropdown button can be changed. + + @section comboctrl_custompopup Setting Custom Popup for wxComboCtrl + + wxComboCtrl needs to be told somehow which control to use and this is done + by SetPopupControl(). However, we need something more than just a wxControl + in this method as, for example, we need to call + SetStringValue("initial text value") and wxControl doesn't have such + method. So we also need a wxComboPopup which is an interface which must be + implemented by a control to be usable as a popup. + + We couldn't derive wxComboPopup from wxControl as this would make it + impossible to have a class deriving from a wxWidgets control and from it, + so instead it is just a mix-in. + + Here's a minimal sample of wxListView popup: + + @code + #include + #include + + class wxListViewComboPopup : public wxListView, public wxComboPopup + { + public: + // Initialize member variables + virtual void Init() + { + m_value = -1; + } + + // Create popup control + virtual bool Create(wxWindow* parent) + { + return wxListView::Create(parent,1,wxPoint(0,0),wxDefaultSize); + } + + // Return pointer to the created control + virtual wxWindow *GetControl() { return this; } + + // Translate string into a list selection + virtual void SetStringValue(const wxString& s) + { + int n = wxListView::FindItem(-1,s); + if ( n >= 0 && n < wxListView::GetItemCount() ) + wxListView::Select(n); + } + + // Get list selection as a string + virtual wxString GetStringValue() const + { + if ( m_value >= 0 ) + return wxListView::GetItemText(m_value); + return wxEmptyString; + } + + // Do mouse hot-tracking (which is typical in list popups) + void OnMouseMove(wxMouseEvent& event) + { + // TODO: Move selection to cursor + } + + // On mouse left up, set the value and close the popup + void OnMouseClick(wxMouseEvent& WXUNUSED(event)) + { + m_value = wxListView::GetFirstSelected(); + + // TODO: Send event as well + + Dismiss(); + } + + protected: + + int m_value; // current item index + + private: + DECLARE_EVENT_TABLE() + }; + + BEGIN_EVENT_TABLE(wxListViewComboPopup, wxListView) + EVT_MOTION(wxListViewComboPopup::OnMouseMove) + EVT_LEFT_UP(wxListViewComboPopup::OnMouseClick) + END_EVENT_TABLE() + @endcode + + Here's how you would create and populate it in a dialog constructor: + + @code + wxComboCtrl* comboCtrl = new wxComboCtrl(this, wxID_ANY, wxEmptyString); + + wxListViewComboPopup* popupCtrl = new wxListViewComboPopup(); + + comboCtrl->SetPopupControl(popupCtrl); + + // Populate using wxListView methods + popupCtrl->InsertItem(popupCtrl->GetItemCount(), "First Item"); + popupCtrl->InsertItem(popupCtrl->GetItemCount(), "Second Item"); + popupCtrl->InsertItem(popupCtrl->GetItemCount(), "Third Item"); + @endcode + + @beginStyleTable + @style{wxCB_READONLY} + Text will not be editable. + @style{wxCB_SORT} + Sorts the entries in the list alphabetically. + @style{wxTE_PROCESS_ENTER} + The control will generate the event wxEVT_COMMAND_TEXT_ENTER + (otherwise pressing Enter key is either processed internally by the + control or used for navigation between dialog controls). Windows + only. + @style{wxCC_SPECIAL_DCLICK} + Double-clicking triggers a call to popup's OnComboDoubleClick. + Actual behaviour is defined by a derived class. For instance, + wxOwnerDrawnComboBox will cycle an item. This style only applies if + wxCB_READONLY is used as well. + @style{wxCC_STD_BUTTON} + Drop button will behave more like a standard push button. + @endStyleTable + + @beginEventTable{wxCommandEvent} + @event{EVT_TEXT(id, func)} + Process a wxEVT_COMMAND_TEXT_UPDATED event, when the text changes. + @event{EVT_TEXT_ENTER(id, func)} + Process a wxEVT_COMMAND_TEXT_ENTER event, when RETURN is pressed in + the combo control. + @endEventTable + + @library{wxbase} + @category{ctrl} + + + @see wxComboBox, wxChoice, wxOwnerDrawnComboBox, wxComboPopup, + wxCommandEvent +*/ +class wxComboCtrl : public wxControl +{ +public: + /** + Default constructor. + */ + wxComboCtrl(); + + /** + Constructor, creating and showing a combo control. + + @param parent + Parent window. Must not be @NULL. + @param id + Window identifier. The value 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 sized + appropriately. + @param style + Window style. See wxComboCtrl. + @param validator + Window validator. + @param name + Window name. + + @see Create(), wxValidator + */ + wxComboCtrl(wxWindow* parent, wxWindowID id, + const wxString& value = "", + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "comboCtrl"); + + /** + Destructor, destroying the combo control. + */ + virtual ~wxComboCtrl(); + + /** + This member function is not normally called in application code. + Instead, it can be implemented in a derived class to create a custom + popup animation. + + The parameters are the same as those for DoShowPopup(). + + @return @true if animation finishes before the function returns, + @false otherwise. In the latter case you need to manually call + DoShowPopup() after the animation ends. + */ + virtual bool AnimateShow(const wxRect& rect, int flags); + + /** + Copies the selected text to the clipboard. + */ + virtual void Copy(); + + /** + Creates the combo control for two-step construction. Derived classes + should call or replace this function. See wxComboCtrl() for further + details. + */ + bool Create(wxWindow* parent, wxWindowID id, + const wxString& value = "", + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "comboCtrl"); + + /** + Copies the selected text to the clipboard and removes the selection. + */ + virtual void Cut(); + + /** + This member function is not normally called in application code. + Instead, it can be implemented in a derived class to return default + wxComboPopup, incase @a popup is @NULL. + + @note If you have implemented OnButtonClick() to do something else than + show the popup, then DoSetPopupControl() must always set @a popup + to @NULL. + */ + void DoSetPopupControl(wxComboPopup* popup); + + /** + This member function is not normally called in application code. + Instead, it must be called in a derived class to make sure popup is + properly shown after a popup animation has finished (but only if + AnimateShow() did not finish the animation within its function scope). + + @param rect + Position to show the popup window at, in screen coordinates. + @param flags + Combination of any of the following: + @beginTable + @row2col{wxComboCtrl::ShowAbove, + Popup is shown above the control instead of below.} + @row2col{wxComboCtrl::CanDeferShow, + Showing the popup can be deferred to happen sometime after + ShowPopup() has finished. In this case, AnimateShow() must + return false.} + @endTable + */ + virtual void DoShowPopup(const wxRect& rect, int flags); + + /** + Enables or disables popup animation, if any, depending on the value of + the argument. + */ + void EnablePopupAnimation(bool enable = true); + + /** + Returns disabled button bitmap that has been set with + SetButtonBitmaps(). + + @return A reference to the disabled state bitmap. + */ + const wxBitmap GetBitmapDisabled() const; + + /** + Returns button mouse hover bitmap that has been set with + SetButtonBitmaps(). + + @return A reference to the mouse hover state bitmap. + */ + const wxBitmap GetBitmapHover() const; + + /** + Returns default button bitmap that has been set with + SetButtonBitmaps(). + + @return A reference to the normal state bitmap. + */ + const wxBitmap GetBitmapNormal() const; + + /** + Returns depressed button bitmap that has been set with + SetButtonBitmaps(). + + @return A reference to the depressed state bitmap. + */ + const wxBitmap GetBitmapPressed() const; + + /** + Returns current size of the dropdown button. + */ + wxSize GetButtonSize(); + + /** + Returns custom painted area in control. + + @see SetCustomPaintWidth(). + */ + int GetCustomPaintWidth() const; + + /** + Returns features supported by wxComboCtrl. If needed feature is + missing, you need to instead use wxGenericComboCtrl, which however may + lack a native look and feel (but otherwise sports identical API). + + @return Value returned is a combination of the flags defined in + wxComboCtrlFeatures. + */ + static int GetFeatures(); + + /** + Returns the insertion point for the combo control's text field. + + @note Under Windows, this function always returns 0 if the combo + control doesn't have the focus. + */ + virtual long GetInsertionPoint() const; + + /** + Returns the last position in the combo control text field. + */ + virtual long GetLastPosition() const; + + /** + Returns current popup interface that has been set with + SetPopupControl(). + */ + wxComboPopup* GetPopupControl(); + + /** + Returns popup window containing the popup control. + */ + wxWindow* GetPopupWindow() const; + + /** + Get the text control which is part of the combo control. + */ + wxTextCtrl* GetTextCtrl() const; + + /** + Returns actual indentation in pixels. + */ + wxCoord GetTextIndent() const; + + /** + Returns area covered by the text field (includes everything except + borders and the dropdown button). + */ + const wxRect GetTextRect() const; + + /** + Returns text representation of the current value. For writable combo + control it always returns the value in the text field. + */ + virtual wxString GetValue() const; + + /** + Dismisses the popup window. + */ + virtual void HidePopup(); + + /** + Returns @true if the popup is currently shown + */ + bool IsPopupShown() const; + + /** + Returns @true if the popup window is in the given state. Possible + values are: + + @beginTable + @row2col{wxComboCtrl::Hidden, Popup window is hidden.} + @row2col{wxComboCtrl::Animating, Popup window is being shown, but the + popup animation has not yet finished.} + @row2col{wxComboCtrl::Visible, Popup window is fully visible.} + @endTable + */ + bool IsPopupWindowState(int state) const; + + /** + Implement in a derived class to define what happens on dropdown button + click. Default action is to show the popup. + + @note If you implement this to do something else than show the popup, + you must then also implement DoSetPopupControl() to always return + @NULL. + */ + virtual void OnButtonClick(); + + /** + Pastes text from the clipboard to the text field. + */ + virtual void Paste(); + + /** + Removes the text between the two positions in the combo control text + field. + + @param from + The first position. + @param to + The last position. + */ + virtual void Remove(long from, long to); + + /** + Replaces the text between two positions with the given text, in the + combo control text field. + + @param from + The first position. + @param to + The second position. + @param text + The text to insert. + */ + virtual void Replace(long from, long to, const wxString& value); + + /** + Sets custom dropdown button graphics. + + @param bmpNormal + Default button image. + @param pushButtonBg + If @true, blank push button background is painted below the image. + @param bmpPressed + Depressed button image. + @param bmpHover + Button image when mouse hovers above it. This should be ignored on + platforms and themes that do not generally draw different kind of + button on mouse hover. + @param bmpDisabled + Disabled button image. + */ + void SetButtonBitmaps(const wxBitmap& bmpNormal, + bool pushButtonBg = false, + const wxBitmap& bmpPressed = wxNullBitmap, + const wxBitmap& bmpHover = wxNullBitmap, + const wxBitmap& bmpDisabled = wxNullBitmap); + + /** + Sets size and position of dropdown button. + + @param width + Button width. Value = 0 specifies default. + @param height + Button height. Value = 0 specifies default. + @param side + Indicates which side the button will be placed. Value can be wxLEFT + or wxRIGHT. + @param spacingX + Horizontal spacing around the button. Default is 0. + */ + void SetButtonPosition(int width = -1, int height = -1, + int side = wxRIGHT, int spacingX = 0); + + /** + Set width, in pixels, of custom painted area in control without + @c wxCB_READONLY style. In read-only wxOwnerDrawnComboBox, this is used + to indicate area that is not covered by the focus rectangle. + */ + void SetCustomPaintWidth(int width); + + /** + Sets the insertion point in the text field. + + @param pos + The new insertion point. + */ + virtual void SetInsertionPoint(long pos); + + /** + Sets the insertion point at the end of the combo control text field. + */ + virtual void SetInsertionPointEnd(); + + /** + Set side of the control to which the popup will align itself. Valid + values are @c wxLEFT, @c wxRIGHT and 0. The default value 0 means that + the most appropriate side is used (which, currently, is always + @c wxLEFT). + */ + void SetPopupAnchor(int anchorSide); + + /** + Set popup interface class derived from wxComboPopup. This method should + be called as soon as possible after the control has been created, + unless OnButtonClick() has been overridden. + */ + void SetPopupControl(wxComboPopup* popup); + + /** + Extends popup size horizontally, relative to the edges of the combo + control. + + @param extLeft + How many pixel to extend beyond the left edge of the control. + Default is 0. + @param extRight + How many pixel to extend beyond the right edge of the control. + Default is 0. + + @remarks Popup minimum width may override arguments. It is up to the + popup to fully take this into account. + */ + void SetPopupExtents(int extLeft, int extRight); + + /** + Sets preferred maximum height of the popup. + + @remarks Value -1 indicates the default. + */ + void SetPopupMaxHeight(int height); + + /** + Sets minimum width of the popup. If wider than combo control, it will + extend to the left. + + @remarks Value -1 indicates the default. Also, popup implementation may + choose to ignore this. + */ + void SetPopupMinWidth(int width); + + /** + Selects the text between the two positions, in the combo control text + field. + + @param from + The first position. + @param to + The second position. + */ + virtual void SetSelection(long from, long to); + + /** + Sets the text for the text field without affecting the popup. Thus, + unlike SetValue(), it works equally well with combo control using + @c wxCB_READONLY style. + */ + void SetText(const wxString& value); + + /** + This will set the space in pixels between left edge of the control and + the text, regardless whether control is read-only or not. Value -1 can + be given to indicate platform default. + */ + void SetTextIndent(int indent); + + /** + Sets the text for the combo control text field. + + @note For a combo control with @c wxCB_READONLY style the string must + be accepted by the popup (for instance, exist in the dropdown + list), otherwise the call to SetValue() is ignored. + */ + virtual void SetValue(const wxString& value); + + /** + Same as SetValue(), but also sends wxCommandEvent of type + wxEVT_COMMAND_TEXT_UPDATED if @a withEvent is @true. + */ + void SetValueWithEvent(const wxString& value, bool withEvent = true); + + /** + Show the popup. + */ + virtual void ShowPopup(); + + /** + Undoes the last edit in the text field. Windows only. + */ + virtual void Undo(); + + /** + Enable or disable usage of an alternative popup window, which + guarantees ability to focus the popup control, and allows common native + controls to function normally. This alternative popup window is usually + a wxDialog, and as such, when it is shown, its parent top-level window + will appear as if the focus has been lost from it. + */ + void UseAltPopupWindow(bool enable = true); +}; + diff --git a/interface/wx/combobox.h b/interface/wx/combobox.h new file mode 100644 index 0000000000..d70190e385 --- /dev/null +++ b/interface/wx/combobox.h @@ -0,0 +1,302 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: combobox.h +// Purpose: interface of wxComboBox +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxComboBox + @wxheader{combobox.h} + + A combobox is like a combination of an edit control and a listbox. It can + be displayed as static list with editable or read-only text field; or a + drop-down list with text field; or a drop-down list without a text field. + + A combobox permits a single selection only. Combobox items are numbered + from zero. + + If you need a customized combobox, have a look at wxComboCtrl, + wxOwnerDrawnComboBox, wxComboPopup and the ready-to-use wxBitmapComboBox. + + @beginStyleTable + @style{wxCB_SIMPLE} + Creates a combobox with a permanently displayed list. Windows only. + @style{wxCB_DROPDOWN} + Creates a combobox with a drop-down list. + @style{wxCB_READONLY} + Same as wxCB_DROPDOWN but only the strings specified as the combobox + choices can be selected, it is impossible to select (even from a + program) a string which is not in the choices list. + @style{wxCB_SORT} + Sorts the entries in the list alphabetically. + @style{wxTE_PROCESS_ENTER} + The control will generate the event wxEVT_COMMAND_TEXT_ENTER + (otherwise pressing Enter key is either processed internally by the + control or used for navigation between dialog controls). Windows + only. + @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 + value of selection. + @event{EVT_TEXT(id, func)} + Process a wxEVT_COMMAND_TEXT_UPDATED event, when the combobox text + changes. + @event{EVT_TEXT_ENTER(id, func)} + Process a wxEVT_COMMAND_TEXT_ENTER event, when RETURN is pressed in + the combobox (notice that the combobox must have been created with + wxTE_PROCESS_ENTER style to receive this event). + @endEventTable + + @library{wxcore} + @category{ctrl} + + + @see wxListBox, wxTextCtrl, wxChoice, wxCommandEvent +*/ +class wxComboBox : public wxControl, public wxItemContainer +{ +public: + /** + Default constructor. + */ + wxComboBox(); + + //@{ + /** + Constructor, creating and showing a combobox. + + @param parent + Parent window. Must not be @NULL. + @param id + Window identifier. The value 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 sized + appropriately. + @param n + Number of strings with which to initialise the control. + @param choices + An array of strings with which to initialise the control. + @param style + Window style. See wxComboBox. + @param validator + Window validator. + @param name + Window name. + + @beginWxPythonOnly + The wxComboBox constructor in wxPython reduces the @a n and @a choices + arguments are to a single argument, which is a list of strings. + @endWxPythonOnly + + @see Create(), wxValidator + */ + wxComboBox(wxWindow* parent, wxWindowID id, + const wxString& value = "", + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + int n = 0, + const wxString choices[] = NULL, + long style = 0, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "comboBox"); + wxComboBox(wxWindow* parent, wxWindowID id, + const wxString& value, + const wxPoint& pos, + const wxSize& size, + const wxArrayString& choices, + long style = 0, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "comboBox"); + //@} + + /** + Destructor, destroying the combobox. + */ + ~wxComboBox(); + + //@{ + /** + Creates the combobox for two-step construction. Derived classes should + call or replace this function. See wxComboBox() for further details. + */ + bool Create(wxWindow* parent, wxWindowID id, + const wxString& value = "", + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + int n, const wxString choices[], + long style = 0, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "comboBox"); + bool Create(wxWindow* parent, wxWindowID id, + const wxString& value, + const wxPoint& pos, + const wxSize& size, + const wxArrayString& choices, + long style = 0, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "comboBox"); + //@} + + /** + Returns @true if the combobox is editable and there is a text selection + to copy to the clipboard. Only available on Windows. + */ + bool CanCopy() const; + + /** + Returns @true if the combobox is editable and there is a text selection + to copy to the clipboard. Only available on Windows. + */ + bool CanCut() const; + + /** + Returns @true if the combobox is editable and there is text on the + clipboard that can be pasted into the text field. Only available on + Windows. + */ + bool CanPaste() const; + + /** + Returns @true if the combobox is editable and the last undo can be + redone. Only available on Windows. + */ + bool CanRedo() const; + + /** + Returns @true if the combobox is editable and the last edit can be + undone. Only available on Windows. + */ + bool CanUndo() const; + + /** + Copies the selected text to the clipboard. + */ + void Copy(); + + /** + Copies the selected text to the clipboard and removes the selection. + */ + void Cut(); + + /** + This function does the same things as wxChoice::GetCurrentSelection() + and returns the item currently selected in the dropdown list if it's + open or the same thing as wxControlWithItems::GetSelection() otherwise. + */ + int GetCurrentSelection() const; + + /** + Returns the insertion point for the combobox's text field. + + @note Under wxMSW, this function always returns 0 if the combobox + doesn't have the focus. + */ + long GetInsertionPoint() const; + + /** + Returns the last position in the combobox text field. + */ + virtual wxTextPos GetLastPosition() const; + + /** + This is the same as wxTextCtrl::GetSelection() for the text control + which is part of the combobox. Notice that this is a different method + from wxControlWithItems::GetSelection(). + + Currently this method is only implemented in wxMSW and wxGTK. + */ + void GetSelection(long* from, long* to) const; + + /** + Returns the current value in the combobox text field. + */ + wxString GetValue() const; + + /** + Pastes text from the clipboard to the text field. + */ + void Paste(); + + /** + Redoes the last undo in the text field. Windows only. + */ + void Redo(); + + /** + Removes the text between the two positions in the combobox text field. + + @param from + The first position. + @param to + The last position. + */ + void Remove(long from, long to); + + /** + Replaces the text between two positions with the given text, in the + combobox text field. + + @param from + The first position. + @param to + The second position. + @param text + The text to insert. + */ + void Replace(long from, long to, const wxString& text); + + /** + Sets the insertion point in the combobox text field. + + @param pos + The new insertion point. + */ + void SetInsertionPoint(long pos); + + /** + Sets the insertion point at the end of the combobox text field. + */ + void SetInsertionPointEnd(); + + /** + Selects the text between the two positions, in the combobox text field. + + @param from + The first position. + @param to + The second position. + + @beginWxPythonOnly + This method is called SetMark() in wxPython, "SetSelection" is kept for + wxControlWithItems::SetSelection(). + @endWxPythonOnly + */ + void SetSelection(long from, long to); + + /** + Sets the text for the combobox text field. + + @note For a combobox with @c wxCB_READONLY style the string must be in + the combobox choices list, otherwise the call to SetValue() is + ignored. + + @param text + The text to set. + */ + void SetValue(const wxString& text); + + /** + Undoes the last edit in the text field. Windows only. + */ + void Undo(); +}; + diff --git a/interface/wx/config.h b/interface/wx/config.h new file mode 100644 index 0000000000..1f7db64161 --- /dev/null +++ b/interface/wx/config.h @@ -0,0 +1,780 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: config.h +// Purpose: interface of wxConfigBase +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxConfigBase + @wxheader{config.h} + + wxConfigBase defines the basic interface of all config classes. It can not + be used by itself (it is an abstract base class) and you will always use + one of its derivations: wxFileConfig, wxRegConfig or any other. + + However, usually you don't even need to know the precise nature of the + class you're working with but you would just use the wxConfigBase methods. + This allows you to write the same code regardless of whether you're working + with the registry under Win32 or text-based config files under Unix (or + even Windows 3.1 .INI files if you're really unlucky). To make writing the + portable code even easier, wxWidgets provides a typedef wxConfig which is + mapped onto the native wxConfigBase implementation on the given platform: + i.e. wxRegConfig under Win32 and wxFileConfig otherwise. + + See @ref overview_config for a description of all features of this class. + + It is highly recommended to use static functions Get() and/or Set(), so + please have a look at them. + + Related Include Files: + + @li @c - Let wxWidgets choose a wxConfig class for your + platform. + @li @c - Base config class. + @li @c - wxFileConfig class. + @li @c - wxRegConfig class, see also wxRegKey. + + + @section configbase_example Example + + Here is how you would typically use this class: + + @code + // using wxConfig instead of writing wxFileConfig or wxRegConfig enhances + // portability of the code + wxConfig *config = new wxConfig("MyAppName"); + + wxString str; + if ( config->Read("LastPrompt", &str) ) { + // last prompt was found in the config file/registry and its value is + // now in str + // ... + } + else { + // no last prompt... + } + + // another example: using default values and the full path instead of just + // key name: if the key is not found , the value 17 is returned + long value = config->ReadLong("/LastRun/CalculatedValues/MaxValue", 17); + + // at the end of the program we would save everything back + config->Write("LastPrompt", str); + config->Write("/LastRun/CalculatedValues/MaxValue", value); + + // the changes will be written back automatically + delete config; + @endcode + + This basic example, of course, doesn't show all wxConfig features, such as + enumerating, testing for existence and deleting the entries and groups of + entries in the config file, its abilities to automatically store the + default values or expand the environment variables on the fly. However, the + main idea is that using this class is easy and that it should normally do + what you expect it to. + + @note In the documentation of this class, the words "config file" also mean + "registry hive" for wxRegConfig and, generally speaking, might mean + any physical storage where a wxConfigBase-derived class stores its + data. + + + @section configbase_static Static Functions + + The static functions provided deal with the "default" config object. + Although its usage is not at all mandatory it may be convenient to use a + global config object instead of creating and deleting the local config + objects each time you need one (especially because creating a wxFileConfig + object might be a time consuming operation). In this case, you may create + this global config object in the very start of the program and Set() it as + the default. Then, from anywhere in your program, you may access it using + the Get() function. This global wxConfig object will be deleted by + wxWidgets automatically if it exists. Note that this implies that if you do + delete this object yourself (usually in wxApp::OnExit()) you must use + Set(@NULL) to prevent wxWidgets from deleting it the second time. + + As it happens, you may even further simplify the procedure described above: + you may forget about calling Set(). When Get() is called and there is no + current object, it will create one using Create() function. To disable this + behaviour DontCreateOnDemand() is provided. + + @note You should use either Set() or Get() because wxWidgets library itself + would take advantage of it and could save various information in it. + For example wxFontMapper or Unix version of wxFileDialog have the + ability to use wxConfig class. + + + @section configbase_paths Path Management + + As explained in the @ref overview_config "config overview", the config + classes support a file system-like hierarchy of keys (files) and groups + (directories). As in the file system case, to specify a key in the config + class you must use a path to it. Config classes also support the notion of + the current group, which makes it possible to use the relative paths. To + clarify all this, here is an example (it is only for the sake of + demonstration, it doesn't do anything sensible!): + + @code + wxConfig *config = new wxConfig("FooBarApp"); + + // right now the current path is '/' + conf->Write("RootEntry", 1); + + // go to some other place: if the group(s) don't exist, they will be created + conf->SetPath("/Group/Subgroup"); + + // create an entry in subgroup + conf->Write("SubgroupEntry", 3); + + // '..' is understood + conf->Write("../GroupEntry", 2); + conf->SetPath(".."); + + wxASSERT( conf->ReadLong("Subgroup/SubgroupEntry", 0) == 3 ); + + // use absolute path: it is allowed, too + wxASSERT( conf->ReadLong("/RootEntry", 0) == 1 ); + @endcode + + It is highly recommended that you restore the path to its old value on + function exit: + + @code + void foo(wxConfigBase *config) + { + wxString strOldPath = config->GetPath(); + + config->SetPath("/Foo/Data"); + // ... + + config->SetPath(strOldPath); + } + @endcode + + Otherwise the assert in the following example will surely fail (we suppose + here that the foo() function is the same as above except that it doesn’t + save and restore the path): + + @code + void bar(wxConfigBase *config) + { + config->Write("Test", 17); + + foo(config); + + // we're reading "/Foo/Data/Test" here! -1 will probably be returned... + wxASSERT( config->ReadLong("Test", -1) == 17 ); + } + @endcode + + Finally, the path separator in wxConfigBase and derived classes is always + "/", regardless of the platform (i.e. it is not "\\" under Windows). + + + @section configbase_enumeration Enumeration + + The enumeration functions allow you to enumerate all entries and groups in + the config file. All functions here return @false when there are no more + items. + + You must pass the same index to GetNext() and GetFirst() (don't modify it). + Please note that it is not the index of the current item (you will have + some great surprises with wxRegConfig if you assume this) and you shouldn't + even look at it: it is just a "cookie" which stores the state of the + enumeration. It can't be stored inside the class because it would prevent + you from running several enumerations simultaneously, that's why you must + pass it explicitly. + + Having said all this, enumerating the config entries/groups is very simple: + + @code + wxConfigBase *config = ...; + wxArrayString aNames; + + // enumeration variables + wxString str; + long dummy; + + // first enum all entries + bool bCont = config->GetFirstEntry(str, dummy); + while ( bCont ) { + aNames.Add(str); + + bCont = GetConfig()->GetNextEntry(str, dummy); + } + + // ... we have all entry names in aNames... + + // now all groups... + bCont = GetConfig()->GetFirstGroup(str, dummy); + while ( bCont ) { + aNames.Add(str); + + bCont = GetConfig()->GetNextGroup(str, dummy); + } + + // ... we have all group (and entry) names in aNames... + @endcode + + There are also functions to get the number of entries/subgroups without + actually enumerating them, but you will probably never need them. + + + @section configbase_keyaccess Key Access + + The key access functions are the core of wxConfigBase class: they allow you + to read and write config file data. All Read() functions take a default + value which will be returned if the specified key is not found in the + config file. + + Currently, supported types of data are: wxString, @c long, @c double, + @c bool, wxColour and any other types for which the functions + wxToString() and wxFromString() are defined. + + Try not to read long values into string variables and vice versa: + although it just might work with wxFileConfig, you will get a system + error with wxRegConfig because in the Windows registry the different + types of entries are indeed used. + + Final remark: the @a szKey parameter for all these functions can + contain an arbitrary path (either relative or absolute), not just the + key name. + + @beginWxPythonOnly + In place of a single overloaded method name, wxPython implements the + following methods: + - Read(key, default="") - Returns a string. + - ReadInt(key, default=0) - Returns an integer. + - ReadFloat(key, default=0.0) - Returns a floating point number. + - ReadBool(key, default=0) - Returns a boolean. + - Write(key, value) - Writes a string. + - WriteInt(key, value) - Writes an int. + - WriteFloat(key, value) - Writes a floating point number. + @endWxPythonOnly + + + @library{wxbase} + @category{misc} +*/ +class wxConfigBase : public wxObject +{ +public: + /** + This is the default and only constructor of the wxConfigBase class, and + derived classes. + + @param appName + The application name. If this is empty, the class will normally use + wxApp::GetAppName() to set it. The application name is used in the + registry key on Windows, and can be used to deduce the local + filename parameter if that is missing. + @param vendorName + The vendor name. If this is empty, it is assumed that no vendor + name is wanted, if this is optional for the current config class. + The vendor name is appended to the application name for + wxRegConfig. + @param localFilename + Some config classes require a local filename. If this is not + present, but required, the application name will be used instead. + @param globalFilename + Some config classes require a global filename. If this is not + present, but required, the application name will be used instead. + @param style + Can be one of wxCONFIG_USE_LOCAL_FILE and wxCONFIG_USE_GLOBAL_FILE. + The style interpretation depends on the config class and is ignored + by some implementations. For wxFileConfig, these styles determine + whether a local or global config file is created or used: if + wxCONFIG_USE_GLOBAL_FILE is used, then settings are read from the + global config file and if wxCONFIG_USE_LOCAL_FILE is used, settings + are read from and written to local config file (if they are both + set, global file is read first, then local file, overwriting global + settings). If the flag is present but the parameter is empty, the + parameter will be set to a default. If the parameter is present but + the style flag not, the relevant flag will be added to the style. + For wxRegConfig, thie GLOBAL flag refers to HKLM key while LOCAL + one is for the usual HKCU one. + @n For wxFileConfig you can also add wxCONFIG_USE_RELATIVE_PATH by + logically or'ing it to either of the _FILE options to tell + wxFileConfig to use relative instead of absolute paths. + @n On non-VMS Unix systems, the default local configuration file is + "~/.appname". However, this path may be also used as user data + directory (see wxStandardPaths::GetUserDataDir()) if the + application has several data files. In this case + wxCONFIG_USE_SUBDIR flag, which changes the default local + configuration file to "~/.appname/appname" should be used. Notice + that this flag is ignored if localFilename is provided. + wxCONFIG_USE_SUBDIR is new since wxWidgets version 2.8.2. + @n For wxFileConfig, you can also add + wxCONFIG_USE_NO_ESCAPE_CHARACTERS which will turn off character + escaping for the values of entries stored in the config file: for + example a foo key with some backslash characters will be stored as + "foo=C:\mydir" instead of the usual storage of "foo=C:\\mydir". + @n The wxCONFIG_USE_NO_ESCAPE_CHARACTERS style can be helpful if your + config file must be read or written to by a non-wxWidgets program + (which might not understand the escape characters). Note, however, + that if wxCONFIG_USE_NO_ESCAPE_CHARACTERS style is used, it is is + now your application's responsibility to ensure that there is no + newline or other illegal characters in a value, before writing that + value to the file. + @param conv + This parameter is only used by wxFileConfig when compiled in + Unicode mode. It specifies the encoding in which the configuration + file is written. + + @remarks By default, environment variable expansion is on and recording + defaults is off. + */ + wxConfigBase(const wxString& appName = wxEmptyString, + const wxString& vendorName = wxEmptyString, + const wxString& localFilename = wxEmptyString, + const wxString& globalFilename = wxEmptyString, + long style = 0, + const wxMBConv& conv = wxConvAuto()); + + /** + Empty but ensures that dtor of all derived classes is virtual. + */ + ~wxConfigBase(); + + + /** + @name Path Management + + See @ref configbase_paths + */ + //@{ + + /** + Retrieve the current path (always as absolute path). + */ + const wxString GetPath() const; + + /** + Set current path: if the first character is '/', it is the absolute + path, otherwise it is a relative path. '..' is supported. If @a strPath + doesn't exist it is created. + */ + void SetPath(const wxString& strPath); + + //@} + + + /** + @name Enumeration + + See @ref configbase_enumeration + */ + //@{ + + /** + Gets the first entry. + + @beginWxPythonOnly + The wxPython version of this method returns a 3-tuple consisting of the + continue flag, the value string, and the index for the next call. + @endWxPythonOnly + */ + bool GetFirstEntry(wxString& str, long& index) const; + + /** + Gets the first group. + + @beginWxPythonOnly + The wxPython version of this method returns a 3-tuple consisting of the + continue flag, the value string, and the index for the next call. + @endWxPythonOnly + */ + bool GetFirstGroup(wxString& str, long& index) const; + + /** + Gets the next entry. + + @beginWxPythonOnly + The wxPython version of this method returns a 3-tuple consisting of the + continue flag, the value string, and the index for the next call. + @endWxPythonOnly + */ + bool GetNextEntry(wxString& str, long& index) const; + + /** + Gets the next group. + + @beginWxPythonOnly + The wxPython version of this method returns a 3-tuple consisting of the + continue flag, the value string, and the index for the next call. + @endWxPythonOnly + */ + bool GetNextGroup(wxString& str, long& index) const; + + /** + Get number of entries in the current group. + */ + uint GetNumberOfEntries(bool bRecursive = false) const; + + /** + Get number of entries/subgroups in the current group, with or without + its subgroups. + */ + uint GetNumberOfGroups(bool bRecursive = false) const; + + //@} + + + enum EntryType + { + Type_Unknown, + Type_String, + Type_Boolean, + Type_Integer, + Type_Float + }; + + /** + @name Tests of Existence + */ + //@{ + + /** + @return @true if either a group or an entry with a given name exists. + */ + bool Exists(wxString& strName) const; + + /** + Returns the type of the given entry or @e Unknown if the entry doesn't + exist. This function should be used to decide which version of Read() + should be used because some of wxConfig implementations will complain + about type mismatch otherwise: e.g., an attempt to read a string value + from an integer key with wxRegConfig will fail. + */ + wxConfigBase::EntryType GetEntryType(const wxString& name) const; + + /** + @return @true if the entry by this name exists. + */ + bool HasEntry(wxString& strName) const; + + /** + @return @true if the group by this name exists. + */ + bool HasGroup(const wxString& strName) const; + + //@} + + + /** + @name Miscellaneous Functions + */ + //@{ + + /** + Returns the application name. + */ + wxString GetAppName() const; + + /** + Returns the vendor name. + */ + wxString GetVendorName() const; + + //@} + + + /** + @name Key Access + + See @ref configbase_keyaccess + */ + //@{ + + /** + Permanently writes all changes (otherwise, they're only written from + object's destructor). + */ + bool Flush(bool bCurrentOnly = false); + + /** + Read a string from the key, returning @true if the value was read. If + the key was not found, @a str is not changed. + */ + bool Read(const wxString& key, wxString* str) const; + /** + Read a string from the key. The default value is returned if the key + was not found. + + @return @true if value was really read, @false if the default was used. + */ + const bool Read(const wxString& key, wxString* str, + const wxString& defaultVal) const; + /** + Another version of Read(), returning the string value directly. + */ + const wxString Read(const wxString& key, + const wxString& defaultVal) const; + /** + Reads a long value, returning @true if the value was found. If the + value was not found, @a l is not changed. + */ + const bool Read(const wxString& key, long* l) const; + /** + Reads a long value, returning @true if the value was found. If the + value was not found, @a defaultVal is used instead. + */ + const bool Read(const wxString& key, long* l, + long defaultVal) const; + /** + Reads a double value, returning @true if the value was found. If the + value was not found, @a d is not changed. + */ + const bool Read(const wxString& key, double* d) const; + /** + Reads a double value, returning @true if the value was found. If the + value was not found, @a defaultVal is used instead. + */ + const bool Read(const wxString& key, double* d, + double defaultVal) const; + /** + Reads a bool value, returning @true if the value was found. If the + value was not found, @a b is not changed. + */ + const bool Read(const wxString& key, bool* b) const; + /** + Reads a bool value, returning @true if the value was found. If the + value was not found, @a defaultVal is used instead. + */ + const bool Read(const wxString& key, bool* d, + bool defaultVal) const; + /** + Reads a binary block, returning @true if the value was found. If the + value was not found, @a buf is not changed. + */ + const bool Read(const wxString& key, wxMemoryBuffer* buf) const; + /** + Reads a value of type T, for which function wxFromString() is defined, + returning @true if the value was found. If the value was not found, + @a value is not changed. + */ + const bool Read(const wxString& key, T* value) const; + /** + Reads a value of type T, for which function wxFromString() is defined, + returning @true if the value was found. If the value was not found, + @a defaultVal is used instead. + */ + const bool Read(const wxString& key, T* value, + const T& defaultVal) const; + + /** + Reads a bool value from the key and returns it. @a defaultVal is + returned if the key is not found. + */ + long ReadBool(const wxString& key, bool defaultVal) const; + + /** + Reads a double value from the key and returns it. @a defaultVal is + returned if the key is not found. + */ + long ReadDouble(const wxString& key, double defaultVal) const; + + /** + Reads a long value from the key and returns it. @a defaultVal is + returned if the key is not found. + */ + long ReadLong(const wxString& key, long defaultVal) const; + + /** + Reads a value of type T (for which the function wxFromString() must be + defined) from the key and returns it. @a defaultVal is returned if the + key is not found. + */ + T ReadObject(const wxString& key, T const& defaultVal) const; + + /** + Writes the wxString value to the config file and returns @true on + success. + */ + bool Write(const wxString& key, const wxString& value); + /** + Writes the long value to the config file and returns @true on success. + */ + bool Write(const wxString& key, long value); + /** + Writes the double value to the config file and returns @true on + success. + */ + bool Write(const wxString& key, double value); + /** + Writes the bool value to the config file and returns @true on success. + */ + bool Write(const wxString& key, bool value); + /** + Writes the wxMemoryBuffer value to the config file and returns @true on + success. + */ + bool Write(const wxString& key, const wxMemoryBuffer& buf); + /** + Writes the specified value to the config file and returns @true on + success. The function wxToString() must be defined for type @e T. + */ + bool Write(const wxString& key, T const& buf); + + //@} + + + /** + @name Rename Entries/Groups + + These functions allow renaming entries or subgroups of the current + group. They will return @false on error, typically because either the + entry/group with the original name doesn't exist, because the + entry/group with the new name already exists or because the function is + not supported in this wxConfig implementation. + */ + //@{ + + /** + Renames an entry in the current group. The entries names (both the old + and the new one) shouldn't contain backslashes, i.e. only simple names + and not arbitrary paths are accepted by this function. + + @return @false if @a oldName doesn't exist or if @a newName already + exists. + */ + bool RenameEntry(const wxString& oldName, const wxString& newName); + + /** + Renames a subgroup of the current group. The subgroup names (both the + old and the new one) shouldn't contain backslashes, i.e. only simple + names and not arbitrary paths are accepted by this function. + + @return @false if @a oldName doesn't exist or if @a newName already + exists. + */ + bool RenameGroup(const wxString& oldName, const wxString& newName); + + //@} + + + /** + @name Delete Entries/Groups + + These functions delete entries and/or groups of entries from the config + file. DeleteAll() is especially useful if you want to erase all traces + of your program presence: for example, when you uninstall it. + */ + //@{ + + /** + Delete the whole underlying object (disk file, registry key, ...). + Primarly for use by uninstallation routine. + */ + bool DeleteAll(); + + /** + Deletes the specified entry and the group it belongs to if it was the + last key in it and the second parameter is @true. + */ + bool DeleteEntry(const wxString& key, + bool bDeleteGroupIfEmpty = true); + + /** + Delete the group (with all subgroups). If the current path is under the + group being deleted it is changed to its deepest still existing + component. E.g. if the current path is @c "/A/B/C/D" and the group @c C + is deleted, the path becomes @c "/A/B". + */ + bool DeleteGroup(const wxString& key); + + //@} + + + /** + @name Options + + Some aspects of wxConfigBase behaviour can be changed during run-time. + The first of them is the expansion of environment variables in the + string values read from the config file: for example, if you have the + following in your config file: + + @code + # config file for my program + UserData = $HOME/data + + # the following syntax is valud only under Windows + UserData = %windir%\\data.dat + @endcode + + The call to Read("UserData") will return something like + @c "/home/zeitlin/data" on linux for example. + + Although this feature is very useful, it may be annoying if you read a + value which containts '$' or '%' symbols (% is used for environment + variables expansion under Windows) which are not used for environment + variable expansion. In this situation you may call + SetExpandEnvVars(@false) just before reading this value and + SetExpandEnvVars(@true) just after. Another solution would be to prefix + the offending symbols with a backslash. + */ + //@{ + + /** + Returns @true if we are expanding environment variables in key values. + */ + bool IsExpandingEnvVars() const; + + /** + Returns @true if we are writing defaults back to the config file. + */ + bool IsRecordingDefaults() const; + + /** + Determine whether we wish to expand environment variables in key + values. + */ + void SetExpandEnvVars(bool bDoIt = true); + + /** + Sets whether defaults are recorded to the config file whenever an + attempt to read the value which is not present in it is done. + + If on (default is off) all default values for the settings used by the + program are written back to the config file. This allows the user to + see what config options may be changed and is probably useful only for + wxFileConfig. + */ + void SetRecordDefaults(bool bDoIt = true); + + //@} + + + /** + Create a new config object: this function will create the "best" + implementation of wxConfig available for the current platform, see + comments near the definition of wxCONFIG_WIN32_NATIVE for details. It + returns the created object and also sets it as the current one. + */ + static wxConfigBase* Create(); + + /** + Calling this function will prevent @e Get() from automatically creating + a new config object if the current one is @NULL. It might be useful to + call it near the program end to prevent "accidental" creation of a new + config object. + */ + static void DontCreateOnDemand(); + + /** + Get the current config object. If there is no current object and + @a CreateOnDemand is @true, this creates one (using Create()) unless + DontCreateOnDemand() was called previously. + */ + static wxConfigBase* Get(bool CreateOnDemand = true); + + /** + Sets the config object as the current one, returns the pointer to the + previous current object (both the parameter and returned value may be + @NULL). + */ + static wxConfigBase* Set(wxConfigBase* pConfig); +}; + diff --git a/interface/wx/control.h b/interface/wx/control.h new file mode 100644 index 0000000000..2a9f824059 --- /dev/null +++ b/interface/wx/control.h @@ -0,0 +1,62 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: control.h +// Purpose: interface of wxControl +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxControl + @wxheader{control.h} + + This is the base class for a control or "widget". + + A control is generally a small window which processes user input and/or + displays one or more item of data. + + @library{wxcore} + @category{ctrl} + + @see wxValidator +*/ +class wxControl : public wxWindow +{ +public: + /** + Simulates the effect of the user issuing a command to the item. + + @see wxCommandEvent + */ + void Command(wxCommandEvent& event); + + /** + Returns the control's text. + + @note The returned string contains mnemonics ("&" characters) if it has + any, use GetLabelText() if they are undesired. + */ + wxString GetLabel() const; + + /** + Returns the control's label without mnemonics. + */ + const wxString GetLabelText(); + + /** + Returns the given @a label string without mnemonics. + */ + static wxString GetLabelText(const wxString& label); + + /** + Sets the item's text. + + Any "&" characters in the @a label are special and indicate that the + following character is a mnemonic for this control and can be used to + activate it from the keyboard (typically by using @e Alt key in + combination with it). To insert a literal ampersand character, you need + to double it, i.e. use "&&". + */ + void SetLabel(const wxString& label); +}; + diff --git a/interface/wx/convauto.h b/interface/wx/convauto.h new file mode 100644 index 0000000000..2de565d473 --- /dev/null +++ b/interface/wx/convauto.h @@ -0,0 +1,97 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: convauto.h +// Purpose: interface of wxConvAuto +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxConvAuto + @wxheader{convauto.h} + + This class implements a Unicode to/from multibyte converter capable of + automatically recognizing the encoding of the multibyte text on input. The + logic used is very simple: the class uses the BOM (byte order mark) if it's + present and tries to interpret the input as UTF-8 otherwise. If this fails, + the input is interpreted as being in the default multibyte encoding which + can be specified in the constructor of a wxConvAuto instance and, in turn, + defaults to the value of GetFallbackEncoding() if not explicitly given. + + For the conversion from Unicode to multibyte, the same encoding as was + previously used for multibyte to Unicode conversion is reused. If there had + been no previous multibyte to Unicode conversion, UTF-8 is used by default. + Notice that once the multibyte encoding is automatically detected, it + doesn't change any more, i.e. it is entirely determined by the first use of + wxConvAuto object in the multibyte-to-Unicode direction. However creating a + copy of wxConvAuto object, either via the usual copy constructor or + assignment operator, or using wxMBConv::Clone(), resets the automatically + detected encoding so that the new copy will try to detect the encoding of + the input on first use. + + This class is used by default in wxWidgets classes and functions reading + text from files such as wxFile, wxFFile, wxTextFile, wxFileConfig and + various stream classes so the encoding set with its SetFallbackEncoding() + method will affect how these classes treat input files. In particular, use + this method to change the fall-back multibyte encoding used to interpret + the contents of the files whose contents isn't valid UTF-8 or to disallow + it completely. + + @library{wxbase} + @category{data} + + @see @ref overview_mbconv +*/ +class wxConvAuto : public wxMBConv +{ +public: + /** + Constructs a new wxConvAuto instance. The object will try to detect the + input of the multibyte text given to its wxMBConv::ToWChar() method + automatically but if the automatic detection of Unicode encodings + fails, the fall-back encoding @a enc will be used to interpret it as + multibyte text. + + The default value of @a enc, @c wxFONTENCODING_DEFAULT, means that the + global default value (which can be set using SetFallbackEncoding()) + should be used. As with that method, passing @c wxFONTENCODING_MAX + inhibits using this encoding completely so the input multibyte text + will always be interpreted as UTF-8 in the absence of BOM and the + conversion will fail if the input doesn't form valid UTF-8 sequence. + + Another special value is @c wxFONTENCODING_SYSTEM which means to use + the encoding currently used on the user system, i.e. the encoding + returned by wxLocale::GetSystemEncoding(). Any other encoding will be + used as is, e.g. passing @c wxFONTENCODING_ISO8859_1 ensures that + non-UTF-8 input will be treated as latin1. + */ + wxConvAuto(wxFontEncoding enc = wxFONTENCODING_DEFAULT); + + /** + Disable the use of the fall back encoding: if the input doesn't have a + BOM and is not valid UTF-8, the conversion will fail. + */ + static void DisableFallbackEncoding(); + + /** + Returns the encoding used by default by wxConvAuto if no other encoding + is explicitly specified in constructor. By default, returns + @c wxFONTENCODING_ISO8859_1 but can be changed using + SetFallbackEncoding(). + */ + static wxFontEncoding GetFallbackEncoding(); + + /** + Changes the encoding used by default by wxConvAuto if no other encoding + is explicitly specified in constructor. The default value, which can be + retrieved using GetFallbackEncoding(), is @c wxFONTENCODING_ISO8859_1. + + Special values of @c wxFONTENCODING_SYSTEM or @c wxFONTENCODING_MAX can + be used for the @a enc parameter to use the encoding of the current + user locale as fall back or not use any encoding for fall back at all, + respectively (just as with the similar constructor parameter). However, + @c wxFONTENCODING_DEFAULT can't be used here. + */ + static void SetFallbackEncoding(wxFontEncoding enc); +}; + diff --git a/interface/wx/cpp.h b/interface/wx/cpp.h new file mode 100644 index 0000000000..b8585c519c --- /dev/null +++ b/interface/wx/cpp.h @@ -0,0 +1,52 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: cpp.h +// Purpose: interface of global functions +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + + +/** @ingroup group_funcmacro_misc */ +//@{ +/** + This macro returns the concatenation of the arguments passed. Unlike when + using the preprocessor operator, the arguments undergo macro expansion + before being concatenated. + + @header{wx/cpp.h} +*/ +#define wxCONCAT(x1, x2) +#define wxCONCAT3(x1, x2, x3) +#define wxCONCAT4(x1, x2, x3, x4) +#define wxCONCAT5(x1, x2, x3, x4, x5) +//@} + +/** @ingroup group_funcmacro_misc */ +//@{ + +/** + Returns the string representation of the given symbol which can be either a + literal or a macro (hence the advantage of using this macro instead of the + standard preprocessor @c # operator which doesn't work with macros). + + Notice that this macro always produces a @c char string, use + wxSTRINGIZE_T() to build a wide string Unicode build. + + @see wxCONCAT() + + @header{wx/cpp.h} +*/ +#define wxSTRINGIZE(x) + +/** + Returns the string representation of the given symbol as either an ASCII or + Unicode string, depending on the current build. This is the + Unicode-friendly equivalent of wxSTRINGIZE(). + + @header{wx/cpp.h} +*/ +#define wxSTRINGIZE_T(x) + +//@} + diff --git a/interface/wx/cshelp.h b/interface/wx/cshelp.h new file mode 100644 index 0000000000..e727f54a71 --- /dev/null +++ b/interface/wx/cshelp.h @@ -0,0 +1,301 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: cshelp.h +// Purpose: interface of wxHelpProvider +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxHelpProvider + @wxheader{cshelp.h} + + wxHelpProvider is an abstract class used by a program implementing + context-sensitive help to show the help text for the given window. + + The current help provider must be explicitly set by the application using + Set(). + + @library{wxcore} + @category{help} + + @see wxContextHelp, wxContextHelpButton, wxSimpleHelpProvider, + wxHelpControllerHelpProvider, wxWindow::SetHelpText(), + wxWindow::GetHelpTextAtPoint() +*/ +class wxHelpProvider +{ +public: + /** + Virtual destructor for any base class. + */ + virtual ~wxHelpProvider(); + + /** + Associates the text with the given window. + + @remarks + Although all help providers have these functions to allow making + wxWindow::SetHelpText() work, not all of them implement the functions. + */ + virtual void AddHelp(wxWindowBase* window, const wxString& text); + + /** + Associates the text with the given ID. + + This help text will be shown for all windows with ID @a id, unless they + have more specific help text associated using the other AddHelp() + prototype. May be used to set the same help string for all Cancel + buttons in the application, for example. + + @remarks + Although all help providers have these functions to allow making + wxWindow::SetHelpText() work, not all of them implement the functions. + */ + virtual void AddHelp(wxWindowID id, const wxString& text); + + /** + Returns pointer to help provider instance. + + Unlike some other classes, the help provider is not created on demand. + This must be explicitly done by the application using Set(). + */ + static wxHelpProvider* Get(); + + /** + This version associates the given text with all windows with this id. + May be used to set the same help string for all Cancel buttons in + the application, for example. + */ + virtual wxString GetHelp(const wxWindowBase* window); + + /** + Removes the association between the window pointer and the help text. + This is called by the wxWindow destructor. Without this, the table of + help strings will fill up and when window pointers are reused, the + wrong help string will be found. + */ + virtual void RemoveHelp(wxWindowBase* window); + + /** + Set the current, application-wide help provider. + + @return Pointer to previous help provider or @NULL if there wasn't any. + */ + static wxHelpProvider* Set(wxHelpProvider* helpProvider); + + /** + Shows help for the given window. + + Override this function if the help doesn't depend on the exact position + inside the window, otherwise you need to override ShowHelpAtPoint(). + Returns @true if help was shown, or @false if no help was available for + this window. + */ + virtual bool ShowHelp(wxWindowBase* window); + + /** + This function may be overridden to show help for the window when it + should depend on the position inside the window, By default this method + forwards to ShowHelp(), so it is enough to only implement the latter if + the help doesn't depend on the position. + + @param window + Window to show help text for. + @param point + Coordinates of the mouse at the moment of help event emission. + @param origin + Help event origin, see wxHelpEvent::GetOrigin. + + @return @true if help was shown, or @false if no help was available + for this window. + + @since 2.7.0 + */ + virtual bool ShowHelpAtPoint(wxWindowBase* window, const wxPoint point, + wxHelpEvent::Origin origin); +}; + + + +/** + @class wxHelpControllerHelpProvider + @wxheader{cshelp.h} + + wxHelpControllerHelpProvider is an implementation of wxHelpProvider which + supports both context identifiers and plain text help strings. If the help + text is an integer, it is passed to wxHelpController::DisplayContextPopup(). + Otherwise, it shows the string in a tooltip as per wxSimpleHelpProvider. If + you use this with a wxCHMHelpController instance on windows, it will use + the native style of tip window instead of wxTipWindow. + + You can use the convenience function wxContextId() to convert an integer + context id to a string for passing to wxWindow::SetHelpText(). + + @library{wxcore} + @category{help} + + @see wxHelpProvider, wxSimpleHelpProvider, wxContextHelp, + wxWindow::SetHelpText(), wxWindow::GetHelpTextAtPoint() +*/ +class wxHelpControllerHelpProvider : public wxSimpleHelpProvider +{ +public: + /** + Note that the instance doesn't own the help controller. The help + controller should be deleted separately. + */ + wxHelpControllerHelpProvider(wxHelpControllerBase* hc = NULL); + + /** + Returns the help controller associated with this help provider. + */ + wxHelpControllerBase* GetHelpController() const; + + /** + Sets the help controller associated with this help provider. + */ + void SetHelpController(wxHelpControllerBase* hc); +}; + + + +/** + @class wxContextHelp + @wxheader{cshelp.h} + + This class changes the cursor to a query and puts the application into a + 'context-sensitive help mode'. When the user left-clicks on a window + within the specified window, a wxEVT_HELP event is sent to that control, + and the application may respond to it by popping up some help. + + For example: + @code + wxContextHelp contextHelp(myWindow); + @endcode + + There are a couple of ways to invoke this behaviour implicitly: + + - Use the wxDIALOG_EX_CONTEXTHELP style for a dialog (Windows only). This + will put a question mark in the titlebar, and Windows will put the + application into context-sensitive help mode automatically, with further + programming. + + - Create a wxContextHelpButton, whose predefined behaviour is + to create a context help object. Normally you will write your application + so that this button is only added to a dialog for non-Windows platforms + (use wxDIALOG_EX_CONTEXTHELP on Windows). + + Note that on Mac OS X, the cursor does not change when in context-sensitive + help mode. + + @library{wxcore} + @category{help} + + @see wxHelpEvent, wxHelpController, wxContextHelpButton +*/ +class wxContextHelp : public wxObject +{ +public: + /** + Constructs a context help object, calling BeginContextHelp() if + @a doNow is @true (the default). + + If @a window is @NULL, the top window is used. + */ + wxContextHelp(wxWindow* window = NULL, bool doNow = true); + + /** + Destroys the context help object. + */ + ~wxContextHelp(); + + /** + Puts the application into context-sensitive help mode. @a window is the + window which will be used to catch events; if @NULL, the top window + will be used. Returns @true if the application was successfully put + into context-sensitive help mode. This function only returns when the + event loop has finished. + */ + bool BeginContextHelp(wxWindow* window = NULL); + + /** + Ends context-sensitive help mode. Not normally called by the + application. + */ + bool EndContextHelp(); +}; + + + +/** + @class wxContextHelpButton + @wxheader{cshelp.h} + + Instances of this class may be used to add a question mark button that when + pressed, puts the application into context-help mode. It does this by + creating a wxContextHelp object which itself generates a wxEVT_HELP event + when the user clicks on a window. + + On Windows, you may add a question-mark icon to a dialog by use of the + wxDIALOG_EX_CONTEXTHELP extra style, but on other platforms you will have + to add a button explicitly, usually next to OK, Cancel or similar buttons. + + @library{wxcore} + @category{help} + + @see wxBitmapButton, wxContextHelp +*/ +class wxContextHelpButton : public wxBitmapButton +{ +public: + /// Default constructor. + wxContextHelpButton(); + + /** + Constructor, creating and showing a context help button. + + @param parent + Parent window. Must not be @NULL. + @param id + Button identifier. Defaults to wxID_CONTEXT_HELP. + @param pos + Button position. + @param size + Button size. If wxDefaultSize is specified then the button is sized + appropriately for the question mark bitmap. + @param style + Window style. + + @remarks + Normally you only need pass the parent window to the constructor, and + use the defaults for the remaining parameters. + */ + wxContextHelpButton(wxWindow* parent, + wxWindowID id = wxID_CONTEXT_HELP, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxBU_AUTODRAW); +}; + + +/** + @class wxSimpleHelpProvider + @wxheader{cshelp.h} + + wxSimpleHelpProvider is an implementation of wxHelpProvider which supports + only plain text help strings, and shows the string associated with the + control (if any) in a tooltip. + + @library{wxcore} + @category{help} + + @see wxHelpProvider, wxHelpControllerHelpProvider, wxContextHelp, + wxWindow::SetHelpText()(, wxWindow::GetHelpTextAtPoint() +*/ +class wxSimpleHelpProvider : public wxHelpProvider +{ +public: + +}; + diff --git a/interface/wx/ctrlsub.h b/interface/wx/ctrlsub.h new file mode 100644 index 0000000000..f540761470 --- /dev/null +++ b/interface/wx/ctrlsub.h @@ -0,0 +1,665 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: ctrlsub.h +// Purpose: interface of wxControlWithItems +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + + +/** + @class wxItemContainerImmutable + @wxheader{ctrlsub.h} + + wxItemContainer defines an interface which is implemented by all controls + which have string subitems each of which may be selected. + + It is decomposed in wxItemContainerImmutable which omits all methods + adding/removing items and is used by wxRadioBox and wxItemContainer itself. + + Note that this is not a control, it's a mixin interface that classes + have to derive from in addition to wxControl or wxWindow. + + Examples: wxListBox, wxCheckListBox, wxChoice and wxComboBox (which + implements an extended interface deriving from this one) + + @library{wxcore} + @category{ctrl} + + @see wxControlWithItems, wxItemContainer +*/ +class wxItemContainerImmutable +{ +public: + /// Constructor + wxItemContainerImmutable(); + + //@{ + + /** + Returns the number of items in the control. + + @see IsEmpty() + */ + virtual unsigned int GetCount() const; + + /** + Returns @true if the control is empty or @false if it has some items. + + @see GetCount() + */ + bool IsEmpty() const; + + /** + Returns the label of the item with the given index. + + @param n + The zero-based index. + + @return The label of the item or an empty string if the position was + invalid. + */ + virtual wxString GetString(unsigned int n) const; + + /** + Returns the array of the labels of all items in the control. + */ + wxArrayString GetStrings() const; + + /** + Sets the label for the given item. + + @param n + The zero-based item index. + @param string + The label to set. + */ + virtual void SetString(unsigned int n, const wxString& s); + + /** + Finds an item whose label matches the given string. + + @param string + String to find. + @param caseSensitive + Whether search is case sensitive (default is not). + + @return The zero-based position of the item, or wxNOT_FOUND if the + string was not found. + */ + virtual int FindString(const wxString& s, bool bCase = false) const; + + //@} + + /// @name Selection + //@{ + + /** + Sets the selection to the given item @a n or removes the selection + entirely if @a n == @c wxNOT_FOUND. + + Note that this does not cause any command events to be emitted nor does + it deselect any other items in the controls which support multiple + selections. + + @param n + The string position to select, starting from zero. + + @see SetString(), SetStringSelection() + */ + virtual void SetSelection(int n); + + /** + Returns the index of the selected item or @c wxNOT_FOUND if no item is + selected. + + @return The position of the current selection. + + @remarks This method can be used with single selection list boxes only, + you should use wxListBox::GetSelections() for the list + boxes with wxLB_MULTIPLE style. + + @see SetSelection(), GetStringSelection() + */ + virtual int GetSelection() const; + + /** + Selects the item with the specified string in the control. This doesn't + cause any command events to be emitted. + + @param string + The string to select. + + @return @true if the specified string has been selected, @false if it + wasn't found in the control. + */ + bool SetStringSelection(const wxString& string); + + /** + Returns the label of the selected item or an empty string if no item is + selected. + + @see GetSelection() + */ + virtual wxString GetStringSelection() const; + + /** + This is the same as SetSelection() and exists only because it is + slightly more natural for controls which support multiple selection. + */ + void Select(int n); + + //@} +}; + + +/** + @class wxItemContainer + @wxheader{ctrlsub.h} + + This class is an abstract base class for some wxWidgets controls which + contain several items such as wxListBox, wxCheckListBox, wxComboBox or + wxChoice. It defines an interface which is implemented by all controls + which have string subitems each of which may be selected. + + wxItemContainer extends wxItemContainerImmutable interface with methods + for adding/removing items. + + It defines the methods for accessing the controls items and although each + of the derived classes implements them differently, they still all conform + to the same interface. + + The items in a wxItemContainer have (non-empty) string labels and, + optionally, client data associated with them. Client data may be of two + different kinds: either simple untyped (@c void *) pointers which are + simply stored by the control but not used in any way by it, or typed + pointers (wxClientData*) which are owned by the control meaning that the + typed client data (and only it) will be deleted when an item is deleted + using Delete() or the entire control is cleared using Clear(), which also + happens when it is destroyed. + + Finally note that in the same control all items must have client data of + the same type (typed or untyped), if any. This type is determined by the + first call to Append() (the version with client data pointer) or + SetClientData(). + + Note that this is not a control, it's a mixin interface that classes + have to derive from in addition to wxControl or wxWindow. Convenience + class wxControlWithItems is provided for this purpose. + + @library{wxcore} + @category{ctrl} + + @see wxControlWithItems, wxItemContainerImmutable +*/ +class wxItemContainer : public wxItemContainerImmutable +{ +public: + //@{ + + /** + Appends item into the control. + + @param item + String to add. + + @return The return value is the index of the newly inserted item. + Note that this may be different from the last one if the + control is sorted (e.g. has @c wxLB_SORT or @c wxCB_SORT + style). + */ + int Append(const wxString& item); + + /** + Appends item into the control. + + @param item + String to add. + @param clientData + Pointer to client data to associate with the new item. + + @return The return value is the index of the newly inserted item. + Note that this may be different from the last one if the + control is sorted (e.g. has @c wxLB_SORT or @c wxCB_SORT + style). + */ + int Append(const wxString& item, void* clientData); + + /** + Appends item into the control. + + @param item + String to add. + @param clientData + Pointer to client data to associate with the new item. + + @return The return value is the index of the newly inserted item. + Note that this may be different from the last one if the + control is sorted (e.g. has @c wxLB_SORT or @c wxCB_SORT + style). + */ + int Append(const wxString& item, wxClientData* clientData); + + /** + Appends several items at once into the control. + + Notice that calling this method is usually much faster than appending + them one by one if you need to add a lot of items. + + @param items + Array of strings to insert. + */ + void Append(const wxArrayString& items); + + /** + Appends several items at once into the control. + + Notice that calling this method is usually much faster than appending + them one by one if you need to add a lot of items. + + @param items + Array of strings to insert. + @param clientData + Array of client data pointers of the same size as @a items to + associate with the new items. + */ + void Append(const wxArrayString& items, void **clientData); + + /** + Appends several items at once into the control. + + Notice that calling this method is usually much faster than appending + them one by one if you need to add a lot of items. + + @param items + Array of strings to insert. + @param clientData + Array of client data pointers of the same size as @a items to + associate with the new items. + */ + void Append(const wxArrayString& items, wxClientData **clientData); + + /** + Appends several items at once into the control. + + Notice that calling this method is usually much faster than appending + them one by one if you need to add a lot of items. + + @param n + Number of items in the @a items array. + @param items + Array of strings of size @a n. + */ + void Append(unsigned int n, const wxString* items); + + /** + Appends several items at once into the control. + + Notice that calling this method is usually much faster than appending + them one by one if you need to add a lot of items. + + @param n + Number of items in the @a items array. + @param items + Array of strings of size @a n. + @param clientData + Array of client data pointers of size @a n to associate with the + new items. + */ + void Append(unsigned int n, const wxString* items, + void** clientData); + + /** + Appends several items at once into the control. + + Notice that calling this method is usually much faster than appending + them one by one if you need to add a lot of items. + + @param n + Number of items in the @a items array. + @param items + Array of strings of size @a n. + @param clientData + Array of client data pointers of size @a n to associate with the + new items. + */ + void Append(unsigned int n, const wxString* items, + wxClientData** clientData); + //@} + + /** + Removes all items from the control. + Clear() also deletes the client data of the existing items if it is + owned by the control. + */ + void Clear(); + + /** + Deletes an item from the control. + + The client data associated with the item will be also deleted if it is + owned by the control. Note that it is an error (signalled by an assert + failure in debug builds) to remove an item with the index negative or + greater or equal than the number of items in the control. + + @param n + The zero-based item index. + + @see Clear() + */ + void Delete(unsigned int n); + + //@{ + + /** + Returns a pointer to the client data associated with the given item (if + any). It is an error to call this function for a control which doesn't + have untyped client data at all although it is OK to call it even if + the given item doesn't have any client data associated with it (but + other items do). + + @param n + The zero-based position of the item. + + @return A pointer to the client data, or @NULL if not present. + */ + void* GetClientData(unsigned int n) const; + + /** + Returns a pointer to the client data associated with the given item (if + any). It is an error to call this function for a control which doesn't + have typed client data at all although it is OK to call it even if the + given item doesn't have any client data associated with it (but other + items do). + + @param n + The zero-based position of the item. + + @return A pointer to the client data, or @NULL if not present. + */ + wxClientData* GetClientObject(unsigned int n) const; + + /** + Associates the given untyped client data pointer with the given item. + Note that it is an error to call this function if any typed client data + pointers had been associated with the control items before. + + @param n + The zero-based item index. + @param data + The client data to associate with the item. + */ + void SetClientData(unsigned int n, void* data); + + /** + Associates the given typed client data pointer with the given item: the + @a data object will be deleted when the item is deleted (either + explicitly by using Delete() or implicitly when the control itself is + destroyed). Note that it is an error to call this function if any + untyped client data pointers had been associated with the control items + before. + + @param n + The zero-based item index. + @param data + The client data to associate with the item. + */ + void SetClientObject(unsigned int n, wxClientData* data); + + //@} + + //@{ + + /** + Inserts item into the control. + + @param item + String to add. + @param pos + Position to insert item before, zero based. + + @return The return value is the index of the newly inserted item. + If the insertion failed for some reason, -1 is returned. + */ + int Insert(const wxString& item, unsigned int pos); + + /** + Inserts item into the control. + + @param item + String to add. + @param pos + Position to insert item before, zero based. + @param clientData + Pointer to client data to associate with the new item. + + @return The return value is the index of the newly inserted item. + If the insertion failed for some reason, -1 is returned. + */ + int Insert(const wxString& item, unsigned int pos, void* clientData); + + /** + Inserts item into the control. + + @param item + String to add. + @param pos + Position to insert item before, zero based. + @param clientData + Pointer to client data to associate with the new item. + + @return The return value is the index of the newly inserted item. + If the insertion failed for some reason, -1 is returned. + */ + int Insert(const wxString& item, unsigned int pos, + wxClientData* clientData); + + /** + Inserts several items at once into the control. + + Notice that calling this method is usually much faster than inserting + them one by one if you need to insert a lot of items. + + @param items + Array of strings to insert. + @param pos + Position to insert the items before, zero based. + */ + void Insert(const wxArrayString& items, unsigned int pos); + + /** + Inserts several items at once into the control. + + Notice that calling this method is usually much faster than inserting + them one by one if you need to insert a lot of items. + + @param items + Array of strings to insert. + @param pos + Position to insert the items before, zero based. + @param clientData + Array of client data pointers of the same size as @a items to + associate with the new items. + */ + void Insert(const wxArrayString& items, unsigned int pos, + void **clientData); + + /** + Inserts several items at once into the control. + + Notice that calling this method is usually much faster than inserting + them one by one if you need to insert a lot of items. + + @param items + Array of strings to insert. + @param pos + Position to insert the items before, zero based. + @param clientData + Array of client data pointers of the same size as @a items to + associate with the new items. + */ + void Insert(const wxArrayString& items, unsigned int pos, + wxClientData **clientData); + + /** + Inserts several items at once into the control. + + Notice that calling this method is usually much faster than inserting + them one by one if you need to insert a lot of items. + + @param n + Number of items in the @a items array. + @param items + Array of strings of size @a n. + @param pos + Position to insert the items before, zero based. + */ + void Insert(unsigned int n, const wxString* items, + unsigned int pos); + + /** + Inserts several items at once into the control. + + Notice that calling this method is usually much faster than inserting + them one by one if you need to insert a lot of items. + + @param n + Number of items in the @a items array. + @param items + Array of strings of size @a n. + @param pos + Position to insert the new items before, zero based. + @param clientData + Array of client data pointers of size @a n to associate with the + new items. + */ + void Insert(unsigned int n, const wxString* items, + unsigned int pos, + void** clientData); + + /** + Inserts several items at once into the control. + + Notice that calling this method is usually much faster than inserting + them one by one if you need to insert a lot of items. + + @param n + Number of items in the @a items array. + @param items + Array of strings of size @a n. + @param pos + Position to insert the new items before, zero based. + @param clientData + Array of client data pointers of size @a n to associate with the + new items. + */ + void Insert(unsigned int n, const wxString* items, + unsigned int pos, + wxClientData** clientData); + //@} + + //@{ + /** + Replaces the current control contents with the given items. + + Notice that calling this method is usually much faster than appending + them one by one if you need to add a lot of items. + + @param items + Array of strings to insert. + */ + void Set(const wxArrayString& items); + + /** + Replaces the current control contents with the given items. + + Notice that calling this method is usually much faster than appending + them one by one if you need to add a lot of items. + + @param items + Array of strings to insert. + @param clientData + Array of client data pointers of the same size as @a items to + associate with the new items. + */ + void Set(const wxArrayString& items, void **clientData); + + /** + Replaces the current control contents with the given items. + + Notice that calling this method is usually much faster than appending + them one by one if you need to add a lot of items. + + @param items + Array of strings to insert. + @param clientData + Array of client data pointers of the same size as @a items to + associate with the new items. + */ + void Set(const wxArrayString& items, wxClientData **clientData); + + /** + Replaces the current control contents with the given items. + + Notice that calling this method is usually much faster than appending + them one by one if you need to add a lot of items. + + @param n + Number of items in the @a items array. + @param items + Array of strings of size @a n. + */ + void Set(unsigned int n, const wxString* items); + + /** + Replaces the current control contents with the given items. + + Notice that calling this method is usually much faster than appending + them one by one if you need to add a lot of items. + + @param n + Number of items in the @a items array. + @param items + Array of strings of size @a n. + @param clientData + Array of client data pointers of size @a n to associate with the + new items. + */ + void Set(unsigned int n, const wxString* items, void** clientData); + + /** + Replaces the current control contents with the given items. + + Notice that calling this method is usually much faster than appending + them one by one if you need to add a lot of items. + + @param n + Number of items in the @a items array. + @param items + Array of strings of size @a n. + @param clientData + Array of client data pointers of size @a n to associate with the + new items. + */ + void Set(unsigned int n, const wxString* items, wxClientData** clientData); + //@} +}; + + +/** + @class wxControlWithItems + @wxheader{ctrlsub.h} + + This is convenience class that derives from both wxControl and + wxItemContainer. It is used as basis for some wxWidgets controls + (wxChoice and wxListBox). + + @library{wxcore} + @category{ctrl} + + @see wxItemContainer, wxItemContainerImmutable +*/ +class wxControlWithItems : public wxControl, public wxItemContainer +{ +}; + diff --git a/interface/wx/cursor.h b/interface/wx/cursor.h new file mode 100644 index 0000000000..7ffa1fdf10 --- /dev/null +++ b/interface/wx/cursor.h @@ -0,0 +1,220 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: cursor.h +// Purpose: interface of wxCursor +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxCursor + @wxheader{cursor.h} + + A cursor is a small bitmap usually used for denoting where the mouse + pointer is, with a picture that might indicate the interpretation of a + mouse click. As with icons, cursors in X and MS Windows are created in a + different manner. Therefore, separate cursors will be created for the + different environments. Platform-specific methods for creating a wxCursor + object are catered for, and this is an occasion where conditional + compilation will probably be required (see wxIcon for an example). + + A single cursor object may be used in many windows (any subwindow type). + The wxWidgets convention is to set the cursor for a window, as in X, rather + than to set it globally as in MS Windows, although a global wxSetCursor() + function is also available for MS Windows use. + + @section cursor_custom Creating a Custom Cursor + + The following is an example of creating a cursor from 32x32 bitmap data + (down_bits) and a mask (down_mask) where 1 is black and 0 is white for the + bits, and 1 is opaque and 0 is transparent for the mask. It works on + Windows and GTK+. + + @code + static char down_bits[] = { 255, 255, 255, 255, 31, + 255, 255, 255, 31, 255, 255, 255, 31, 255, 255, 255, + 31, 255, 255, 255, 31, 255, 255, 255, 31, 255, 255, + 255, 31, 255, 255, 255, 31, 255, 255, 255, 25, 243, + 255, 255, 19, 249, 255, 255, 7, 252, 255, 255, 15, 254, + 255, 255, 31, 255, 255, 255, 191, 255, 255, 255, 255, + 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, + 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, + 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, + 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, + 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, + 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, + 255 }; + + static char down_mask[] = { 240, 1, 0, 0, 240, 1, + 0, 0, 240, 1, 0, 0, 240, 1, 0, 0, 240, 1, 0, 0, 240, 1, + 0, 0, 240, 1, 0, 0, 240, 1, 0, 0, 255, 31, 0, 0, 255, + 31, 0, 0, 254, 15, 0, 0, 252, 7, 0, 0, 248, 3, 0, 0, + 240, 1, 0, 0, 224, 0, 0, 0, 64, 0, 0, 0, 0, 0, 0, 0, 0, + 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, + 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, + 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, + 0, 0, 0, 0, 0 }; + + #ifdef __WXMSW__ + wxBitmap down_bitmap(down_bits, 32, 32); + wxBitmap down_mask_bitmap(down_mask, 32, 32); + + down_bitmap.SetMask(new wxMask(down_mask_bitmap)); + wxImage down_image = down_bitmap.ConvertToImage(); + down_image.SetOption(wxIMAGE_OPTION_CUR_HOTSPOT_X, 6); + down_image.SetOption(wxIMAGE_OPTION_CUR_HOTSPOT_Y, 14); + wxCursor down_cursor = wxCursor(down_image); + #else + wxCursor down_cursor = wxCursor(down_bits, 32, 32, 6, 14, + down_mask, wxWHITE, wxBLACK); + #endif + @endcode + + @library{wxcore} + @category{gdi} + + @stdobjects + - ::wxNullCursor + - ::wxSTANDARD_CURSOR + - ::wxHOURGLASS_CURSOR + - ::wxCROSS_CURSOR + + @see wxBitmap, wxIcon, wxWindow::SetCursor(), wxSetCursor(), + ::wxStockCursor +*/ +class wxCursor : public wxBitmap +{ +public: + /** + Default constructor. + */ + wxCursor(); + /** + Constructs a cursor by passing an array of bits (Motif and GTK+ only). + @a maskBits is used only under Motif and GTK+. The parameters @a fg and + @a bg are only present on GTK+, and force the cursor to use particular + background and foreground colours. + + If either @a hotSpotX or @a hotSpotY is -1, the hotspot will be the + centre of the cursor image (Motif only). + + @param bits + An array of bits. + @param maskBits + Bits for a mask bitmap. + @param width + Cursor width. + @param height + Cursor height. + @param hotSpotX + Hotspot x coordinate. + @param hotSpotY + Hotspot y coordinate. + */ + wxCursor(const char bits[], int width, int height, + int hotSpotX = -1, int hotSpotY = -1, + const char maskBits[] = NULL, + wxColour* fg = NULL, wxColour* bg = NULL); + /** + Constructs a cursor by passing a string resource name or filename. + + On MacOS when specifying a string resource name, first the color + cursors 'crsr' and then the black/white cursors 'CURS' in the resource + chain are scanned through. + + @a hotSpotX and @a hotSpotY are currently only used under Windows when + loading from an icon file, to specify the cursor hotspot relative to + the top left of the image. + + @param type + Icon type to load. Under Motif, type defaults to wxBITMAP_TYPE_XBM. + Under Windows, it defaults to wxBITMAP_TYPE_CUR_RESOURCE. Under + MacOS, it defaults to wxBITMAP_TYPE_MACCURSOR_RESOURCE. + Under X, the permitted cursor types are: +
    +
  • wxBITMAP_TYPE_XBM - Load an X bitmap file.
    • +
+ Under Windows, the permitted types are: + - wxBITMAP_TYPE_CUR - Load a cursor from a .cur cursor file (only + if USE_RESOURCE_LOADING_IN_MSW is enabled in + setup.h). + - wxBITMAP_TYPE_CUR_RESOURCE - Load a Windows resource (as + specified in the .rc file). + - wxBITMAP_TYPE_ICO - Load a cursor from a .ico icon file (only if + USE_RESOURCE_LOADING_IN_MSW is enabled in + setup.h). Specify @a hotSpotX and @a hotSpotY. + @param hotSpotX + Hotspot x coordinate. + @param hotSpotY + Hotspot y coordinate. + */ + wxCursor(const wxString& cursorName, long type, + int hotSpotX = 0, int hotSpotY = 0); + /** + Constructs a cursor using a cursor identifier. + + @param cursorId + A stock cursor identifier. See ::wxStockCursor. + */ + wxCursor(wxStockCursor cursorId); + /** + Constructs a cursor from a wxImage. If cursor are monochrome on the + current platform, colors with the RGB elements all greater than 127 + will be foreground, colors less than this background. The mask (if any) + will be used to specify the transparent area. + + In wxMSW the foreground will be white and the background black. If the + cursor is larger than 32x32 it is resized. + + In wxGTK, colour cursors and alpha channel are supported (starting from + GTK+ 2.2). Otherwise the two most frequent colors will be used for + foreground and background. In any case, the cursor will be displayed at + the size of the image. + + In wxMac, if the cursor is larger than 16x16 it is resized and + currently only shown as black/white (mask respected). + */ + wxCursor(const wxImage& image); + /** + Copy constructor, uses @ref overview_refcount "reference counting". + + @param cursor + Pointer or reference to a cursor to copy. + */ + wxCursor(const wxCursor& cursor); + + /** + Destroys the cursor. See + @ref overview_refcount_destruct "reference-counted object destruction" + for more info. + + A cursor can be reused for more than one window, and does not get + destroyed when the window is destroyed. wxWidgets destroys all cursors + on application exit, although it is best to clean them up explicitly. + */ + ~wxCursor(); + + /** + Returns @true if cursor data is present. + */ + bool IsOk() const; + + /** + Assignment operator, using @ref overview_refcount "reference counting". + */ + wxCursor operator =(const wxCursor& cursor); +}; + + +/** + @name Predefined cursors. + + @see wxStockCursor +*/ +//@{ +wxCursor wxNullCursor; +wxCursor* wxSTANDARD_CURSOR; +wxCursor* wxHOURGLASS_CURSOR; +wxCursor* wxCROSS_CURSOR; +//@} + diff --git a/interface/wx/dataobj.h b/interface/wx/dataobj.h new file mode 100644 index 0000000000..fd5035b5ee --- /dev/null +++ b/interface/wx/dataobj.h @@ -0,0 +1,705 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: dataobj.h +// Purpose: interface of wx*DataObject +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxCustomDataObject + @wxheader{dataobj.h} + + wxCustomDataObject is a specialization of wxDataObjectSimple for some + application-specific data in arbitrary (either custom or one of the + standard ones). The only restriction is that it is supposed that this data + can be copied bitwise (i.e. with @c memcpy()), so it would be a bad idea to + make it contain a C++ object (though C struct is fine). + + By default, wxCustomDataObject stores the data inside in a buffer. To put + the data into the buffer you may use either SetData() or TakeData() + depending on whether you want the object to make a copy of data or not. + + This class may be used as is, but if you don't want store the data inside + the object but provide it on demand instead, you should override GetSize(), + GetData() and SetData() (or may be only the first two or only the last one + if you only allow reading/writing the data). + + @library{wxcore} + @category{dnd} + + @see wxDataObject +*/ +class wxCustomDataObject : public wxDataObjectSimple +{ +public: + /** + The constructor accepts a @a format argument which specifies the + (single) format supported by this object. If it isn't set here, + wxDataObjectSimple::SetFormat() should be used. + */ + wxCustomDataObject(const wxDataFormat& format = wxFormatInvalid); + + /** + The destructor will free the data held by the object. Notice that + although it calls the virtual Free() function, the base class version + will always be called (C++ doesn't allow calling virtual functions from + constructors or destructors), so if you override Free(), you should + override the destructor in your class as well (which would probably + just call the derived class' version of Free()). + */ + virtual ~wxCustomDataObject(); + + /** + This function is called to allocate @a size bytes of memory from + SetData(). The default version just uses the operator new. + */ + virtual void* Alloc(size_t size); + + /** + This function is called when the data is freed, you may override it to + anything you want (or may be nothing at all). The default version calls + operator delete[] on the data. + */ + virtual void Free(); + + /** + Returns a pointer to the data. + */ + virtual void* GetData() const; + + /** + Returns the data size in bytes. + */ + virtual size_t GetSize() const; + + /** + Set the data. The data object will make an internal copy. + + @beginWxPythonOnly + This method expects a string in wxPython. You can pass nearly any + object by pickling it first. + @endWxPythonOnly + */ + virtual void SetData(size_t size, const void data); + + /** + Like SetData(), but doesn't copy the data - instead the object takes + ownership of the pointer. + + @beginWxPythonOnly + This method expects a string in wxPython. You can pass nearly any + object by pickling it first. + @endWxPythonOnly + */ + virtual void TakeData(size_t size, const void data); +}; + + + +/** + @class wxDataObjectComposite + @wxheader{dataobj.h} + + wxDataObjectComposite is the simplest wxDataObject derivation which may be + used to support multiple formats. It contains several wxDataObjectSimple + objects and supports any format supported by at least one of them. Only one + of these data objects is @e preferred (the first one if not explicitly + changed by using the second parameter of Add()) and its format determines + the preferred format of the composite data object as well. + + See wxDataObject documentation for the reasons why you might prefer to use + wxDataObject directly instead of wxDataObjectComposite for efficiency + reasons. + + @library{wxcore} + @category{dnd} + + @see @ref overview_dnd, wxDataObject, wxDataObjectSimple, wxFileDataObject, + wxTextDataObject, wxBitmapDataObject +*/ +class wxDataObjectComposite : public wxDataObject +{ +public: + /** + The default constructor. + */ + wxDataObjectComposite(); + + /** + Adds the @a dataObject to the list of supported objects and it becomes + the preferred object if @a preferred is @true. + */ + void Add(wxDataObjectSimple dataObject, bool preferred = false); + + /** + Report the format passed to the SetData() method. This should be the + format of the data object within the composite that recieved data from + the clipboard or the DnD operation. You can use this method to find + out what kind of data object was recieved. + */ + wxDataFormat GetReceivedFormat() const; +}; + + + +/** + @class wxDataObjectSimple + @wxheader{dataobj.h} + + This is the simplest possible implementation of the wxDataObject class. The + data object of (a class derived from) this class only supports one format, + so the number of virtual functions to be implemented is reduced. + + Notice that this is still an abstract base class and cannot be used + directly, it must be derived. The objects supporting rendering the data + must override GetDataSize() and GetDataHere() while the objects which may + be set must override SetData(). Of course, the objects supporting both + operations must override all three methods. + + @beginWxPythonOnly + If you wish to create a derived wxDataObjectSimple class in wxPython you + should derive the class from wxPyDataObjectSimple in order to get + Python-aware capabilities for the various virtual methods. + @endWxPythonOnly + + @beginWxPerlOnly + In wxPerl, you need to derive your data object class from + Wx::PlDataObjectSimple. + @endWxPerlOnly + + @library{wxcore} + @category{dnd} + + @see @ref overview_dnd, @ref page_samples_dnd, wxFileDataObject, + wxTextDataObject, wxBitmapDataObject +*/ +class wxDataObjectSimple : public wxDataObject +{ +public: + /** + Constructor accepts the supported format (none by default) which may + also be set later with SetFormat(). + */ + wxDataObjectSimple(const wxDataFormat& format = wxFormatInvalid); + + /** + Copy the data to the buffer, return @true on success. Must be + implemented in the derived class if the object supports rendering its + data. + + @beginWxPythonOnly + When implementing this method in wxPython, no additional parameters are + required and the data should be returned from the method as a string. + @endWxPythonOnly + */ + virtual bool GetDataHere(void buf) const; + + /** + Gets the size of our data. Must be implemented in the derived class if + the object supports rendering its data. + */ + virtual size_t GetDataSize() const; + + /** + Returns the (one and only one) format supported by this object. It is + assumed that the format is supported in both directions. + */ + const wxDataFormat GetFormat() const; + + /** + Copy the data from the buffer, return @true on success. Must be + implemented in the derived class if the object supports setting its + data. + + @beginWxPythonOnly + When implementing this method in wxPython, the data comes as a single + string parameter rather than the two shown here. + @endWxPythonOnly + */ + virtual bool SetData(size_t len, const void buf); + + /** + Sets the supported format. + */ + void SetFormat(const wxDataFormat& format); +}; + + + +/** + @class wxBitmapDataObject + @wxheader{dataobj.h} + + wxBitmapDataObject is a specialization of wxDataObject for bitmap data. It + can be used without change to paste data into the wxClipboard or a + wxDropSource. A user may wish to derive a new class from this class for + providing a bitmap on-demand in order to minimize memory consumption when + offering data in several formats, such as a bitmap and GIF. + + This class may be used as is, but GetBitmap() may be overridden to increase + efficiency. + + @beginWxPythonOnly + If you wish to create a derived wxBitmapDataObject class in wxPython you + should derive the class from wxPyBitmapDataObject in order to get + Python-aware capabilities for the various virtual methods. + @endWxPythonOnly + + @library{wxcore} + @category{dnd} + + @see @ref overview_dnd, wxDataObject, wxDataObjectSimple, wxFileDataObject, + wxTextDataObject, wxDataObject +*/ +class wxBitmapDataObject : public wxDataObjectSimple +{ +public: + /** + Constructor, optionally passing a bitmap (otherwise use SetBitmap() + later). + */ + wxBitmapDataObject(const wxBitmap& bitmap = wxNullBitmap); + + /** + Returns the bitmap associated with the data object. You may wish to + override this method when offering data on-demand, but this is not + required by wxWidgets' internals. Use this method to get data in bitmap + form from the wxClipboard. + */ + virtual wxBitmap GetBitmap() const; + + /** + Sets the bitmap associated with the data object. This method is called + when the data object receives data. Usually there will be no reason to + override this function. + */ + virtual void SetBitmap(const wxBitmap& bitmap); +}; + + + +/** + @class wxDataFormat + @wxheader{dataobj.h} + + A wxDataFormat is an encapsulation of a platform-specific format handle + which is used by the system for the clipboard and drag and drop operations. + The applications are usually only interested in, for example, pasting data + from the clipboard only if the data is in a format the program understands + and a data format is something which uniquely identifies this format. + + On the system level, a data format is usually just a number (@c CLIPFORMAT + under Windows or @c Atom under X11, for example) and the standard formats + are, indeed, just numbers which can be implicitly converted to wxDataFormat. + The standard formats are: + + @beginDefList + @itemdef{wxDF_INVALID, + An invalid format - used as default argument for functions taking + a wxDataFormat argument sometimes.} + @itemdef{wxDF_TEXT, + Text format (wxString).} + @itemdef{wxDF_BITMAP, + A bitmap (wxBitmap).} + @itemdef{wxDF_METAFILE, + A metafile (wxMetafile, Windows only).} + @itemdef{wxDF_FILENAME, + A list of filenames.} + @itemdef{wxDF_HTML, + An HTML string. This is only valid when passed to + wxSetClipboardData when compiled with Visual C++ in non-Unicode + mode.} + @endDefList + + As mentioned above, these standard formats may be passed to any function + taking wxDataFormat argument because wxDataFormat has an implicit + conversion from them (or, to be precise from the type + @c wxDataFormat::NativeFormat which is the type used by the underlying + platform for data formats). + + Aside the standard formats, the application may also use custom formats + which are identified by their names (strings) and not numeric identifiers. + Although internally custom format must be created (or @e registered) first, + you shouldn't care about it because it is done automatically the first time + the wxDataFormat object corresponding to a given format name is created. + The only implication of this is that you should avoid having global + wxDataFormat objects with non-default constructor because their + constructors are executed before the program has time to perform all + necessary initialisations and so an attempt to do clipboard format + registration at this time will usually lead to a crash! + + @library{wxbase} + @category{dnd} + + @see @ref overview_dnd, @ref page_samples_dnd, wxDataObject +*/ +class wxDataFormat +{ +public: + /** + Constructs a data format object for one of the standard data formats or + an empty data object (use SetType() or SetId() later in this case). + */ + wxDataFormat(NativeFormat format = wxDF_INVALID); + /** + Constructs a data format object for a custom format identified by its + name @a format. + */ + wxDataFormat(const wxChar format); + + /** + Returns the name of a custom format (this function will fail for a + standard format). + */ + wxString GetId() const; + + /** + Returns the platform-specific number identifying the format. + */ + NativeFormat GetType() const; + + /** + Sets the format to be the custom format identified by the given name. + */ + void SetId(const wxChar format); + + /** + Sets the format to the given value, which should be one of wxDF_XXX + constants. + */ + void SetType(NativeFormat format); + + /** + Returns @true if the formats are different. + */ + bool operator !=(const wxDataFormat& format) const; + + /** + Returns @true if the formats are equal. + */ + bool operator ==(const wxDataFormat& format) const; +}; + + + +/** + @class wxURLDataObject + @wxheader{dataobj.h} + + wxURLDataObject is a wxDataObject containing an URL and can be used e.g. + when you need to put an URL on or retrieve it from the clipboard: + + @code + wxTheClipboard->SetData(new wxURLDataObject(url)); + @endcode + + @note This class is derived from wxDataObjectComposite on Windows rather + than wxTextDataObject on all other platforms. + + @library{wxcore} + @category{dnd} + + @see @ref overview_dnd, wxDataObject +*/ +class wxURLDataObject: public wxTextDataObject +{ +public: + /** + Constructor, may be used to initialize the URL. If @a url is empty, + SetURL() can be used later. + */ + wxURLDataObject(const wxString& url = wxEmptyString); + + /** + Returns the URL stored by this object, as a string. + */ + wxString GetURL() const; + + /** + Sets the URL stored by this object. + */ + void SetURL(const wxString& url); +}; + + + +/** + @class wxDataObject + @wxheader{dataobj.h} + + A wxDataObject represents data that can be copied to or from the clipboard, + or dragged and dropped. The important thing about wxDataObject is that this + is a 'smart' piece of data unlike 'dumb' data containers such as memory + buffers or files. Being 'smart' here means that the data object itself + should know what data formats it supports and how to render itself in each + of its supported formats. + + A supported format, incidentally, is exactly the format in which the data + can be requested from a data object or from which the data object may be + set. In the general case, an object may support different formats on + 'input' and 'output', i.e. it may be able to render itself in a given + format but not be created from data on this format or vice versa. + wxDataObject defines an enumeration type which distinguishes between them: + + @code + enum Direction + { + Get = 0x01, // format is supported by GetDataHere() + Set = 0x02 // format is supported by SetData() + }; + @endcode + + See wxDataFormat documentation for more about formats. + + Not surprisingly, being 'smart' comes at a price of added complexity. This + is reasonable for the situations when you really need to support multiple + formats, but may be annoying if you only want to do something simple like + cut and paste text. + + To provide a solution for both cases, wxWidgets has two predefined classes + which derive from wxDataObject: wxDataObjectSimple and + wxDataObjectComposite. wxDataObjectSimple is the simplest wxDataObject + possible and only holds data in a single format (such as HTML or text) and + wxDataObjectComposite is the simplest way to implement a wxDataObject that + does support multiple formats because it achieves this by simply holding + several wxDataObjectSimple objects. + + So, you have several solutions when you need a wxDataObject class (and you + need one as soon as you want to transfer data via the clipboard or drag and + drop): + + -# Use one of the built-in classes. + - You may use wxTextDataObject, wxBitmapDataObject or wxFileDataObject + in the simplest cases when you only need to support one format and + your data is either text, bitmap or list of files. + -# Use wxDataObjectSimple + - Deriving from wxDataObjectSimple is the simplest solution for custom + data - you will only support one format and so probably won't be able + to communicate with other programs, but data transfer will work in + your program (or between different copies of it). + -# Use wxDataObjectComposite + - This is a simple but powerful solution which allows you to support + any number of formats (either standard or custom if you combine it + with the previous solution). + -# Use wxDataObject Directly + - This is the solution for maximal flexibility and efficiency, but it + is also the most difficult to implement. + + Please note that the easiest way to use drag and drop and the clipboard + with multiple formats is by using wxDataObjectComposite, but it is not the + most efficient one as each wxDataObjectSimple would contain the whole data + in its respective formats. Now imagine that you want to paste 200 pages of + text in your proprietary format, as well as Word, RTF, HTML, Unicode and + plain text to the clipboard and even today's computers are in trouble. For + this case, you will have to derive from wxDataObject directly and make it + enumerate its formats and provide the data in the requested format on + demand. + + Note that neither the GTK+ data transfer mechanisms for clipboard and drag + and drop, nor OLE data transfer, copy any data until another application + actually requests the data. This is in contrast to the 'feel' offered to + the user of a program who would normally think that the data resides in the + clipboard after having pressed 'Copy' - in reality it is only declared to + be available. + + There are several predefined data object classes derived from + wxDataObjectSimple: wxFileDataObject, wxTextDataObject, wxBitmapDataObject + and wxURLDataObject which can be used without change. + + You may also derive your own data object classes from wxCustomDataObject + for user-defined types. The format of user-defined data is given as a + mime-type string literal, such as "application/word" or "image/png". These + strings are used as they are under Unix (so far only GTK+) to identify a + format and are translated into their Windows equivalent under Win32 (using + the OLE IDataObject for data exchange to and from the clipboard and for + drag and drop). Note that the format string translation under Windows is + not yet finished. + + Each class derived directly from wxDataObject must override and implement + all of its functions which are pure virtual in the base class. The data + objects which only render their data or only set it (i.e. work in only one + direction), should return 0 from GetFormatCount(). + + @beginWxPythonOnly + At this time this class is not directly usable from wxPython. Derive a + class from wxPyDataObjectSimple() instead. + @endWxPythonOnly + + @beginWxPerlOnly + This class is not currently usable from wxPerl; you may use + Wx::PlDataObjectSimple instead. + @endWxPerlOnly + + @library{wxcore} + @category{dnd} + + @see @ref overview_dnd, @ref page_samples_dnd, wxFileDataObject, + wxTextDataObject, wxBitmapDataObject, wxCustomDataObject, + wxDropTarget, wxDropSource, wxTextDropTarget, wxFileDropTarget +*/ +class wxDataObject +{ +public: + /** + Constructor. + */ + wxDataObject(); + + /** + Destructor. + */ + ~wxDataObject(); + + /** + Copy all supported formats in the given direction to the array pointed + to by @a formats. There is enough space for GetFormatCount(dir) formats + in it. + */ + virtual void GetAllFormats(wxDataFormat* formats, + Direction dir = Get) const; + + /** + The method will write the data of the format @a format in the buffer + @a buf and return @true on success, @false on failure. + */ + virtual bool GetDataHere(const wxDataFormat& format, void buf) const; + + /** + Returns the data size of the given format @a format. + */ + virtual size_t GetDataSize(const wxDataFormat& format) const; + + /** + Returns the number of available formats for rendering or setting the + data. + */ + virtual size_t GetFormatCount(Direction dir = Get) const; + + /** + Returns the preferred format for either rendering the data (if @a dir + is @c Get, its default value) or for setting it. Usually this will be + the native format of the wxDataObject. + */ + virtual wxDataFormat GetPreferredFormat(Direction dir = Get) const; + + /** + Set the data in the format @a format of the length @a len provided in + the buffer @a buf. + + @return @true on success, @false on failure. + */ + virtual bool SetData(const wxDataFormat& format, size_t len, + const void buf); +}; + + + +/** + @class wxTextDataObject + @wxheader{dataobj.h} + + wxTextDataObject is a specialization of wxDataObject for text data. It can + be used without change to paste data into the wxClipboard or a + wxDropSource. A user may wish to derive a new class from this class for + providing text on-demand in order to minimize memory consumption when + offering data in several formats, such as plain text and RTF because by + default the text is stored in a string in this class, but it might as well + be generated when requested. For this, GetTextLength() and GetText() will + have to be overridden. + + Note that if you already have the text inside a string, you will not + achieve any efficiency gain by overriding these functions because copying + wxStrings is already a very efficient operation (data is not actually + copied because wxStrings are reference counted). + + @beginWxPythonOnly + If you wish to create a derived wxTextDataObject class in wxPython you + should derive the class from wxPyTextDataObject in order to get + Python-aware capabilities for the various virtual methods. + @endWxPythonOnly + + @library{wxcore} + @category{dnd} + + @see @ref overview_dnd, wxDataObject, wxDataObjectSimple, wxFileDataObject, + wxBitmapDataObject +*/ +class wxTextDataObject : public wxDataObjectSimple +{ +public: + /** + Constructor, may be used to initialise the text (otherwise SetText() + should be used later). + */ + wxTextDataObject(const wxString& text = wxEmptyString); + + /** + Returns the text associated with the data object. You may wish to + override this method when offering data on-demand, but this is not + required by wxWidgets' internals. Use this method to get data in text + form from the wxClipboard. + */ + virtual wxString GetText() const; + + /** + Returns the data size. By default, returns the size of the text data + set in the constructor or using SetText(). This can be overridden to + provide text size data on-demand. It is recommended to return the text + length plus 1 for a trailing zero, but this is not strictly required. + */ + virtual size_t GetTextLength() const; + + /** + Sets the text associated with the data object. This method is called + when the data object receives the data and, by default, copies the text + into the member variable. If you want to process the text on the fly + you may wish to override this function. + */ + virtual void SetText(const wxString& strText); +}; + + + +/** + @class wxFileDataObject + @wxheader{dataobj.h} + + wxFileDataObject is a specialization of wxDataObject for file names. The + program works with it just as if it were a list of absolute file names, but + internally it uses the same format as Explorer and other compatible + programs under Windows or GNOME/KDE filemanager under Unix which makes it + possible to receive files from them using this class. + + @warning Under all non-Windows platforms this class is currently + "input-only", i.e. you can receive the files from another + application, but copying (or dragging) file(s) from a wxWidgets + application is not currently supported. PS: GTK2 should work as + well. + + @library{wxcore} + @category{dnd} + + @see wxDataObject, wxDataObjectSimple, wxTextDataObject, + wxBitmapDataObject, wxDataObject +*/ +class wxFileDataObject : public wxDataObjectSimple +{ +public: + /** + Constructor. + */ + wxFileDataObject(); + + /** + Adds a file to the file list represented by this data object (Windows + only). + */ + virtual void AddFile(const wxString& file); + + /** + Returns the array of file names. + */ + const wxArrayString GetFilenames() const; +}; + diff --git a/interface/wx/dataview.h b/interface/wx/dataview.h new file mode 100644 index 0000000000..533e8ec36b --- /dev/null +++ b/interface/wx/dataview.h @@ -0,0 +1,1997 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: dataview.h +// Purpose: interface of wxDataViewIconText +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxDataViewIconText + @wxheader{dataview.h} + + wxDataViewIconText is used by + wxDataViewIconTextRenderer + for data transfer. This class can be converted to a from + a wxVariant. + + @library{wxbase} + @category{dvc} +*/ +class wxDataViewIconText : public wxObject +{ +public: + //@{ + /** + Constructor. + */ + wxDataViewIconText(const wxString& text = wxEmptyString, + const wxIcon& icon = wxNullIcon); + wxDataViewIconText(const wxDataViewIconText& other); + //@} + + /** + Gets the icon. + */ + const wxIcon GetIcon() const; + + /** + Gets the text. + */ + wxString GetText() const; + + /** + Set the icon. + */ + void SetIcon(const wxIcon& icon); + + /** + Set the text. + */ + void SetText(const wxString& text); +}; + + + +/** + @class wxDataViewEvent + @wxheader{dataview.h} + + wxDataViewEvent - the event class for the wxDataViewCtrl notifications + + @library{wxadv} + @category{events,dvc} +*/ +class wxDataViewEvent : public wxNotifyEvent +{ +public: + //@{ + /** + + */ + wxDataViewEvent(wxEventType commandType = wxEVT_NULL, + int winid = 0); + wxDataViewEvent(const wxDataViewEvent& event); + //@} + + /** + Used to clone the event. + */ + wxEvent* Clone() const; + + /** + Returns the position of the column in the control or -1 + if no column field was set by the event emitter. + */ + int GetColumn() const; + + /** + Returns a pointer to the wxDataViewColumn from which + the event was emitted or @NULL. + */ + wxDataViewColumn* GetDataViewColumn(); + + /** + Returns the wxDataViewModel associated with the event. + */ + wxDataViewModel* GetModel() const; + + /** + Returns a the position of a context menu event in screen coordinates. + */ + wxPoint GetPosition() const; + + /** + Returns a reference to a value. + */ + const wxVariant GetValue() const; + + /** + + */ + void SetColumn(int col); + + /** + For wxEVT_DATAVIEW_COLUMN_HEADER_CLICKED only. + */ + void SetDataViewColumn(wxDataViewColumn* col); + + /** + + */ + void SetModel(wxDataViewModel* model); + + /** + + */ + void SetValue(const wxVariant& value); +}; + + + +/** + @class wxDataViewModel + @wxheader{dataview.h} + + wxDataViewModel is the base class for all data model to be + displayed by a wxDataViewCtrl. + All other models derive from it and must implement its + pure virtual functions in order to define a complete + data model. In detail, you need to override + wxDataViewModel::IsContainer, + wxDataViewModel::GetParent, + wxDataViewModel::GetChildren, + wxDataViewModel::GetColumnCount, + wxDataViewModel::GetColumnType and + wxDataViewModel::GetValue in order to + define the data model which acts as an interface between + your actual data and the wxDataViewCtrl. Since you will + usually also allow the wxDataViewCtrl to change your data + through its graphical interface, you will also have to override + wxDataViewModel::SetValue which the + wxDataViewCtrl will call when a change to some data has been + commited. + + wxDataViewModel (as indeed the entire wxDataViewCtrl + code) is using wxVariant to store data and + its type in a generic way. wxVariant can be extended to contain + almost any data without changes to the original class. + + The data that is presented through this data model is expected + to change at run-time. You need to inform the data model when + a change happened. Depending on what happened you need to call + one of the following methods: + wxDataViewModel::ValueChanged, + wxDataViewModel::ItemAdded, + wxDataViewModel::ItemDeleted, + wxDataViewModel::ItemChanged, + wxDataViewModel::Cleared. There are + plural forms for notification of addition, change + or removal of several item at once. See + wxDataViewModel::ItemsAdded, + wxDataViewModel::ItemsDeleted, + wxDataViewModel::ItemsChanged. + + Note that wxDataViewModel does not define the position or + index of any item in the control because different controls + might display the same data differently. wxDataViewModel does + provide a wxDataViewModel::Compare method + which the wxDataViewCtrl may use to sort the data either + in conjunction with a column header or without (see + wxDataViewModel::HasDefaultCompare). + + This class maintains a list of + wxDataViewModelNotifier + which link this class to the specific implementations on the + supported platforms so that e.g. calling + wxDataViewModel::ValueChanged + on this model will just call + wxDataViewModelNotifier::ValueChanged + for each notifier that has been added. You can also add + your own notifier in order to get informed about any changes + to the data in the list model. + + Currently wxWidgets provides the following models apart + from the base model: + wxDataViewIndexListModel, + wxDataViewVirtualListModel, + wxDataViewTreeStore. + + Note that wxDataViewModel is reference counted, derives from + wxObjectRefData and cannot be deleted + directly as it can be shared by several wxDataViewCtrls. This + implies that you need to decrease the reference count after + associating the model with a control like this: + + @code + wxDataViewCtrl *musicCtrl = new wxDataViewCtrl( this, ID_MUSIC_CTRL ); + wxDataViewModel *musicModel = new MyMusicModel; + m_musicCtrl-AssociateModel( musicModel ); + musicModel-DecRef(); // avoid memory leak !! + // add columns now + @endcode + + + @library{wxadv} + @category{dvc} +*/ +class wxDataViewModel : public wxObjectRefData +{ +public: + /** + Constructor. + */ + wxDataViewModel(); + + /** + Destructor. This should not be called directly. Use DecRef() instead. + */ + ~wxDataViewModel(); + + /** + Adds a wxDataViewModelNotifier + to the model. + */ + void AddNotifier(wxDataViewModelNotifier* notifier); + + /** + Called to inform the model that all data has been cleared. The + control will reread the data from the model again. + */ + virtual bool Cleared(); + + /** + The compare function to be used by control. The default compare function + sorts by container and other items separately and in ascending order. + Override this for a different sorting behaviour. + See also HasDefaultCompare(). + */ + virtual int Compare(const wxDataViewItem& item1, + const wxDataViewItem& item2, + unsigned int column, + bool ascending); + + /** + Oberride this to indicate that the item has special font attributes. + This only affects the + wxDataViewTextRendererText() renderer. + See also wxDataViewItemAttr. + */ + bool GetAttr(const wxDataViewItem& item, unsigned int col, + wxDataViewItemAttr& attr); + + /** + Override this so the control can query the child items of + an item. Returns the number of items. + */ + virtual unsigned int GetChildren(const wxDataViewItem& item, + wxDataViewItemArray& children) const; + + /** + Override this to indicate the number of columns in the model. + */ + virtual unsigned int GetColumnCount() const; + + /** + Override this to indicate what type of data is stored in the + column specified by @e col. This should return a string + indicating the type of data as reported by wxVariant. + */ + virtual wxString GetColumnType(unsigned int col) const; + + /** + Override this to indicate which wxDataViewItem representing the parent + of @a item or an invalid wxDataViewItem if the the root item is + the parent item. + */ + virtual wxDataViewItem GetParent(const wxDataViewItem& item) const; + + /** + Override this to indicate the value of @e item + A wxVariant is used to store the data. + */ + virtual void GetValue(wxVariant& variant, + const wxDataViewItem& item, + unsigned int col) const; + + /** + Override this method to indicate if a container item merely + acts as a headline (or for categorisation) or if it also + acts a normal item with entries for futher columns. By + default returns @e @false. + */ + virtual bool HasContainerColumns(const wxDataViewItem& item) const; + + /** + Override this to indicate that the model provides a default compare + function that the control should use if no wxDataViewColumn has been + chosen for sorting. Usually, the user clicks on a column header for + sorting, the data will be sorted alphanumerically. If any other + order (e.g. by index or order of appearance) is required, then this + should be used. See also wxDataViewIndexListModel + for a model which makes use of this. + */ + virtual bool HasDefaultCompare() const; + + /** + Override this to indicate of @a item is a container, i.e. if + it can have child items. + */ + virtual bool IsContainer(const wxDataViewItem& item) const; + + /** + Call this to inform the model that an item has been added + to the data. + */ + virtual bool ItemAdded(const wxDataViewItem& parent, + const wxDataViewItem& item); + + /** + Call this to inform the model that an item has changed. + This will eventually emit a wxEVT_DATAVIEW_ITEM_VALUE_CHANGED + event (in which the column fields will not be set) to the user. + */ + virtual bool ItemChanged(const wxDataViewItem& item); + + /** + Call this to inform the model that an item has been deleted from the data. + */ + virtual bool ItemDeleted(const wxDataViewItem& parent, + const wxDataViewItem& item); + + /** + Call this to inform the model that several items have been added + to the data. + */ + virtual bool ItemsAdded(const wxDataViewItem& parent, + const wxDataViewItemArray& items); + + /** + Call this to inform the model that several items have changed. + This will eventually emit wxEVT_DATAVIEW_ITEM_VALUE_CHANGED + events (in which the column fields will not be set) to the user. + */ + virtual bool ItemsChanged(const wxDataViewItemArray& items); + + /** + Call this to inform the model that several items have been deleted. + */ + virtual bool ItemsDeleted(const wxDataViewItem& parent, + const wxDataViewItemArray& items); + + /** + Remove the @a notifier from the list of notifiers. + */ + void RemoveNotifier(wxDataViewModelNotifier* notifier); + + /** + Call this to initiate a resort after the sort function has + been changed. + */ + virtual void Resort(); + + /** + This gets called in order to set a value in the data model. + The most common scenario is that the wxDataViewCtrl calls + this method after the user changed some data in the view. + Afterwards ValueChanged() + has to be called! + */ + virtual bool SetValue(const wxVariant& variant, + const wxDataViewItem& item, + unsigned int col); + + /** + Call this to inform this model that a value in the model has + been changed. This is also called from wxDataViewCtrl's + internal editing code, e.g. when editing a text field + in the control. + This will eventually emit a wxEVT_DATAVIEW_ITEM_VALUE_CHANGED + event to the user. + */ + virtual bool ValueChanged(const wxDataViewItem& item, + unsigned int col); +}; + + + +/** + @class wxDataViewIndexListModel + @wxheader{dataview.h} + + wxDataViewIndexListModel is a specialized data model which lets + you address an item by its position (row) rather than its + wxDataViewItem (which you can obtain from this class). + This model also provides its own wxDataViewIndexListModel::Compare + method which sorts the model's data by the index. + + This model is not a virtual model since the control stores + each wxDataViewItem. Use wxDataViewVirtualListModel if you + need to display millions of items or have other reason to + use a virtual control. + + @library{wxbase} + @category{dvc} +*/ +class wxDataViewIndexListModel : public wxDataViewModel +{ +public: + /** + Constructor. + */ + wxDataViewIndexListModel(unsigned int initial_size = 0); + + /** + Destructor. + */ + ~wxDataViewIndexListModel(); + + /** + Compare method that sorts the items by their index. + */ + int Compare(const wxDataViewItem& item1, + const wxDataViewItem& item2, + unsigned int column, bool ascending); + + /** + Oberride this to indicate that the row has special font attributes. + This only affects the + wxDataViewTextRendererText() renderer. + See also wxDataViewItemAttr. + */ + bool GetAttr(unsigned int row, unsigned int col, + wxDataViewItemAttr& attr); + + /** + Returns the wxDataViewItem at the given @e row. + */ + wxDataViewItem GetItem(unsigned int row) const; + + /** + Returns the position of given @e item. + */ + unsigned int GetRow(const wxDataViewItem& item) const; + + /** + Override this to allow getting values from the model. + */ + void GetValue(wxVariant& variant, unsigned int row, + unsigned int col) const; + + /** + Call this after if the data has to be read again from + the model. This is useful after major changes when + calling the methods below (possibly thousands of times) + doesn't make sense. + */ + void Reset(unsigned int new_size); + + /** + Call this after a row has been appended to the model. + */ + void RowAppended(); + + /** + Call this after a row has been changed. + */ + void RowChanged(unsigned int row); + + /** + Call this after a row has been deleted. + */ + void RowDeleted(unsigned int row); + + /** + Call this after a row has been inserted at the given position. + */ + void RowInserted(unsigned int before); + + /** + Call this after a row has been prepended to the model. + */ + void RowPrepended(); + + /** + Call this after a value has been changed. + */ + void RowValueChanged(unsigned int row, unsigned int col); + + /** + Call this after rows have been deleted. The array will internally + get copied and sorted in descending order so that the rows with + the highest position will be deleted first. + */ + void RowsDeleted(const wxArrayInt& rows); + + /** + Called in order to set a value in the model. + */ + bool SetValue(const wxVariant& variant, unsigned int row, + unsigned int col); +}; + + + +/** + @class wxDataViewVirtualListModel + @wxheader{dataview.h} + + wxDataViewVirtualListModel is a specialized data model which lets + you address an item by its position (row) rather than its + wxDataViewItem and as such offers the exact same interface as + wxDataViewIndexListModel. The important difference is that under + platforms other than OS X, using this model will result in a + truely virtual control able to handle millions of items as the + control doesn't store any item (a feature not supported by the + Carbon API under OS X). + + @see wxDataViewIndexListModel for the API. + + @library{wxbase} + @category{dvc} +*/ +class wxDataViewVirtualListModel : public wxDataViewModel +{ +public: + /** + Constructor. + */ + wxDataViewVirtualListModel(unsigned int initial_size = 0); +}; + + + +/** + @class wxDataViewItemAttr + @wxheader{dataview.h} + + This class is used to indicate to a wxDataViewCtrl + that a certain Item() has extra font attributes + for its renderer. For this, it is required to override + wxDataViewModel::GetAttr. + + Attributes are currently only supported by + wxDataViewTextRendererText(). + + @library{wxadv} + @category{dvc} +*/ +class wxDataViewItemAttr +{ +public: + /** + Constructor. + */ + wxDataViewItemAttr(); + + /** + Call this to indicate that the item shall be displayed in bold text. + */ + void SetBold(bool set); + + /** + Call this to indicate that the item shall be displayed with + that colour. + */ + void SetColour(const wxColour& colour); + + /** + Call this to indicate that the item shall be displayed in italic text. + */ + void SetItalic(bool set); +}; + + + +/** + @class wxDataViewItem + @wxheader{dataview.h} + + wxDataViewItem is a small opaque class that represents an + item in a wxDataViewCtrl in a + persistent way, i.e. indepent of the position of the + item in the control or changes to its contents. It must + hold a unique ID of type @e void* in its only field + and can be converted to a from it. + + If the ID is @e @NULL the wxDataViewItem is invalid and + wxDataViewItem::IsOk will return @e @false + which used in many places in the API of wxDataViewCtrl + to indicate that e.g. no item was found. An ID of @NULL + is also used to indicate the invisible root. Examples + for this are + wxDataViewModel::GetParent and + wxDataViewModel::GetChildren. + + @library{wxadv} + @category{dvc} +*/ +class wxDataViewItem +{ +public: + //@{ + /** + + */ + wxDataViewItem(void* id = NULL); + wxDataViewItem(const wxDataViewItem& item); + //@} + + /** + Returns the ID. + */ + void* GetID() const; + + /** + Returns @true if the ID is not @e @NULL. + */ + bool IsOk() const; +}; + + + +/** + @class wxDataViewCtrl + @wxheader{dataview.h} + + wxDataViewCtrl is a control to display data either + in a tree like fashion or in a tabular form or both. + If you only need to display a simple tree structure + with an API more like the older wxTreeCtrl class, + then the specialized wxDataViewTreeCtrl + can be used. + + A wxDataViewItem is used + to represent a (visible) item in the control. + + Unlike wxListCtrl wxDataViewCtrl doesn't + get its data from the user through virtual functions or by + setting it directly. Instead you need to write your own + wxDataViewModel and associate + it with this control. Then you need to add a number of + wxDataViewColumn to this control to + define what each column shall display. Each wxDataViewColumn + in turn owns 1 instance of a + wxDataViewRenderer to render its + cells. A number of standard renderers for rendering text, dates, + images, toggle, a progress bar etc. are provided. Additionally, + the user can write custom renderes deriving from + wxDataViewCustomRenderer + for displaying anything. + + All data transfer from the control to the model and the user + code is done through wxVariant which can + be extended to support more data formats as necessary. + Accordingly, all type information uses the strings returned + from wxVariant::GetType. + + @beginStyleTable + @style{wxDV_SINGLE} + Single selection mode. This is the default. + @style{wxDV_MULTIPLE} + Multiple selection mode. + @style{wxDV_ROW_LINES} + Use alternating colours for rows if supported by platform and theme. + @style{wxDV_HORIZ_RULES} + Display fine rules between row if supported. + @style{wxDV_VERT_RULES} + Display fine rules between columns is supported. + @style{wxDV_VARIABLE_LINE_HEIGHT} + Allow variable line heights. This can be inefficient when displaying large number of items. + @endStyleTable + + @library{wxadv} + @category{ctrl,dvc} + +*/ +class wxDataViewCtrl : public wxControl +{ +public: + /** + Default Constructor. + */ + wxDataViewCtrl(); + + /** + Constructor. Calls Create(). + */ + wxDataViewCtrl(wxWindow* parent, wxWindowID id, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0, + const wxValidator& validator = wxDefaultValidator); + + /** + Destructor. + */ + ~wxDataViewCtrl(); + + /** + Appends a wxDataViewColumn to the control. Returns @true on success. + Note that there is a number of short cut methods which implicitly create + a wxDataViewColumn and a wxDataViewRenderer for it (see below). + */ + virtual bool AppendColumn(wxDataViewColumn* col); + + /** + Prepends a wxDataViewColumn to the control. Returns @true on success. + Note that there is a number of short cut methods which implicitly create + a wxDataViewColumn and a wxDataViewRenderer for it. + */ + virtual bool PrependColumn(wxDataViewColumn* col); + + /** + Inserts a wxDataViewColumn to the control. Returns @true on success. + */ + virtual bool InsertColumn(unsigned int pos, wxDataViewColumn* col); + + //@{ + /** + Appends a column for rendering a bitmap. Returns the wxDataViewColumn + created in the function or @NULL on failure. + */ + wxDataViewColumn* AppendBitmapColumn(const wxString& label, + unsigned int model_column, + wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, + int width = -1, + wxAlignment align = wxALIGN_CENTER, + int flags = wxDATAVIEW_COL_RESIZABLE); + wxDataViewColumn* AppendBitmapColumn(const wxBitmap& label, + unsigned int model_column, + wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, + int width = -1, + wxAlignment align = wxALIGN_CENTER, + int flags = wxDATAVIEW_COL_RESIZABLE); + //@} + + //@{ + /** + Appends a column for rendering a date. Returns the wxDataViewColumn + created in the function or @NULL on failure. + + NB: The @e align parameter is applied to both the column header and + the column renderer. + */ + wxDataViewColumn* AppendDateColumn(const wxString& label, + unsigned int model_column, + wxDataViewCellMode mode = wxDATAVIEW_CELL_ACTIVATABLE, + int width = -1, + wxAlignment align = wxALIGN_CENTER, + int flags = wxDATAVIEW_COL_RESIZABLE); + wxDataViewColumn* AppendDateColumn(const wxBitmap& label, + unsigned int model_column, + wxDataViewCellMode mode = wxDATAVIEW_CELL_ACTIVATABLE, + int width = -1, + wxAlignment align = wxALIGN_CENTER, + int flags = wxDATAVIEW_COL_RESIZABLE); + //@} + + //@{ + /** + Appends a column for rendering text with an icon. Returns the wxDataViewColumn + created in the function or @NULL on failure. This method uses the + wxDataViewIconTextRenderer class. + + NB: The @e align parameter is applied to both the column header and + the column renderer. + */ + wxDataViewColumn* AppendIconTextColumn(const wxString& label, + unsigned int model_column, + wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, + int width = -1, + wxAlignment align = wxALIGN_LEFT, + int flags = wxDATAVIEW_COL_RESIZABLE); + wxDataViewColumn* AppendIconTextColumn(const wxBitmap& label, + unsigned int model_column, + wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, + int width = -1, + wxAlignment align = wxALIGN_LEFT, + int flags = wxDATAVIEW_COL_RESIZABLE); + //@} + + //@{ + /** + Appends a column for rendering a progress indicator. Returns the + wxDataViewColumn created in the function or @NULL on failure. + + NB: The @e align parameter is applied to both the column header and + the column renderer. + */ + wxDataViewColumn* AppendProgressColumn(const wxString& label, + unsigned int model_column, + wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, + int width = 80, + wxAlignment align = wxALIGN_CENTER, + int flags = wxDATAVIEW_COL_RESIZABLE); + wxDataViewColumn* AppendProgressColumn(const wxBitmap& label, + unsigned int model_column, + wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, + int width = 80, + wxAlignment align = wxALIGN_CENTER, + int flags = wxDATAVIEW_COL_RESIZABLE); + //@} + + //@{ + /** + Appends a column for rendering text. Returns the wxDataViewColumn + created in the function or @NULL on failure. + + NB: The @e align parameter is applied to both the column header and + the column renderer. + */ + wxDataViewColumn* AppendTextColumn(const wxString& label, + unsigned int model_column, + wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, + int width = -1, + wxAlignment align = wxALIGN_LEFT, + int flags = wxDATAVIEW_COL_RESIZABLE); + wxDataViewColumn* AppendTextColumn(const wxBitmap& label, + unsigned int model_column, + wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, + int width = -1, + wxAlignment align = wxALIGN_LEFT, + int flags = wxDATAVIEW_COL_RESIZABLE); + //@} + + //@{ + /** + Appends a column for rendering a toggle. Returns the wxDataViewColumn + created in the function or @NULL on failure. + + NB: The @e align parameter is applied to both the column header and + the column renderer. + */ + wxDataViewColumn* AppendToggleColumn(const wxString& label, + unsigned int model_column, + wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, + int width = 30, + wxAlignment align = wxALIGN_CENTER, + int flags = wxDATAVIEW_COL_RESIZABLE); + wxDataViewColumn* AppendToggleColumn(const wxBitmap& label, + unsigned int model_column, + wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, + int width = 30, + wxAlignment align = wxALIGN_CENTER, + int flags = wxDATAVIEW_COL_RESIZABLE); + //@} + + /** + Associates a wxDataViewModel with the control. This increases the reference + count of the model by 1. + */ + virtual bool AssociateModel(wxDataViewModel* model); + + /** + Removes all columns. + */ + virtual bool ClearColumns(); + + /** + Unselects all rows. + */ + void ClearSelection(); + + /** + Collapses the item. + */ + void Collapse(const wxDataViewItem& item); + + /** + Create the control. Useful for two step creation. + */ + bool Create(wxWindow* parent, wxWindowID id, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0, + const wxValidator& validator = wxDefaultValidator); + + /** + Deletes given column. + */ + virtual bool DeleteColumn(const wxDataViewColumn* column); + + /** + Call this to ensure that the given item is visible. + */ + void EnsureVisible(const wxDataViewItem& item, + const wxDataViewColumn* column = NULL); + + /** + Expands the item. + */ + void Expand(const wxDataViewItem& item); + + /** + Returns pointer to the column. @a pos refers to the + position in the control which may change after reordering + columns by the user. + */ + virtual wxDataViewColumn* GetColumn(unsigned int pos) const; + + /** + Returns the number of columns. + */ + virtual unsigned int GetColumnCount() const; + + /** + Returns the position of the column or -1 if not found in the control. + */ + virtual int GetColumnPosition(const wxDataViewColumn* column) const; + + /** + Returns column containing the expanders. + */ + wxDataViewColumn* GetExpanderColumn() const; + + /** + Returns indentation. + */ + int GetIndent() const; + + /** + Returns item rect. + */ + wxRect GetItemRect(const wxDataViewItem& item, + const wxDataViewColumn* col = NULL) const; + + /** + Returns pointer to the data model associated with the + control (if any). + */ + virtual wxDataViewModel* GetModel() const; + + /** + Returns first selected item or an invalid item if none is selected. + */ + wxDataViewItem GetSelection() const; + + /** + Fills @a sel with currently selected items and returns + their number. + */ + int GetSelections(wxDataViewItemArray& sel) const; + + /** + Returns the wxDataViewColumn currently responsible for sorting + or @NULL if none has been selected. + */ + virtual wxDataViewColumn* GetSortingColumn() const; + + /** + Hittest. + */ + void HitTest(const wxPoint& point, wxDataViewItem& item, + wxDataViewColumn*& col) const; + + /** + Return @true if the item is selected. + */ + bool IsSelected(const wxDataViewItem& item) const; + + /** + Select the given item. + */ + void Select(const wxDataViewItem& item); + + /** + Select all items. + */ + void SelectAll(); + + /** + Set which column shall contain the tree-like expanders. + */ + void SetExpanderColumn(wxDataViewColumn* col); + + /** + Sets the indendation. + */ + void SetIndent(int indent); + + /** + Sets the selection to the array of wxDataViewItems. + */ + void SetSelections(const wxDataViewItemArray& sel); + + /** + Unselect the given item. + */ + void Unselect(const wxDataViewItem& item); + + /** + Unselect all item. This method only has effect if multiple + selections are allowed. + */ + void UnselectAll(); +}; + + + +/** + @class wxDataViewModelNotifier + @wxheader{dataview.h} + + A wxDataViewModelNotifier instance is owned by a + wxDataViewModel + and mirrors its notification interface. See + the documentation of that class for further + information. + + @library{wxbase} + @category{dvc} +*/ +class wxDataViewModelNotifier +{ +public: + /** + Constructor. + */ + wxDataViewModelNotifier(); + + /** + Destructor. + */ + ~wxDataViewModelNotifier(); + + /** + Called by owning model. + */ + bool Cleared(); + + /** + Get owning wxDataViewModel. + */ + wxDataViewModel* GetOwner() const; + + /** + Called by owning model. + */ + bool ItemAdded(const wxDataViewItem& parent, + const wxDataViewItem& item); + + /** + Called by owning model. + */ + bool ItemChanged(const wxDataViewItem& item); + + /** + Called by owning model. + */ + bool ItemDeleted(const wxDataViewItem& parent, + const wxDataViewItem& item); + + /** + Called by owning model. + */ + bool ItemsAdded(const wxDataViewItem& parent, + const wxDataViewItemArray& items); + + /** + Called by owning model. + */ + bool ItemsChanged(const wxDataViewItemArray& items); + + /** + Called by owning model. + */ + bool ItemsDeleted(const wxDataViewItem& parent, + const wxDataViewItemArray& items); + + /** + Called by owning model. + */ + void Resort(); + + /** + Set owner of this notifier. Used internally. + */ + void SetOwner(wxDataViewModel* owner); + + /** + Called by owning model. + */ + bool ValueChanged(const wxDataViewItem& item, unsigned int col); +}; + + + +/** + @class wxDataViewRenderer + @wxheader{dataview.h} + + This class is used by wxDataViewCtrl to render the individual cells. + One instance of a renderer class is owned by a wxDataViewColumn. There + is a number of ready-to-use renderers provided: + wxDataViewTextRenderer, + wxDataViewTextRendererAttr, + wxDataViewIconTextRenderer, + wxDataViewToggleRenderer, + wxDataViewProgressRenderer, + wxDataViewBitmapRenderer, + wxDataViewDateRenderer. + wxDataViewSpinRenderer. + + Additionally, the user can write own renderers by deriving from + wxDataViewCustomRenderer. + + The @e wxDataViewCellMode flag controls, what actions + the cell data allows. @e wxDATAVIEW_CELL_ACTIVATABLE + indicates that the user can double click the cell and + something will happen (e.g. a window for editing a date + will pop up). @e wxDATAVIEW_CELL_EDITABLE indicates + that the user can edit the data in-place, i.e. an control + will show up after a slow click on the cell. This behaviour + is best known from changing the filename in most file + managers etc. + + + @code + enum wxDataViewCellMode + { + wxDATAVIEW_CELL_INERT, + wxDATAVIEW_CELL_ACTIVATABLE, + wxDATAVIEW_CELL_EDITABLE + }; + @endcode + + The @e wxDataViewCellRenderState flag controls how the + the renderer should display its contents in a cell: + + @code + enum wxDataViewCellRenderState + { + wxDATAVIEW_CELL_SELECTED = 1, + wxDATAVIEW_CELL_PRELIT = 2, + wxDATAVIEW_CELL_INSENSITIVE = 4, + wxDATAVIEW_CELL_FOCUSED = 8 + }; + @endcode + + + @library{wxadv} + @category{dvc} +*/ +class wxDataViewRenderer : public wxObject +{ +public: + /** + Constructor. + */ + wxDataViewRenderer(const wxString& varianttype, + wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, + int align = wxDVR_DEFAULT_ALIGNMENT ); + + /** + Returns the alignment. See SetAlignment() + */ + virtual int GetAlignment() const; + + /** + Returns the cell mode. + */ + virtual wxDataViewCellMode GetMode(); + + /** + Returns pointer to the owning wxDataViewColumn. + */ + virtual wxDataViewColumn* GetOwner() const; + + /** + This methods retrieves the value from the renderer in order to + transfer the value back to the data model. Returns @e @false + on failure. + */ + virtual bool GetValue(wxVariant& value); + + /** + Returns a string with the type of the wxVariant + supported by this renderer. + */ + virtual wxString GetVariantType(); + + /** + Sets the alignment of the renderer's content. The default value + of wxDVR_DEFAULT_ALIGMENT indicates that the content should + have the same alignment as the column header. The method is + not implemented under OS X and the renderer always aligns its + contents as the column header on that platform. The other platforms + support both vertical and horizontal alignment. + */ + virtual void SetAlignment( int align ); + /** + Sets the owning wxDataViewColumn. This + is usually called from within wxDataViewColumn. + */ + virtual void SetOwner(wxDataViewColumn* owner); + + /** + Set the value of the renderer (and thus its cell) to @e value. + The internal code will then render this cell with this data. + */ + virtual bool SetValue(const wxVariant& value); + + /** + Before data is committed to the data model, it is passed to this + method where it can be checked for validity. This can also be + used for checking a valid range or limiting the user input in + a certain aspect (e.g. max number of characters or only alphanumeric + input, ASCII only etc.). Return @e @false if the value is + not valid. + Please note that due to implementation limitations, this validation + is done after the editing control already is destroyed and the + editing process finished. + */ + virtual bool Validate(wxVariant& value); +}; + + + +/** + @class wxDataViewTextRenderer + @wxheader{dataview.h} + + wxDataViewTextRenderer is used for rendering text. It supports + in-place editing if desired. + + @library{wxadv} + @category{dvc} +*/ +class wxDataViewTextRenderer : public wxDataViewRenderer +{ +public: + /** + + */ + wxDataViewTextRenderer(const wxString& varianttype = "string", + wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, + int align = wxDVR_DEFAULT_ALIGNMENT ); +}; + + + +/** + @class wxDataViewIconTextRenderer + @wxheader{dataview.h} + + The wxDataViewIconTextRenderer class is used to display text with + a small icon next to it as it is typically done in a file manager. + This classes uses the wxDataViewIconText + helper class to store its data. wxDataViewIonText can be converted + to a from a wxVariant using the left shift + operator. + + @library{wxadv} + @category{dvc} +*/ +class wxDataViewIconTextRenderer : public wxDataViewRenderer +{ +public: + /** + + */ + wxDataViewIconTextRenderer(const wxString& varianttype = "wxDataViewIconText", + wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, + int align = wxDVR_DEFAULT_ALIGNMENT ); +}; + + + +/** + @class wxDataViewProgressRenderer + @wxheader{dataview.h} + + wxDataViewProgressRenderer + + @library{wxadv} + @category{dvc} +*/ +class wxDataViewProgressRenderer : public wxDataViewRenderer +{ +public: + /** + + */ + wxDataViewProgressRenderer(const wxString& label = wxEmptyString, + const wxString& varianttype = "long", + wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, + int align = wxDVR_DEFAULT_ALIGNMENT ); +}; + + + +/** + @class wxDataViewSpinRenderer + @wxheader{dataview.h} + + This is a specialized renderer for rendering integer values. It + supports modifying the values in-place by using a wxSpinCtrl. + The renderer only support variants of type @e long. + + @library{wxbase} + @category{dvc} +*/ +class wxDataViewSpinRenderer : public wxDataViewCustomRenderer +{ +public: + /** + Constructor. @a min and @a max indicate the minimum und + maximum values of for the wxSpinCtrl. + */ + wxDataViewSpinRenderer(int min, int max, + wxDataViewCellMode mode = wxDATAVIEW_CELL_EDITABLE, + int align = wxDVR_DEFAULT_ALIGNMENT); +}; + + + +/** + @class wxDataViewToggleRenderer + @wxheader{dataview.h} + + wxDataViewToggleRenderer + + @library{wxadv} + @category{dvc} +*/ +class wxDataViewToggleRenderer : public wxDataViewRenderer +{ +public: + /** + + */ + wxDataViewToggleRenderer(const wxString& varianttype = "bool", + wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT); +}; + + + +/** + @class wxDataViewDateRenderer + @wxheader{dataview.h} + + wxDataViewDateRenderer + + @library{wxadv} + @category{dvc} +*/ +class wxDataViewDateRenderer : public wxDataViewRenderer +{ +public: + /** + + */ + wxDataViewDateRenderer(const wxString& varianttype = "datetime", + wxDataViewCellMode mode = wxDATAVIEW_CELL_ACTIVATABLE); +}; + + + +/** + @class wxDataViewTextRendererAttr + @wxheader{dataview.h} + + The same as wxDataViewTextRenderer but with + support for font attributes. Font attributes are currently only supported + under GTK+ and MSW. + + See also wxDataViewModel::GetAttr and + wxDataViewItemAttr. + + @library{wxadv} + @category{dvc} +*/ +class wxDataViewTextRendererAttr : public wxDataViewTextRenderer +{ +public: + /** + + */ + wxDataViewTextRendererAttr(const wxString& varianttype = "string", + wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, + int align = wxDVR_DEFAULT_ALIGNMENT); +}; + + + +/** + @class wxDataViewCustomRenderer + @wxheader{dataview.h} + + You need to derive a new class from wxDataViewCustomRenderer in + order to write a new renderer. You need to override at least + wxDataViewRenderer::SetValue, + wxDataViewRenderer::GetValue, + wxDataViewCustomRenderer::GetSize + and wxDataViewCustomRenderer::Render. + + If you want your renderer to support in-place editing then you + also need to override + wxDataViewCustomRenderer::HasEditorCtrl, + wxDataViewCustomRenderer::CreateEditorCtrl + and wxDataViewCustomRenderer::GetValueFromEditorCtrl. + Note that a special event handler will be pushed onto that + editor control which handles ENTER and focus out events + in order to end the editing. + + @library{wxadv} + @category{dvc} +*/ +class wxDataViewCustomRenderer : public wxDataViewRenderer +{ +public: + /** + Constructor. + */ + wxDataViewCustomRenderer(const wxString& varianttype = "string", + wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, + int align = wxDVR_DEFAULT_ALIGNMENT ); + + /** + Destructor. + */ + ~wxDataViewCustomRenderer(); + + /** + Override this to react to double clicks or ENTER. This method will + only be called in wxDATAVIEW_CELL_ACTIVATABLE mode. + */ + virtual bool Activate( wxRect cell, + wxDataViewModel* model, + const wxDataViewItem & item, + unsigned int col ); + + /** + Override this to create the actual editor control once editing + is about to start. @a parent is the parent of the editor + control, @a labelRect indicates the position and + size of the editor control and @a value is its initial value: + */ + virtual wxControl* CreateEditorCtrl(wxWindow* parent, + wxRect labelRect, + const wxVariant& value); + + /** + Create DC on request. Internal. + */ + virtual wxDC* GetDC(); + + /** + Return size required to show content. + */ + virtual wxSize GetSize(); + + /** + Overrride this so that the renderer can get the value + from the editor control (pointed to by @e editor): + */ + virtual bool GetValueFromEditorCtrl(wxControl* editor, + wxVariant& value); + + /** + Override this and make it return @e @true in order to + indicate that this renderer supports in-place editing. + */ + virtual bool HasEditorCtrl(); + + /** + Overrride this to react to a left click. This method will + only be called in wxDATAVIEW_CELL_ACTIVATABLE mode. + */ + virtual bool LeftClick( wxPoint cursor, + wxRect cell, + wxDataViewModel * model, + const wxDataViewItem & item, + unsigned int col ); + + /** + Override this to render the cell. Before this is called, + wxDataViewRenderer::SetValue was called + so that this instance knows what to render. + */ + virtual bool Render(wxRect cell, wxDC* dc, int state); + + /** + This method should be called from within Render() + whenever you need to render simple text. This will ensure that the + correct colour, font and vertical alignment will be chosen so the + text will look the same as text drawn by native renderers. + */ + bool RenderText(const wxString& text, int xoffset, wxRect cell, + wxDC* dc, int state); + + /** + Overrride this to start a drag operation. Not yet + supported + */ + virtual bool StartDrag(wxPoint cursor, wxRect cell, + wxDataViewModel* model, + const wxDataViewItem & item, + unsigned int col); +}; + + + +/** + @class wxDataViewBitmapRenderer + @wxheader{dataview.h} + + wxDataViewBitmapRenderer + + @library{wxadv} + @category{dvc} +*/ +class wxDataViewBitmapRenderer : public wxDataViewRenderer +{ +public: + /** + + */ + wxDataViewBitmapRenderer(const wxString& varianttype = "wxBitmap", + wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, + int align = wxDVR_DEFAULT_ALIGNMENT, +}; + + + +/** + @class wxDataViewColumn + @wxheader{dataview.h} + + This class represents a column in a wxDataViewCtrl. + One wxDataViewColumn is bound to one column in the data model, + to which the wxDataViewCtrl has been associated. + + An instance of wxDataViewRenderer is used by + this class to render its data. + + @library{wxadv} + @category{dvc} +*/ +class wxDataViewColumn : public wxObject +{ +public: + //@{ + /** + Constructors. + */ + wxDataViewColumn(const wxString& title, + wxDataViewRenderer* renderer, + unsigned int model_column, + int width = wxDVC_DEFAULT_WIDTH, + wxAlignment align = wxALIGN_CENTRE, + int flags = wxDATAVIEW_COL_RESIZABLE); + wxDataViewColumn(const wxBitmap& bitmap, + wxDataViewRenderer* renderer, + unsigned int model_column, + int width = wxDVC_DEFAULT_WIDTH, + wxAlignment align = wxALIGN_CENTRE, + int flags = wxDATAVIEW_COL_RESIZABLE); + //@} + + /** + Destructor. + */ + ~wxDataViewColumn(); + + /** + Returns the bitmap in the header of the column, if any. + */ + const wxBitmap GetBitmap(); + + /** + Returns the index of the column of the model, which this + wxDataViewColumn is displaying. + */ + unsigned int GetModelColumn(); + + /** + Returns the owning wxDataViewCtrl. + */ + wxDataViewCtrl* GetOwner() const; + + /** + Returns the renderer of this wxDataViewColumn. + See also wxDataViewRenderer. + */ + wxDataViewRenderer* GetRenderer(); + + /** + Returns @true if the column is reorderable. + */ + bool GetReorderable(); + + /** + Returns @true if the column is sortable. + See SetSortable() + */ + bool GetSortable(); + + /** + Returns the width of the column. + */ + int GetWidth(); + + /** + Returns @true, if the sort order is ascending. + See also SetSortOrder() + */ + bool IsSortOrderAscending(); + + /** + Set the alignment of the column header. + */ + void SetAlignment(wxAlignment align); + + /** + Set the bitmap of the column header. + */ + void SetBitmap(const wxBitmap& bitmap); + + /** + Indicate wether the column can be reordered by the + user using the mouse. This is typically implemented + visually by dragging the header button around. + */ + void SetReorderable(bool reorderable); + + /** + Indicate the sort order if the implementation of the + wxDataViewCtrl supports it, most commonly by showing + a little arrow. + */ + void SetSortOrder(bool ascending); + + /** + Indicate that the column is sortable. This does + not show any sorting indicate yet, but it does + make the column header clickable. Call + SetSortOrder() + afterwards to actually make the sort indicator appear. + If @a sortable is @false, the column header is + no longer clickable and the sort indicator (little + arrow) will disappear. + */ + void SetSortable(bool sortable); + + /** + Set the title of the column header to @e title. + */ + void SetTitle(const wxString& title); +}; + + + +/** + @class wxDataViewTreeCtrl + @wxheader{dataview.h} + + This class is a wxDataViewCtrl which internally + uses a wxDataViewTreeStore and forwards + most of its API to that class. Additionally, it uses a wxImageList + to store a list of icons. The main purpose of this class is to look + like a wxTreeCtrl to make a transition from it + to the wxDataViewCtrl class simpler. + + @library{wxbase} + @category{ctrl,dvc} + +*/ +class wxDataViewTreeCtrl : public wxDataViewCtrl +{ +public: + //@{ + /** + Constructor. Calls Create(). + */ + wxDataViewTreeCtrl(); + wxDataViewTreeCtrl(wxWindow* parent, wxWindowID id, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxDV_NO_HEADER, + const wxValidator& validator = wxDefaultValidator); + //@} + + /** + Destructor. Deletes the image list if any. + */ + ~wxDataViewTreeCtrl(); + + /** + + */ + wxDataViewItem AppendContainer(const wxDataViewItem& parent, + const wxString& text, + int icon = -1, + int expanded = -1, + wxClientData* data = NULL); + + /** + + */ + wxDataViewItem AppendItem(const wxDataViewItem& parent, + const wxString& text, + int icon = -1, + wxClientData* data = NULL); + + /** + Creates the control and a wxDataViewTreeStore as + its internal model. + */ + bool Create(wxWindow* parent, wxWindowID id, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxDV_NO_HEADER, + const wxValidator& validator = wxDefaultValidator); + + /** + Calls the identical method from wxDataViewTreeStore. + */ + void DeleteAllItems(); + + /** + Calls the identical method from wxDataViewTreeStore. + */ + void DeleteChildren(const wxDataViewItem& item); + + /** + Calls the identical method from wxDataViewTreeStore. + */ + void DeleteItem(const wxDataViewItem& item); + + /** + Calls the identical method from wxDataViewTreeStore. + */ + int GetChildCount(const wxDataViewItem& parent) const; + + /** + Returns the image list. + */ + wxImageList* GetImageList(); + + /** + Calls the identical method from wxDataViewTreeStore. + */ + wxClientData* GetItemData(const wxDataViewItem& item) const; + + /** + Calls the identical method from wxDataViewTreeStore. + */ + const wxIcon GetItemExpandedIcon(const wxDataViewItem& item) const; + + /** + Calls the identical method from wxDataViewTreeStore. + */ + const wxIcon GetItemIcon(const wxDataViewItem& item) const; + + /** + Calls the identical method from wxDataViewTreeStore. + */ + wxString GetItemText(const wxDataViewItem& item) const; + + /** + Calls the identical method from wxDataViewTreeStore. + */ + wxDataViewItem GetNthChild(const wxDataViewItem& parent, + unsigned int pos) const; + + //@{ + /** + Returns the store. + */ + wxDataViewTreeStore* GetStore() const; + const wxDataViewTreeStore* GetStore() const; + //@} + + /** + Calls the same method from wxDataViewTreeStore but uess + and index position in the image list instead of a wxIcon. + */ + wxDataViewItem InsertContainer(const wxDataViewItem& parent, + const wxDataViewItem& previous, + const wxString& text, + int icon = -1, + int expanded = -1, + wxClientData* data = NULL); + + /** + Calls the same method from wxDataViewTreeStore but uess + and index position in the image list instead of a wxIcon. + */ + wxDataViewItem InsertItem(const wxDataViewItem& parent, + const wxDataViewItem& previous, + const wxString& text, + int icon = -1, + wxClientData* data = NULL); + + /** + Calls the same method from wxDataViewTreeStore but uess + and index position in the image list instead of a wxIcon. + */ + wxDataViewItem PrependContainer(const wxDataViewItem& parent, + const wxString& text, + int icon = -1, + int expanded = -1, + wxClientData* data = NULL); + + /** + Calls the same method from wxDataViewTreeStore but uess + and index position in the image list instead of a wxIcon. + */ + wxDataViewItem PrependItem(const wxDataViewItem& parent, + const wxString& text, + int icon = -1, + wxClientData* data = NULL); + + /** + Sets the image list. + */ + void SetImageList(wxImageList* imagelist); + + /** + Calls the identical method from wxDataViewTreeStore. + */ + void SetItemData(const wxDataViewItem& item, wxClientData* data); + + /** + Calls the identical method from wxDataViewTreeStore. + */ + void SetItemExpandedIcon(const wxDataViewItem& item, + const wxIcon& icon); + + /** + Calls the identical method from wxDataViewTreeStore. + */ + void SetItemIcon(const wxDataViewItem& item, const wxIcon& icon); + + /** + Calls the identical method from wxDataViewTreeStore. + */ + void SetItemText(const wxDataViewItem& item, + const wxString& text); +}; + + + +/** + @class wxDataViewTreeStore + @wxheader{dataview.h} + + wxDataViewTreeStore is a specialised wxDataViewModel + for displaying simple trees very much like wxTreeCtrl + does and it offers a similar API. This class actually stores the entire + tree (therefore its name) and implements all virtual methods from the base + class so it can be used directly without having to derive any class from it. + This comes at the price of much reduced flexibility. + + @library{wxadv} + @category{dvc} +*/ +class wxDataViewTreeStore : public wxDataViewModel +{ +public: + /** + Constructor. Creates the invisible root node internally. + */ + wxDataViewTreeStore(); + + /** + Destructor. + */ + ~wxDataViewTreeStore(); + + /** + Append a container. + */ + wxDataViewItem AppendContainer(const wxDataViewItem& parent, + const wxString& text, + const wxIcon& icon = wxNullIcon, + const wxIcon& expanded = wxNullIcon, + wxClientData* data = NULL); + + /** + Append an item. + */ + wxDataViewItem AppendItem(const wxDataViewItem& parent, + const wxString& text, + const wxIcon& icon = wxNullIcon, + wxClientData* data = NULL); + + /** + Delete all item in the model. + */ + void DeleteAllItems(); + + /** + Delete all children of the item, but not the item itself. + */ + void DeleteChildren(const wxDataViewItem& item); + + /** + Delete this item. + */ + void DeleteItem(const wxDataViewItem& item); + + /** + Return the number of children of item. + */ + int GetChildCount(const wxDataViewItem& parent) const; + + /** + Returns the client data asoociated with the item. + */ + wxClientData* GetItemData(const wxDataViewItem& item) const; + + /** + Returns the icon to display in expanded containers. + */ + const wxIcon GetItemExpandedIcon(const wxDataViewItem& item) const; + + /** + Returns the icon of the item. + */ + const wxIcon GetItemIcon(const wxDataViewItem& item) const; + + /** + Returns the text of the item. + */ + wxString GetItemText(const wxDataViewItem& item) const; + + /** + Returns the nth child item of item. + */ + wxDataViewItem GetNthChild(const wxDataViewItem& parent, + unsigned int pos) const; + + /** + Inserts a container after @e previous. + */ + wxDataViewItem InsertContainer(const wxDataViewItem& parent, + const wxDataViewItem& previous, + const wxString& text, + const wxIcon& icon = wxNullIcon, + const wxIcon& expanded = wxNullIcon, + wxClientData* data = NULL); + + /** + Inserts an item after @e previous. + */ + wxDataViewItem InsertItem(const wxDataViewItem& parent, + const wxDataViewItem& previous, + const wxString& text, + const wxIcon& icon = wxNullIcon, + wxClientData* data = NULL); + + /** + Inserts a container before the first child item or @e parent. + */ + wxDataViewItem PrependContainer(const wxDataViewItem& parent, + const wxString& text, + const wxIcon& icon = wxNullIcon, + const wxIcon& expanded = wxNullIcon, + wxClientData* data = NULL); + + /** + Inserts an item before the first child item or @e parent. + */ + wxDataViewItem PrependItem(const wxDataViewItem& parent, + const wxString& text, + const wxIcon& icon = wxNullIcon, + wxClientData* data = NULL); + + /** + Sets the client data associated with the item. + */ + void SetItemData(const wxDataViewItem& item, wxClientData* data); + + /** + Sets the expanded icon for the item. + */ + void SetItemExpandedIcon(const wxDataViewItem& item, + const wxIcon& icon); + + /** + Sets the icon for the item. + */ + void SetItemIcon(const wxDataViewItem& item, const wxIcon& icon); +}; + diff --git a/interface/wx/datectrl.h b/interface/wx/datectrl.h new file mode 100644 index 0000000000..d32451ce57 --- /dev/null +++ b/interface/wx/datectrl.h @@ -0,0 +1,157 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: datectrl.h +// Purpose: interface of wxDatePickerCtrl +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxDatePickerCtrl + @wxheader{datectrl.h} + + This control allows the user to select a date. Unlike wxCalendarCtrl, which + is a relatively big control, wxDatePickerCtrl is implemented as a small + window showing the currently selected date. The control can be edited using + the keyboard, and can also display a popup window for more user-friendly + date selection, depending on the styles used and the platform, except + PalmOS where date is selected using native dialog. + + It is only available if @c wxUSE_DATEPICKCTRL is set to 1. + + @beginStyleTable + @style{wxDP_SPIN} + Creates a control without a month calendar drop down but with + spin-control-like arrows to change individual date components. This + style is not supported by the generic version. + @style{wxDP_DROPDOWN} + Creates a control with a month calendar drop-down part from which + the user can select a date. + @style{wxDP_DEFAULT} + Creates a control with the style that is best supported for the + current platform (currently wxDP_SPIN under Windows and + wxDP_DROPDOWN elsewhere). + @style{wxDP_ALLOWNONE} + With this style, the control allows the user to not enter any valid + date at all. Without it - the default - the control always has some + valid date. + @style{wxDP_SHOWCENTURY} + Forces display of the century in the default date format. Without + this style the century could be displayed, or not, depending on the + default date representation in the system. + @endStyleTable + + @beginEventTable{wxDateEvent} + @event{EVT_DATE_CHANGED(id, func)} + This event fires when the user changes the current selection in the + control. + @endEventTable + + @library{wxadv} + @category{pickers} + + + @see wxCalendarCtrl, wxDateEvent +*/ +class wxDatePickerCtrl : public wxControl +{ +public: + /** + Initializes the object and calls Create() with all the parameters. + */ + wxDatePickerCtrl(wxWindow* parent, wxWindowID id, + const wxDateTime& dt = wxDefaultDateTime, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxDP_DEFAULT | wxDP_SHOWCENTURY, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "datectrl"); + + /** + @param parent + Parent window, must not be non-@NULL. + @param id + The identifier for the control. + @param dt + The initial value of the control, if an invalid date (such as the + default value) is used, the control is set to today. + @param pos + Initial position. + @param size + Initial size. If left at default value, the control chooses its own + best size by using the height approximately equal to a text control + and width large enough to show the date string fully. + @param style + The window style, should be left at 0 as there are no special + styles for this control in this version. + @param validator + Validator which can be used for additional date checks. + @param name + Control name. + + @return @true if the control was successfully created or @false if + creation failed. + */ + bool Create(wxWindow* parent, wxWindowID id, + const wxDateTime& dt = wxDefaultDateTime, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxDP_DEFAULT | wxDP_SHOWCENTURY, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "datectrl"); + + /** + If the control had been previously limited to a range of dates using + SetRange(), returns the lower and upper bounds of this range. If no + range is set (or only one of the bounds is set), @a dt1 and/or @a dt2 + are set to be invalid. + + @param dt1 + Pointer to the object which receives the lower range limit or + becomes invalid if it is not set. May be @NULL if the caller is not + interested in lower limit. + @param dt2 + Same as above but for the upper limit. + + @return @false if no range limits are currently set, @true if at least + one bound is set. + */ + bool GetRange(wxDateTime* dt1, wxDateTime dt2) const; + + /** + Returns the currently selected. If there is no selection or the + selection is outside of the current range, an invalid object is + returned. + */ + wxDateTime GetValue() const; + + /** + Sets the display format for the date in the control. See wxDateTime for + the meaning of format strings. + + @note This function is only available in the generic version of this + control. The native version always uses the current system locale. + + @remarks If the format parameter is invalid, the behaviour is undefined. + */ + void SetFormat(const wxChar* format); + + /** + Sets the valid range for the date selection. If @a dt1 is valid, it + becomes the earliest date (inclusive) accepted by the control. If + @a dt2 is valid, it becomes the latest possible date. + + @remarks If the current value of the control is outside of the newly + set range bounds, the behaviour is undefined. + */ + void SetRange(const wxDateTime& dt1, const wxDateTime& dt2); + + /** + Changes the current value of the control. The date should be valid and + included in the currently selected range, if any. + + Calling this method does not result in a date change event. + */ + void SetValue(const wxDateTime& dt); +}; + diff --git a/interface/wx/dateevt.h b/interface/wx/dateevt.h new file mode 100644 index 0000000000..13bb4bb7e5 --- /dev/null +++ b/interface/wx/dateevt.h @@ -0,0 +1,34 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: dateevt.h +// Purpose: interface of wxDateEvent +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxDateEvent + @wxheader{dateevt.h} + + This event class holds information about a date change and is used together + with wxDatePickerCtrl. It also serves as a base class + for wxCalendarEvent. + + @library{wxadv} + @category{events} +*/ +class wxDateEvent : public wxCommandEvent +{ +public: + /** + Returns the date. + */ + const wxDateTime GetDate() const; + + /** + Sets the date carried by the event, normally only used by the library + internally. + */ + void SetDate(const wxDateTime& date); +}; + diff --git a/interface/wx/datetime.h b/interface/wx/datetime.h new file mode 100644 index 0000000000..ce9810ebb6 --- /dev/null +++ b/interface/wx/datetime.h @@ -0,0 +1,2061 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: datetime.h +// Purpose: interface of wxDateTime +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxDateTime + @wxheader{datetime.h} + + wxDateTime class represents an absolute moment in the time. + + The type @c wxDateTime_t is typedefed as unsigned short and is + used to contain the number of years, hours, minutes, seconds and + milliseconds. + + + @section datetime_constants Constants + + Global constant wxDefaultDateTime and synonym for it wxInvalidDateTime are + defined. This constant will be different from any valid wxDateTime object. + + All the following constants are defined inside wxDateTime class (i.e., to + refer to them you should prepend their names with "wxDateTime::"). + + Time zone symbolic names: + + @code + enum TZ + { + // the time in the current time zone + Local, + + // zones from GMT (= Greenwhich Mean Time): they're guaranteed to be + // consequent numbers, so writing something like `GMT0 + offset' is + // safe if abs(offset) <= 12 + + // underscore stands for minus + GMT_12, GMT_11, GMT_10, GMT_9, GMT_8, GMT_7, + GMT_6, GMT_5, GMT_4, GMT_3, GMT_2, GMT_1, + GMT0, + GMT1, GMT2, GMT3, GMT4, GMT5, GMT6, + GMT7, GMT8, GMT9, GMT10, GMT11, GMT12, GMT13, + // Note that GMT12 and GMT_12 are not the same: there is a difference + // of exactly one day between them + + // some symbolic names for TZ + + // Europe + WET = GMT0, // Western Europe Time + WEST = GMT1, // Western Europe Summer Time + CET = GMT1, // Central Europe Time + CEST = GMT2, // Central Europe Summer Time + EET = GMT2, // Eastern Europe Time + EEST = GMT3, // Eastern Europe Summer Time + MSK = GMT3, // Moscow Time + MSD = GMT4, // Moscow Summer Time + + // US and Canada + AST = GMT_4, // Atlantic Standard Time + ADT = GMT_3, // Atlantic Daylight Time + EST = GMT_5, // Eastern Standard Time + EDT = GMT_4, // Eastern Daylight Saving Time + CST = GMT_6, // Central Standard Time + CDT = GMT_5, // Central Daylight Saving Time + MST = GMT_7, // Mountain Standard Time + MDT = GMT_6, // Mountain Daylight Saving Time + PST = GMT_8, // Pacific Standard Time + PDT = GMT_7, // Pacific Daylight Saving Time + HST = GMT_10, // Hawaiian Standard Time + AKST = GMT_9, // Alaska Standard Time + AKDT = GMT_8, // Alaska Daylight Saving Time + + // Australia + + A_WST = GMT8, // Western Standard Time + A_CST = GMT13 + 1, // Central Standard Time (+9.5) + A_EST = GMT10, // Eastern Standard Time + A_ESST = GMT11, // Eastern Summer Time + + // New Zealand + NZST = GMT12, // Standard Time + NZDT = GMT13, // Daylight Saving Time + + // Universal Coordinated Time = the new and politically correct name + // for GMT + UTC = GMT0 + }; + @endcode + + Month names: Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec and + Inv_Month for an invalid month are the values of @c wxDateTime::Month enum. + + Likewise, Sun, Mon, Tue, Wed, Thu, Fri, Sat, and Inv_WeekDay are the values + in @c wxDateTime::WeekDay enum. + + Finally, Inv_Year is defined to be an invalid value for year parameter. + + GetMonthName() and GetWeekDayName() functions use the following flags: + + @code + enum NameFlags + { + Name_Full = 0x01, // return full name + Name_Abbr = 0x02 // return abbreviated name + }; + @endcode + + Several functions accept an extra parameter specifying the calendar to use + (although most of them only support now the Gregorian calendar). This + parameters is one of the following values: + + @code + enum Calendar + { + Gregorian, // calendar currently in use in Western countries + Julian // calendar in use since -45 until the 1582 (or later) + }; + @endcode + + Date calculations often depend on the country and wxDateTime allows to set + the country whose conventions should be used using SetCountry(). It takes + one of the following values as parameter: + + @code + enum Country + { + Country_Unknown, // no special information for this country + Country_Default, // set the default country with SetCountry() method + // or use the default country with any other + + Country_WesternEurope_Start, + Country_EEC = Country_WesternEurope_Start, + France, + Germany, + UK, + Country_WesternEurope_End = UK, + + Russia, + + USA + }; + @endcode + + Different parts of the world use different conventions for the week start. + In some countries, the week starts on Sunday, while in others -- on Monday. + The ISO standard doesn't address this issue, so we support both conventions + in the functions whose result depends on it (GetWeekOfYear() and + GetWeekOfMonth()). + + The desired behvaiour may be specified by giving one of the following + constants as argument to these functions: + + @code + enum WeekFlags + { + Default_First, // Sunday_First for US, Monday_First for the rest + Monday_First, // week starts with a Monday + Sunday_First // week starts with a Sunday + }; + @endcode + + + @section datetime_static Static Functions + + All static functions either set or return the static variables of + wxDateSpan (the country), return the current moment, year, month or number + of days in it, or do some general calendar-related actions. + + Please note that although several function accept an extra Calendar + parameter, it is currently ignored as only the Gregorian calendar is + supported. Future versions will support other calendars. + + @beginWxPythonOnly + These methods are standalone functions named + "wxDateTime_" in wxPython. + @endWxPythonOnly + + + @section datetime_formatting Date Formatting and Parsing + + The date formatting and parsing functions convert wxDateTime objects to and + from text. The conversions to text are mostly trivial: you can either do it + using the default date and time representations for the current locale + (FormatDate() and FormatTime()), using the international standard + representation defined by ISO 8601 (FormatISODate(), FormatISOTime() and + FormatISOCombined()) or by specifying any format at all and using Format() + directly. + + The conversions from text are more interesting, as there are much more + possibilities to care about. The simplest cases can be taken care of with + ParseFormat() which can parse any date in the given (rigid) format. + ParseRfc822Date() is another function for parsing dates in predefined + format -- the one of RFC 822 which (still...) defines the format of email + messages on the Internet. This format can not be described with + @c strptime(3)-like format strings used by Format(), hence the need for a + separate function. + + But the most interesting functions are ParseTime(), ParseDate() and + ParseDateTime(). They try to parse the date and time (or only one of them) + in 'free' format, i.e. allow them to be specified in any of possible ways. + These functions will usually be used to parse the (interactive) user input + which is not bound to be in any predefined format. As an example, + ParseDateTime() can parse the strings such as "tomorrow", "March first" and + even "next Sunday". + + Finally notice that each of the parsing functions is available in several + overloads: if the input string is a narrow (@c char *) string, then a + narrow pointer is returned. If the input string is a wide string, a wide + char pointer is returned. Finally, if the input parameter is a wxString, a + narrow char pointer is also returned for backwards compatibility but there + is also an additional argument of wxString::const_iterator type in which, + if it is not @NULL, an iterator pointing to the end of the scanned string + part is returned. + + + @library{wxbase} + @category{data} + + @stdobjects + - ::wxDefaultDateTime + + @see @ref overview_datetime, wxTimeSpan, wxDateSpan, wxCalendarCtrl +*/ +class wxDateTime +{ +public: + /** + @name Constructors, Assignment Operators and Setters + + Constructors and various Set() methods are collected here. If you + construct a date object from separate values for day, month and year, + you should use IsValid() method to check that the values were correct + as constructors can not return an error code. + */ + //@{ + + /** + Default constructor. Use one of the Set() functions to initialize the + object later. + */ + wxDateTime(); + /** + Same as Set(). + + @beginWxPythonOnly + This constructor is named "wxDateTimeFromTimeT" in wxPython. + @endWxPythonOnly + */ + wxDateTime& wxDateTime(time_t timet); + /** + Same as Set(). + + @beginWxPythonOnly Unsupported. @endWxPythonOnly + */ + wxDateTime& wxDateTime(const struct tm& tm); + /** + Same as Set(). + + @beginWxPythonOnly + This constructor is named "wxDateTimeFromJDN" in wxPython. + @endWxPythonOnly + */ + wxDateTime& wxDateTime(double jdn); + /** + Same as Set(). + + @beginWxPythonOnly + This constructor is named "wxDateTimeFromHMS" in wxPython. + @endWxPythonOnly + */ + wxDateTime& wxDateTime(wxDateTime_t hour, wxDateTime_t minute = 0, + wxDateTime_t second = 0, wxDateTime_t millisec = 0); + /** + Same as Set(). + + @beginWxPythonOnly + This constructor is named "wxDateTimeFromDMY" in wxPython. + @endWxPythonOnly + */ + wxDateTime(wxDateTime_t day, Month month = Inv_Month, + int year = Inv_Year, wxDateTime_t hour = 0, + wxDateTime_t minute = 0, wxDateTime_t second = 0, + wxDateTime_t millisec = 0); + + /** + Same as SetFromMSWSysTime. + + @param st + Input, Windows SYSTEMTIME reference + @since 2.9.0 + @remarks MSW only + */ + wxDateTime(const struct _SYSTEMTIME& st); + + + /** + Reset time to midnight (00:00:00) without changing the date. + */ + wxDateTime& ResetTime(); + + /** + Constructs the object from @a timet value holding the number of seconds + since Jan 1, 1970. + + @beginWxPythonOnly + This method is named "SetTimeT" in wxPython. + @endWxPythonOnly + */ + wxDateTime& Set(time_t timet); + /** + Sets the date and time from the broken down representation in the + standard @a tm structure. + + @beginWxPythonOnly Unsupported. @endWxPythonOnly + */ + wxDateTime& Set(const struct tm& tm); + /** + Sets the date from the so-called Julian Day Number. + + By definition, the Julian Day Number, usually abbreviated as JDN, of a + particular instant is the fractional number of days since 12 hours + Universal Coordinated Time (Greenwich mean noon) on January 1 of the + year -4712 in the Julian proleptic calendar. + + @beginWxPythonOnly + This method is named "SetJDN" in wxPython. + @endWxPythonOnly + */ + wxDateTime& Set(double jdn); + /** + Sets the date to be equal to Today() and the time from supplied + parameters. + + @beginWxPythonOnly + This method is named "SetHMS" in wxPython. + @endWxPythonOnly + */ + wxDateTime& Set(wxDateTime_t hour, wxDateTime_t minute = 0, + wxDateTime_t second = 0, wxDateTime_t millisec = 0); + /** + Sets the date and time from the parameters. + */ + wxDateTime& Set(wxDateTime_t day, Month month = Inv_Month, + int year = Inv_Year, wxDateTime_t hour = 0, + wxDateTime_t minute = 0, wxDateTime_t second = 0, + wxDateTime_t millisec = 0); + + /** + Sets the day without changing other date components. + */ + wxDateTime& SetDay(short unsigned int); + + /** + Sets the date from the date and time in DOS format. + */ + wxDateTime& SetFromDOS(unsigned long ddt); + + /** + Sets the hour without changing other date components. + */ + wxDateTime& SetHour(short unsigned int); + + /** + Sets the millisecond without changing other date components. + */ + wxDateTime& SetMillisecond(short unsigned int); + + /** + Sets the minute without changing other date components. + */ + wxDateTime& SetMinute(short unsigned int); + + /** + Sets the month without changing other date components. + */ + wxDateTime& SetMonth(Month month); + + /** + Sets the second without changing other date components. + */ + wxDateTime& SetSecond(short unsigned int); + + /** + Sets the date and time of to the current values. Same as assigning the + result of Now() to this object. + */ + wxDateTime& SetToCurrent(); + + /** + Sets the year without changing other date components. + */ + wxDateTime& SetYear(int year); + + /** + Same as Set(). + */ + wxDateTime& operator=(time_t timet); + /** + Same as Set(). + */ + wxDateTime& operator=(const struct tm& tm); + + //@} + + + + /** + @name Accessors + + Here are the trivial accessors. Other functions, which might have to + perform some more complicated calculations to find the answer are under + the "Date Arithmetics" section. + */ + //@{ + + /** + Returns the date and time in DOS format. + */ + long unsigned int GetAsDOS() const; + + /** + Initialize using the Windows SYSTEMTIME structure. + @param st + Input, Windows SYSTEMTIME reference + @since 2.9.0 + @remarks MSW only + */ + wxDateTime& SetFromMSWSysTime(const struct _SYSTEMTIME& st); + + /** + Returns the date and time in the Windows SYSTEMTIME format. + @param st + Output, pointer to Windows SYSTEMTIME + @since 2.9.0 + @remarks MSW only + */ + void GetAsMSWSysTime(struct _SYSTEMTIME* st) const; + + /** + Returns the century of this date. + */ + int GetCentury(const TimeZone& tz = Local) const; + + /** + Returns the object having the same date component as this one but time + of 00:00:00. + + @since 2.8.2 + + @see ResetTime() + */ + wxDateTime GetDateOnly() const; + + /** + Returns the day in the given timezone (local one by default). + */ + short unsigned int GetDay(const TimeZone& tz = Local) const; + + /** + Returns the day of the year (in 1-366 range) in the given timezone + (local one by default). + */ + short unsigned int GetDayOfYear(const TimeZone& tz = Local) const; + + /** + Returns the hour in the given timezone (local one by default). + */ + short unsigned int GetHour(const TimeZone& tz = Local) const; + + /** + Returns the milliseconds in the given timezone (local one by default). + */ + short unsigned int GetMillisecond(const TimeZone& tz = Local) const; + + /** + Returns the minute in the given timezone (local one by default). + */ + short unsigned int GetMinute(const TimeZone& tz = Local) const; + + /** + Returns the month in the given timezone (local one by default). + */ + Month GetMonth(const TimeZone& tz = Local) const; + + /** + Returns the seconds in the given timezone (local one by default). + */ + short unsigned int GetSecond(const TimeZone& tz = Local) const; + + /** + Returns the number of seconds since Jan 1, 1970. An assert failure will + occur if the date is not in the range covered by @c time_t type. + */ + time_t GetTicks() const; + + /** + Returns broken down representation of the date and time. + */ + Tm GetTm(const TimeZone& tz = Local) const; + + /** + Returns the week day in the given timezone (local one by default). + */ + WeekDay GetWeekDay(const TimeZone& tz = Local) const; + + /** + Returns the ordinal number of the week in the month (in 1-5 range). + + As GetWeekOfYear(), this function supports both conventions for the + week start. See the description of these @c WeekFlags in the + @ref datetime_constants section. + */ + wxDateTime_t GetWeekOfMonth(WeekFlags flags = Monday_First, + const TimeZone& tz = Local) const; + + /** + Returns the number of the week of the year this date is in. The first + week of the year is, according to international standards, the one + containing Jan 4 or, equivalently, the first week which has Thursday in + this year. Both of these definitions are the same as saying that the + first week of the year must contain more than half of its days in this + year. Accordingly, the week number will always be in 1-53 range (52 for + non-leap years). + + The function depends on the @ref datetime_constants "week start" + convention specified by the @a flags argument but its results for + @c Sunday_First are not well-defined as the ISO definition quoted above + applies to the weeks starting on Monday only. + */ + wxDateTime_t GetWeekOfYear(WeekFlags flags = Monday_First, + const TimeZone& tz = Local) const; + + /** + Returns the year in the given timezone (local one by default). + */ + int GetYear(const TimeZone& tz = Local) const; + + /** + Returns @true if the given date is later than the date of adoption of + the Gregorian calendar in the given country (and hence the Gregorian + calendar calculations make sense for it). + */ + bool IsGregorianDate(GregorianAdoption country = Gr_Standard) const; + + /** + Returns @true if the object represents a valid time moment. + */ + bool IsValid() const; + + /** + Returns @true is this day is not a holiday in the given country. + */ + bool IsWorkDay(Country country = Country_Default) const; + + //@} + + + + /** + @name Date Comparison + + There are several functions to allow date comparison. To supplement + them, a few global operators, etc taking wxDateTime are defined. + */ + //@{ + + /** + Returns @true if this date precedes the given one. + */ + bool IsEarlierThan(const wxDateTime& datetime) const; + + /** + Returns @true if the two dates are strictly identical. + */ + bool IsEqualTo(const wxDateTime& datetime) const; + + /** + Returns @true if the date is equal to another one up to the given time + interval, i.e. if the absolute difference between the two dates is less + than this interval. + */ + bool IsEqualUpTo(const wxDateTime& dt, const wxTimeSpan& ts) const; + + /** + Returns @true if this date is later than the given one. + */ + bool IsLaterThan(const wxDateTime& datetime) const; + + /** + Returns @true if the date is the same without comparing the time parts. + */ + bool IsSameDate(const wxDateTime& dt) const; + + /** + Returns @true if the time is the same (although dates may differ). + */ + bool IsSameTime(const wxDateTime& dt) const; + + /** + Returns @true if this date lies strictly between the two given dates. + + @see IsBetween() + */ + bool IsStrictlyBetween(const wxDateTime& t1, + const wxDateTime& t2) const; + + /** + Returns @true if IsStrictlyBetween() is @true or if the date is equal + to one of the limit values. + + @see IsStrictlyBetween() + */ + bool IsBetween(const wxDateTime& t1, const wxDateTime& t2) const; + + //@} + + + + /** + @name Date Arithmetics + + These functions carry out + @ref overview_datetime_arithmetics "arithmetics" on the wxDateTime + objects. As explained in the overview, either wxTimeSpan or wxDateSpan + may be added to wxDateTime, hence all functions are overloaded to + accept both arguments. + + Also, both Add() and Subtract() have both const and non-const version. + The first one returns a new object which represents the sum/difference + of the original one with the argument while the second form modifies + the object to which it is applied. The operators "-=" and "+=" are + defined to be equivalent to the second forms of these functions. + */ + //@{ + + /** + Adds the given date span to this object. + + @beginWxPythonOnly + This method is named "AddDS" in wxPython. + @endWxPythonOnly + */ + wxDateTime Add(const wxDateSpan& diff) const; + /** + Adds the given date span to this object. + + @beginWxPythonOnly + This method is named "AddDS" in wxPython. + @endWxPythonOnly + */ + wxDateTime Add(const wxDateSpan& diff); + /** + Adds the given time span to this object. + + @beginWxPythonOnly + This method is named "AddTS" in wxPython. + @endWxPythonOnly + */ + wxDateTime Add(const wxTimeSpan& diff) const; + /** + Adds the given time span to this object. + + @beginWxPythonOnly + This method is named "AddTS" in wxPython. + @endWxPythonOnly + */ + wxDateTime& Add(const wxTimeSpan& diff); + + /** + Subtracts the given time span from this object. + + @beginWxPythonOnly + This method is named "SubtractTS" in wxPython. + @endWxPythonOnly + */ + wxDateTime Subtract(const wxTimeSpan& diff) const; + /** + Subtracts the given time span from this object. + + @beginWxPythonOnly + This method is named "SubtractTS" in wxPython. + @endWxPythonOnly + */ + wxDateTime& Subtract(const wxTimeSpan& diff); + /** + Subtracts the given date span from this object. + + @beginWxPythonOnly + This method is named "SubtractDS" in wxPython. + @endWxPythonOnly + */ + wxDateTime Subtract(const wxDateSpan& diff) const; + /** + Subtracts the given date span from this object. + + @beginWxPythonOnly + This method is named "SubtractDS" in wxPython. + @endWxPythonOnly + */ + wxDateTime& Subtract(const wxDateSpan& diff); + /** + Subtracts another date from this one and returns the difference between + them as a wxTimeSpan. + */ + wxTimeSpan Subtract(const wxDateTime& dt) const; + + /** + Adds the given date span to this object. + */ + wxDateTime operator+=(const wxDateSpan& diff); + /** + Subtracts the given date span from this object. + */ + wxDateTime& operator-=(const wxDateSpan& diff); + /** + Adds the given time span to this object. + */ + wxDateTime& operator+=(const wxTimeSpan& diff); + /** + Subtracts the given time span from this object. + */ + wxDateTime& operator-=(const wxTimeSpan& diff); + + //@} + + + + /** + @name Date Formatting and Parsing + + See @ref datetime_formatting + */ + //@{ + + /** + This function does the same as the standard ANSI C @c strftime(3) + function. Please see its description for the meaning of @a format + parameter. + + It also accepts a few wxWidgets-specific extensions: you can optionally + specify the width of the field to follow using @c printf(3)-like syntax + and the format specification @c "%l" can be used to get the number of + milliseconds. + + @see ParseFormat() + */ + wxString Format(const wxChar* format = wxDefaultDateTimeFormat, + const TimeZone& tz = Local) const; + + /** + Identical to calling Format() with @c "%x" argument (which means + "preferred date representation for the current locale"). + */ + wxString FormatDate() const; + + /** + Returns the combined date-time representation in the ISO 8601 format + @c "YYYY-MM-DDTHH:MM:SS". The @a sep parameter default value produces + the result exactly corresponding to the ISO standard, but it can also + be useful to use a space as seprator if a more human-readable combined + date-time representation is needed. + + @see FormatISODate(), FormatISOTime(), ParseISOCombined() + */ + wxString FormatISOCombined(char sep = 'T') const; + + /** + This function returns the date representation in the ISO 8601 format + @c "YYYY-MM-DD". + */ + wxString FormatISODate() const; + + /** + This function returns the time representation in the ISO 8601 format + @c "HH:MM:SS". + */ + wxString FormatISOTime() const; + + /** + Identical to calling Format() with @c "%X" argument (which means + "preferred time representation for the current locale"). + */ + wxString FormatTime() const; + + /** + This function is like ParseDateTime(), but it only allows the date to + be specified. It is thus less flexible then ParseDateTime(), but also + has less chances to misinterpret the user input. + + @return @NULL if the conversion failed, otherwise return the pointer + to the character which stopped the scan. + */ + const char* ParseDate(const wxString& date, + wxString::const_iterator* end = NULL); + /** + This function is like ParseDateTime(), but it only allows the date to + be specified. It is thus less flexible then ParseDateTime(), but also + has less chances to misinterpret the user input. + + @return @NULL if the conversion failed, otherwise return the pointer + to the character which stopped the scan. + */ + const char* ParseDate(const char* date); + /** + This function is like ParseDateTime(), but it only allows the date to + be specified. It is thus less flexible then ParseDateTime(), but also + has less chances to misinterpret the user input. + + @return @NULL if the conversion failed, otherwise return the pointer + to the character which stopped the scan. + */ + const wchar_t* ParseDate(const wchar_t* date); + + /** + Parses the string @a datetime containing the date and time in free + format. This function tries as hard as it can to interpret the given + string as date and time. Unlike ParseRfc822Date(), it will accept + anything that may be accepted and will only reject strings which can + not be parsed in any way at all. + + @return @NULL if the conversion failed, otherwise return the pointer + to the character which stopped the scan. + */ + const char* ParseDateTime(const wxString& datetime, + wxString::const_iterator* end = NULL); + /** + Parses the string @a datetime containing the date and time in free + format. This function tries as hard as it can to interpret the given + string as date and time. Unlike ParseRfc822Date(), it will accept + anything that may be accepted and will only reject strings which can + not be parsed in any way at all. + + @return @NULL if the conversion failed, otherwise return the pointer + to the character which stopped the scan. + */ + const char* ParseDateTime(const char* datetime); + /** + Parses the string @a datetime containing the date and time in free + format. This function tries as hard as it can to interpret the given + string as date and time. Unlike ParseRfc822Date(), it will accept + anything that may be accepted and will only reject strings which can + not be parsed in any way at all. + + @return @NULL if the conversion failed, otherwise return the pointer + to the character which stopped the scan. + */ + const wchar_t* ParseDateTime(const wchar_t* datetime); + + /** + This function parses the string @a date according to the given + @e format. The system @c strptime(3) function is used whenever + available, but even if it is not, this function is still implemented, + although support for locale-dependent format specifiers such as + @c "%c", @c "%x" or @c "%X" may not be perfect and GNU extensions such + as @c "%z" and @c "%Z" are not implemented. This function does handle + the month and weekday names in the current locale on all platforms, + however. + + Please see the description of the ANSI C function @c strftime(3) for + the syntax of the format string. + + The @a dateDef parameter is used to fill in the fields which could not + be determined from the format string. For example, if the format is + @c "%d" (the day of the month), the month and the year are taken from + @a dateDef. If it is not specified, Today() is used as the default + date. + + @return @NULL if the conversion failed, otherwise return the pointer + to the character which stopped the scan. + */ + const char* ParseFormat(const wxString& date, + const wxString& format = wxDefaultDateTimeFormat, + const wxDateTime& dateDef = wxDefaultDateTime, + wxString::const_iterator* end = NULL); + /** + This function parses the string @a date according to the given + @e format. The system @c strptime(3) function is used whenever + available, but even if it is not, this function is still implemented, + although support for locale-dependent format specifiers such as + @c "%c", @c "%x" or @c "%X" may not be perfect and GNU extensions such + as @c "%z" and @c "%Z" are not implemented. This function does handle + the month and weekday names in the current locale on all platforms, + however. + + Please see the description of the ANSI C function @c strftime(3) for + the syntax of the format string. + + The @a dateDef parameter is used to fill in the fields which could not + be determined from the format string. For example, if the format is + @c "%d" (the day of the month), the month and the year are taken from + @a dateDef. If it is not specified, Today() is used as the default + date. + + @return @NULL if the conversion failed, otherwise return the pointer + to the character which stopped the scan. + */ + const char* ParseFormat(const char* date, + const wxString& format = wxDefaultDateTimeFormat, + const wxDateTime& dateDef = wxDefaultDateTime); + /** + This function parses the string @a date according to the given + @e format. The system @c strptime(3) function is used whenever + available, but even if it is not, this function is still implemented, + although support for locale-dependent format specifiers such as + @c "%c", @c "%x" or @c "%X" may not be perfect and GNU extensions such + as @c "%z" and @c "%Z" are not implemented. This function does handle + the month and weekday names in the current locale on all platforms, + however. + + Please see the description of the ANSI C function @c strftime(3) for + the syntax of the format string. + + The @a dateDef parameter is used to fill in the fields which could not + be determined from the format string. For example, if the format is + @c "%d" (the day of the month), the month and the year are taken from + @a dateDef. If it is not specified, Today() is used as the default + date. + + @return @NULL if the conversion failed, otherwise return the pointer + to the character which stopped the scan. + */ + const wchar_t* ParseFormat(const wchar_t* date, + const wxString& format = wxDefaultDateTimeFormat, + const wxDateTime& dateDef = wxDefaultDateTime); + + /** + This function parses the string containing the date and time in ISO + 8601 combined format @c "YYYY-MM-DDTHH:MM:SS". The separator between + the date and time parts must be equal to @a sep for the function to + succeed. + + @return @true if the entire string was parsed successfully, @false + otherwise. + */ + bool ParseISOCombined(const wxString& date, char sep = 'T'); + + /** + This function parses the date in ISO 8601 format @c "YYYY-MM-DD". + + @return @true if the entire string was parsed successfully, @false + otherwise. + */ + bool ParseISODate(const wxString& date); + + /** + This function parses the time in ISO 8601 format @c "HH:MM:SS". + + @return @true if the entire string was parsed successfully, @false + otherwise. + */ + bool ParseISOTime(const wxString& date); + + /** + Parses the string @a date looking for a date formatted according to the + RFC 822 in it. The exact description of this format may, of course, be + found in the RFC (section 5), but, briefly, this is the format used in + the headers of Internet email messages and one of the most common + strings expressing date in this format may be something like + @c "Sat, 18 Dec 1999 00:48:30 +0100". + + Returns @NULL if the conversion failed, otherwise return the pointer to + the character immediately following the part of the string which could + be parsed. If the entire string contains only the date in RFC 822 + format, the returned pointer will be pointing to a @c NUL character. + + This function is intentionally strict, it will return an error for any + string which is not RFC 822 compliant. If you need to parse date + formatted in more free ways, you should use ParseDateTime() or + ParseDate() instead. + */ + const char* ParseRfc822Date(const wxString& date, + wxString::const_iterator* end = NULL); + /** + Parses the string @a date looking for a date formatted according to the + RFC 822 in it. The exact description of this format may, of course, be + found in the RFC (section 5), but, briefly, this is the format used in + the headers of Internet email messages and one of the most common + strings expressing date in this format may be something like + @c "Sat, 18 Dec 1999 00:48:30 +0100". + + Returns @NULL if the conversion failed, otherwise return the pointer to + the character immediately following the part of the string which could + be parsed. If the entire string contains only the date in RFC 822 + format, the returned pointer will be pointing to a @c NUL character. + + This function is intentionally strict, it will return an error for any + string which is not RFC 822 compliant. If you need to parse date + formatted in more free ways, you should use ParseDateTime() or + ParseDate() instead. + */ + const char* ParseRfc822Date(const char* date); + /** + Parses the string @a date looking for a date formatted according to the + RFC 822 in it. The exact description of this format may, of course, be + found in the RFC (section 5), but, briefly, this is the format used in + the headers of Internet email messages and one of the most common + strings expressing date in this format may be something like + @c "Sat, 18 Dec 1999 00:48:30 +0100". + + Returns @NULL if the conversion failed, otherwise return the pointer to + the character immediately following the part of the string which could + be parsed. If the entire string contains only the date in RFC 822 + format, the returned pointer will be pointing to a @c NUL character. + + This function is intentionally strict, it will return an error for any + string which is not RFC 822 compliant. If you need to parse date + formatted in more free ways, you should use ParseDateTime() or + ParseDate() instead. + */ + const wchar_t* ParseRfc822Date(const wchar_t* date); + + /** + This functions is like ParseDateTime(), but only allows the time to be + specified in the input string. + + @return @NULL if the conversion failed, otherwise return the pointer + to the character which stopped the scan. + */ + const char* ParseTime(const wxString& time, + wxString::const_iterator* end = NULL); + /** + This functions is like ParseDateTime(), but only allows the time to be + specified in the input string. + + @return @NULL if the conversion failed, otherwise return the pointer + to the character which stopped the scan. + */ + const char* ParseTime(const char* time); + /** + This functions is like ParseDateTime(), but only allows the time to be + specified in the input string. + + @return @NULL if the conversion failed, otherwise return the pointer + to the character which stopped the scan. + */ + const wchar_t* ParseTime(const wchar_t* time); + + //@} + + + + /** + @name Calendar Calculations + + The functions in this section perform the basic calendar calculations, + mostly related to the week days. They allow to find the given week day + in the week with given number (either in the month or in the year) and + so on. + + None of the functions in this section modify the time part of the + wxDateTime, they only work with the date part of it. + */ + //@{ + + /** + Returns the copy of this object to which SetToLastMonthDay() was + applied. + */ + wxDateTime GetLastMonthDay(Month month = Inv_Month, + int year = Inv_Year) const; + + /** + Returns the copy of this object to which SetToLastWeekDay() was + applied. + */ + wxDateTime GetLastWeekDay(WeekDay weekday, Month month = Inv_Month, + int year = Inv_Year); + + /** + Returns the copy of this object to which SetToNextWeekDay() was + applied. + */ + wxDateTime GetNextWeekDay(WeekDay weekday) const; + + /** + Returns the copy of this object to which SetToPrevWeekDay() was + applied. + */ + wxDateTime GetPrevWeekDay(WeekDay weekday) const; + + /** + Returns the copy of this object to which SetToWeekDay() was applied. + */ + wxDateTime GetWeekDay(WeekDay weekday, int n = 1, Month month = Inv_Month, + int year = Inv_Year) const; + + /** + Returns the copy of this object to which SetToWeekDayInSameWeek() was + applied. + */ + wxDateTime GetWeekDayInSameWeek(WeekDay weekday, + WeekFlags flags = Monday_First) const; + + /** + Returns the copy of this object to which SetToYearDay() was applied. + */ + wxDateTime GetYearDay(wxDateTime_t yday) const; + + /** + Sets the date to the last day in the specified month (the current one + by default). + + @return The reference to the modified object itself. + */ + wxDateTime SetToLastMonthDay(Month month = Inv_Month, + int year = Inv_Year); + + /** + The effect of calling this function is the same as of calling + @c SetToWeekDay(-1, weekday, month, year). The date will be set to the + last @a weekday in the given month and year (the current ones by + default). Always returns @true. + */ + bool SetToLastWeekDay(WeekDay weekday, Month month = Inv_Month, + int year = Inv_Year); + + /** + Sets the date so that it will be the first @a weekday following the + current date. + + @return The reference to the modified object itself. + */ + wxDateTime& SetToNextWeekDay(WeekDay weekday); + + /** + Sets the date so that it will be the last @a weekday before the current + date. + + @return The reference to the modified object itself. + */ + wxDateTime& SetToPrevWeekDay(WeekDay weekday); + + /** + Sets the date to the @e n-th @a weekday in the given month of the given + year (the current month and year are used by default). The parameter + @a n may be either positive (counting from the beginning of the month) + or negative (counting from the end of it). + + For example, SetToWeekDay(2, wxDateTime::Wed) will set the date to the + second Wednesday in the current month and + SetToWeekDay(-1, wxDateTime::Sun) will set the date to the last Sunday + in the current month. + + @return @true if the date was modified successfully, @false otherwise + meaning that the specified date doesn't exist. + */ + bool SetToWeekDay(WeekDay weekday, int n = 1, + Month month = Inv_Month, int year = Inv_Year); + + /** + Adjusts the date so that it will still lie in the same week as before, + but its week day will be the given one. + + @return The reference to the modified object itself. + */ + wxDateTime SetToWeekDayInSameWeek(WeekDay weekday, + WeekFlags flags = Monday_First); + + /** + Sets the date to the day number @a yday in the same year (i.e., unlike + the other functions, this one does not use the current year). The day + number should be in the range 1-366 for the leap years and 1-365 for + the other ones. + + @return The reference to the modified object itself. + */ + wxDateTime& SetToYearDay(wxDateTime_t yday); + + //@} + + + + /** + @name Astronomical/Historical Functions + + Some degree of support for the date units used in astronomy and/or + history is provided. You can construct a wxDateTime object from a + JDN and you may also get its JDN, MJD or Rata Die number from it. + + Related functions in other groups: wxDateTime(double), Set(double) + */ + //@{ + + /** + Synonym for GetJulianDayNumber(). + */ + double GetJDN() const; + + /** + Returns the JDN corresponding to this date. Beware of rounding errors! + + @see GetModifiedJulianDayNumber() + */ + double GetJulianDayNumber() const; + + /** + Synonym for GetModifiedJulianDayNumber(). + */ + double GetMJD() const; + + /** + Returns the @e "Modified Julian Day Number" (MJD) which is, by + definition, is equal to JDN - 2400000.5. The MJDs are simpler to work + with as the integral MJDs correspond to midnights of the dates in the + Gregorian calendar and not the noons like JDN. The MJD 0 represents + Nov 17, 1858. + */ + double GetModifiedJulianDayNumber() const; + + /** + Return the @e Rata Die number of this date. + + By definition, the Rata Die number is a date specified as the number of + days relative to a base date of December 31 of the year 0. Thus January + 1 of the year 1 is Rata Die day 1. + */ + double GetRataDie() const; + + //@} + + + + /** + @name Time Zone and DST Support + + Please see the @ref overview_datetime_timezones "time zone overview" + for more information about time zones. Normally, these functions should + be rarely used. + + Related functions in other groups: GetBeginDST(), GetEndDST() + */ + //@{ + + /** + Transform the date from the given time zone to the local one. If + @a noDST is @true, no DST adjustments will be made. + + @return The date in the local time zone. + */ + wxDateTime FromTimezone(const TimeZone& tz, bool noDST = false) const; + + /** + Returns @true if the DST is applied for this date in the given country. + + @see GetBeginDST(), GetEndDST() + */ + int IsDST(Country country = Country_Default) const; + + /** + Same as FromTimezone() but modifies the object in place. + */ + wxDateTime MakeFromTimezone(const TimeZone& tz, bool noDST = false); + + /** + Modifies the object in place to represent the date in another time + zone. If @a noDST is @true, no DST adjustments will be made. + */ + wxDateTime MakeTimezone(const TimeZone& tz, bool noDST = false); + + /** + This is the same as calling MakeTimezone() with the argument @c GMT0. + */ + wxDateTime& MakeUTC(bool noDST = false); + + /** + Transform the date to the given time zone. If @a noDST is @true, no DST + adjustments will be made. + + @return The date in the new time zone. + */ + wxDateTime ToTimezone(const TimeZone& tz, bool noDST = false) const; + + /** + This is the same as calling ToTimezone() with the argument @c GMT0. + */ + wxDateTime ToUTC(bool noDST = false) const; + + //@} + + + + + + /** + Converts the year in absolute notation (i.e. a number which can be + negative, positive or zero) to the year in BC/AD notation. For the + positive years, nothing is done, but the year 0 is year 1 BC and so for + other years there is a difference of 1. + + This function should be used like this: + + @code + wxDateTime dt(...); + int y = dt.GetYear(); + printf("The year is %d%s", wxDateTime::ConvertYearToBC(y), y > 0 ? "AD" : "BC"); + @endcode + */ + static int ConvertYearToBC(int year); + + /** + Returns the translations of the strings @c AM and @c PM used for time + formatting for the current locale. Either of the pointers may be @NULL + if the corresponding value is not needed. + */ + static void GetAmPmStrings(wxString* am, wxString* pm); + + /** + Get the beginning of DST for the given country in the given year + (current one by default). This function suffers from limitations + described in the @ref overview_datetime_dst "DST overview". + + @see GetEndDST() + */ + static wxDateTime GetBeginDST(int year = Inv_Year, + Country country = Country_Default); + + /** + Returns the end of DST for the given country in the given year (current + one by default). + + @see GetBeginDST() + */ + static wxDateTime GetEndDST(int year = Inv_Year, + Country country = Country_Default); + + /** + Get the current century, i.e. first two digits of the year, in given + calendar (only Gregorian is currently supported). + */ + static int GetCentury(int year); + + /** + Returns the current default country. The default country is used for + DST calculations, for example. + + @see SetCountry() + */ + static Country GetCountry(); + + /** + Get the current month in given calendar (only Gregorian is currently + supported). + */ + static Month GetCurrentMonth(Calendar cal = Gregorian); + + /** + Get the current year in given calendar (only Gregorian is currently + supported). + */ + static int GetCurrentYear(Calendar cal = Gregorian); + + /** + Gets the full (default) or abbreviated (specify @c Name_Abbr name of + the given month. + + @see GetWeekDayName() + */ + static wxString GetMonthName(Month month, NameFlags flags = Name_Full); + + /** + Returns the number of days in the given year. The only supported value + for @a cal currently is @c Gregorian. + + @beginWxPythonOnly + This method is named "GetNumberOfDaysInYear" in wxPython. + @endWxPythonOnly + */ + static wxDateTime_t GetNumberOfDays(int year, Calendar cal = Gregorian); + + /** + Returns the number of days in the given month of the given year. The + only supported value for @a cal currently is @c Gregorian. + + @beginWxPythonOnly + This method is named "GetNumberOfDaysInMonth" in wxPython. + @endWxPythonOnly + */ + static wxDateTime_t GetNumberOfDays(Month month, int year = Inv_Year, + Calendar cal = Gregorian); + + /** + Returns the current time. + */ + static time_t GetTimeNow(); + + /** + Returns the current time broken down using the buffer whose adress is + passed to the function with @a tm to store the result. + */ + static struct tm* GetTmNow(struct tm *tm); + + /** + Returns the current time broken down. Note that this function returns a + pointer to a static buffer that's reused by calls to this function and + certain C library functions (e.g. localtime). If there is any chance + your code might be used in a multi-threaded application, you really + should use GetTmNow(struct tm *) instead. + */ + static struct tm* GetTmNow(); + + /** + Gets the full (default) or abbreviated (specify @c Name_Abbr) name of + the given week day. + + @see GetMonthName() + */ + static wxString GetWeekDayName(WeekDay weekday, + NameFlags flags = Name_Full); + + /** + Returns @true if DST was used n the given year (the current one by + default) in the given country. + */ + static bool IsDSTApplicable(int year = Inv_Year, + Country country = Country_Default); + + /** + Returns @true if the @a year is a leap one in the specified calendar. + This functions supports Gregorian and Julian calendars. + */ + static bool IsLeapYear(int year = Inv_Year, Calendar cal = Gregorian); + + /** + This function returns @true if the specified (or default) country is + one of Western European ones. It is used internally by wxDateTime to + determine the DST convention and date and time formatting rules. + */ + static bool IsWestEuropeanCountry(Country country = Country_Default); + + /** + Returns the object corresponding to the current time. + + Example: + + @code + wxDateTime now = wxDateTime::Now(); + printf("Current time in Paris:\t%s\n", now.Format("%c", wxDateTime::CET).c_str()); + @endcode + + @note This function is accurate up to seconds. UNow() should be used + for better precision, but it is less efficient and might not be + available on all platforms. + + @see Today() + */ + static wxDateTime Now(); + + /** + Sets the country to use by default. This setting influences the DST + calculations, date formatting and other things. + + The possible values for @a country parameter are enumerated in the + @ref datetime_constants section. + + @see GetCountry() + */ + static void SetCountry(Country country); + + /** + Set the date to the given @a weekday in the week number @a numWeek of + the given @a year . The number should be in range 1-53. + + Note that the returned date may be in a different year than the one + passed to this function because both the week 1 and week 52 or 53 (for + leap years) contain days from different years. See GetWeekOfYear() for + the explanation of how the year weeks are counted. + */ + static wxDateTime SetToWeekOfYear(int year, wxDateTime_t numWeek, + WeekDay weekday = Mon); + + /** + Returns the object corresponding to the midnight of the current day + (i.e. the same as Now(), but the time part is set to 0). + + @see Now() + */ + static wxDateTime Today(); + + /** + Returns the object corresponding to the current time including the + milliseconds if a function to get time with such precision is available + on the current platform (supported under most Unices and Win32). + + @see Now() + */ + static wxDateTime UNow(); +}; + +/** + Global instance of an empty wxDateTime object. + + @todo Would it be better to rename this wxNullDateTime so it's consistent + with the rest of the "empty/invalid/null" global objects? +*/ +const wxDateTime wxDefaultDateTime; + + + +/** + @class wxDateTimeWorkDays + @wxheader{datetime.h} + + @todo Write wxDateTimeWorkDays documentation. + + @library{wxbase} + @category{data} +*/ +class wxDateTimeWorkDays +{ +public: + +}; + + + +/** + @class wxDateSpan + @wxheader{datetime.h} + + This class is a "logical time span" and is useful for implementing program + logic for such things as "add one month to the date" which, in general, + doesn't mean to add 60*60*24*31 seconds to it, but to take the same date + the next month (to understand that this is indeed different consider adding + one month to Feb, 15 -- we want to get Mar, 15, of course). + + When adding a month to the date, all lesser components (days, hours, ...) + won't be changed unless the resulting date would be invalid: for example, + Jan 31 + 1 month will be Feb 28, not (non-existing) Feb 31. + + Because of this feature, adding and subtracting back again the same + wxDateSpan will @b not, in general, give back the original date: Feb 28 - 1 + month will be Jan 28, not Jan 31! + + wxDateSpan objects can be either positive or negative. They may be + multiplied by scalars which multiply all deltas by the scalar: i.e. + 2*(1 month and 1 day) is 2 months and 2 days. They can be added together + with wxDateTime or wxTimeSpan, but the type of result is different for each + case. + + @warning If you specify both weeks and days, the total number of days added + will be 7*weeks + days! See also GetTotalDays(). + + Equality operators are defined for wxDateSpans. Two wxDateSpans are equal + if and only if they both give the same target date when added to @b every + source date. Thus wxDateSpan::Months(1) is not equal to + wxDateSpan::Days(30), because they don't give the same date when added to + Feb 1st. But wxDateSpan::Days(14) is equal to wxDateSpan::Weeks(2). + + Finally, notice that for adding hours, minutes and so on you don't need + this class at all: wxTimeSpan will do the job because there are no + subtleties associated with those (we don't support leap seconds). + + @library{wxbase} + @category{data} + + @see @ref overview_datetime, wxDateTime +*/ +class wxDateSpan +{ +public: + /** + Constructs the date span object for the given number of years, months, + weeks and days. Note that the weeks and days add together if both are + given. + */ + wxDateSpan(int years = 0, int months = 0, int weeks = 0, int days = 0); + + /** + Returns the sum of two date spans. + + @return A new wxDateSpan object with the result. + */ + wxDateSpan Add(const wxDateSpan& other) const; + /** + Adds the given wxDateSpan to this wxDateSpan and returns a reference + to itself. + */ + wxDateSpan& Add(const wxDateSpan& other); + + /** + Returns a date span object corresponding to one day. + + @see Days() + */ + static wxDateSpan Day(); + + /** + Returns a date span object corresponding to the given number of days. + + @see Day() + */ + static wxDateSpan Days(int days); + + /** + Returns the number of days (not counting the weeks component) in this + date span. + + @see GetTotalDays() + */ + int GetDays() const; + + /** + Returns the number of the months (not counting the years) in this date + span. + */ + int GetMonths() const; + + /** + Returns the combined number of days in this date span, counting both + weeks and days. This doesn't take months or years into account. + + @see GetWeeks(), GetDays() + */ + int GetTotalDays() const; + + /** + Returns the number of weeks in this date span. + + @see GetTotalDays() + */ + int GetWeeks() const; + + /** + Returns the number of years in this date span. + */ + int GetYears() const; + + /** + Returns a date span object corresponding to one month. + + @see Months() + */ + static wxDateSpan Month(); + + /** + Returns a date span object corresponding to the given number of months. + + @see Month() + */ + static wxDateSpan Months(int mon); + + /** + Returns the product of the date span by the specified @a factor. The + product is computed by multiplying each of the components by the + @a factor. + + @return A new wxDateSpan object with the result. + */ + wxDateSpan Multiply(int factor) const; + /** + Multiplies this date span by the specified @a factor. The product is + computed by multiplying each of the components by the @a factor. + + @return A reference to this wxDateSpan object modified in place. + */ + wxDateSpan& Multiply(int factor); + + /** + Changes the sign of this date span. + + @see Negate() + */ + wxDateSpan& Neg(); + + /** + Returns a date span with the opposite sign. + + @see Neg() + */ + wxDateSpan Negate() const; + + /** + Sets the number of days (without modifying any other components) in + this date span. + */ + wxDateSpan& SetDays(int n); + + /** + Sets the number of months (without modifying any other components) in + this date span. + */ + wxDateSpan& SetMonths(int n); + + /** + Sets the number of weeks (without modifying any other components) in + this date span. + */ + wxDateSpan& SetWeeks(int n); + + /** + Sets the number of years (without modifying any other components) in + this date span. + */ + wxDateSpan& SetYears(int n); + + /** + Returns the difference of two date spans. + + @return A new wxDateSpan object with the result. + */ + wxDateSpan Subtract(const wxDateSpan& other) const; + /** + Subtracts the given wxDateSpan to this wxDateSpan and returns a + reference to itself. + */ + wxDateSpan& Subtract(const wxDateSpan& other); + + /** + Returns a date span object corresponding to one week. + + @see Weeks() + */ + static wxDateSpan Week(); + + /** + Returns a date span object corresponding to the given number of weeks. + + @see Week() + */ + static wxDateSpan Weeks(int weeks); + + /** + Returns a date span object corresponding to one year. + + @see Years() + */ + static wxDateSpan Year(); + + /** + Returns a date span object corresponding to the given number of years. + + @see Year() + */ + static wxDateSpan Years(int years); + + /** + Adds the given wxDateSpan to this wxDateSpan and returns the result. + */ + wxDateSpan& operator+=(const wxDateSpan& other); + + /** + Subtracts the given wxDateSpan to this wxDateSpan and returns the + result. + */ + wxDateSpan& operator-=(const wxDateSpan& other); + + /** + Changes the sign of this date span. + + @see Negate() + */ + wxDateSpan& operator-(); + + /** + Multiplies this date span by the specified @a factor. The product is + computed by multiplying each of the components by the @a factor. + + @return A reference to this wxDateSpan object modified in place. + */ + wxDateSpan& operator*=(int factor); + + /** + Returns @true if this date span is different from the other one. + */ + bool operator!=(const wxDateSpan&) const; + + /** + Returns @true if this date span is equal to the other one. Two date + spans are considered equal if and only if they have the same number of + years and months and the same total number of days (counting both days + and weeks). + */ + bool operator==(const wxDateSpan&) const; +}; + + + +/** + @class wxTimeSpan + @wxheader{datetime.h} + + wxTimeSpan class represents a time interval. + + @library{wxbase} + @category{data} + + @see @ref overview_datetime, wxDateTime +*/ +class wxTimeSpan +{ +public: + /** + Default constructor, constructs a zero timespan. + */ + wxTimeSpan(); + /** + Constructs timespan from separate values for each component, with the + date set to 0. Hours are not restricted to 0-24 range, neither are + minutes, seconds or milliseconds. + */ + wxTimeSpan(long hours, long min, long sec, long msec); + + /** + Returns the absolute value of the timespan: does not modify the object. + */ + wxTimeSpan Abs() const; + + /** + Returns the sum of two time spans. + + @return A new wxDateSpan object with the result. + */ + wxTimeSpan Add(const wxTimeSpan& diff) const; + /** + Adds the given wxTimeSpan to this wxTimeSpan and returns a reference + to itself. + */ + wxTimeSpan& Add(const wxTimeSpan& diff); + + /** + Returns the timespan for one day. + */ + static wxTimespan Day(); + + /** + Returns the timespan for the given number of days. + */ + static wxTimespan Days(long days); + + /** + Returns the string containing the formatted representation of the time + span. The following format specifiers are allowed after %: + + - @c H - Number of Hours + - @c M - Number of Minutes + - @c S - Number of Seconds + - @c l - Number of Milliseconds + - @c D - Number of Days + - @c E - Number of Weeks + - @c % - The percent character + + Note that, for example, the number of hours in the description above is + not well defined: it can be either the total number of hours (for + example, for a time span of 50 hours this would be 50) or just the hour + part of the time span, which would be 2 in this case as 50 hours is + equal to 2 days and 2 hours. + + wxTimeSpan resolves this ambiguity in the following way: if there had + been, indeed, the @c %D format specified preceding the @c %H, then it + is interpreted as 2. Otherwise, it is 50. + + The same applies to all other format specifiers: if they follow a + specifier of larger unit, only the rest part is taken, otherwise the + full value is used. + */ + wxString Format(const wxString& = wxDefaultTimeSpanFormat) const; + + /** + Returns the difference in number of days. + */ + int GetDays() const; + + /** + Returns the difference in number of hours. + */ + int GetHours() const; + + /** + Returns the difference in number of milliseconds. + */ + wxLongLong GetMilliseconds() const; + + /** + Returns the difference in number of minutes. + */ + int GetMinutes() const; + + /** + Returns the difference in number of seconds. + */ + wxLongLong GetSeconds() const; + + /** + Returns the internal representation of timespan. + */ + wxLongLong GetValue() const; + + /** + Returns the difference in number of weeks. + */ + int GetWeeks() const; + + /** + Returns the timespan for one hour. + */ + static wxTimespan Hour(); + + /** + Returns the timespan for the given number of hours. + */ + static wxTimespan Hours(long hours); + + /** + Returns @true if two timespans are equal. + */ + bool IsEqualTo(const wxTimeSpan& ts) const; + + /** + Compares two timespans: works with the absolute values, i.e. -2 hours + is longer than 1 hour. Also, it will return @false if the timespans are + equal in absolute value. + */ + bool IsLongerThan(const wxTimeSpan& ts) const; + + /** + Returns @true if the timespan is negative. + */ + bool IsNegative() const; + + /** + Returns @true if the timespan is empty. + */ + bool IsNull() const; + + /** + Returns @true if the timespan is positive. + */ + bool IsPositive() const; + + /** + Compares two timespans: works with the absolute values, i.e. 1 hour is + shorter than -2 hours. Also, it will return @false if the timespans are + equal in absolute value. + */ + bool IsShorterThan(const wxTimeSpan& ts) const; + + /** + Returns the timespan for one millisecond. + */ + static wxTimespan Millisecond(); + + /** + Returns the timespan for the given number of milliseconds. + */ + static wxTimespan Milliseconds(long ms); + + /** + Returns the timespan for one minute. + */ + static wxTimespan Minute(); + + /** + Returns the timespan for the given number of minutes. + */ + static wxTimespan Minutes(long min); + + /** + Returns the product of this time span by @a n. + + @return A new wxTimeSpan object with the result. + */ + wxTimeSpan Multiply(int n) const; + /** + Multiplies this time span by @a n. + + @return A reference to this wxTimeSpan object modified in place. + */ + wxTimeSpan& Multiply(int n); + + /** + Negate the value of the timespan. + + @see Negate() + */ + wxTimeSpan& Neg(); + + /** + Returns timespan with inverted sign. + + @see Neg() + */ + wxTimeSpan Negate() const; + + /** + Returns the timespan for one second. + */ + static wxTimespan Second(); + + /** + Returns the timespan for the given number of seconds. + */ + static wxTimespan Seconds(long sec); + + /** + Returns the difference of two time spans. + + @return A new wxDateSpan object with the result. + */ + wxTimeSpan Subtract(const wxTimeSpan& diff) const; + /** + Subtracts the given wxTimeSpan to this wxTimeSpan and returns a + reference to itself. + */ + wxTimeSpan& Subtract(const wxTimeSpan& diff); + + /** + Returns the timespan for one week. + */ + static wxTimespan Week(); + + /** + Returns the timespan for the given number of weeks. + */ + static wxTimespan Weeks(long weeks); + + /** + Adds the given wxTimeSpan to this wxTimeSpan and returns the result. + */ + wxTimeSpan& operator+=(const wxTimeSpan& diff); + + /** + Multiplies this time span by @a n. + + @return A reference to this wxTimeSpan object modified in place. + */ + wxTimeSpan& operator*=(int n); + + /** + Negate the value of the timespan. + + @see Negate() + */ + wxTimeSpan& operator-(); + + /** + Subtracts the given wxTimeSpan to this wxTimeSpan and returns the + result. + */ + wxTimeSpan& operator-=(const wxTimeSpan& diff); +}; + + + +/** + @class wxDateTimeHolidayAuthority + @wxheader{datetime.h} + + @todo Write wxDateTimeHolidayAuthority documentation. + + @library{wxbase} + @category{misc} +*/ +class wxDateTimeHolidayAuthority +{ +public: + +}; + diff --git a/interface/wx/datstrm.h b/interface/wx/datstrm.h new file mode 100644 index 0000000000..3a0629dba9 --- /dev/null +++ b/interface/wx/datstrm.h @@ -0,0 +1,280 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: datstrm.h +// Purpose: interface of wxDataInputStream and wxDataOutputStream +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxDataOutputStream + @wxheader{datstrm.h} + + This class provides functions that write binary data types in a portable + way. Data can be written in either big-endian or little-endian format, + little-endian being the default on all architectures. + + If you want to write data to text files (or streams) use wxTextOutputStream + instead. + + The "<<" operator is overloaded and you can use this class like a standard + C++ iostream. See wxDataInputStream for its usage and caveats. + + @library{wxbase} + @category{streams} + + @see wxDataInputStream +*/ +class wxDataOutputStream +{ +public: + /** + Constructs a datastream object from an output stream. Only write + methods will be available. + + @param stream + The output stream. + */ + wxDataOutputStream(wxOutputStream& stream); + /** + Constructs a datastream object from an output stream. Only write + methods will be available. This constructor is only available in + Unicode builds of wxWidgets. + + @param stream + The output stream. + @param conv + Charset conversion object object used to encoding Unicode strings + before writing them to the stream in Unicode mode (see + WriteString() for a detailed description). Note that you must not + destroy @a conv before you destroy this wxDataOutputStream + instance! It is recommended to use the default value (UTF-8). + */ + wxDataOutputStream(wxOutputStream& stream, + const wxMBConv& conv = wxConvAuto()); + + /** + Destroys the wxDataOutputStream object. + */ + ~wxDataOutputStream(); + + /** + If @a be_order is @true, all data will be written in big-endian order, + e.g. for reading on a Sparc or from Java-Streams (which always use + big-endian order), otherwise data will be written in little-endian + order. + */ + void BigEndianOrdered(bool be_order); + + /** + Writes the single byte @a i8 to the stream. + */ + void Write8(wxUint8 i8); + /** + Writes an array of bytes to the stream. The amount of bytes to write is + specified with the @a size variable. + */ + void Write8(const wxUint8* buffer, size_t size); + + /** + Writes the 16 bit unsigned integer @a i16 to the stream. + */ + void Write16(wxUint16 i16); + /** + Writes an array of 16 bit unsigned integer to the stream. The amount of + 16 bit unsigned integer to write is specified with the @a size variable. + */ + void Write16(const wxUint16* buffer, size_t size); + + /** + Writes the 32 bit unsigned integer @a i32 to the stream. + */ + void Write32(wxUint32 i32); + /** + Writes an array of 32 bit unsigned integer to the stream. The amount of + 32 bit unsigned integer to write is specified with the @a size variable. + */ + void Write32(const wxUint32* buffer, size_t size); + + /** + Writes the 64 bit unsigned integer @a i64 to the stream. + */ + void Write64(wxUint64 i64); + /** + Writes an array of 64 bit unsigned integer to the stream. The amount of + 64 bit unsigned integer to write is specified with the @a size variable. + */ + void Write64(const wxUint64* buffer, size_t size); + + /** + Writes the double @a f to the stream using the IEEE format. + */ + void WriteDouble(double f); + /** + Writes an array of double to the stream. The amount of double to write is + specified with the @a size variable. + */ + void WriteDouble(const double* buffer, size_t size); + + /** + Writes @a string to the stream. Actually, this method writes the size + of the string before writing @a string itself. + + In ANSI build of wxWidgets, the string is written to the stream in + exactly same way it is represented in memory. In Unicode build, + however, the string is first converted to multibyte representation with + @e conv object passed to stream's constructor (consequently, ANSI + applications can read data written by Unicode application, as long as + they agree on encoding) and this representation is written to the + stream. UTF-8 is used by default. + */ + void WriteString(const wxString& string); +}; + + + +/** + @class wxDataInputStream + @wxheader{datstrm.h} + + This class provides functions that read binary data types in a portable + way. Data can be read in either big-endian or little-endian format, + little-endian being the default on all architectures. + + If you want to read data from text files (or streams) use wxTextInputStream + instead. + + The ">>" operator is overloaded and you can use this class like a standard + C++ iostream. Note, however, that the arguments are the fixed size types + wxUint32, wxInt32 etc and on a typical 32-bit computer, none of these match + to the "long" type (wxInt32 is defined as signed int on 32-bit + architectures) so that you cannot use long. To avoid problems (here and + elsewhere), make use of the wxInt32, wxUint32, etc types. + + For example: + + @code + wxFileInputStream input( "mytext.dat" ); + wxDataInputStream store( input ); + wxUint8 i1; + float f2; + wxString line; + + store >> i1; // read a 8 bit integer. + store >> i1 >> f2; // read a 8 bit integer followed by float. + store >> line; // read a text line + @endcode + + @library{wxbase} + @category{streams} + + @see wxDataOutputStream +*/ +class wxDataInputStream +{ +public: + /** + Constructs a datastream object from an input stream. Only read methods + will be available. + + @param stream + The input stream. + */ + wxDataInputStream(wxInputStream& stream); + /** + Constructs a datastream object from an input stream. Only read methods + will be available. This constructor is only available in Unicode builds + of wxWidgets. + + @param stream + The input stream. + @param conv + Charset conversion object object used to decode strings in Unicode + mode (see ReadString() for a detailed description). Note that you + must not destroy @a conv before you destroy this wxDataInputStream + instance! + */ + wxDataInputStream(wxInputStream& stream, + const wxMBConv& conv = wxConvAuto()); + + /** + Destroys the wxDataInputStream object. + */ + ~wxDataInputStream(); + + /** + If @a be_order is @true, all data will be read in big-endian order, + such as written by programs on a big endian architecture (e.g. Sparc) + or written by Java-Streams (which always use big-endian order). + */ + void BigEndianOrdered(bool be_order); + + /** + Reads a single byte from the stream. + */ + wxUint8 Read8(); + /** + Reads bytes from the stream in a specified buffer. The amount of bytes + to read is specified by the @a size variable. + */ + void Read8(wxUint8* buffer, size_t size); + + /** + Reads a 16 bit unsigned integer from the stream. + */ + wxUint16 Read16(); + /** + Reads 16 bit unsigned integers from the stream in a specified buffer. + The amount of 16 bit unsigned integers to read is specified by the + @a size variable. + */ + void Read16(wxUint16* buffer, size_t size); + + /** + Reads a 32 bit unsigned integer from the stream. + */ + wxUint32 Read32(); + /** + Reads 32 bit unsigned integers from the stream in a specified buffer. + The amount of 32 bit unsigned integers to read is specified by the + @a size variable. + */ + void Read32(wxUint32* buffer, size_t size); + + /** + Reads a 64 bit unsigned integer from the stream. + */ + wxUint64 Read64(); + /** + Reads 64 bit unsigned integers from the stream in a specified buffer. + The amount of 64 bit unsigned integers to read is specified by the + @a size variable. + */ + void Read64(wxUint64* buffer, size_t size); + + /** + Reads a double (IEEE encoded) from the stream. + */ + double ReadDouble(); + /** + Reads double data (IEEE encoded) from the stream in a specified buffer. + The amount of doubles to read is specified by the @a size variable. + */ + void ReadDouble(double* buffer, size_t size); + + /** + Reads a string from a stream. Actually, this function first reads a + long integer specifying the length of the string (without the last null + character) and then reads the string. + + In Unicode build of wxWidgets, the fuction first reads multibyte + (char*) string from the stream and then converts it to Unicode using + the @e conv object passed to constructor and returns the result as + wxString. You are responsible for using the same convertor as when + writing the stream. + + @see wxDataOutputStream::WriteString() + */ + wxString ReadString(); +}; + diff --git a/interface/wx/dc.h b/interface/wx/dc.h new file mode 100644 index 0000000000..107cc06058 --- /dev/null +++ b/interface/wx/dc.h @@ -0,0 +1,1145 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: dc.h +// Purpose: interface of wxDC +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxDC + @wxheader{dc.h} + + A wxDC is a @e "device context" onto which graphics and text can be drawn. + It is intended to represent different output devices and offers a common + abstract API for drawing on any of them. + + wxWidgets offers an alternative drawing API based on the modern drawing + backends GDI+, CoreGraphics and Cairo. See wxGraphicsContext, wxGraphicsRenderer + and related classes. There is also a wxGCDC linking the APIs by offering + the wxDC API ontop of a wxGraphicsContext. + + wxDC is an abstract base class and cannot be created directly. + Use wxPaintDC, wxClientDC, wxWindowDC, wxScreenDC, wxMemoryDC or + wxPrinterDC. Notice that device contexts which are associated with windows + (i.e. wxClientDC, wxWindowDC and wxPaintDC) use the window font and colours + by default (starting with wxWidgets 2.9.0) but the other device context + classes use system-default values so you always must set the appropriate + fonts and colours before using them. + + In addition to the versions of the methods documented below, there + are also versions which accept single wxPoint parameter instead + of the two wxCoord ones or wxPoint and wxSize instead of the four + wxCoord parameters. + + Beginning with wxWidgets 2.9.0 the entire wxDC code has been + reorganized. All platform dependent code (actually all drawing code) + has been moved into backend classes which derive from a common + wxDCImpl class. The user-visible classes such as wxClientDC and + wxPaintDC merely forward all calls to the backend implementation. + + On Mac OS X colours with alpha channel are supported. Instances wxPen + or wxBrush that are built from wxColour use the colour's alpha values + when stroking or filling. + + @library{wxcore} + @category{dc,gdi} + + @see @ref overview_dc, wxGraphicsContext + + @todo Precise definition of default/initial state. + @todo Pixelwise definition of operations (e.g. last point of a line not + drawn). + @todo Coordinates: state clearly which type of coordinates are returned by + the various Get*Point() or similar functions - often they are client + coordinates but not always. +*/ +class wxDC : public wxObject +{ +public: + /** + Copy from a source DC to this DC, specifying the destination + coordinates, size of area to copy, source DC, source coordinates, + logical function, whether to use a bitmap mask, and mask source + position. + + @param xdest + Destination device context x position. + @param ydest + Destination device context y position. + @param width + Width of source area to be copied. + @param height + Height of source area to be copied. + @param source + Source device context. + @param xsrc + Source device context x position. + @param ysrc + Source device context y position. + @param logicalFunc + Logical function to use, see SetLogicalFunction(). + @param useMask + If @true, Blit does a transparent blit using the mask that is + associated with the bitmap selected into the source device context. + The Windows implementation does the following if MaskBlt cannot be + used: +
    +
  1. Creates a temporary bitmap and copies the destination area into + it.
    2. +
  2. Copies the source area into the temporary bitmap using the + specified logical function.
    3. +
  3. Sets the masked area in the temporary bitmap to BLACK by ANDing + the mask bitmap with the temp bitmap with the foreground colour + set to WHITE and the bg colour set to BLACK.
    4. +
  4. Sets the unmasked area in the destination area to BLACK by + ANDing the mask bitmap with the destination area with the + foreground colour set to BLACK and the background colour set to + WHITE.
    5. +
  5. ORs the temporary bitmap with the destination area.
    6. +
  6. Deletes the temporary bitmap.
    7. +
+ This sequence of operations ensures that the source's transparent + area need not be black, and logical functions are supported. + @n @b Note: on Windows, blitting with masks can be speeded up + considerably by compiling wxWidgets with the wxUSE_DC_CACHE option + enabled. You can also influence whether MaskBlt or the explicit + mask blitting code above is used, by using wxSystemOptions and + setting the @c no-maskblt option to 1. + @param xsrcMask + Source x position on the mask. If both xsrcMask and ysrcMask are + -1, xsrc and ysrc will be assumed for the mask source position. + Currently only implemented on Windows. + @param ysrcMask + Source y position on the mask. If both xsrcMask and ysrcMask are + -1, xsrc and ysrc will be assumed for the mask source position. + Currently only implemented on Windows. + + @remarks There is partial support for Blit() in wxPostScriptDC, under X. + + @see StretchBlit(), wxMemoryDC, wxBitmap, wxMask + */ + bool Blit(wxCoord xdest, wxCoord ydest, wxCoord width, + wxCoord height, wxDC* source, wxCoord xsrc, wxCoord ysrc, + int logicalFunc = wxCOPY, bool useMask = false, + wxCoord xsrcMask = -1, wxCoord ysrcMask = -1); + + /** + Adds the specified point to the bounding box which can be retrieved + with MinX(), MaxX() and MinY(), MaxY() functions. + + @see ResetBoundingBox() + */ + void CalcBoundingBox(wxCoord x, wxCoord y); + + /** + Clears the device context using the current background brush. + */ + void Clear(); + + /** + Performs all necessary computations for given platform and context type + after each change of scale and origin parameters. Usually called + automatically internally after such changes. + */ + virtual void ComputeScaleAndOrigin(); + + /** + Displays a cross hair using the current pen. This is a vertical and + horizontal line the height and width of the window, centred on the + given point. + */ + void CrossHair(wxCoord x, wxCoord y); + + /** + Destroys the current clipping region so that none of the DC is clipped. + + @see SetClippingRegion() + */ + void DestroyClippingRegion(); + + /** + Convert device X coordinate to logical coordinate, using the current + mapping mode. + */ + virtual wxCoord DeviceToLogicalX(wxCoord x); + + /** + Convert device X coordinate to relative logical coordinate, using the + current mapping mode but ignoring the x axis orientation. Use this + function for converting a width, for example. + */ + virtual wxCoord DeviceToLogicalXRel(wxCoord x); + + /** + Converts device Y coordinate to logical coordinate, using the current + mapping mode. + */ + virtual wxCoord DeviceToLogicalY(wxCoord y); + + /** + Convert device Y coordinate to relative logical coordinate, using the + current mapping mode but ignoring the y axis orientation. Use this + function for converting a height, for example. + */ + virtual wxCoord DeviceToLogicalYRel(wxCoord y); + + /** + Draws an arc of a circle, centred on (@a xc, @a yc), with starting + point (@a x1, @a y1) and ending at (@a x2, @a y2). The current pen is + used for the outline and the current brush for filling the shape. + + The arc is drawn in a counter-clockwise direction from the start point + to the end point. + */ + void DrawArc(wxCoord x1, wxCoord y1, wxCoord x2, wxCoord y2, + wxCoord xc, wxCoord yc); + + /** + Draw a bitmap on the device context at the specified point. If + @a transparent is @true and the bitmap has a transparency mask, the + bitmap will be drawn transparently. + + When drawing a mono-bitmap, the current text foreground colour will be + used to draw the foreground of the bitmap (all bits set to 1), and the + current text background colour to draw the background (all bits set to + 0). + + @see SetTextForeground(), SetTextBackground(), wxMemoryDC + */ + void DrawBitmap(const wxBitmap& bitmap, wxCoord x, wxCoord y, + bool transparent); + + //@{ + /** + Draws a check mark inside the given rectangle. + */ + void DrawCheckMark(wxCoord x, wxCoord y, wxCoord width, wxCoord height); + void DrawCheckMark(const wxRect& rect); + //@} + + //@{ + /** + Draws a circle with the given centre and radius. + + @see DrawEllipse() + */ + void DrawCircle(wxCoord x, wxCoord y, wxCoord radius); + void DrawCircle(const wxPoint& pt, wxCoord radius); + //@} + + //@{ + /** + Draws an ellipse contained in the rectangle specified either with the + given top left corner and the given size or directly. The current pen + is used for the outline and the current brush for filling the shape. + + @see DrawCircle() + */ + void DrawEllipse(wxCoord x, wxCoord y, wxCoord width, wxCoord height); + void DrawEllipse(const wxPoint& pt, const wxSize& size); + void DrawEllipse(const wxRect& rect); + //@} + + /** + Draws an arc of an ellipse. The current pen is used for drawing the arc + and the current brush is used for drawing the pie. + + @a x and @a y specify the x and y coordinates of the upper-left corner + of the rectangle that contains the ellipse. + + @a width and @a height specify the width and height of the rectangle + that contains the ellipse. + + @a start and @a end specify the start and end of the arc relative to + the three-o'clock position from the center of the rectangle. Angles are + specified in degrees (360 is a complete circle). Positive values mean + counter-clockwise motion. If @a start is equal to @e end, a complete + ellipse will be drawn. + */ + void DrawEllipticArc(wxCoord x, wxCoord y, wxCoord width, wxCoord height, + double start, double end); + + /** + Draw an icon on the display (does nothing if the device context is + PostScript). This can be the simplest way of drawing bitmaps on a + window. + */ + void DrawIcon(const wxIcon& icon, wxCoord x, wxCoord y); + + //@{ + /** + Draw optional bitmap and the text into the given rectangle and aligns + it as specified by alignment parameter; it also will emphasize the + character with the given index if it is != -1 and return the bounding + rectangle if required. + */ + virtual void DrawLabel(const wxString& text, const wxBitmap& image, + const wxRect& rect, + int alignment = wxALIGN_LEFT | wxALIGN_TOP, + int indexAccel = -1, wxRect* rectBounding = NULL); + void DrawLabel(const wxString& text, const wxRect& rect, + int alignment = wxALIGN_LEFT | wxALIGN_TOP, + int indexAccel = -1); + //@} + + /** + Draws a line from the first point to the second. The current pen is + used for drawing the line. Note that the point (@a x2, @a y2) is not + part of the line and is not drawn by this function (this is consistent + with the behaviour of many other toolkits). + */ + void DrawLine(wxCoord x1, wxCoord y1, wxCoord x2, wxCoord y2); + + /** + Draws lines using an array of points of size @a n adding the optional + offset coordinate. The current pen is used for drawing the lines. + + @beginWxPythonOnly + The wxPython version of this method accepts a Python list of wxPoint + objects. + @endWxPythonOnly + */ + void DrawLines(int n, wxPoint points[], wxCoord xoffset = 0, + wxCoord yoffset = 0); + /** + This method uses a list of wxPoints, adding the optional offset + coordinate. The programmer is responsible for deleting the list of + points. + + @beginWxPythonOnly + The wxPython version of this method accepts a Python list of wxPoint + objects. + @endWxPythonOnly + */ + void DrawLines(const wxPointList* points, + wxCoord xoffset = 0, wxCoord yoffset = 0); + + /** + Draws a point using the color of the current pen. Note that the other + properties of the pen are not used, such as width. + */ + void DrawPoint(wxCoord x, wxCoord y); + + /** + Draws a filled polygon using an array of points of size @a n, adding + the optional offset coordinate. The first and last points are + automatically closed. + + The last argument specifies the fill rule: @b wxODDEVEN_RULE (the + default) or @b wxWINDING_RULE. + + The current pen is used for drawing the outline, and the current brush + for filling the shape. Using a transparent brush suppresses filling. + */ + void DrawPolygon(int n, wxPoint points[], wxCoord xoffset = 0, + wxCoord yoffset = 0, int fill_style = wxODDEVEN_RULE); + /** + This method draws a filled polygon using a list of wxPoints, adding the + optional offset coordinate. The first and last points are automatically + closed. + + The last argument specifies the fill rule: @b wxODDEVEN_RULE (the + default) or @b wxWINDING_RULE. + + The current pen is used for drawing the outline, and the current brush + for filling the shape. Using a transparent brush suppresses filling. + + The programmer is responsible for deleting the list of points. + + @beginWxPythonOnly + The wxPython version of this method accepts a Python list of wxPoint + objects. + @endWxPythonOnly + */ + void DrawPolygon(const wxPointList* points, + wxCoord xoffset = 0, wxCoord yoffset = 0, + int fill_style = wxODDEVEN_RULE); + + /** + Draws two or more filled polygons using an array of @a points, adding + the optional offset coordinates. + + Notice that for the platforms providing a native implementation of this + function (Windows and PostScript-based wxDC currently), this is more + efficient than using DrawPolygon() in a loop. + + @a n specifies the number of polygons to draw, the array @e count of + size @a n specifies the number of points in each of the polygons in the + @a points array. + + The last argument specifies the fill rule: @b wxODDEVEN_RULE (the + default) or @b wxWINDING_RULE. + + The current pen is used for drawing the outline, and the current brush + for filling the shape. Using a transparent brush suppresses filling. + + The polygons maybe disjoint or overlapping. Each polygon specified in a + call to DrawPolyPolygon() must be closed. Unlike polygons created by + the DrawPolygon() member function, the polygons created by this + method are not closed automatically. + + @beginWxPythonOnly + Not implemented yet. + @endWxPythonOnly + */ + void DrawPolyPolygon(int n, int count[], wxPoint points[], + wxCoord xoffset = 0, wxCoord yoffset = 0, + int fill_style = wxODDEVEN_RULE); + + /** + Draws a rectangle with the given top left corner, and with the given + size. The current pen is used for the outline and the current brush + for filling the shape. + */ + void DrawRectangle(wxCoord x, wxCoord y, wxCoord width, wxCoord height); + + /** + Draws the text rotated by @a angle degrees. + + @note Under Win9x only TrueType fonts can be drawn by this function. In + particular, a font different from @c wxNORMAL_FONT should be used + as the latter is not a TrueType font. @c wxSWISS_FONT is an + example of a font which is. + + @see DrawText() + */ + void DrawRotatedText(const wxString& text, wxCoord x, wxCoord y, + double angle); + + /** + Draws a rectangle with the given top left corner, and with the given + size. The corners are quarter-circles using the given radius. The + current pen is used for the outline and the current brush for filling + the shape. + + If @a radius is positive, the value is assumed to be the radius of the + rounded corner. If @a radius is negative, the absolute value is assumed + to be the @e proportion of the smallest dimension of the rectangle. + This means that the corner can be a sensible size relative to the size + of the rectangle, and also avoids the strange effects X produces when + the corners are too big for the rectangle. + */ + void DrawRoundedRectangle(wxCoord x, wxCoord y, wxCoord width, + wxCoord height, double radius); + + //@{ + /** + Draws a spline between all given points using the current pen. + + @beginWxPythonOnly + The wxPython version of this method accepts a Python list of wxPoint + objects. + @endWxPythonOnly + */ + void DrawSpline(int n, wxPoint points[]); + void DrawSpline(const wxPointList* points); + void DrawSpline(wxCoord x1, wxCoord y1, wxCoord x2, wxCoord y2, + wxCoord x3, wxCoord y3); + //@} + + /** + Draws a text string at the specified point, using the current text + font, and the current text foreground and background colours. + + The coordinates refer to the top-left corner of the rectangle bounding + the string. See GetTextExtent() for how to get the dimensions of a text + string, which can be used to position the text more precisely. + + @note Under wxGTK, the current + @ref GetLogicalFunction() "logical function" is used by this + function but it is ignored by wxMSW. Thus, you should avoid using + logical functions with this function in portable programs. + */ + void DrawText(const wxString& text, wxCoord x, wxCoord y); + + /** + Ends a document (only relevant when outputting to a printer). + */ + void EndDoc(); + + /** + Ends a document page (only relevant when outputting to a printer). + */ + void EndPage(); + + /** + Flood fills the device context starting from the given point, using + the current brush colour, and using a style: + + - wxFLOOD_SURFACE: The flooding occurs until a colour other than the + given colour is encountered. + - wxFLOOD_BORDER: The area to be flooded is bounded by the given + colour. + + @return @false if the operation failed. + + @note The present implementation for non-Windows platforms may fail to + find colour borders if the pixels do not match the colour + exactly. However the function will still return @true. + */ + bool FloodFill(wxCoord x, wxCoord y, const wxColour& colour, + int style = wxFLOOD_SURFACE); + + /** + Gets the brush used for painting the background. + + @see wxDC::SetBackground() + */ + const wxBrush GetBackground() const; + + /** + Returns the current background mode: @c wxSOLID or @c wxTRANSPARENT. + + @see SetBackgroundMode() + */ + int GetBackgroundMode() const; + + /** + Gets the current brush. + + @see wxDC::SetBrush() + */ + const wxBrush GetBrush() const; + + /** + Gets the character height of the currently set font. + */ + wxCoord GetCharHeight(); + + /** + Gets the average character width of the currently set font. + */ + wxCoord GetCharWidth(); + + /** + Gets the rectangle surrounding the current clipping region. + + @beginWxPythonOnly + No arguments are required and the four values defining the rectangle + are returned as a tuple. + @endWxPythonOnly + */ + void GetClippingBox(wxCoord x, wxCoord y, wxCoord width, wxCoord height); + + /** + Returns the depth (number of bits/pixel) of this DC. + + @see wxDisplayDepth() + */ + int GetDepth() const; + + /** + Gets the current font. Notice that even although each device context + object has some default font after creation, this method would return a + wxNullFont initially and only after calling SetFont() a valid font is + returned. + */ + const wxFont GetFont() const; + + /** + Gets the current layout direction of the device context. On platforms + where RTL layout is supported, the return value will either be + @c wxLayout_LeftToRight or @c wxLayout_RightToLeft. If RTL layout is + not supported, the return value will be @c wxLayout_Default. + + @see SetLayoutDirection() + */ + wxLayoutDirection GetLayoutDirection() const; + + /** + Gets the current logical function. + + @see SetLogicalFunction() + */ + int GetLogicalFunction(); + + /** + Gets the mapping mode for the device context. + + @see SetMapMode() + */ + int GetMapMode(); + + /** + Gets the dimensions of the string using the currently selected font. + @a string is the text string to measure, @e heightLine, if non @NULL, + is where to store the height of a single line. + + The text extent is set in the given @a w and @a h pointers. + + If the optional parameter @a font is specified and valid, then it is + used for the text extent calculation, otherwise the currently selected + font is used. + + @note This function works with both single-line and multi-line strings. + + @see wxFont, SetFont(), GetPartialTextExtents(), GetTextExtent() + */ + void GetMultiLineTextExtent(const wxString& string, wxCoord* w, + wxCoord* h, + wxCoord* heightLine = NULL, + wxFont* font = NULL) const; + /** + Gets the dimensions of the string using the currently selected font. + @a string is the text string to measure, @e heightLine, if non @NULL, + is where to store the height of a single line. + + @return The text extent as a wxSize object. + + @note This function works with both single-line and multi-line strings. + + @see wxFont, SetFont(), GetPartialTextExtents(), GetTextExtent() + */ + const wxSize GetMultiLineTextExtent(const wxString& string) const; + + /** + Fills the @a widths array with the widths from the beginning of @a text + to the corresponding character of @a text. The generic version simply + builds a running total of the widths of each character using + GetTextExtent(), however if the various platforms have a native API + function that is faster or more accurate than the generic + implementation then it should be used instead. + + @beginWxPythonOnly + This method only takes the @a text parameter and returns a Python list + of integers. + @endWxPythonOnly + + @see GetMultiLineTextExtent(), GetTextExtent() + */ + bool GetPartialTextExtents(const wxString& text, + wxArrayInt& widths) const; + + /** + Gets the current pen. + + @see SetPen() + */ + const wxPen GetPen() const; + + /** + Gets in @a colour the colour at the specified location. Not available + for wxPostScriptDC or wxMetafileDC. + + @note Setting a pixel can be done using DrawPoint(). + + @beginWxPythonOnly + The wxColour value is returned and is not required as a parameter. + @endWxPythonOnly + */ + bool GetPixel(wxCoord x, wxCoord y, wxColour* colour); + + /** + Returns the resolution of the device in pixels per inch. + */ + wxSize GetPPI() const; + + //@{ + /** + This gets the horizontal and vertical resolution in device units. It + can be used to scale graphics to fit the page. + + For example, if @e maxX and @e maxY represent the maximum horizontal + and vertical 'pixel' values used in your application, the following + code will scale the graphic to fit on the printer page: + + @code + wxCoord w, h; + dc.GetSize(&w, &h); + double scaleX = (double)(maxX / w); + double scaleY = (double)(maxY / h); + dc.SetUserScale(min(scaleX, scaleY),min(scaleX, scaleY)); + @endcode + + @beginWxPythonOnly + In place of a single overloaded method name, wxPython implements the + following methods: + - GetSize() - Returns a wxSize. + - GetSizeWH() - Returns a 2-tuple (width, height). + @endWxPythonOnly + */ + void GetSize(wxCoord* width, wxCoord* height) const; + const wxSize GetSize() const; + //@} + + //@{ + /** + Returns the horizontal and vertical resolution in millimetres. + */ + void GetSizeMM(wxCoord* width, wxCoord* height) const; + const wxSize GetSizeMM() const; + //@} + + /** + Gets the current text background colour. + + @see SetTextBackground() + */ + const wxColour GetTextBackground() const; + + //@{ + /** + Gets the dimensions of the string using the currently selected font. + @a string is the text string to measure, @a descent is the dimension + from the baseline of the font to the bottom of the descender, and + @a externalLeading is any extra vertical space added to the font by the + font designer (usually is zero). + + The text extent is returned in @a w and @a h pointers or as a wxSize + object depending on which version of this function is used. + + If the optional parameter @a font is specified and valid, then it is + used for the text extent calculation. Otherwise the currently selected + font is. + + @note This function only works with single-line strings. + + @beginWxPythonOnly + The following methods are implemented in wxPython: + - GetTextExtent(string) - Returns a 2-tuple, (width, height). + - GetFullTextExtent(string, font=NULL) - + Returns a 4-tuple, (width, height, descent, externalLeading). + @endWxPythonOnly + + @see wxFont, SetFont(), GetPartialTextExtents(), + GetMultiLineTextExtent() + */ + void GetTextExtent(const wxString& string, wxCoord* w, wxCoord* h, + wxCoord* descent = NULL, + wxCoord* externalLeading = NULL, + const wxFont* font = NULL) const; + const wxSize GetTextExtent(const wxString& string) const; + //@} + + /** + Gets the current text foreground colour. + + @see SetTextForeground() + */ + const wxColour GetTextForeground() const; + + /** + Gets the current user scale factor. + + @see SetUserScale() + */ + void GetUserScale(double x, double y); + + //@{ + /** + Fill the area specified by rect with a radial gradient, starting from + @a initialColour at the centre of the circle and fading to + @a destColour on the circle outside. + + @a circleCenter are the relative coordinates of centre of the circle in + the specified @e rect. If not specified, the circle is placed at the + centre of rect. + + @note Currently this function is very slow, don't use it for real-time + drawing. + */ + void GradientFillConcentric(const wxRect& rect, + const wxColour& initialColour, + const wxColour& destColour); + void GradientFillConcentric(const wxRect& rect, + const wxColour& initialColour, + const wxColour& destColour, + const wxPoint& circleCenter); + //@} + + /** + Fill the area specified by @a rect with a linear gradient, starting + from @a initialColour and eventually fading to @e destColour. The + @a nDirection specifies the direction of the colour change, default is + to use @a initialColour on the left part of the rectangle and + @a destColour on the right one. + */ + void GradientFillLinear(const wxRect& rect, + const wxColour& initialColour, + const wxColour& destColour, + wxDirection nDirection = wxEAST); + + /** + Returns @true if the DC is ok to use. + */ + bool Ok(); + + /** + Converts logical X coordinate to device coordinate, using the current + mapping mode. + */ + virtual wxCoord LogicalToDeviceX(wxCoord x); + + /** + Converts logical X coordinate to relative device coordinate, using the + current mapping mode but ignoring the x axis orientation. Use this for + converting a width, for example. + */ + virtual wxCoord LogicalToDeviceXRel(wxCoord x); + + /** + Converts logical Y coordinate to device coordinate, using the current + mapping mode. + */ + virtual wxCoord LogicalToDeviceY(wxCoord y); + + /** + Converts logical Y coordinate to relative device coordinate, using the + current mapping mode but ignoring the y axis orientation. Use this for + converting a height, for example. + */ + virtual wxCoord LogicalToDeviceYRel(wxCoord y); + + /** + Gets the maximum horizontal extent used in drawing commands so far. + */ + wxCoord MaxX(); + + /** + Gets the maximum vertical extent used in drawing commands so far. + */ + wxCoord MaxY(); + + /** + Gets the minimum horizontal extent used in drawing commands so far. + */ + wxCoord MinX(); + + /** + Gets the minimum vertical extent used in drawing commands so far. + */ + wxCoord MinY(); + + /** + Resets the bounding box: after a call to this function, the bounding + box doesn't contain anything. + + @see CalcBoundingBox() + */ + void ResetBoundingBox(); + + /** + Sets the x and y axis orientation (i.e., the direction from lowest to + highest values on the axis). The default orientation is x axis from + left to right and y axis from top down. + + @param xLeftRight + True to set the x axis orientation to the natural left to right + orientation, @false to invert it. + @param yBottomUp + True to set the y axis orientation to the natural bottom up + orientation, @false to invert it. + */ + void SetAxisOrientation(bool xLeftRight, bool yBottomUp); + + /** + Sets the current background brush for the DC. + */ + void SetBackground(const wxBrush& brush); + + /** + @a mode may be one of wxSOLID and wxTRANSPARENT. This setting + determines whether text will be drawn with a background colour or not. + */ + void SetBackgroundMode(int mode); + + /** + Sets the current brush for the DC. + + If the argument is wxNullBrush, the current brush is selected out of + the device context (leaving wxDC without any valid brush), allowing the + current brush to be destroyed safely. + + @see wxBrush, wxMemoryDC (for the interpretation of colours when + drawing into a monochrome bitmap) + */ + void SetBrush(const wxBrush& brush); + + //@{ + /** + Sets the clipping region for this device context to the intersection of + the given region described by the parameters of this method and the + previously set clipping region. You should call DestroyClippingRegion() + if you want to set the clipping region exactly to the region specified. + + The clipping region is an area to which drawing is restricted. Possible + uses for the clipping region are for clipping text or for speeding up + window redraws when only a known area of the screen is damaged. + + @see DestroyClippingRegion(), wxRegion + */ + void SetClippingRegion(wxCoord x, wxCoord y, wxCoord width, + wxCoord height); + void SetClippingRegion(const wxPoint& pt, const wxSize& sz); + void SetClippingRegion(const wxRect& rect); + //@} + + /** + Sets the clipping region for this device context. + + Unlike SetClippingRegion(), this function works with physical + coordinates and not with the logical ones. + */ + void SetDeviceClippingRegion(const wxRegion& region); + + /** + Sets the device origin (i.e., the origin in pixels after scaling has + been applied). This function may be useful in Windows printing + operations for placing a graphic on a page. + */ + void SetDeviceOrigin(wxCoord x, wxCoord y); + + /** + Sets the current font for the DC. It must be a valid font, in + particular you should not pass wxNullFont to this method. + + @see wxFont + */ + void SetFont(const wxFont& font); + + /** + Sets the current layout direction for the device context. @a dir may be + either @c wxLayout_Default, @c wxLayout_LeftToRight or + @c wxLayout_RightToLeft. + + @see GetLayoutDirection() + */ + void SetLayoutDirection(wxLayoutDirection dir); + + /** + Sets the current logical function for the device context. This + determines how a source pixel (from a pen or brush colour, or source + device context if using Blit()) combines with a destination pixel in + the current device context. + + The possible values and their meaning in terms of source and + destination pixel values are as follows: + + @verbatim + wxAND src AND dst + wxAND_INVERT (NOT src) AND dst + wxAND_REVERSE src AND (NOT dst) + wxCLEAR 0 + wxCOPY src + wxEQUIV (NOT src) XOR dst + wxINVERT NOT dst + wxNAND (NOT src) OR (NOT dst) + wxNOR (NOT src) AND (NOT dst) + wxNO_OP dst + wxOR src OR dst + wxOR_INVERT (NOT src) OR dst + wxOR_REVERSE src OR (NOT dst) + wxSET 1 + wxSRC_INVERT NOT src + wxXOR src XOR dst + @endverbatim + + The default is wxCOPY, which simply draws with the current colour. The + others combine the current colour and the background using a logical + operation. wxINVERT is commonly used for drawing rubber bands or moving + outlines, since drawing twice reverts to the original colour. + */ + void SetLogicalFunction(int function); + + /** + The mapping mode of the device context defines the unit of measurement + used to convert logical units to device units. Note that in X, text + drawing isn't handled consistently with the mapping mode; a font is + always specified in point size. However, setting the user scale (see + SetUserScale()) scales the text appropriately. In Windows, scalable + TrueType fonts are always used; in X, results depend on availability of + fonts, but usually a reasonable match is found. + + The coordinate origin is always at the top left of the screen/printer. + + Drawing to a Windows printer device context uses the current mapping + mode, but mapping mode is currently ignored for PostScript output. + + The mapping mode can be one of the following: + - wxMM_TWIPS: Each logical unit is 1/20 of a point, or 1/1440 of an + inch. + - wxMM_POINTS: Each logical unit is a point, or 1/72 of an inch. + - wxMM_METRIC: Each logical unit is 1 mm. + - wxMM_LOMETRIC: Each logical unit is 1/10 of a mm. + - wxMM_TEXT: Each logical unit is 1 device pixel. + */ + void SetMapMode(int mode); + + /** + If this is a window DC or memory DC, assigns the given palette to the + window or bitmap associated with the DC. If the argument is + wxNullPalette, the current palette is selected out of the device + context, and the original palette restored. + + @see wxPalette + */ + void SetPalette(const wxPalette& palette); + + /** + Sets the current pen for the DC. If the argument is wxNullPen, the + current pen is selected out of the device context (leaving wxDC without + any valid pen), allowing the current brush to be destroyed safely. + + @see wxMemoryDC for the interpretation of colours when drawing into a + monochrome bitmap. + */ + void SetPen(const wxPen& pen); + + /** + Sets the current text background colour for the DC. + */ + void SetTextBackground(const wxColour& colour); + + /** + Sets the current text foreground colour for the DC. + + @see wxMemoryDC for the interpretation of colours when drawing into a + monochrome bitmap. + */ + void SetTextForeground(const wxColour& colour); + + /** + Sets the user scaling factor, useful for applications which require + 'zooming'. + */ + void SetUserScale(double xScale, double yScale); + + /** + Starts a document (only relevant when outputting to a printer). + @a message is a message to show while printing. + */ + bool StartDoc(const wxString& message); + + /** + Starts a document page (only relevant when outputting to a printer). + */ + bool StartPage(); + + /** + Copy from a source DC to this DC, specifying the destination + coordinates, destination size, source DC, source coordinates, size of + source area to copy, logical function, whether to use a bitmap mask, + and mask source position. + + @param xdest + Destination device context x position. + @param ydest + Destination device context y position. + @param dstWidth + Width of destination area. + @param dstHeight + Height of destination area. + @param source + Source device context. + @param xsrc + Source device context x position. + @param ysrc + Source device context y position. + @param srcWidth + Width of source area to be copied. + @param srcHeight + Height of source area to be copied. + @param logicalFunc + Logical function to use, see SetLogicalFunction(). + @param useMask + If @true, Blit does a transparent blit using the mask that is + associated with the bitmap selected into the source device context. + The Windows implementation does the following if MaskBlt cannot be + used: +
    +
  1. Creates a temporary bitmap and copies the destination area into + it.
    2. +
  2. Copies the source area into the temporary bitmap using the + specified logical function.
    3. +
  3. Sets the masked area in the temporary bitmap to BLACK by ANDing + the mask bitmap with the temp bitmap with the foreground colour + set to WHITE and the bg colour set to BLACK.
    4. +
  4. Sets the unmasked area in the destination area to BLACK by + ANDing the mask bitmap with the destination area with the + foreground colour set to BLACK and the background colour set to + WHITE.
    5. +
  5. ORs the temporary bitmap with the destination area.
    6. +
  6. Deletes the temporary bitmap.
    7. +
+ This sequence of operations ensures that the source's transparent + area need not be black, and logical functions are supported. + @n @b Note: on Windows, blitting with masks can be speeded up + considerably by compiling wxWidgets with the wxUSE_DC_CACHE option + enabled. You can also influence whether MaskBlt or the explicit + mask blitting code above is used, by using wxSystemOptions and + setting the @c no-maskblt option to 1. + @param xsrcMask + Source x position on the mask. If both xsrcMask and ysrcMask are + -1, xsrc and ysrc will be assumed for the mask source position. + Currently only implemented on Windows. + @param ysrcMask + Source y position on the mask. If both xsrcMask and ysrcMask are + -1, xsrc and ysrc will be assumed for the mask source position. + Currently only implemented on Windows. + + There is partial support for Blit() in wxPostScriptDC, under X. + + StretchBlit() is only implemented under wxMAC and wxMSW. + + See wxMemoryDC for typical usage. + + @since 2.9.0 + + @see Blit(), wxMemoryDC, wxBitmap, wxMask + */ + bool StretchBlit(wxCoord xdest, wxCoord ydest, + wxCoord dstWidth, wxCoord dstHeight, + wxDC* source, wxCoord xsrc, wxCoord ysrc, + wxCoord srcWidth, wxCoord srcHeight, + int logicalFunc = wxCOPY, + bool useMask = false, + wxCoord xsrcMask = -1, wxCoord ysrcMask = -1); +}; + + + +/** + @class wxDCClipper + @wxheader{dc.h} + + wxDCClipper is a small helper class for setting a clipping region on a wxDC + and unsetting it automatically. An object of wxDCClipper class is typically + created on the stack so that it is automatically destroyed when the object + goes out of scope. A typical usage example: + + @code + void MyFunction(wxDC& dc) + { + wxDCClipper clip(dc, rect); + // ... drawing functions here are affected by clipping rect ... + } + + void OtherFunction() + { + wxDC dc; + MyFunction(dc); + // ... drawing functions here are not affected by clipping rect ... + } + @endcode + + @library{wxcore} + @category{gdi} + + @see wxDC::SetClippingRegion() +*/ +class wxDCClipper +{ +public: + //@{ + /** + Sets the clipping region to the specified region/coordinates. + + The clipping region is automatically unset when this object is destroyed. + */ + wxDCClipper(wxDC& dc, const wxRegion& r); + wxDCClipper(wxDC& dc, const wxRect& rect); + wxDCClipper(wxDC& dc, int x, int y, int w, int h); + //@} +}; + diff --git a/interface/wx/dcbuffer.h b/interface/wx/dcbuffer.h new file mode 100644 index 0000000000..569ccdba03 --- /dev/null +++ b/interface/wx/dcbuffer.h @@ -0,0 +1,180 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: dcbuffer.h +// Purpose: interface of wxBufferedDC +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxBufferedDC + @wxheader{dcbuffer.h} + + This class provides a simple way to avoid flicker: when drawing on it, + everything is in fact first drawn on an in-memory buffer (a wxBitmap) and + then copied to the screen, using the associated wxDC, only once, when this + object is destroyed. wxBufferedDC itself is typically associated with + wxClientDC, if you want to use it in your @c EVT_PAINT handler, you should + look at wxBufferedPaintDC instead. + + When used like this, a valid @e DC must be specified in the constructor + while the @e buffer bitmap doesn't have to be explicitly provided, by + default this class will allocate the bitmap of required size itself. + However using a dedicated bitmap can speed up the redrawing process by + eliminating the repeated creation and destruction of a possibly big bitmap. + Otherwise, wxBufferedDC can be used in the same way as any other device + context. + + There is another possible use for wxBufferedDC is to use it to maintain a + backing store for the window contents. In this case, the associated @e DC + may be @NULL but a valid backing store bitmap should be specified. + + Finally, please note that GTK+ 2.0 as well as OS X provide double buffering + themselves natively. You can either use wxWindow::IsDoubleBuffered() to + determine whether you need to use buffering or not, or use + wxAutoBufferedPaintDC to avoid needless double buffering on the systems + which already do it automatically. + + @library{wxcore} + @category{dc} + + @see wxDC, wxMemoryDC, wxBufferedPaintDC, wxAutoBufferedPaintDC +*/ +class wxBufferedDC : public wxMemoryDC +{ +public: + /** + Default constructor. You must call one of the Init() methods later in + order to use the device context. + */ + wxBufferedDC(); + + //@{ + /** + Creates a buffer for the provided @dc. Init() must not be called when + using this constructor. + + @param dc + The underlying DC: everything drawn to this object will be flushed + to this DC when this object is destroyed. You may pass @NULL in + order to just initialize the buffer, and not flush it. + @param area + The size of the bitmap to be used for buffering (this bitmap is + created internally when it is not given explicitly). + @param buffer + Explicitly provided bitmap to be used for buffering: this is the + most efficient solution as the bitmap doesn't have to be recreated + each time but it also requires more memory as the bitmap is never + freed. The bitmap should have appropriate size, anything drawn + outside of its bounds is clipped. + @param style + wxBUFFER_CLIENT_AREA to indicate that just the client area of the + window is buffered, or wxBUFFER_VIRTUAL_AREA to indicate that the + buffer bitmap covers the virtual area. + */ + wxBufferedDC(wxDC* dc, const wxSize& area, + int style = wxBUFFER_CLIENT_AREA); + wxBufferedDC(wxDC* dc, wxBitmap& buffer, + int style = wxBUFFER_CLIENT_AREA); + //@} + + /** + Copies everything drawn on the DC so far to the underlying DC + associated with this object, if any. + */ + ~wxBufferedDC(); + + //@{ + /** + Initializes the object created using the default constructor. Please + see the constructors for parameter details. + */ + void Init(wxDC* dc, const wxSize& area, + int style = wxBUFFER_CLIENT_AREA); + void Init(wxDC* dc, wxBitmap& buffer, + int style = wxBUFFER_CLIENT_AREA); + //@} +}; + + + +/** + @class wxAutoBufferedPaintDC + @wxheader{dcbuffer.h} + + This wxDC derivative can be used inside of an @c EVT_PAINT() event handler + to achieve double-buffered drawing. Just use this class instead of + wxPaintDC and make sure wxWindow::SetBackgroundStyle() is called with + wxBG_STYLE_CUSTOM somewhere in the class initialization code, and that's + all you have to do to (mostly) avoid flicker. + + The difference between wxBufferedPaintDC and this class is that this class + won't double-buffer on platforms which have native double-buffering + already, avoiding any unneccessary buffering to avoid flicker. + + wxAutoBufferedPaintDC is simply a typedef of wxPaintDC on platforms that + have native double-buffering, otherwise, it is a typedef of + wxBufferedPaintDC. + + @library{wxbase} + @category{dc} + + @see wxDC, wxBufferedPaintDC, wxPaintDC +*/ +class wxAutoBufferedPaintDC : public wxBufferedPaintDC +{ +public: + /** + Constructor. Pass a pointer to the window on which you wish to paint. + */ + wxAutoBufferedPaintDC(wxWindow* window); +}; + + + +/** + @class wxBufferedPaintDC + @wxheader{dcbuffer.h} + + This is a subclass of wxBufferedDC which can be used inside of an + @c EVT_PAINT() event handler to achieve double-buffered drawing. Just use + this class instead of wxPaintDC and make sure + wxWindow::SetBackgroundStyle() is called with wxBG_STYLE_CUSTOM somewhere + in the class initialization code, and that's all you have to do to (mostly) + avoid flicker. The only thing to watch out for is that if you are using + this class together with wxScrolled, you probably do @b not want to call + wxScrolled::PrepareDC() on it as it already does this internally for the + real underlying wxPaintDC. + + @library{wxcore} + @category{dc} + + @see wxDC, wxBufferedDC, wxAutoBufferedPaintDC, wxPaintDC +*/ +class wxBufferedPaintDC : public wxBufferedDC +{ +public: + //@{ + /** + As with wxBufferedDC, you may either provide the bitmap to be used for + buffering or let this object create one internally (in the latter case, + the size of the client part of the window is used). + + Pass wxBUFFER_CLIENT_AREA for the @a style parameter to indicate that + just the client area of the window is buffered, or + wxBUFFER_VIRTUAL_AREA to indicate that the buffer bitmap covers the + virtual area. + */ + wxBufferedPaintDC(wxWindow* window, wxBitmap& buffer, + int style = wxBUFFER_CLIENT_AREA); + wxBufferedPaintDC(wxWindow* window, + int style = wxBUFFER_CLIENT_AREA); + //@} + + /** + Copies everything drawn on the DC so far to the window associated with + this object, using a wxPaintDC. + */ + ~wxBufferedPaintDC(); +}; + diff --git a/interface/wx/dcclient.h b/interface/wx/dcclient.h new file mode 100644 index 0000000000..17f39ca1a8 --- /dev/null +++ b/interface/wx/dcclient.h @@ -0,0 +1,112 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: dcclient.h +// Purpose: interface of wxClientDC and wxPaintDC +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxPaintDC + @wxheader{dcclient.h} + + A wxPaintDC must be constructed if an application wishes to paint on the + client area of a window from within an EVT_PAINT() event handler. This + should normally be constructed as a temporary stack object; don't store a + wxPaintDC object. If you have an EVT_PAINT() handler, you @e must create a + wxPaintDC object within it even if you don't actually use it. + + Using wxPaintDC within your EVT_PAINT() handler is important because it + automatically sets the clipping area to the damaged area of the window. + Attempts to draw outside this area do not appear. + + To draw on a window from outside your EVT_PAINT() handler, construct a + wxClientDC object. + + To draw on the whole window including decorations, construct a wxWindowDC + object (Windows only). + + A wxPaintDC object is initialized to use the same font and colours as the + window it is associated with. + + @library{wxcore} + @category{dc} + + @see wxDC, wxClientDC, wxMemoryDC, wxWindowDC, wxScreenDC +*/ +class wxPaintDC : public wxWindowDC +{ +public: + /** + Constructor. Pass a pointer to the window on which you wish to paint. + */ + wxPaintDC(wxWindow* window); +}; + + + +/** + @class wxClientDC + @wxheader{dcclient.h} + + A wxClientDC must be constructed if an application wishes to paint on the + client area of a window from outside an EVT_PAINT() handler. This should + normally be constructed as a temporary stack object; don't store a + wxClientDC object. + + To draw on a window from within an EVT_PAINT() handler, construct a + wxPaintDC object instead. + + To draw on the whole window including decorations, construct a wxWindowDC + object (Windows only). + + A wxClientDC object is initialized to use the same font and colours as the + window it is associated with. + + @library{wxcore} + @category{dc} + + @see wxDC, wxMemoryDC, wxPaintDC, wxWindowDC, wxScreenDC +*/ +class wxClientDC : public wxWindowDC +{ +public: + /** + Constructor. Pass a pointer to the window on which you wish to paint. + */ + wxClientDC(wxWindow* window); +}; + + + +/** + @class wxWindowDC + @wxheader{dcclient.h} + + A wxWindowDC must be constructed if an application wishes to paint on the + whole area of a window (client and decorations). This should normally be + constructed as a temporary stack object; don't store a wxWindowDC object. + + To draw on a window from inside an EVT_PAINT() handler, construct a + wxPaintDC object instead. + + To draw on the client area of a window from outside an EVT_PAINT() handler, + construct a wxClientDC object. + + A wxWindowDC object is initialized to use the same font and colours as the + window it is associated with. + + @library{wxcore} + @category{dc} + + @see wxDC, wxMemoryDC, wxPaintDC, wxClientDC, wxScreenDC +*/ +class wxWindowDC : public wxDC +{ +public: + /** + Constructor. Pass a pointer to the window on which you wish to paint. + */ + wxWindowDC(wxWindow* window); +}; + diff --git a/interface/wx/dcgraph.h b/interface/wx/dcgraph.h new file mode 100644 index 0000000000..e4d4459bfc --- /dev/null +++ b/interface/wx/dcgraph.h @@ -0,0 +1,44 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: dcgraph.h +// Purpose: interface of wxGCDC +// Author: wxWidgets team +// RCS-ID: $Id: $ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxGCDC + @wxheader{dcgraph.h} + + wxGCDC is a device context that draws on a wxGraphicsContext. + + @library{wxcore} + @category{dc} + + @see wxDC, wxGraphicsContext +*/ + +class wxGCDC: public wxDC +{ +public: + /** + Constructs a wxGCDC from a wxWindowDC. + */ + wxGCDC( const wxWindowDC& dc ); + + /** + Constructs a wxGCDC from a wxMemoryDC. + */ + wxGCDC( const wxMemoryDC& dc ); + + /** + Constructs a wxGCDC from a wxPrinterDC. + */ + wxGCDC( const wxPrinterDC& dc ); + + /** + Retrieves associated wxGraphicsContext + */ + wxGraphicsContext* GetGraphicsContext(); +}; + diff --git a/interface/wx/dcmemory.h b/interface/wx/dcmemory.h new file mode 100644 index 0000000000..e1e6a998eb --- /dev/null +++ b/interface/wx/dcmemory.h @@ -0,0 +1,99 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: dcmemory.h +// Purpose: interface of wxMemoryDC +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxMemoryDC + @wxheader{dcmemory.h} + + A memory device context provides a means to draw graphics onto a bitmap. + When drawing in to a mono-bitmap, using @c wxWHITE, @c wxWHITE_PEN and + @c wxWHITE_BRUSH will draw the background colour (i.e. 0) whereas all other + colours will draw the foreground colour (i.e. 1). + + A bitmap must be selected into the new memory DC before it may be used for + anything. Typical usage is as follows: + + @code + // Create a memory DC + wxMemoryDC temp_dc; + temp_dc.SelectObject(test_bitmap); + + // We can now draw into the memory DC... + // Copy from this DC to another DC. + old_dc.Blit(250, 50, BITMAP_WIDTH, BITMAP_HEIGHT, temp_dc, 0, 0); + @endcode + + Note that the memory DC must be deleted (or the bitmap selected out of it) + before a bitmap can be reselected into another memory DC. + + And, before performing any other operations on the bitmap data, the bitmap + must be selected out of the memory DC: + + @code + temp_dc.SelectObject(wxNullBitmap); + @endcode + + This happens automatically when wxMemoryDC object goes out of scope. + + @library{wxcore} + @category{dc} + + @see wxBitmap, wxDC +*/ +class wxMemoryDC : public wxDC +{ +public: + /** + Constructs a new memory device context. + + Use the wxDC::Ok() member to test whether the constructor was + successful in creating a usable device context. Don't forget to select + a bitmap into the DC before drawing on it. + */ + wxMemoryDC(); + /** + Constructs a new memory device context and calls SelectObject() with + the given bitmap. + + Use the wxDC::Ok() member to test whether the constructor was + successful in creating a usable device context. + */ + wxMemoryDC(wxBitmap& bitmap); + + /** + Works exactly like SelectObjectAsSource() but this is the function you + should use when you select a bitmap because you want to modify it, e.g. + drawing on this DC. + + Using SelectObjectAsSource() when modifying the bitmap may incurr some + problems related to wxBitmap being a reference counted object (see + @ref overview_refcount). + + Also, before using the updated bitmap data, make sure to select it out + of context first (for example by selecting wxNullBitmap into the device + context). + + @see wxDC::DrawBitmap() + */ + void SelectObject(wxBitmap& bitmap); + + /** + Selects the given bitmap into the device context, to use as the memory + bitmap. Selecting the bitmap into a memory DC allows you to draw into + the DC (and therefore the bitmap) and also to use wxDC::Blit() to copy + the bitmap to a window. For this purpose, you may find wxDC::DrawIcon() + easier to use instead. + + If the argument is wxNullBitmap (or some other uninitialised wxBitmap) + the current bitmap is selected out of the device context, and the + original bitmap restored, allowing the current bitmap to be destroyed + safely. + */ + void SelectObjectAsSource(const wxBitmap& bitmap); +}; + diff --git a/interface/wx/dcmirror.h b/interface/wx/dcmirror.h new file mode 100644 index 0000000000..d15af962f0 --- /dev/null +++ b/interface/wx/dcmirror.h @@ -0,0 +1,37 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: dcmirror.h +// Purpose: interface of wxMirrorDC +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxMirrorDC + @wxheader{dcmirror.h} + + wxMirrorDC is a simple wrapper class which is always associated with a real + wxDC object and either forwards all of its operations to it without changes + (no mirroring takes place) or exchanges @e x and @e y coordinates which + makes it possible to reuse the same code to draw a figure and its mirror -- + i.e. reflection related to the diagonal line x == y. + + @since 2.5.0 + + @library{wxcore} + @category{dc} +*/ +class wxMirrorDC : public wxDC +{ +public: + /** + Creates a (maybe) mirrored DC associated with the real @a dc. + Everything drawn on wxMirrorDC will appear (and maybe mirrored) on + @a dc. + + @a mirror specifies if we do mirror (if it is @true) or not (if it is + @false). + */ + wxMirrorDC(wxDC& dc, bool mirror); +}; + diff --git a/interface/wx/dcprint.h b/interface/wx/dcprint.h new file mode 100644 index 0000000000..db6c74f0eb --- /dev/null +++ b/interface/wx/dcprint.h @@ -0,0 +1,60 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: dcprint.h +// Purpose: interface of wxPrinterDC +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxPrinterDC + @wxheader{dcprint.h} + + A printer device context is specific to MSW and Mac, and allows access to + any printer with a Windows or Macintosh driver. See wxDC for further + information on device contexts, and wxDC::GetSize() for advice on achieving + the correct scaling for the page. + + @library{wxcore} + @category{printing} + + @see @ref overview_printing, wxDC +*/ +class wxPrinterDC : public wxDC +{ +public: + /** + Constructor. Pass a wxPrintData object with information necessary for + setting up a suitable printer device context. This is the recommended + way to construct a wxPrinterDC. Make sure you specify a reference to a + wxPrintData object, not a pointer - you may not even get a warning if + you pass a pointer instead. + */ + wxPrinterDC(const wxPrintData& printData); + /** + Constructor. With empty strings for the first three arguments, the + default printer dialog is displayed. @a device indicates the type of + printer and @a output is an optional file for printing to. The + @a driver parameter is currently unused. Use the wxDC::Ok() member to + test whether the constructor was successful in creating a usable device + context. + + @deprecated This constructor is deprecated and retained only for + backward compatibility. + */ + wxPrinterDC(const wxString& driver, const wxString& device, + const wxString& output, const bool interactive = true, + int orientation = wxPORTRAIT); + + /** + Return the rectangle in device coordinates that corresponds to the full + paper area, including the nonprinting regions of the paper. The point + (0,0) in device coordinates is the top left corner of the page + rectangle, which is the printable area on MSW and Mac. The coordinates + of the top left corner of the paper rectangle will therefore have small + negative values, while the bottom right coordinates will be somewhat + larger than the values returned by wxDC::GetSize(). + */ + wxRect wxPrinterDC::GetPaperRect(); +}; + diff --git a/interface/wx/dcps.h b/interface/wx/dcps.h new file mode 100644 index 0000000000..34630fb92f --- /dev/null +++ b/interface/wx/dcps.h @@ -0,0 +1,58 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: dcps.h +// Purpose: interface of wxPostScriptDC +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxPostScriptDC + @wxheader{dcps.h} + + This defines the wxWidgets Encapsulated PostScript device context, which + can write PostScript files on any platform. See wxDC for descriptions of + the member functions. + + @library{wxbase} + @category{dc} +*/ +class wxPostScriptDC : public wxDC +{ +public: + /** + Constructs a PostScript printer device context from a wxPrintData + object. + */ + wxPostScriptDC(const wxPrintData& printData); + /** + Constructor. @a output is an optional file for printing to, and if + @a interactive is @true a dialog box will be displayed for adjusting + various parameters. @a parent is the parent of the printer dialog box. + + Use the wxDC::Ok() member to test whether the constructor was + successful in creating a usable device context. + + See wxPrintData for various functions to set and get PostScript + printing settings. + + @deprecated This constructor is deprecated. + */ + wxPostScriptDC(const wxString& output, + bool interactive = true, + wxWindow* parent); + + /** + Return resolution used in PostScript output. + + @see SetResolution() + */ + static int GetResolution(); + + /** + Set resolution (in pixels per inch) that will be used in PostScript + output. Default is 720ppi. + */ + static void SetResolution(int ppi); +}; + diff --git a/interface/wx/dcscreen.h b/interface/wx/dcscreen.h new file mode 100644 index 0000000000..80e4c9ec66 --- /dev/null +++ b/interface/wx/dcscreen.h @@ -0,0 +1,83 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: dcscreen.h +// Purpose: interface of wxScreenDC +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxScreenDC + @wxheader{dcscreen.h} + + A wxScreenDC can be used to paint on the screen. This should normally be + constructed as a temporary stack object; don't store a wxScreenDC object. + + @library{wxcore} + @category{dc} + + @see wxDC, wxMemoryDC, wxPaintDC, wxClientDC, wxWindowDC +*/ +class wxScreenDC : public wxDC +{ +public: + /** + Constructor. + */ + wxScreenDC(); + + /** + Use this in conjunction with StartDrawingOnTop(). + + This function destroys the temporary window created to implement on-top + drawing (X only). + */ + bool EndDrawingOnTop(); + + /** + Use this in conjunction with EndDrawingOnTop() to ensure that drawing + to the screen occurs on top of existing windows. Without this, some + window systems (such as X) only allow drawing to take place underneath + other windows. + + This version of StartDrawingOnTop() is used to specify that the area + that will be drawn on coincides with the given window. It is + recommended that an area of the screen is specified with + StartDrawingOnTop(wxRect*) because with large regions, flickering + effects are noticeable when destroying the temporary transparent window + used to implement this feature. + + You might use this function when implementing a drag feature, for + example as in the wxSplitterWindow implementation. + + @remarks This function is probably obsolete since the X implementations + allow drawing directly on the screen now. However, the fact + that this function allows the screen to be refreshed + afterwards, may be useful to some applications. + */ + bool StartDrawingOnTop(wxWindow* window); + /** + Use this in conjunction with EndDrawingOnTop() to ensure that drawing + to the screen occurs on top of existing windows. Without this, some + window systems (such as X) only allow drawing to take place underneath + other windows. + + This version of StartDrawingOnTop() is used to specify an area of the + screen which is to be drawn on. If @NULL is passed, the whole screen is + available. It is recommended that an area of the screen is specified + with this function rather than with StartDrawingOnTop(wxWindow*), + because with large regions, flickering effects are noticeable when + destroying the temporary transparent window used to implement this + feature. + + You might use this function when implementing a drag feature, for + example as in the wxSplitterWindow implementation. + + @remarks This function is probably obsolete since the X implementations + allow drawing directly on the screen now. However, the fact + that this function allows the screen to be refreshed + afterwards, may be useful to some applications. + */ + bool StartDrawingOnTop(wxRect* rect = NULL); +}; + diff --git a/interface/wx/dcsvg.h b/interface/wx/dcsvg.h new file mode 100644 index 0000000000..bae993d5a3 --- /dev/null +++ b/interface/wx/dcsvg.h @@ -0,0 +1,660 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: dcsvg.h +// Purpose: interface of wxSVGFileDC +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxSVGFileDC + @wxheader{dcsvg.h} + + A wxSVGFileDC is a device context onto which graphics and text can be + drawn, and the output produced as a vector file, in SVG format (see the W3C + SVG Specifications ). This + format can be read by a range of programs, including a Netscape plugin + (Adobe), full details are given in the SVG Implementation and Resource + Directory . Vector formats may often be smaller than + raster formats. + + The intention behind wxSVGFileDC is that it can be used to produce a file + corresponding to the screen display context, wxSVGFileDC, by passing the + wxSVGFileDC as a parameter instead of a wxSVGFileDC. Thus the wxSVGFileDC + is a write-only class. + + As the wxSVGFileDC is a vector format, raster operations like GetPixel() + are unlikely to be supported. However, the SVG specification allows for PNG + format raster files to be embedded in the SVG, and so bitmaps, icons and + blit operations in wxSVGFileDC are supported. + + A more substantial SVG library (for reading and writing) is available at + the wxArt2D website . + + @library{wxcore} + @category{dc} +*/ +class wxSVGFileDC : public wxDC +{ +public: + /** + Initializes a wxSVGFileDC with the given @a f filename with a default + size (340x240) at 72.0 dots per inch (a frequent screen resolution). + */ + wxSVGFileDC(wxString f); + /** + Initializes a wxSVGFileDC with the given @a f filename with the given + @a Width and @a Height at 72.0 dots per inch. + */ + wxSVGFileDC(wxString f, int Width, int Height); + /** + Initializes a wxSVGFileDC with the given @a f filename with the given + @a Width and @a Height at @a dpi resolution. + */ + wxSVGFileDC(wxString f, int Width, int Height, float dpi); + + /** + Destructor. + */ + ~wxSVGFileDC(); + + /** + Copies from a source DC to this DC, specifying the destination + coordinates, size of area to copy, source DC, source coordinates, + logical function, whether to use a bitmap mask, and mask source + position. + + @see wxDC::Blit() + */ + bool Blit(wxCoord xdest, wxCoord ydest, wxCoord width, wxCoord height, + wxSVGFileDC* source, wxCoord xsrc, wxCoord ysrc, + int logicalFunc = wxCOPY, bool useMask = FALSE, + wxCoord xsrcMask = -1, wxCoord ysrcMask = -1); + + /** + Adds the specified point to the bounding box which can be retrieved + with wxDC::MinX(), wxDC::MaxX() and wxDC::MinY(), wxDC::MaxY() + functions. + */ + void CalcBoundingBox(wxCoord x, wxCoord y); + + /** + This makes no sense in wxSVGFileDC and does nothing. + */ + void Clear(); + + /** + Not Implemented. + */ + void CrossHair(wxCoord x, wxCoord y); + + /** + Not Implemented. + */ + void DestroyClippingRegion(); + + /** + Convert device X coordinate to logical coordinate, using the current + mapping mode. + */ + wxCoord DeviceToLogicalX(wxCoord x); + + /** + Convert device X coordinate to relative logical coordinate, using the + current mapping mode but ignoring the x axis orientation. Use this + function for converting a width, for example. + */ + wxCoord DeviceToLogicalXRel(wxCoord x); + + /** + Converts device Y coordinate to logical coordinate, using the current + mapping mode. + */ + wxCoord DeviceToLogicalY(wxCoord y); + + /** + Convert device Y coordinate to relative logical coordinate, using the + current mapping mode but ignoring the y axis orientation. Use this + function for converting a height, for example. + */ + wxCoord DeviceToLogicalYRel(wxCoord y); + + /** + Draws an arc of a circle, centred on (@a xc, @a yc), with starting + point (@a x1, @a y1) and ending at (@a x2, @a y2). The current pen is + used for the outline and the current brush for filling the shape. + + The arc is drawn in a counter-clockwise direction from the start point + to the end point. + */ + void DrawArc(wxCoord x1, wxCoord y1, wxCoord x2, wxCoord y2, + wxCoord xc, wxCoord yc); + + /** + Draw a bitmap on the device context at the specified point. If + @a transparent is @true and the bitmap has a transparency mask, the + bitmap will be drawn transparently. + + When drawing a mono-bitmap, the current text foreground colour will be + used to draw the foreground of the bitmap (all bits set to 1), and the + current text background colour to draw the background (all bits set to + 0). + + @see wxDC::SetTextForeground(), wxDC::SetTextBackground(), wxMemoryDC + */ + void DrawBitmap(const wxBitmap& bitmap, wxCoord x, wxCoord y, + bool transparent); + + //@{ + /** + Draws a check mark inside the given rectangle. + */ + void DrawCheckMark(wxCoord x, wxCoord y, wxCoord width, wxCoord height); + void DrawCheckMark(const wxRect& rect); + //@} + + //@{ + /** + Draws a circle with the given centre and radius. + + @see wxDC::DrawEllipse() + */ + void DrawCircle(wxCoord x, wxCoord y, wxCoord radius); + void DrawCircle(const wxPoint& pt, wxCoord radius); + //@} + + //@{ + /** + Draws an ellipse contained in the rectangle specified either with the + given top left corner and the given size or directly. The current pen + is used for the outline and the current brush for filling the shape. + + @see wxDC::DrawCircle() + */ + void DrawEllipse(wxCoord x, wxCoord y, wxCoord width, wxCoord height); + void DrawEllipse(const wxPoint& pt, const wxSize& size); + void DrawEllipse(const wxRect& rect); + //@} + + /** + Draws an arc of an ellipse. The current pen is used for drawing the arc + and the current brush is used for drawing the pie. + + @a x and @a y specify the x and y coordinates of the upper-left corner + of the rectangle that contains the ellipse. + + @a width and @a height specify the width and height of the rectangle + that contains the ellipse. + + @a start and @a end specify the start and end of the arc relative to + the three-o'clock position from the center of the rectangle. Angles are + specified in degrees (360 is a complete circle). Positive values mean + counter-clockwise motion. If @a start is equal to @a end, a complete + ellipse will be drawn. + */ + void DrawEllipticArc(wxCoord x, wxCoord y, wxCoord width, wxCoord height, + double start, double end); + + /** + Draw an icon on the display (does nothing if the device context is + PostScript). This can be the simplest way of drawing bitmaps on a + window. + */ + void DrawIcon(const wxIcon& icon, wxCoord x, wxCoord y); + + /** + Draws a line from the first point to the second. The current pen is + used for drawing the line. + */ + void DrawLine(wxCoord x1, wxCoord y1, wxCoord x2, wxCoord y2); + + //@{ + /** + Draws lines using an array of @a points of size @a n, or list of + pointers to points, adding the optional offset coordinate. The current + pen is used for drawing the lines. The programmer is responsible for + deleting the list of points. + */ + void DrawLines(int n, wxPoint points[], wxCoord xoffset = 0, + wxCoord yoffset = 0); + void DrawLines(wxList* points, wxCoord xoffset = 0, + wxCoord yoffset = 0); + //@} + + /** + Draws a point using the current pen. + */ + void DrawPoint(wxCoord x, wxCoord y); + + //@{ + /** + Draws a filled polygon using an array of @a points of size @a n, + or list of pointers to points, adding the optional offset coordinate. + wxWidgets automatically closes the first and last points. + + The last argument specifies the fill rule: @c wxODDEVEN_RULE (the + default) or @c wxWINDING_RULE. + + The current pen is used for drawing the outline, and the current brush + for filling the shape. Using a transparent brush suppresses filling. + + The programmer is responsible for deleting the list of points. + */ + void DrawPolygon(int n, wxPoint points[], wxCoord xoffset = 0, + wxCoord yoffset = 0, int fill_style = wxODDEVEN_RULE); + void DrawPolygon(wxList* points, wxCoord xoffset = 0, + wxCoord yoffset = 0, int fill_style = wxODDEVEN_RULE); + //@} + + /** + Draws a rectangle with the given top left corner, and with the given + size. The current pen is used for the outline and the current brush + for filling the shape. + */ + void DrawRectangle(wxCoord x, wxCoord y, wxCoord width, wxCoord height); + + /** + Draws the text rotated by @a angle degrees. + + The wxMSW wxDC and wxSVGFileDC rotate the text around slightly + different points, depending on the size of the font. + */ + void DrawRotatedText(const wxString& text, wxCoord x, wxCoord y, + double angle); + + /** + Draws a rectangle with the given top left corner, and with the given + size. The corners are quarter-circles using the given radius. The + current pen is used for the outline and the current brush for filling + the shape. + + If @a radius is positive, the value is assumed to be the radius of the + rounded corner. If @a radius is negative, the absolute value is assumed + to be the @e proportion of the smallest dimension of the rectangle. + This means that the corner can be a sensible size relative to the size + of the rectangle, and also avoids the strange effects X produces when + the corners are too big for the rectangle. + */ + void DrawRoundedRectangle(wxCoord x, wxCoord y, wxCoord width, + wxCoord height, double radius = 20); + + /** + Draws a spline between all given control points, using the current pen. + The programmer is responsible for deleting the list of points. The + spline is drawn using a series of lines, using an algorithm taken from + the X drawing program "XFIG". + */ + void DrawSpline(wxList* points); + /** + @param string + The text string to measure. + Draws a three-point spline using the current pen. + */ + void DrawSpline(wxCoord x1, wxCoord y1, wxCoord x2, wxCoord y2, + wxCoord x3, wxCoord y3); + + /** + Draws a text string at the specified point, using the current text + font, and the current text foreground and background colours. + + The coordinates refer to the top-left corner of the rectangle bounding + the string. See wxDC::GetTextExtent() for how to get the dimensions of + a text string, which can be used to position the text more precisely. + */ + void DrawText(const wxString& text, wxCoord x, wxCoord y); + + /** + Does nothing. + */ + void EndDoc(); + + /** + Does nothing. + */ + void EndDrawing(); + + /** + Does nothing. + */ + void EndPage(); + + /** + Not implemented. + */ + void FloodFill(wxCoord x, wxCoord y, const wxColour& colour, + int style = wxFLOOD_SURFACE); + + //@{ + /** + Gets the brush used for painting the background. + + @see SetBackground() + */ + wxBrush GetBackground() const; + const wxBrush GetBackground() const; + //@} + + /** + Returns the current background mode: @c wxSOLID or @c wxTRANSPARENT. + + @see SetBackgroundMode() + */ + int GetBackgroundMode() const; + + //@{ + /** + Gets the current brush. + + @see SetBrush() + */ + wxBrush GetBrush() const; + const wxBrush GetBrush() const; + //@} + + /** + Gets the character height of the currently set font. + */ + wxCoord GetCharHeight(); + + /** + Gets the average character width of the currently set font. + */ + wxCoord GetCharWidth(); + + /** + Not implemented. + */ + void GetClippingBox(wxCoord x, wxCoord y, wxCoord width, wxCoord height); + + //@{ + /** + Gets the current font. + + @see SetFont() + */ + wxFont GetFont() const; + const wxFont GetFont() const; + //@} + + /** + Gets the current logical function. + + @see SetLogicalFunction() + */ + int GetLogicalFunction(); + + /** + Gets the mapping mode for the device context. + + @see SetMapMode() + */ + int GetMapMode(); + + //@{ + /** + Gets the current pen. + + @see SetPen() + */ + wxPen GetPen() const; + const wxPen GetPen() const; + //@} + + /** + Not implemented. + */ + bool GetPixel(wxCoord x, wxCoord y, wxColour* colour); + + /** + For a Windows printer device context, this gets the horizontal and + vertical resolution. + */ + void GetSize(wxCoord* width, wxCoord* height); + + //@{ + /** + Gets the current text background colour. + + @see SetTextBackground() + */ + wxColour GetTextBackground() const; + const wxColour GetTextBackground() const; + //@} + + /** + Gets the dimensions of the string using the currently selected font. + + @param string + The text string to measure. + @param w + This value will be set to the width after this call. + @param h + This value will be set to the height after this call. + @param descent + The dimension from the baseline of the font to the bottom of the + descender. + @param externalLeading + Any extra vertical space added to the font by the font designer + (usually is zero). + + The optional parameter @a font specifies an alternative to the + currently selected font: but note that this does not yet work under + Windows, so you need to set a font for the device context first. + + @see wxFont, SetFont() + */ + void GetTextExtent(const wxString& string, wxCoord* w, wxCoord* h, + wxCoord* descent = NULL, + wxCoord* externalLeading = NULL, + wxFont* font = NULL); + + //@{ + /** + Gets the current text foreground colour. + + @see SetTextForeground() + */ + wxColour GetTextForeground() const; + const wxColour GetTextForeground() const; + //@} + + /** + Gets the current user scale factor. + + @see SetUserScale() + */ + void GetUserScale(double x, double y); + + /** + Converts logical X coordinate to device coordinate, using the current + mapping mode. + */ + wxCoord LogicalToDeviceX(wxCoord x); + + /** + Converts logical X coordinate to relative device coordinate, using the + current mapping mode but ignoring the x axis orientation. Use this for + converting a width, for example. + */ + wxCoord LogicalToDeviceXRel(wxCoord x); + + /** + Converts logical Y coordinate to device coordinate, using the current + mapping mode. + */ + wxCoord LogicalToDeviceY(wxCoord y); + + /** + Converts logical Y coordinate to relative device coordinate, using the + current mapping mode but ignoring the y axis orientation. Use this for + converting a height, for example. + */ + wxCoord LogicalToDeviceYRel(wxCoord y); + + /** + Gets the maximum horizontal extent used in drawing commands so far. + */ + wxCoord MaxX(); + + /** + Gets the maximum vertical extent used in drawing commands so far. + */ + wxCoord MaxY(); + + /** + Gets the minimum horizontal extent used in drawing commands so far. + */ + wxCoord MinX(); + + /** + Gets the minimum vertical extent used in drawing commands so far. + */ + wxCoord MinY(); + + /** + Returns @true if the DC is ok to use. @false values arise from being + unable to write the file. + */ + bool Ok(); + + /** + Resets the bounding box. After a call to this function, the bounding + box doesn't contain anything. + + @see CalcBoundingBox() + */ + void ResetBoundingBox(); + + /** + Sets the x and y axis orientation (i.e., the direction from lowest to + highest values on the axis). The default orientation is the natural + orientation, e.g. x axis from left to right and y axis from bottom up. + + @param xLeftRight + @true to set the x axis orientation to the natural left to right + orientation, @false to invert it. + @param yBottomUp + @true to set the y axis orientation to the natural bottom up + orientation, @false to invert it. + */ + void SetAxisOrientation(bool xLeftRight, bool yBottomUp); + + /** + Sets the current background brush for the DC. + */ + void SetBackground(const wxBrush& brush); + + /** + @a mode may be one of wxSOLID and wxTRANSPARENT. This setting determines + whether text will be drawn with a background colour or not. + */ + void SetBackgroundMode(int mode); + + /** + Sets the current brush for the DC. If the argument is wxNullBrush, the + current brush is selected out of the device context, and the original + brush restored, allowing the current brush to be destroyed safely. + + @see wxBrush, wxMemoryDC (for the interpretation of colours + when drawing into a monochrome bitmap). + */ + void SetBrush(const wxBrush& brush); + + //@{ + /** + Not implemented. + */ + void SetClippingRegion(wxCoord x, wxCoord y, wxCoord width, + wxCoord height); + void SetClippingRegion(const wxPoint& pt, const wxSize& sz); + void SetClippingRegion(const wxRect& rect); + void SetClippingRegion(const wxRegion& region); + //@} + + /** + Sets the device origin (i.e., the origin in pixels after scaling has + been applied). This function may be useful in Windows printing + operations for placing a graphic on a page. + */ + void SetDeviceOrigin(wxCoord x, wxCoord y); + + /** + Sets the current font for the DC. It must be a valid font, in + particular you should not pass @c wxNullFont to this method. + + @see wxFont + */ + void SetFont(const wxFont& font); + + /** + Does the same as wxDC::SetLogicalFunction(), except that only wxCOPY is + avalaible. Trying to set one of the othe values will fail. + */ + void SetLogicalFunction(int function); + + /** + The mapping mode of the device context defines the unit of measurement + used to convert logical units to device units. Note that in X, text + drawing isn't handled consistently with the mapping mode; a font is + always specified in point size. However, setting the user scale scales + the text appropriately. In Windows, scalable TrueType fonts are always + used; in X, results depend on availability of fonts, but usually a + reasonable match is found. + + Note that the coordinate origin should ideally be selectable, but for + now is always at the top left of the screen/printer. + + Drawing to a Windows printer device context under UNIX uses the current + mapping mode, but mapping mode is currently ignored for PostScript + output. + + The mapping mode can be one of the following: + - wxMM_TWIPS - Each logical unit is 1/20 of a point, or 1/1440 of an + inch. + - wxMM_POINTS - Each logical unit is a point, or 1/72 of an inch. + - wxMM_METRIC - Each logical unit is 1 mm. + - wxMM_LOMETRIC - Each logical unit is 1/10 of a mm. + - wxMM_TEXT - Each logical unit is 1 pixel. + */ + void SetMapMode(int mode); + + /** + Not implemented. + */ + void SetPalette(const wxPalette& palette); + + /** + Sets the current pen for the DC. If the argument is wxNullPen, the + current pen is selected out of the device context, and the original pen + restored. + + @see wxMemoryDC (for the interpretation of colours when drawing into a + monochrome bitmap) + */ + void SetPen(const wxPen& pen); + + /** + Sets the current text background colour for the DC. + */ + void SetTextBackground(const wxColour& colour); + + /** + Sets the current text foreground colour for the DC. + + @see wxMemoryDC (for the interpretation of colours when drawing into a + monochrome bitmap) + */ + void SetTextForeground(const wxColour& colour); + + /** + Sets the user scaling factor, useful for applications which require + "zooming". + */ + void SetUserScale(double xScale, double yScale); + + /** + Does nothing. + */ + bool StartDoc(const wxString& message); +}; + diff --git a/interface/wx/dde.h b/interface/wx/dde.h new file mode 100644 index 0000000000..66b979df74 --- /dev/null +++ b/interface/wx/dde.h @@ -0,0 +1,352 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: dde.h +// Purpose: interface of wxDDEConnection +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxDDEConnection + @wxheader{dde.h} + + A wxDDEConnection object represents the connection between a client and a + server. It can be created by making a connection using a wxDDEClient + object, or by the acceptance of a connection by a wxDDEServer object. The + bulk of a DDE (Dynamic Data Exchange) conversation is controlled by calling + members in a wxDDEConnection object or by overriding its members. + + An application should normally derive a new connection class from + wxDDEConnection, in order to override the communication event handlers to + do something interesting. + + This DDE-based implementation is available on Windows only, but a + platform-independent, socket-based version of this API is available using + wxTCPConnection. + + @library{wxbase} + @category{ipc} + + @see wxConnectionBase, wxDDEClient, wxDDEServer, @ref overview_ipc +*/ +class wxDDEConnection : public wxConnectionBase +{ +public: + /** + Constructs a connection object. If no user-defined connection object is + to be derived from wxDDEConnection, then the constructor should not be + called directly, since the default connection object will be provided + on requesting (or accepting) a connection. However, if the user defines + his or her own derived connection object, the + wxDDEServer::OnAcceptConnection() and/or + wxDDEClient::OnMakeConnection() members should be replaced by functions + which construct the new connection object. + + A default buffer will be associated with this connection. + */ + wxDDEConnection(); + /** + Constructs a connection object. If no user-defined connection object is + to be derived from wxDDEConnection, then the constructor should not be + called directly, since the default connection object will be provided + on requesting (or accepting) a connection. However, if the user defines + his or her own derived connection object, the + wxDDEServer::OnAcceptConnection() and/or + wxDDEClient::OnMakeConnection() members should be replaced by functions + which construct the new connection object. + + @param buffer + Buffer for this connection object to use in transactions. + @param size + Size of the buffer given. + */ + wxDDEConnection(void* buffer, size_t size); + + //@{ + /** + Called by the server application to advise the client of a change in + the data associated with the given item. Causes the client connection's + OnAdvise() member to be called. + + @return @true if successful. + */ + bool Advise(const wxString& item, const void* data, size_t size, + wxIPCFormat format = wxIPC_PRIVATE); + bool Advise(const wxString& item, const char* data); + bool Advise(const wxString& item, const wchar_t* data); + bool Advise(const wxString& item, const wxString data); + //@} + + /** + Called by the client or server application to disconnect from the other + program; it causes the OnDisconnect() message to be sent to the + corresponding connection object in the other program. The default + behaviour of OnDisconnect() is to delete the connection, but the + calling application must explicitly delete its side of the connection + having called Disconnect(). + + @return @true if successful. + */ + bool Disconnect(); + + //@{ + /** + Called by the client application to execute a command on the server. + Can also be used to transfer arbitrary data to the server (similar to + Poke() in that respect). Causes the server connection's OnExecute() + member to be called. + + @return @true if successful. + */ + bool Execute(const void* data, size_t size, + wxIPCFormat format = wxIPC_PRIVATE); + bool Execute(const char* data); + bool Execute(const wchar_t* data); + bool Execute(const wxString data); + //@} + + /** + Message sent to the client application when the server notifies it of a + change in the data associated with the given item. + */ + virtual bool OnAdvise(const wxString& topic, const wxString& item, + const void* data, size_t size, wxIPCFormat format); + + /** + Message sent to the client or server application when the other + application notifies it to delete the connection. Default behaviour is + to delete the connection object. + */ + virtual bool OnDisconnect(); + + /** + Message sent to the server application when the client notifies it to + execute the given data. Note that there is no item associated with + this message. + */ + virtual bool OnExecute(const wxString& topic, const void* data, + size_t size, wxIPCFormat format); + + /** + Message sent to the server application when the client notifies it to + accept the given data. + */ + virtual bool OnPoke(const wxString& topic, const wxString& item, + const void* data, size_t size, wxIPCFormat format); + + /** + Message sent to the server application when the client calls Request(). + The server should respond by returning a character string from + OnRequest(), or @NULL to indicate no data. + */ + virtual const void* OnRequest(const wxString& topic, + const wxString& item, size_t* size, + wxIPCFormat format); + + /** + Message sent to the server application by the client, when the client + wishes to start an "advise loop" for the given topic and item. The + server can refuse to participate by returning @false. + */ + virtual bool OnStartAdvise(const wxString& topic, const wxString& item); + + /** + Message sent to the server application by the client, when the client + wishes to stop an "advise loop" for the given topic and item. The + server can refuse to stop the advise loop by returning @false, although + this doesn't have much meaning in practice. + */ + virtual bool OnStopAdvise(const wxString& topic, const wxString& item); + + //@{ + /** + Called by the client application to poke data into the server. Can be + used to transfer arbitrary data to the server. Causes the server + connection's OnPoke() member to be called. + + @return @true if successful. + */ + bool Poke(const wxString& item, const void* data, size_t size, + wxIPCFormat format = wxIPC_PRIVATE); + bool Poke(const wxString& item, const char* data); + bool Poke(const wxString& item, const wchar_t* data); + bool Poke(const wxString& item, const wxString data); + //@} + + /** + Called by the client application to request data from the server. + Causes the server connection's OnRequest() member to be called. + + @return A character string (actually a pointer to the connection's + buffer) if successful, @NULL otherwise. + */ + const void* Request(const wxString& item, size_t* size, + wxIPCFormat format = wxIPC_TEXT); + + /** + Called by the client application to ask if an advise loop can be + started with the server. Causes the server connection's OnStartAdvise() + member to be called. + + @return @true if the server okays it, @false otherwise. + */ + bool StartAdvise(const wxString& item); + + /** + Called by the client application to ask if an advise loop can be + stopped. Causes the server connection's OnStopAdvise() member to be + called. + + @return @true if the server okays it, @false otherwise. + */ + bool StopAdvise(const wxString& item); +}; + + + +/** + @class wxDDEClient + @wxheader{dde.h} + + A wxDDEClient object represents the client part of a client-server DDE + (Dynamic Data Exchange) conversation. + + To create a client which can communicate with a suitable server, you need + to derive a class from wxDDEConnection and another from wxDDEClient. The + custom wxDDEConnection class will intercept communications in a + "conversation" with a server, and the custom wxDDEServer is required so + that a user-overridden OnMakeConnection() member can return a + wxDDEConnection of the required class, when a connection is made. + + This DDE-based implementation is available on Windows only, but a + platform-independent, socket-based version of this API is available using + wxTCPClient. + + @library{wxbase} + @category{ipc} + + @see wxDDEServer, wxDDEConnection, @ref overview_ipc +*/ +class wxDDEClient : public wxObject +{ +public: + /** + Constructs a client object. + */ + wxDDEClient(); + + /** + Tries to make a connection with a server specified by the host (machine + name under UNIX, ignored under Windows), service name (must contain an + integer port number under UNIX), and topic string. If the server allows + a connection, a wxDDEConnection object will be returned. + + The type of wxDDEConnection returned can be altered by overriding the + OnMakeConnection() member to return your own derived connection object. + */ + wxConnectionBase* MakeConnection(const wxString& host, + const wxString& service, + const wxString& topic); + + /** + The type of wxDDEConnection returned from a MakeConnection() call can + be altered by deriving the OnMakeConnection() member to return your own + derived connection object. By default, a wxDDEConnection object is + returned. + + The advantage of deriving your own connection class is that it will + enable you to intercept messages initiated by the server, such as + wxDDEConnection::OnAdvise(). You may also want to store + application-specific data in instances of the new class. + */ + wxConnectionBase* OnMakeConnection(); + + /** + Returns @true if this is a valid host name, @false otherwise. This + always returns @true under MS Windows. + */ + bool ValidHost(const wxString& host); +}; + + + +/** + @class wxDDEServer + @wxheader{dde.h} + + A wxDDEServer object represents the server part of a client-server DDE + (Dynamic Data Exchange) conversation. + + This DDE-based implementation is available on Windows only, but a + platform-independent, socket-based version of this API is available using + wxTCPServer. + + @library{wxbase} + @category{ipc} + + @see wxDDEClient, wxDDEConnection, @ref overview_ipc +*/ +class wxDDEServer +{ +public: + /** + Constructs a server object. + */ + wxDDEServer(); + + /** + Registers the server using the given service name. Under UNIX, the + string must contain an integer id which is used as an Internet port + number. @false is returned if the call failed (for example, if the port + number is already in use). + */ + bool Create(const wxString& service); + + /** + When a client calls wxDDEClient::MakeConnection(), the server receives + the message and this member is called. The application should derive a + member to intercept this message and return a connection object of + either the standard wxDDEConnection type, or of a user-derived type. + + If the @a topic is "STDIO", the application may wish to refuse the + connection. Under UNIX, when a server is created the + OnAcceptConnection() message is always sent for standard input and + output, but in the context of DDE messages it doesn't make a lot of + sense. + */ + virtual wxConnectionBase* OnAcceptConnection(const wxString& topic); +}; + + + +// ============================================================================ +// Global functions/macros +// ============================================================================ + +/** @ingroup group_funcmacro_misc */ +//@{ + +/** + Called when wxWidgets exits, to clean up the DDE system. This no longer + needs to be called by the application. + + @see wxDDEInitialize() + + @header{wx/dde.h} +*/ +void wxDDECleanUp(); + +/** + Initializes the DDE system. May be called multiple times without harm. + + This no longer needs to be called by the application: it will be called by + wxWidgets if necessary. + + @see wxDDEServer, wxDDEClient, wxDDEConnection, wxDDECleanUp() + + @header{wx/dde.h} +*/ +void wxDDEInitialize(); + +//@} + diff --git a/interface/wx/debug.h b/interface/wx/debug.h new file mode 100644 index 0000000000..6338b91479 --- /dev/null +++ b/interface/wx/debug.h @@ -0,0 +1,220 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: debug.h +// Purpose: interface of global functions +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** @ingroup group_funcmacro_debug */ +//@{ + +/** + Assert macro. An error message will be generated if the condition is @false in + debug mode, but nothing will be done in the release build. + Please note that the condition in wxASSERT() should have no side effects + because it will not be executed in release mode at all. + + @see wxASSERT_MSG(), wxCOMPILE_TIME_ASSERT() + + @header{wx/debug.h} +*/ +#define wxASSERT( condition ) + +/** + This macro results in a + @ref overview_wxcompiletimeassert "compile time assertion failure" if the + size of the given @c type is less than @c size bits. + + You may use it like this, for example: + + @code + // we rely on the int being able to hold values up to 2^32 + wxASSERT_MIN_BITSIZE(int, 32); + + // can't work with the platforms using UTF-8 for wchar_t + wxASSERT_MIN_BITSIZE(wchar_t, 16); + @endcode + + @header{wx/debug.h} +*/ +#define wxASSERT_MIN_BITSIZE( type, size ) + +/** + Assert macro with message. An error message will be generated if the + condition is @false. + + @see wxASSERT(), wxCOMPILE_TIME_ASSERT() + + @header{wx/debug.h} +*/ +#define wxASSERT_MSG( condition, message ) + +/** + Checks that the condition is @true, returns with the given return value if + not (stops execution in debug mode). This check is done even in release + mode. + + @header{wx/debug.h} +*/ +#define wxCHECK( condition, retValue ) + +/** + Checks that the condition is @true, returns with the given return value if + not (stops execution in debug mode). This check is done even in release + mode. + + This macro may be only used in non-void functions, see also wxCHECK_RET(). + + @header{wx/debug.h} +*/ +#define wxCHECK_MSG( condition, retValue, message ) + +/** + Checks that the condition is @true, and returns if not (stops execution + with the given error message in debug mode). This check is done even in + release mode. + + This macro should be used in void functions instead of wxCHECK_MSG(). + + @header{wx/debug.h} +*/ +#define wxCHECK_RET( condition, message ) + +/** + Checks that the condition is @true, and if not, it will wxFAIL() and + execute the given @c operation if it is not. This is a generalisation of + wxCHECK() and may be used when something else than just returning from the + function must be done when the @c condition is @false. This check is done + even in release mode. + + @header{wx/debug.h} +*/ +#define wxCHECK2(condition, operation) + +/** + This is the same as wxCHECK2(), but wxFAIL_MSG() with the specified + @c message is called instead of wxFAIL() if the @c condition is @false. + + @header{wx/debug.h} +*/ +#define wxCHECK2_MSG( condition, operation, message ) + +/** + Using wxCOMPILE_TIME_ASSERT() results in a compilation error if the + specified @c condition is @false. The compiler error message should include + the @c message identifier - please note that it must be a valid C++ + identifier and not a string unlike in the other cases. + + This macro is mostly useful for testing the expressions involving the + @c sizeof operator as they can't be tested by the preprocessor but it is + sometimes desirable to test them at the compile time. + + Note that this macro internally declares a struct whose name it tries to + make unique by using the @c __LINE__ in it but it may still not work if you + use it on the same line in two different source files. In this case you may + either change the line in which either of them appears on or use the + wxCOMPILE_TIME_ASSERT2() macro. + + Also note that Microsoft Visual C++ has a bug which results in compiler + errors if you use this macro with 'Program Database For Edit And Continue' + (@c /ZI) option, so you shouldn't use it ('Program Database' (@c /Zi) is ok + though) for the code making use of this macro. + + @see wxASSERT_MSG(), wxASSERT_MIN_BITSIZE() + + @header{wx/debug.h} +*/ +#define wxCOMPILE_TIME_ASSERT( condition, message ) + +/** + This macro is identical to wxCOMPILE_TIME_ASSERT() except that it allows + you to specify a unique @c name for the struct internally defined by this + macro to avoid getting the compilation errors described for + wxCOMPILE_TIME_ASSERT(). + + @header{wx/debug.h} +*/ +#define wxCOMPILE_TIME_ASSERT2(condition, message, name) + +/** + Will always generate an assert error if this code is reached (in debug + mode). + + @see wxFAIL_MSG() + + @header{wx/debug.h} +*/ +#define wxFAIL() + +/** + Will always generate an assert error with specified message if this code is + reached (in debug mode). + + This macro is useful for marking unreachable" code areas, for example it + may be used in the "default:" branch of a switch statement if all possible + cases are processed above. + + @see wxFAIL() + + @header{wx/debug.h} +*/ +#define wxFAIL_MSG( message ) + +/** + Returns @true if the program is running under debugger, @false otherwise. + + Please note that this function is currently only implemented for Win32 and + Mac builds using CodeWarrior and always returns @false elsewhere. + + @header{wx/debug.h} +*/ +bool wxIsDebuggerRunning(); + +/** + This function is called whenever one of debugging macros fails (i.e. + condition is @false in an assertion). It is only defined in the debug mode, + in release builds the wxCHECK() failures don't result in anything. + + To override the default behaviour in the debug builds which is to show the + user a dialog asking whether he wants to abort the program, continue or + continue ignoring any subsequent assert failures, you may override + wxApp::OnAssertFailure() which is called by this function if the global + application object exists. + + @header{wx/debug.h} +*/ +void wxOnAssert( const char* fileName, + int lineNumber, + const char* function, + const char* condition, + const char* message = NULL ); + +/** + In debug mode (when @c __WXDEBUG__ is defined) this function generates a + debugger exception meaning that the control is passed to the debugger if + one is attached to the process. Otherwise the program just terminates + abnormally. In release mode this function does nothing. + + @header{wx/debug.h} +*/ +void wxTrap(); + +//@} + + + +/** @ingroup group_funcmacro_misc */ +//@{ + +/** + This macro expands to the name of the current function if the compiler + supports any of @c __FUNCTION__, @c __func__ or equivalent variables or + macros or to @NULL if none of them is available. + + @header{wx/debug.h} +*/ +#define __WXFUNCTION__ + +//@} + diff --git a/interface/wx/debugrpt.h b/interface/wx/debugrpt.h new file mode 100644 index 0000000000..bb40cb1997 --- /dev/null +++ b/interface/wx/debugrpt.h @@ -0,0 +1,351 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: debugrpt.h +// Purpose: interface of wxDebugReport* +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxDebugReportPreview + @wxheader{debugrpt.h} + + This class presents the debug report to the user and allows him to veto + report entirely or remove some parts of it. Although not mandatory, using + this class is strongly recommended as data included in the debug report + might contain sensitive private information and the user should be notified + about it as well as having a possibility to examine the data which had been + gathered to check whether this is effectively the case and discard the + debug report if it is. + + wxDebugReportPreview is an abstract base class, currently the only concrete + class deriving from it is wxDebugReportPreviewStd. + + @library{wxqa} + @category{debugging} +*/ +class wxDebugReportPreview +{ +public: + /** + Default constructor. + */ + wxDebugReportPreview(); + + /** + Destructor is trivial as well but should be virtual for a base class. + */ + virtual ~wxDebugReportPreview(); + + /** + Present the report to the user and allow him to modify it by removing + some or all of the files and, potentially, adding some notes. + + @return @true if the report should be processed or @false if the user + chose to cancel report generation or removed all files from + it. + */ + virtual bool Show(wxDebugReport& dbgrpt) const; +}; + + + +/** + @class wxDebugReportCompress + @wxheader{debugrpt.h} + + wxDebugReportCompress is a wxDebugReport which compresses all the files in + this debug report into a single ZIP file in its wxDebugReport::Process() + function. + + @library{wxqa} + @category{debugging} +*/ +class wxDebugReportCompress : public wxDebugReport +{ +public: + /** + Default constructor does nothing special. + */ + wxDebugReportCompress(); + + /** + Returns the full path of the compressed file (empty if creation + failed). + */ + const wxString GetCompressedFileName() const; +}; + + + +/** + @class wxDebugReport + @wxheader{debugrpt.h} + + wxDebugReport is used to generate a debug report, containing information + about the program current state. It is usually used from + wxApp::OnFatalException() as shown in the @ref page_samples_debugrpt. + + A wxDebugReport object contains one or more files. A few of them can be + created by the class itself but more can be created from the outside and + then added to the report. Also note that several virtual functions may be + overridden to further customize the class behaviour. + + Once a report is fully assembled, it can simply be left in the temporary + directory so that the user can email it to the developers (in which case + you should still use wxDebugReportCompress to compress it in a single file) + or uploaded to a Web server using wxDebugReportUpload (setting up the Web + server to accept uploads is your responsibility, of course). Other + handlers, for example for automatically emailing the report, can be defined + as well but are not currently included in wxWidgets. + + A typical usage example: + + @code + wxDebugReport report; + wxDebugReportPreviewStd preview; + + report.AddCurrentContext(); // could also use AddAll() + report.AddCurrentDump(); // to do both at once + + if ( preview.Show(report) ) + report.Process(); + @endcode + + @library{wxqa} + @category{debugging} +*/ +class wxDebugReport +{ +public: + /** + This enum is used for functions that report either the current state or + the state during the last (fatal) exception. + */ + enum Context { + Context_Current, + Context_Exception + }; + + /** + The constructor creates a temporary directory where the files that will + be included in the report are created. Use IsOk() to check for errors. + */ + wxDebugReport(); + + /** + The destructor normally destroys the temporary directory created in the + constructor with all the files it contains. Call Reset() to prevent + this from happening. + */ + ~wxDebugReport(); + + /** + Adds all available information to the report. Currently this includes a + text (XML) file describing the process context and, under Win32, a + minidump file. + */ + void AddAll(Context context = Context_Exception); + + /** + Add an XML file containing the current or exception context and the + stack trace. + */ + bool AddContext(Context ctx); + + /** + The same as calling AddContext(Context_Current). + */ + bool AddCurrentContext(); + + /** + The same as calling AddDump(Context_Current). + */ + bool AddCurrentDump(); + + /** + Adds the minidump file to the debug report. + + Minidumps are only available under recent Win32 versions + (@c dbghlp32.dll can be installed under older systems to make minidumps + available). + */ + bool AddDump(Context ctx); + + /** + The same as calling AddContext(Context_Exception). + */ + bool AddExceptionContext(); + + /** + The same as calling AddDump(Context_Exception). + */ + bool AddExceptionDump(); + + /** + Add another file to the report. If @a filename is an absolute path, it + is copied to a file in the debug report directory with the same name. + Otherwise the file should already exist in this directory + @a description only exists to be displayed to the user in the report + summary shown by wxDebugReportPreview. + + @see GetDirectory(), AddText() + */ + void AddFile(const wxString& filename, const wxString& description); + + /** + This is a convenient wrapper around AddFile(). It creates the file with + the given @a name and writes @a text to it, then adds the file to the + report. The @a filename shouldn't contain the path. + + @return @true if file could be added successfully, @false if an IO + error occurred. + */ + bool AddText(const wxString& filename, const wxString& text, + const wxString& description); + + /** + This function may be overridden to add arbitrary custom context to the + XML context file created by AddContext(). By default, it does nothing. + */ + void DoAddCustomContext(wxXmlNode* nodeRoot); + + /** + This function may be overridden to modify the contents of the exception + tag in the XML context file. + */ + bool DoAddExceptionInfo(wxXmlNode* nodeContext); + + /** + This function may be overridden to modify the contents of the modules + tag in the XML context file. + */ + bool DoAddLoadedModules(wxXmlNode* nodeModules); + + /** + This function may be overridden to modify the contents of the system + tag in the XML context file. + */ + bool DoAddSystemInfo(wxXmlNode* nodeSystemInfo); + + /** + This method should be used to construct the full name of the files + which you wish to add to the report using AddFile(). + + @return The name of the temporary directory used for the files in this + report. + */ + const wxString GetDirectory() const; + + /** + Retrieves the name (relative to GetDirectory()) and the description of + the file with the given index. If @a n is greater than or equal to the + number of filse, @false is returned. + */ + bool GetFile(size_t n, wxString* name, wxString* desc) const; + + /** + Gets the current number files in this report. + */ + size_t GetFilesCount() const; + + /** + Gets the name used as a base name for various files, by default + wxApp::GetAppName() is used. + */ + wxString GetReportName() const; + + /** + Returns @true if the object was successfully initialized. If this + method returns @false the report can't be used. + */ + bool IsOk() const; + + /** + Processes this report: the base class simply notifies the user that the + report has been generated. This is usually not enough -- instead you + should override this method to do something more useful to you. + */ + bool Process(); + + /** + Removes the file from report: this is used by wxDebugReportPreview to + allow the user to remove files potentially containing private + information from the report. + */ + void RemoveFile(const wxString& name); + + /** + Resets the directory name we use. The object can't be used any more + after this as it becomes uninitialized and invalid. + */ + void Reset(); +}; + + + +/** + @class wxDebugReportPreviewStd + @wxheader{debugrpt.h} + + wxDebugReportPreviewStd is a standard debug report preview window. It + displays a dialog allowing the user to examine the contents of a debug + report, remove files from and add notes to it. + + @library{wxqa} + @category{debugging} +*/ +class wxDebugReportPreviewStd : public wxDebugReportPreview +{ +public: + /** + Trivial default constructor. + */ + wxDebugReportPreviewStd(); + + /** + Shows the dialog. + + @see wxDebugReportPreview::Show() + */ + bool Show(wxDebugReport& dbgrpt) const; +}; + + + +/** + @class wxDebugReportUpload + @wxheader{debugrpt.h} + + This class is used to upload a compressed file using HTTP POST request. As + this class derives from wxDebugReportCompress, before upload the report is + compressed in a single ZIP file. + + @library{wxqa} + @category{debugging} +*/ +class wxDebugReportUpload : public wxDebugReportCompress +{ +public: + /** + This class will upload the compressed file created by its base class to + an HTML multipart/form-data form at the specified address. The @a url + is the upload page address, @a input is the name of the @c "type=file" + control on the form used for the file name and @a action is the value + of the form action field. The report is uploaded using the @e curl + program which should be available, the @e curl parameter may be used to + specify the full path to it. + */ + wxDebugReportUpload(const wxString& url, const wxString& input, + const wxString& action, + const wxString& curl = "curl"); + + /** + This function may be overridden in a derived class to show the output + from curl: this may be an HTML page or anything else that the server + returned. Value returned by this function becomes the return value of + wxDebugReport::Process(). + */ + bool OnServerReply(const wxArrayString& reply); +}; + diff --git a/interface/wx/defs.h b/interface/wx/defs.h new file mode 100644 index 0000000000..61b05d3599 --- /dev/null +++ b/interface/wx/defs.h @@ -0,0 +1,362 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: defs.h +// Purpose: interface of global functions +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + Item kinds for use with wxMenu, wxMenuItem, and wxToolBar. + + @see wxMenu::Append(), wxMenuItem::wxMenuItem(), wxToolBar::AddTool() +*/ +enum wxItemKind +{ + wxITEM_SEPARATOR = -1, + + /** + Normal tool button / menu item. + + @see wxToolBar::AddTool(), wxMenu::AppendItem(). + */ + wxITEM_NORMAL, + + /** + Check (or toggle) tool button / menu item. + + @see wxToolBar::AddCheckTool(), wxMenu::AppendCheckItem(). + */ + wxITEM_CHECK, + + /** + Radio tool button / menu item. + + @see wxToolBar::AddRadioTool(), wxMenu::AppendRadioItem(). + */ + wxITEM_RADIO, + + /** + Normal tool button with a dropdown arrow next to it. Clicking the + dropdown arrow sends a @c wxEVT_COMMAND_TOOL_DROPDOWN_CLICKED event and may + also display the menu previously associated with the item with + wxToolBar::SetDropdownMenu(). Currently this type of tools is supported + under MSW and GTK. + */ + wxITEM_DROPDOWN, + + wxITEM_MAX +}; + + +/** + Paper size types for use with the printing framework. + + @see overview_printing, wxPrintData::SetPaperId() +*/ +enum wxPaperSize +{ + wxPAPER_NONE, ///< Use specific dimensions + wxPAPER_LETTER, ///< Letter, 8 1/2 by 11 inches + wxPAPER_LEGAL, ///< Legal, 8 1/2 by 14 inches + wxPAPER_A4, ///< A4 Sheet, 210 by 297 millimeters + wxPAPER_CSHEET, ///< C Sheet, 17 by 22 inches + wxPAPER_DSHEET, ///< D Sheet, 22 by 34 inches + wxPAPER_ESHEET, ///< E Sheet, 34 by 44 inches + wxPAPER_LETTERSMALL, ///< Letter Small, 8 1/2 by 11 inches + wxPAPER_TABLOID, ///< Tabloid, 11 by 17 inches + wxPAPER_LEDGER, ///< Ledger, 17 by 11 inches + wxPAPER_STATEMENT, ///< Statement, 5 1/2 by 8 1/2 inches + wxPAPER_EXECUTIVE, ///< Executive, 7 1/4 by 10 1/2 inches + wxPAPER_A3, ///< A3 sheet, 297 by 420 millimeters + wxPAPER_A4SMALL, ///< A4 small sheet, 210 by 297 millimeters + wxPAPER_A5, ///< A5 sheet, 148 by 210 millimeters + wxPAPER_B4, ///< B4 sheet, 250 by 354 millimeters + wxPAPER_B5, ///< B5 sheet, 182-by-257-millimeter paper + wxPAPER_FOLIO, ///< Folio, 8-1/2-by-13-inch paper + wxPAPER_QUARTO, ///< Quarto, 215-by-275-millimeter paper + wxPAPER_10X14, ///< 10-by-14-inch sheet + wxPAPER_11X17, ///< 11-by-17-inch sheet + wxPAPER_NOTE, ///< Note, 8 1/2 by 11 inches + wxPAPER_ENV_9, ///< #9 Envelope, 3 7/8 by 8 7/8 inches + wxPAPER_ENV_10, ///< #10 Envelope, 4 1/8 by 9 1/2 inches + wxPAPER_ENV_11, ///< #11 Envelope, 4 1/2 by 10 3/8 inches + wxPAPER_ENV_12, ///< #12 Envelope, 4 3/4 by 11 inches + wxPAPER_ENV_14, ///< #14 Envelope, 5 by 11 1/2 inches + wxPAPER_ENV_DL, ///< DL Envelope, 110 by 220 millimeters + wxPAPER_ENV_C5, ///< C5 Envelope, 162 by 229 millimeters + wxPAPER_ENV_C3, ///< C3 Envelope, 324 by 458 millimeters + wxPAPER_ENV_C4, ///< C4 Envelope, 229 by 324 millimeters + wxPAPER_ENV_C6, ///< C6 Envelope, 114 by 162 millimeters + wxPAPER_ENV_C65, ///< C65 Envelope, 114 by 229 millimeters + wxPAPER_ENV_B4, ///< B4 Envelope, 250 by 353 millimeters + wxPAPER_ENV_B5, ///< B5 Envelope, 176 by 250 millimeters + wxPAPER_ENV_B6, ///< B6 Envelope, 176 by 125 millimeters + wxPAPER_ENV_ITALY, ///< Italy Envelope, 110 by 230 millimeters + wxPAPER_ENV_MONARCH, ///< Monarch Envelope, 3 7/8 by 7 1/2 inches + wxPAPER_ENV_PERSONAL, ///< 6 3/4 Envelope, 3 5/8 by 6 1/2 inches + wxPAPER_FANFOLD_US, ///< US Std Fanfold, 14 7/8 by 11 inches + wxPAPER_FANFOLD_STD_GERMAN, ///< German Std Fanfold, 8 1/2 by 12 inches + wxPAPER_FANFOLD_LGL_GERMAN, ///< German Legal Fanfold, 8 1/2 by 13 inches + + // Windows 95 Only + + wxPAPER_ISO_B4, ///< B4 (ISO) 250 x 353 mm + wxPAPER_JAPANESE_POSTCARD, ///< Japanese Postcard 100 x 148 mm + wxPAPER_9X11, ///< 9 x 11 in + wxPAPER_10X11, ///< 10 x 11 in + wxPAPER_15X11, ///< 15 x 11 in + wxPAPER_ENV_INVITE, ///< Envelope Invite 220 x 220 mm + wxPAPER_LETTER_EXTRA, ///< Letter Extra 9 \275 x 12 in + wxPAPER_LEGAL_EXTRA, ///< Legal Extra 9 \275 x 15 in + wxPAPER_TABLOID_EXTRA, ///< Tabloid Extra 11.69 x 18 in + wxPAPER_A4_EXTRA, ///< A4 Extra 9.27 x 12.69 in + wxPAPER_LETTER_TRANSVERSE, ///< Letter Transverse 8 \275 x 11 in + wxPAPER_A4_TRANSVERSE, ///< A4 Transverse 210 x 297 mm + wxPAPER_LETTER_EXTRA_TRANSVERSE, ///< Letter Extra Transverse 9\275 x 12 in + wxPAPER_A_PLUS, ///< SuperA/SuperA/A4 227 x 356 mm + wxPAPER_B_PLUS, ///< SuperB/SuperB/A3 305 x 487 mm + wxPAPER_LETTER_PLUS, ///< Letter Plus 8.5 x 12.69 in + wxPAPER_A4_PLUS, ///< A4 Plus 210 x 330 mm + wxPAPER_A5_TRANSVERSE, ///< A5 Transverse 148 x 210 mm + wxPAPER_B5_TRANSVERSE, ///< B5 (JIS) Transverse 182 x 257 mm + wxPAPER_A3_EXTRA, ///< A3 Extra 322 x 445 mm + wxPAPER_A5_EXTRA, ///< A5 Extra 174 x 235 mm + wxPAPER_B5_EXTRA, ///< B5 (ISO) Extra 201 x 276 mm + wxPAPER_A2, ///< A2 420 x 594 mm + wxPAPER_A3_TRANSVERSE, ///< A3 Transverse 297 x 420 mm + wxPAPER_A3_EXTRA_TRANSVERSE, ///< A3 Extra Transverse 322 x 445 mm + + wxPAPER_DBL_JAPANESE_POSTCARD, ///< Japanese Double Postcard 200 x 148 mm + wxPAPER_A6, ///< A6 105 x 148 mm + wxPAPER_JENV_KAKU2, ///< Japanese Envelope Kaku #2 + wxPAPER_JENV_KAKU3, ///< Japanese Envelope Kaku #3 + wxPAPER_JENV_CHOU3, ///< Japanese Envelope Chou #3 + wxPAPER_JENV_CHOU4, ///< Japanese Envelope Chou #4 + wxPAPER_LETTER_ROTATED, ///< Letter Rotated 11 x 8 1/2 in + wxPAPER_A3_ROTATED, ///< A3 Rotated 420 x 297 mm + wxPAPER_A4_ROTATED, ///< A4 Rotated 297 x 210 mm + wxPAPER_A5_ROTATED, ///< A5 Rotated 210 x 148 mm + wxPAPER_B4_JIS_ROTATED, ///< B4 (JIS) Rotated 364 x 257 mm + wxPAPER_B5_JIS_ROTATED, ///< B5 (JIS) Rotated 257 x 182 mm + wxPAPER_JAPANESE_POSTCARD_ROTATED, ///< Japanese Postcard Rotated 148 x 100 mm + wxPAPER_DBL_JAPANESE_POSTCARD_ROTATED, ///< Double Japanese Postcard Rotated 148 x 200 mm + wxPAPER_A6_ROTATED, ///< A6 Rotated 148 x 105 mm + wxPAPER_JENV_KAKU2_ROTATED, ///< Japanese Envelope Kaku #2 Rotated + wxPAPER_JENV_KAKU3_ROTATED, ///< Japanese Envelope Kaku #3 Rotated + wxPAPER_JENV_CHOU3_ROTATED, ///< Japanese Envelope Chou #3 Rotated + wxPAPER_JENV_CHOU4_ROTATED, ///< Japanese Envelope Chou #4 Rotated + wxPAPER_B6_JIS, ///< B6 (JIS) 128 x 182 mm + wxPAPER_B6_JIS_ROTATED, ///< B6 (JIS) Rotated 182 x 128 mm + wxPAPER_12X11, ///< 12 x 11 in + wxPAPER_JENV_YOU4, ///< Japanese Envelope You #4 + wxPAPER_JENV_YOU4_ROTATED, ///< Japanese Envelope You #4 Rotated + wxPAPER_P16K, ///< PRC 16K 146 x 215 mm + wxPAPER_P32K, ///< PRC 32K 97 x 151 mm + wxPAPER_P32KBIG, ///< PRC 32K(Big) 97 x 151 mm + wxPAPER_PENV_1, ///< PRC Envelope #1 102 x 165 mm + wxPAPER_PENV_2, ///< PRC Envelope #2 102 x 176 mm + wxPAPER_PENV_3, ///< PRC Envelope #3 125 x 176 mm + wxPAPER_PENV_4, ///< PRC Envelope #4 110 x 208 mm + wxPAPER_PENV_5, ///< PRC Envelope #5 110 x 220 mm + wxPAPER_PENV_6, ///< PRC Envelope #6 120 x 230 mm + wxPAPER_PENV_7, ///< PRC Envelope #7 160 x 230 mm + wxPAPER_PENV_8, ///< PRC Envelope #8 120 x 309 mm + wxPAPER_PENV_9, ///< PRC Envelope #9 229 x 324 mm + wxPAPER_PENV_10, ///< PRC Envelope #10 324 x 458 mm + wxPAPER_P16K_ROTATED, ///< PRC 16K Rotated + wxPAPER_P32K_ROTATED, ///< PRC 32K Rotated + wxPAPER_P32KBIG_ROTATED, ///< PRC 32K(Big) Rotated + wxPAPER_PENV_1_ROTATED, ///< PRC Envelope #1 Rotated 165 x 102 mm + wxPAPER_PENV_2_ROTATED, ///< PRC Envelope #2 Rotated 176 x 102 mm + wxPAPER_PENV_3_ROTATED, ///< PRC Envelope #3 Rotated 176 x 125 mm + wxPAPER_PENV_4_ROTATED, ///< PRC Envelope #4 Rotated 208 x 110 mm + wxPAPER_PENV_5_ROTATED, ///< PRC Envelope #5 Rotated 220 x 110 mm + wxPAPER_PENV_6_ROTATED, ///< PRC Envelope #6 Rotated 230 x 120 mm + wxPAPER_PENV_7_ROTATED, ///< PRC Envelope #7 Rotated 230 x 160 mm + wxPAPER_PENV_8_ROTATED, ///< PRC Envelope #8 Rotated 309 x 120 mm + wxPAPER_PENV_9_ROTATED, ///< PRC Envelope #9 Rotated 324 x 229 mm + wxPAPER_PENV_10_ROTATED ///< PRC Envelope #10 Rotated 458 x 324 m +}; + + +/** @ingroup group_funcmacro_byteorder */ +//@{ + +/** + This macro will swap the bytes of the @a value variable from little endian + to big endian or vice versa unconditionally, i.e. independently of the + current platform. + + @header{wx/defs.h} +*/ +#define wxINT32_SWAP_ALWAYS( wxInt32 value ) +#define wxUINT32_SWAP_ALWAYS( wxUint32 value ) +#define wxINT16_SWAP_ALWAYS( wxInt16 value ) +#define wxUINT16_SWAP_ALWAYS( wxUint16 value ) + +//@} + +/** @ingroup group_funcmacro_byteorder */ +//@{ + +/** + This macro will swap the bytes of the @a value variable from little endian + to big endian or vice versa if the program is compiled on a big-endian + architecture (such as Sun work stations). If the program has been compiled + on a little-endian architecture, the value will be unchanged. + + Use these macros to read data from and write data to a file that stores + data in little-endian (for example Intel i386) format. + + @header{wx/defs.h} +*/ +#define wxINT32_SWAP_ON_BE( wxInt32 value ) +#define wxUINT32_SWAP_ON_BE( wxUint32 value ) +#define wxINT16_SWAP_ON_BE( wxInt16 value ) +#define wxUINT16_SWAP_ON_BE( wxUint16 value ) + +//@} + +/** @ingroup group_funcmacro_byteorder */ +//@{ + +/** + This macro will swap the bytes of the @a value variable from little endian + to big endian or vice versa if the program is compiled on a little-endian + architecture (such as Intel PCs). If the program has been compiled on a + big-endian architecture, the value will be unchanged. + + Use these macros to read data from and write data to a file that stores + data in big-endian format. + + @header{wx/defs.h} +*/ +#define wxINT32_SWAP_ON_LE( wxInt32 value ) +#define wxUINT32_SWAP_ON_LE( wxUint32 value ) +#define wxINT16_SWAP_ON_LE( wxInt16 value ) +#define wxUINT16_SWAP_ON_LE( wxUint16 value ) + +//@} + + + +/** @ingroup group_funcmacro_misc */ +//@{ + +/** + This macro can be used around a function declaration to generate warnings + indicating that this function is deprecated (i.e. obsolete and planned to + be removed in the future) when it is used. Only Visual C++ 7 and higher and + g++ compilers currently support this functionality. + + Example of use: + + @code + // old function, use wxString version instead + wxDEPRECATED( void wxGetSomething(char *buf, size_t len) ); + + // ... + wxString wxGetSomething(); + @endcode + + @header{wx/defs.h} +*/ +#define wxDEPRECATED(function) + +/** + This is a special version of wxDEPRECATED() macro which only does something + when the deprecated function is used from the code outside wxWidgets itself + but doesn't generate warnings when it is used from wxWidgets. + + It is used with the virtual functions which are called by the library + itself -- even if such function is deprecated the library still has to call + it to ensure that the existing code overriding it continues to work, but + the use of this macro ensures that a deprecation warning will be generated + if this function is used from the user code or, in case of Visual C++, even + when it is simply overridden. + + @header{wx/defs.h} +*/ +#define wxDEPRECATED_BUT_USED_INTERNALLY(function) + +/** + This macro is similar to wxDEPRECATED() but can be used to not only declare + the function @a function as deprecated but to also provide its (inline) + implementation @a body. + + It can be used as following: + + @code + class wxFoo + { + public: + // OldMethod() is deprecated, use NewMethod() instead + void NewMethod(); + wxDEPRECATED_INLINE( void OldMethod(), NewMethod() ); + }; + @endcode + + @header{wx/defs.h} +*/ +#define wxDEPRECATED_INLINE(func, body) + +/** + @c wxEXPLICIT is a macro which expands to the C++ @c explicit keyword if + the compiler supports it or nothing otherwise. Thus, it can be used even in + the code which might have to be compiled with an old compiler without + support for this language feature but still take advantage of it when it is + available. + + @header{wx/defs.h} +*/ +#define wxEXPLICIT + +/** + GNU C++ compiler gives a warning for any class whose destructor is private + unless it has a friend. This warning may sometimes be useful but it doesn't + make sense for reference counted class which always delete themselves + (hence destructor should be private) but don't necessarily have any + friends, so this macro is provided to disable the warning in such case. The + @a name parameter should be the name of the class but is only used to + construct a unique friend class name internally. + + Example of using the macro: + + @code + class RefCounted + { + public: + RefCounted() { m_nRef = 1; } + void IncRef() { m_nRef++ ; } + void DecRef() { if ( !--m_nRef ) delete this; } + + private: + ~RefCounted() { } + + wxSUPPRESS_GCC_PRIVATE_DTOR(RefCounted) + }; + @endcode + + Notice that there should be no semicolon after this macro. + + @header{wx/defs.h} +*/ +#define wxSUPPRESS_GCC_PRIVATE_DTOR_WARNING(name) + +/** + This macro is the same as the standard C99 @c va_copy for the compilers + which support it or its replacement for those that don't. It must be used + to preserve the value of a @c va_list object if you need to use it after + passing it to another function because it can be modified by the latter. + + As with @c va_start, each call to @c wxVaCopy must have a matching + @c va_end. + + @header{wx/defs.h} +*/ +void wxVaCopy(va_list argptrDst, va_list argptrSrc); + +//@} + + diff --git a/interface/wx/dialog.h b/interface/wx/dialog.h new file mode 100644 index 0000000000..3052b2e0e5 --- /dev/null +++ b/interface/wx/dialog.h @@ -0,0 +1,613 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: dialog.h +// Purpose: interface of wxDialog +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + Modes used for wxDialog::SetLayoutAdaptationMode(). +*/ +enum wxDialogLayoutAdaptationMode +{ + wxDIALOG_ADAPTATION_MODE_DEFAULT = 0, ///< Use global adaptation enabled status. + wxDIALOG_ADAPTATION_MODE_ENABLED = 1, ///< Enable this dialog overriding global status. + wxDIALOG_ADAPTATION_MODE_DISABLED = 2 ///< Disable this dialog overriding global status. +}; + +/** + @class wxDialog + @wxheader{dialog.h} + + A dialog box is a window with a title bar and sometimes a system menu, + which can be moved around the screen. It can contain controls and other + windows and is often used to allow the user to make some choice or to + answer a question. + + Dialogs can be made scrollable, automatically, for computers with low + resolution screens: please see @ref overview_dialog_autoscrolling for + further details. + + Dialogs usually contains either a single button allowing to close the + dialog or two buttons, one accepting the changes and the other one + discarding them (such button, if present, is automatically activated if the + user presses the "Esc" key). By default, buttons with the standard wxID_OK + and wxID_CANCEL identifiers behave as expected. Starting with wxWidgets 2.7 + it is also possible to use a button with a different identifier instead, + see SetAffirmativeId() and SetEscapeId(). + + Also notice that the CreateButtonSizer() should be used to create the + buttons appropriate for the current platform and positioned correctly + (including their order which is platform-dependent). + + @section dialog_modal Modal and Modeless + + There are two kinds of dialog, modal and modeless. A modal dialog blocks + program flow and user input on other windows until it is dismissed, whereas + a modeless dialog behaves more like a frame in that program flow continues, + and input in other windows is still possible. To show a modal dialog you + should use the ShowModal() method while to show a dialog modelessly you + simply use Show(), just as with frames. + + Note that the modal dialog is one of the very few examples of + wxWindow-derived objects which may be created on the stack and not on the + heap. In other words, while most windows would be created like this: + + @code + void AskUser() + { + MyAskDialog *dlg = new MyAskDialog(...); + if ( dlg->ShowModal() == wxID_OK ) + // ... + //else: dialog was cancelled or some another button pressed + + dlg->Destroy(); + } + @endcode + + You can achieve the same result with dialogs by using simpler code: + + @code + void AskUser() + { + MyAskDialog dlg(...); + if ( dlg.ShowModal() == wxID_OK ) + // ... + + // no need to call Destroy() here + } + @endcode + + An application can define a wxCloseEvent handler for the dialog to respond + to system close events. + + @beginStyleTable + @style{wxCAPTION} + Puts a caption on the dialog box. + @style{wxDEFAULT_DIALOG_STYLE} + Equivalent to a combination of wxCAPTION, wxCLOSE_BOX and + wxSYSTEM_MENU (the last one is not used under Unix). + @style{wxRESIZE_BORDER} + Display a resizeable frame around the window. + @style{wxSYSTEM_MENU} + Display a system menu. + @style{wxCLOSE_BOX} + Displays a close box on the frame. + @style{wxMAXIMIZE_BOX} + Displays a maximize box on the dialog. + @style{wxMINIMIZE_BOX} + Displays a minimize box on the dialog. + @style{wxTHICK_FRAME} + Display a thick frame around the window. + @style{wxSTAY_ON_TOP} + The dialog stays on top of all other windows. + @style{wxNO_3D} + Under Windows, specifies that the child controls should not have 3D + borders unless specified in the control. + @style{wxDIALOG_NO_PARENT} + By default, a dialog created with a @NULL parent window will be + given the @ref wxApp::GetTopWindow() "application's top level window" + as parent. Use this style to prevent this from happening and create + an orphan dialog. This is not recommended for modal dialogs. + @style{wxDIALOG_EX_CONTEXTHELP} + Under Windows, puts a query button on the caption. When pressed, + Windows will go into a context-sensitive help mode and wxWidgets + will send a wxEVT_HELP event if the user clicked on an application + window. Note that this is an extended style and must be set by + calling SetExtraStyle() before Create is called (two-step + construction). + @style{wxDIALOG_EX_METAL} + On Mac OS X, frames with this style will be shown with a metallic + look. This is an extra style. + @endStyleTable + + Under Unix or Linux, MWM (the Motif Window Manager) or other window + managers recognizing the MHM hints should be running for any of these + styles to have an effect. + + @library{wxcore} + @category{cmndlg} + + @see @ref overview_dialog, wxFrame, @ref overview_validator +*/ +class wxDialog : public wxTopLevelWindow +{ +public: + /** + Default constructor. + */ + wxDialog(); + /** + Constructor. + + @param parent + Can be @NULL, a frame or another dialog box. + @param id + An identifier for the dialog. A value of -1 is taken to mean a + default. + @param title + The title of the dialog. + @param pos + The dialog position. The value wxDefaultPosition indicates a + default position, chosen by either the windowing system or + wxWidgets, depending on platform. + @param size + The dialog size. The value wxDefaultSize indicates a default size, + chosen by either the windowing system or wxWidgets, depending on + platform. + @param style + The window style. + @param name + Used to associate a name with the window, allowing the application + user to set Motif resource values for individual dialog boxes. + + @see Create() + */ + wxDialog(wxWindow* parent, wxWindowID id, const wxString& title, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxDEFAULT_DIALOG_STYLE, + const wxString& name = "dialogBox"); + + /** + Destructor. Deletes any child windows before deleting the physical + window. + */ + ~wxDialog(); + + /** + Adds an identifier to be regarded as a main button for the + non-scrolling area of a dialog. + + @see @ref overview_dialog_autoscrolling (for more on layout adaptation) + */ + void AddMainButtonId(wxWindowID id); + + /** + Returns @true if this dialog can and should perform layout adaptation + using DoLayoutAdaptation(), usually if the dialog is too large to fit + on the display. + + @see @ref overview_dialog_autoscrolling (for more on layout adaptation) + */ + bool CanDoLayoutAdapation(); + + /** + Centres the dialog box on the display. + + @param direction + May be wxHORIZONTAL, wxVERTICAL or wxBOTH. + */ + void Centre(int direction = wxBOTH); + + /** + Used for two-step dialog box construction. + + @see wxDialog() + */ + bool Create(wxWindow* parent, wxWindowID id, const wxString& title, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxDEFAULT_DIALOG_STYLE, + const wxString& name = "dialogBox"); + + /** + Creates a sizer with standard buttons. @a flags is a bit list of the + following flags: wxOK, wxCANCEL, wxYES, wxNO, wxAPPLY, wxCLOSE, wxHELP, + wxNO_DEFAULT. + + The sizer lays out the buttons in a manner appropriate to the platform. + + This function uses CreateStdDialogButtonSizer() internally for most + platforms but doesn't create the sizer at all for the platforms with + hardware buttons (such as smartphones) for which it sets up the + hardware buttons appropriately and returns @NULL, so don't forget to + test that the return value is valid before using it. + */ + wxSizer* CreateButtonSizer(long flags); + + /** + Creates a sizer with standard buttons using CreateButtonSizer() + separated from the rest of the dialog contents by a horizontal + wxStaticLine. + + @note Just like CreateButtonSizer(), this function may return @NULL if + no buttons were created. + */ + wxSizer* CreateSeparatedButtonSizer(long flags); + + /** + Creates a wxStdDialogButtonSizer with standard buttons. @a flags is a + bit list of the following flags: wxOK, wxCANCEL, wxYES, wxNO, wxAPPLY, + wxCLOSE, wxHELP, wxNO_DEFAULT. + + The sizer lays out the buttons in a manner appropriate to the platform. + */ + wxStdDialogButtonSizer* CreateStdDialogButtonSizer(long flags); + + /** + Performs layout adaptation, usually if the dialog is too large to fit + on the display. + + @see @ref overview_dialog_autoscrolling (for more on layout adaptation) + */ + bool DoLayoutAdapation(); + + /** + This function is called when the titlebar OK button is pressed + (PocketPC only). A command event for the identifier returned by + GetAffirmativeId() is sent by default. You can override this function. + If the function returns @false, wxWidgets will call Close() for the + dialog. + */ + virtual bool DoOK(); + + /** + A static function enabling or disabling layout adaptation for all + dialogs. + + @see @ref overview_dialog_autoscrolling (for more on layout adaptation) + */ + static void EnableLayoutAdaptation(bool enable); + + /** + Ends a modal dialog, passing a value to be returned from the + ShowModal() invocation. + + @param retCode + The value that should be returned by ShowModal. + + @see ShowModal(), GetReturnCode(), SetReturnCode() + */ + void EndModal(int retCode); + + /** + Gets the identifier of the button which works like standard OK button + in this dialog. + + @see SetAffirmativeId() + */ + int GetAffirmativeId() const; + + /** + Override this to return a window containing the main content of the + dialog. This is particularly useful when the dialog implements pages, + such as wxPropertySheetDialog, and allows the + @ref overview_dialog "layout adaptation code" to know that only the + pages need to be made scrollable. + */ + wxWindow* GetContentWindow() const; + + /** + Gets the identifier of the button to map presses of @c ESC button to. + + @see SetEscapeId() + */ + int GetEscapeId() const; + + /** + Returns @true if the dialog has been adapted, usually by making it + scrollable to work with a small display. + + @see @ref overview_dialog_autoscrolling (for more on layout adaptation) + */ + bool GetLayoutAdaptationDone() const; + + /** + Gets a value representing the aggressiveness of search for buttons and + sizers to be in the non-scrolling part of a layout-adapted dialog. Zero + switches off adaptation, and 3 allows search for standard buttons + anywhere in the dialog. + + @see @ref overview_dialog_autoscrolling (for more on layout adaptation) + */ + int GetLayoutAdaptationLevel(); + + /** + Gets the adaptation mode, overriding the global adaptation flag. + + @see @ref overview_dialog_autoscrolling (for more on layout adaptation) + */ + wxDialogLayoutAdaptationMode GetLayoutAdaptationMode() const; + + /** + A static function getting the current layout adapter object. + + @see @ref overview_dialog_autoscrolling (for more on layout adaptation) + */ + static wxDialogLayoutAdapter* GetLayoutAdapter(); + + /** + Returns an array of identifiers to be regarded as the main buttons for + the non-scrolling area of a dialog. + + @see @ref overview_dialog_autoscrolling (for more on layout adaptation) + */ + wxArrayInt GetMainButtonIds(); + + /** + Gets the return code for this window. + + @remarks A return code is normally associated with a modal dialog, + where ShowModal() returns a code to the application. + + @see SetReturnCode(), ShowModal(), EndModal() + */ + int GetReturnCode(); + + /** + On PocketPC, a dialog is automatically provided with an empty toolbar. + This function allows you to access the toolbar and add tools to it. + Removing tools and adding arbitrary controls are not currently + supported. + + This function is not available on any other platform. + */ + wxToolBar* GetToolBar() const; + + /** + Iconizes or restores the dialog. Windows only. + + @param iconize + If @true, iconizes the dialog box; if @false, shows and restores it. + + @remarks Note that in Windows, iconization has no effect since dialog + boxes cannot be iconized. However, applications may need to + explicitly restore dialog boxes under Motif which have + user-iconizable frames, and under Windows calling + Iconize(@false) will bring the window to the front, as does + Show(@true). + */ + void Iconize(bool iconize); + + /** + Returns @true if the dialog box is iconized. Windows only. + + @remarks Always returns @false under Windows since dialogs cannot be + iconized. + */ + bool IsIconized() const; + + /** + A static function returning @true if layout adaptation is enabled for + all dialogs. + + @see @ref overview_dialog_autoscrolling (for more on layout adaptation) + */ + static bool IsLayoutAdaptationEnabled(); + + /** + Returns @true if @a id is in the array of identifiers to be regarded as + the main buttons for the non-scrolling area of a dialog. + + @see @ref overview_dialog_autoscrolling (for more on layout adaptation) + */ + bool IsMainButton(wxWindowID& id) const; + + /** + Returns @true if the dialog box is modal, @false otherwise. + */ + bool IsModal() const; + + /** + The default handler for wxEVT_SYS_COLOUR_CHANGED. + + @param event + The colour change event. + + @remarks Changes the dialog's colour to conform to the current settings + (Windows only). Add an event table entry for your dialog 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 the notification + to child windows and controls. + + @see wxSysColourChangedEvent + */ + void OnSysColourChanged(wxSysColourChangedEvent& event); + + /** + Sets the identifier to be used as OK button. When the button with this + identifier is pressed, the dialog calls wxWindow::Validate() and + wxWindow::TransferDataFromWindow() and, if they both return @true, + closes the dialog with wxID_OK return code. + + Also, when the user presses a hardware OK button on the devices having + one or the special OK button in the PocketPC title bar, an event with + this id is generated. + + By default, the affirmative id is wxID_OK. + + @see GetAffirmativeId(), SetEscapeId() + */ + void SetAffirmativeId(int id); + + /** + Sets the identifier of the button which should work like the standard + "Cancel" button in this dialog. When the button with this id is + clicked, the dialog is closed. Also, when the user presses @c ESC key + in the dialog or closes the dialog using the close button in the title + bar, this is mapped to the click of the button with the specified id. + + By default, the escape id is the special value wxID_ANY meaning that + wxID_CANCEL button is used if it's present in the dialog and otherwise + the button with GetAffirmativeId() is used. Another special value for + @a id is wxID_NONE meaning that @c ESC presses should be ignored. If + any other value is given, it is interpreted as the id of the button to + map the escape key to. + */ + void SetEscapeId(int id); + + /** + Sets the icon for this dialog. + + @param icon + The icon to associate with this dialog. + + @see wxIcon + */ + void SetIcon(const wxIcon& icon); + + /** + Sets the icons for this dialog. + + @param icons + The icons to associate with this dialog. + + @see wxIconBundle + */ + void SetIcons(const wxIconBundle& icons); + + /** + Marks the dialog as having been adapted, usually by making it + scrollable to work with a small display. + + @see @ref overview_dialog_autoscrolling (for more on layout adaptation) + */ + void SetLayoutAdaptationDone(bool done); + + /** + Sets the aggressiveness of search for buttons and sizers to be in the + non-scrolling part of a layout-adapted dialog. Zero switches off + adaptation, and 3 allows search for standard buttons anywhere in the + dialog. + + @see @ref overview_dialog_autoscrolling (for more on layout adaptation) + */ + void SetLayoutAdaptationLevel(int level); + + /** + Sets the adaptation mode, overriding the global adaptation flag. + + @see wxDialogLayoutAdaptationMode, @ref overview_dialog_autoscrolling + (for more on layout adaptation) + */ + void SetLayoutAdaptationMode(wxDialogLayoutAdaptationMode mode); + + /** + A static function for setting the current layout adapter object, + returning the old adapter. If you call this, you should delete the old + adapter object. + + @see wxDialogLayoutAdapter, @ref overview_dialog_autoscrolling + */ + static wxDialogLayoutAdapter* SetLayoutAdapter(wxDialogLayoutAdapter* adapter); + + /** + @deprecated This function doesn't work for all ports, just use + ShowModal() to show a modal dialog instead. + + Allows the programmer to specify whether the dialog box is modal + (Show() blocks control until the dialog is hidden) or modeless (control + returns immediately). + + @param flag + If @true, the dialog will be modal, otherwise it will be modeless. + */ + void SetModal(bool flag); + + /** + Sets the return code for this window. + + A return code is normally associated with a modal dialog, where + ShowModal() returns a code to the application. The function EndModal() + calls SetReturnCode(). + + @param retCode + The integer return code, usually a control identifier. + + @see GetReturnCode(), ShowModal(), EndModal() + */ + void SetReturnCode(int retCode); + + /** + Hides or shows the dialog. The preferred way of dismissing a modal + dialog is to use EndModal(). + + @param show + If @true, the dialog box is shown and brought to the front, + otherwise the box is hidden. If @false and the dialog is modal, + control is returned to the calling program. + */ + bool Show(bool show); + + /** + Shows a modal dialog. + + Program flow does not return until the dialog has been dismissed with + EndModal(). + + Notice that it is possible to call ShowModal() for a dialog which had + been previously shown with Show(), this allows to make an existing + modeless dialog modal. However ShowModal() can't be called twice + without intervening EndModal() calls. + + @return The value set with SetReturnCode(). + + @see EndModal(), GetReturnCode(), SetReturnCode() + */ + int ShowModal(); +}; + + + +/** + @class wxDialogLayoutAdapter + @wxheader{dialog.h} + + This abstract class is the base for classes that help wxWidgets peform + run-time layout adaptation of dialogs. Principally, this is to cater for + small displays by making part of the dialog scroll, but the application + developer may find other uses for layout adaption. + + By default, there is one instance of wxStandardDialogLayoutAdapter which + can perform adaptation for most custom dialogs and dialogs with book + controls such as wxPropertySheetDialog. + + @library{wxcore} + @category{winlayout} + + @see @ref overview_dialog_autoscrolling +*/ +class wxDialogLayoutAdapter +{ +public: + /** + Default constructor. + */ + wxDialogLayoutAdapter(); + + /** + Override this to returns @true if adaptation can and should be done. + */ + bool CanDoLayoutAdaptation(wxDialog* dialog); + + /** + Override this to perform layout adaptation, such as making parts of the + dialog scroll and resizing the dialog to fit the display. Normally this + function will be called just before the dialog is shown. + */ + bool DoLayoutAdaptation(wxDialog* dialog); +}; + diff --git a/interface/wx/dialup.h b/interface/wx/dialup.h new file mode 100644 index 0000000000..849d21cbbd --- /dev/null +++ b/interface/wx/dialup.h @@ -0,0 +1,217 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: dialup.h +// Purpose: interface of wxDialUpManager +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxDialUpManager + @wxheader{dialup.h} + + This class encapsulates functions dealing with verifying the connection + status of the workstation (connected to the Internet via a direct + connection, connected through a modem or not connected at all) and to + establish this connection if possible/required (i.e. in the case of the + modem). + + The program may also wish to be notified about the change in the connection + status (for example, to perform some action when the user connects to the + network the next time or, on the contrary, to stop receiving data from the + net when the user hangs up the modem). For this, you need to use one of the + event macros described below. + + This class is different from other wxWidgets classes in that there is at + most one instance of this class in the program accessed via Create() and + you can't create the objects of this class directly. + + @beginEventTable{wxDialUpEvent} + @event{EVT_DIALUP_CONNECTED(func)} + A connection with the network was established. + @event{EVT_DIALUP_DISCONNECTED(func)} + The connection with the network was lost. + @endEventTable + + @library{wxcore} + @category{net} + + @see @ref page_samples_dialup, wxDialUpEvent +*/ +class wxDialUpManager +{ +public: + /** + Destructor. + */ + ~wxDialUpManager(); + + /** + Cancel dialing the number initiated with Dial() with async parameter + equal to @true. + + @note This won't result in a DISCONNECTED event being sent. + + @see IsDialing() + */ + bool CancelDialing(); + + /** + This function should create and return the object of the + platform-specific class derived from wxDialUpManager. You should delete + the pointer when you are done with it. + */ + wxDialUpManager* Create(); + + /** + Dial the given ISP, use @a username and @a password to authenticate. + + The parameters are only used under Windows currently, for Unix you + should use SetConnectCommand() to customize this functions behaviour. + + If no @a nameOfISP is given, the function will select the default one + (proposing the user to choose among all connections defined on this + machine) and if no username and/or password are given, the function + will try to do without them, but will ask the user if really needed. + + If @a async parameter is @false, the function waits until the end of + dialing and returns @true upon successful completion. + + If @a async is @true, the function only initiates the connection and + returns immediately - the result is reported via events (an event is + sent anyhow, but if dialing failed it will be a DISCONNECTED one). + */ + bool Dial(const wxString& nameOfISP = wxEmptyString, + const wxString& username = wxEmptyString, + const wxString& password = wxEmptyString, + bool async = true); + + /** + Disable automatic check for connection status change - notice that the + @c wxEVT_DIALUP_XXX events won't be sent any more neither. + */ + void DisableAutoCheckOnlineStatus(); + + /** + Enable automatic checks for the connection status and sending of + wxEVT_DIALUP_CONNECTED/wxEVT_DIALUP_DISCONNECTED events. The interval + parameter is only for Unix where we do the check manually and specifies + how often should we repeat the check (each minute by default). Under + Windows, the notification about the change of connection status is sent + by the system and so we don't do any polling and this parameter is + ignored. + + @return @false if couldn't set up automatic check for online status. + */ + bool EnableAutoCheckOnlineStatus(size_t nSeconds = 60); + + /** + This function is only implemented under Windows. + + Fills the array with the names of all possible values for the first + parameter to Dial() on this machine and returns their number (may be + 0). + */ + size_t GetISPNames(wxArrayString& names) const; + + /** + Hang up the currently active dial up connection. + */ + bool HangUp(); + + /** + Returns @true if the computer has a permanent network connection (i.e. + is on a LAN) and so there is no need to use Dial() function to go + online. + + @note This function tries to guess the result and it is not always + guaranteed to be correct, so it is better to ask user for + confirmation or give him a possibility to override it. + */ + bool IsAlwaysOnline() const; + + /** + Returns @true if (async) dialing is in progress. + + @see Dial() + */ + bool IsDialing() const; + + /** + Returns @true if the dialup manager was initialized correctly. If this + function returns @false, no other functions will work neither, so it is + a good idea to call this function and check its result before calling + any other wxDialUpManager methods. + */ + bool IsOk() const; + + /** + Returns @true if the computer is connected to the network: under + Windows, this just means that a RAS connection exists, under Unix we + check that the "well-known host" (as specified by SetWellKnownHost()) + is reachable. + */ + bool IsOnline() const; + + /** + This method is for Unix only. + + Sets the commands to start up the network and to hang up again. + */ + void SetConnectCommand(const wxString& commandDial = "/usr/bin/pon", + const wxString& commandHangup = "/usr/bin/poff") const; + + /** + Sometimes the built-in logic for determining the online status may + fail, so, in general, the user should be allowed to override it. This + function allows to forcefully set the online status - whatever our + internal algorithm may think about it. + + @see IsOnline() + */ + void SetOnlineStatus(bool isOnline = true); + + /** + This method is for Unix only. + + Under Unix, the value of well-known host is used to check whether we're + connected to the internet. It is unused under Windows, but this + function is always safe to call. The default value is + @c "www.yahoo.com:80". + */ + void SetWellKnownHost(const wxString& hostname, int portno = 80); +}; + + + +/** + @class wxDialUpEvent + @wxheader{dialup.h} + + This is the event class for the dialup events sent by wxDialUpManager. + + @library{wxcore} + @category{events} +*/ +class wxDialUpEvent : public wxEvent +{ +public: + /** + Constructor is only used by wxDialUpManager. + */ + wxDialUpEvent(bool isConnected, bool isOwnEvent); + + /** + Is this a @c CONNECTED or @c DISCONNECTED event? In other words, does + it notify about transition from offline to online state or vice versa? + */ + bool IsConnectedEvent() const; + + /** + Does this event come from wxDialUpManager::Dial() or from some extrenal + process (i.e. does it result from our own attempt to establish the + connection)? + */ + bool IsOwnEvent() const; +}; + diff --git a/interface/wx/dir.h b/interface/wx/dir.h new file mode 100644 index 0000000000..82b40531ca --- /dev/null +++ b/interface/wx/dir.h @@ -0,0 +1,292 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: dir.h +// Purpose: interface of wxDir and wxDirTraverser +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + Possible return values of wxDirTraverser callback functions. +*/ +enum wxDirTraverseResult +{ + wxDIR_IGNORE = -1, ///< Ignore this directory but continue with others. + wxDIR_STOP, ///< Stop traversing. + wxDIR_CONTINUE ///< Continue into this directory. +}; + +/** + @class wxDirTraverser + @wxheader{dir.h} + + wxDirTraverser is an abstract interface which must be implemented by + objects passed to wxDir::Traverse() function. + + Example of use (this works almost like wxDir::GetAllFiles()): + + @code + class wxDirTraverserSimple : public wxDirTraverser + { + public: + wxDirTraverserSimple(wxArrayString& files) : m_files(files) { } + + virtual wxDirTraverseResult OnFile(const wxString& filename) + { + m_files.Add(filename); + return wxDIR_CONTINUE; + } + + virtual wxDirTraverseResult OnDir(const wxString& WXUNUSED(dirname)) + { + return wxDIR_CONTINUE; + } + + private: + wxArrayString& m_files; + }; + + // get the names of all files in the array + wxArrayString files; + wxDirTraverserSimple traverser(files); + + wxDir dir(dirname); + dir.Traverse(traverser); + @endcode + + @library{wxbase} + @category{file} +*/ +class wxDirTraverser +{ +public: + /** + This function is called for each directory. It may return ::wxDIR_STOP + to abort traversing completely, ::wxDIR_IGNORE to skip this directory + but continue with others or ::wxDIR_CONTINUE to enumerate all files and + subdirectories in this directory. + + This is a pure virtual function and must be implemented in the derived + class. + */ + virtual wxDirTraverseResult OnDir(const wxString& dirname); + + /** + This function is called for each file. It may return ::wxDIR_STOP to + abort traversing (for example, if the file being searched is found) or + ::wxDIR_CONTINUE to proceed. + + This is a pure virtual function and must be implemented in the derived + class. + */ + virtual wxDirTraverseResult OnFile(const wxString& filename); + + /** + This function is called for each directory which we failed to open for + enumerating. It may return ::wxDIR_STOP to abort traversing completely, + ::wxDIR_IGNORE to skip this directory but continue with others or + ::wxDIR_CONTINUE to retry opening this directory once again. + + The base class version always returns ::wxDIR_IGNORE. + */ + virtual wxDirTraverseResult OnOpenError(const wxString& openerrorname); +}; + + + +/** + These flags define what kind of filenames are included in the list of files + enumerated by wxDir::GetFirst() and wxDir::GetNext(). +*/ +enum +{ + wxDIR_FILES = 0x0001, ///< Includes files. + wxDIR_DIRS = 0x0002, ///< Includes directories. + wxDIR_HIDDEN = 0x0004, ///< Includes hidden files. + wxDIR_DOTDOT = 0x0008, ///< Includes "." and "..". + + wxDIR_DEFAULT = wxDIR_FILES | wxDIR_DIRS | wxDIR_HIDDEN +}; + +/** + @class wxDir + @wxheader{dir.h} + + wxDir is a portable equivalent of Unix open/read/closedir functions which + allow enumerating of the files in a directory. wxDir allows to enumerate + files as well as directories. + + wxDir also provides a flexible way to enumerate files recursively using + Traverse() or a simpler GetAllFiles() function. + + Example of use: + + @code + wxDir dir(wxGetCwd()); + + if ( !dir.IsOpened() ) + { + // deal with the error here - wxDir would already log an error message + // explaining the exact reason of the failure + return; + } + + puts("Enumerating object files in current directory:"); + + wxString filename; + + bool cont = dir.GetFirst(&filename, filespec, flags); + while ( cont ) + { + printf("%s\n", filename.c_str()); + + cont = dir.GetNext(&filename); + } + @endcode + + @library{wxbase} + @category{file} +*/ +class wxDir +{ +public: + /** + Default constructor, use Open() afterwards. + */ + wxDir(); + /** + Opens the directory for enumeration, use IsOpened() to test for errors. + */ + wxDir(const wxString& dir); + + /** + Destructor cleans up the associated resources. It is not virtual and so + this class is not meant to be used polymorphically. + */ + ~wxDir(); + + /** + Test for existence of a directory with the given name. + */ + static bool Exists(const wxString& dir); + + /** + The function returns the path of the first file matching the given + @a filespec or an empty string if there are no files matching it. + + The @a flags parameter may or may not include ::wxDIR_FILES, the + function always behaves as if it were specified. By default, @a flags + includes ::wxDIR_DIRS and so the function recurses into the + subdirectories but if this flag is not specified, the function + restricts the search only to the directory @a dirname itself. + + @see Traverse() + */ + static wxString FindFirst(const wxString& dirname, + const wxString& filespec, + int flags = wxDIR_DEFAULT); + + /** + The function appends the names of all the files under directory + @a dirname to the array @a files (note that its old content is + preserved). Only files matching the @a filespec are taken, with empty + spec matching all the files. + + The @a flags parameter should always include ::wxDIR_FILES or the array + would be unchanged and should include ::wxDIR_DIRS flag to recurse into + subdirectories (both flags are included in the value by default). + + @see Traverse() + */ + static size_t GetAllFiles(const wxString& dirname, wxArrayString* files, + const wxString& filespec = wxEmptyString, + int flags = wxDIR_DEFAULT); + + /** + Start enumerating all files matching @a filespec (or all files if it is + empty) and @e flags, return @true on success. + */ + bool GetFirst(wxString* filename, + const wxString& filespec = wxEmptyString, + int flags = wxDIR_DEFAULT) const; + + /** + Returns the name of the directory itself. The returned string does not + have the trailing path separator (slash or backslash). + */ + wxString GetName() const; + + /** + Continue enumerating files which satisfy the criteria specified by the + last call to GetFirst(). + */ + bool GetNext(wxString* filename) const; + + /** + Returns the size (in bytes) of all files recursively found in @c dir or + @c wxInvalidSize in case of error. + + In case it happens that while traversing folders a file's size can not + be read, that file is added to the @a filesSkipped array, if not @NULL, + and then skipped. This usually happens with some special folders which + are locked by the operating system or by another process. Remember that + when the size of @a filesSkipped is not zero, then the returned value + is not 100% accurate and, if the skipped files were big, it could be + far from real size of the directory. + + @see wxFileName::GetHumanReadableSize(), wxGetDiskSpace() + */ + static wxULongLong GetTotalSize(const wxString& dir, + wxArrayString* filesSkipped = NULL); + + /** + Returns @true if the directory contains any files matching the given + @a filespec. If @a filespec is empty, look for any files at all. In any + case, even hidden files are taken into account. + */ + bool HasFiles(const wxString& filespec = wxEmptyString) const; + + /** + Returns @true if the directory contains any subdirectories (if a non + empty @a filespec is given, only check for directories matching it). + The hidden subdirectories are taken into account as well. + */ + bool HasSubDirs(const wxString& dirspec = wxEmptyString) const; + + /** + Returns @true if the directory was successfully opened by a previous + call to Open(). + */ + bool IsOpened() const; + + /** + Open the directory for enumerating, returns @true on success or @false + if an error occurred. + */ + bool Open(const wxString& dir); + + /** + Enumerate all files and directories under the given directory + recursively calling the element of the provided wxDirTraverser object + for each of them. + + More precisely, the function will really recurse into subdirectories if + @a flags contains ::wxDIR_DIRS flag. It will ignore the files (but + still possibly recurse into subdirectories) if ::wxDIR_FILES flag is + given. + + For each found directory, @ref wxDirTraverser::OnDir() "sink.OnDir()" + is called and @ref wxDirTraverser::OnFile() "sink.OnFile()" is called + for every file. Depending on the return value, the enumeration may + continue or stop. + + The function returns the total number of files found or @c "(size_t)-1" + on error. + + @see GetAllFiles() + */ + size_t Traverse(wxDirTraverser& sink, + const wxString& filespec = wxEmptyString, + int flags = wxDIR_DEFAULT); +}; + diff --git a/interface/wx/dirctrl.h b/interface/wx/dirctrl.h new file mode 100644 index 0000000000..b83c4248df --- /dev/null +++ b/interface/wx/dirctrl.h @@ -0,0 +1,190 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: dirctrl.h +// Purpose: interface of wxGenericDirCtrl +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxGenericDirCtrl + @wxheader{dirctrl.h} + + This control can be used to place a directory listing (with optional + files) on an arbitrary window. + + The control contains a wxTreeCtrl window representing the directory + hierarchy, and optionally, a wxChoice window containing a list of filters. + + @beginStyleTable + @style{wxDIRCTRL_DIR_ONLY} + Only show directories, and not files. + @style{wxDIRCTRL_3D_INTERNAL} + Use 3D borders for internal controls. + @style{wxDIRCTRL_SELECT_FIRST} + When setting the default path, select the first file in the + directory. + @style{wxDIRCTRL_EDIT_LABELS} + Allow the folder and file labels to be editable. + @endStyleTable + + @library{wxbase} + @category{ctrl} + +*/ +class wxGenericDirCtrl : public wxControl +{ +public: + /** + Default constructor. + */ + wxGenericDirCtrl(); + /** + Main constructor. + + @param parent + Parent window. + @param id + Window identifier. + @param dir + Initial folder. + @param pos + Position. + @param size + Size. + @param style + Window style. Please see wxGenericDirCtrl for a list of possible + styles. + @param filter + A filter string, using the same syntax as that for wxFileDialog. + This may be empty if filters are not being used. Example: + @c "All files (*.*)|*.*|JPEG files (*.jpg)|*.jpg" + @param defaultFilter + The zero-indexed default filter setting. + @param name + The window name. + */ + wxGenericDirCtrl(wxWindow* parent, const wxWindowID id = -1, + const wxString& dir = wxDirDialogDefaultFolderStr, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxDIRCTRL_3D_INTERNAL|wxBORDER_SUNKEN, + const wxString& filter = wxEmptyString, + int defaultFilter = 0, + const wxString& name = wxTreeCtrlNameStr); + + /** + Destructor. + */ + ~wxGenericDirCtrl(); + + /** + Collapse the given @a path. + */ + bool CollapsePath(const wxString& path); + + /** + Collapses the entire tree. + */ + void CollapseTree(); + + /** + Create function for two-step construction. See wxGenericDirCtrl() for + details. + */ + bool Create(wxWindow* parent, const wxWindowID id = -1, + const wxString& dir = wxDirDialogDefaultFolderStr, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxDIRCTRL_3D_INTERNAL|wxBORDER_SUNKEN, + const wxString& filter = wxEmptyString, + int defaultFilter = 0, + const wxString& name = wxTreeCtrlNameStr); + + /** + Tries to expand as much of the given @a path as possible, so that the + filename or directory is visible in the tree control. + */ + bool ExpandPath(const wxString& path); + + /** + Gets the default path. + */ + wxString GetDefaultPath() const; + + /** + Gets selected filename path only (else empty string). + + This function doesn't count a directory as a selection. + */ + wxString GetFilePath() const; + + /** + Returns the filter string. + */ + wxString GetFilter() const; + + /** + Returns the current filter index (zero-based). + */ + int GetFilterIndex() const; + + /** + Returns a pointer to the filter list control (if present). + */ + wxDirFilterListCtrl* GetFilterListCtrl() const; + + /** + Gets the currently-selected directory or filename. + */ + wxString GetPath() const; + + /** + Returns the root id for the tree control. + */ + wxTreeItemId GetRootId(); + + /** + Returns a pointer to the tree control. + */ + wxTreeCtrl* GetTreeCtrl() const; + + /** + Initializes variables. + */ + void Init(); + + /** + Collapse and expand the tree, thus re-creating it from scratch. May be + used to update the displayed directory content. + */ + void ReCreateTree(); + + /** + Sets the default path. + */ + void SetDefaultPath(const wxString& path); + + /** + Sets the filter string. + */ + void SetFilter(const wxString& filter); + + /** + Sets the current filter index (zero-based). + */ + void SetFilterIndex(int n); + + /** + Sets the current path. + */ + void SetPath(const wxString& path); + + /** + @param show + If @true, hidden folders and files will be displayed by the + control. If @false, they will not be displayed. + */ + void ShowHidden(bool show); +}; + diff --git a/interface/wx/dirdlg.h b/interface/wx/dirdlg.h new file mode 100644 index 0000000000..4d21deac85 --- /dev/null +++ b/interface/wx/dirdlg.h @@ -0,0 +1,132 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: dirdlg.h +// Purpose: interface of wxDirDialog +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxDirDialog + @wxheader{dirdlg.h} + + This class represents the directory chooser dialog. + + @beginStyleTable + @style{wxDD_DEFAULT_STYLE} + Equivalent to a combination of wxDEFAULT_DIALOG_STYLE and + wxRESIZE_BORDER (the last one is not used under wxWinCE). + @style{wxDD_DIR_MUST_EXIST} + The dialog will allow the user to choose only an existing folder. + When this style is not given, a "Create new directory" button is + added to the dialog (on Windows) or some other way is provided to + the user to type the name of a new folder. + @style{wxDD_CHANGE_DIR} + Change the current working directory to the directory chosen by the + user. + @endStyleTable + + @note On Windows the new directory button is only available with recent + versions of the common dialogs. + + @library{wxcore} + @category{cmndlg} + + @see @ref overview_cmndlg_dir, wxFileDialog +*/ +class wxDirDialog : public wxDialog +{ +public: + /** + Constructor. Use ShowModal() to show the dialog. + + @param parent + Parent window. + @param message + Message to show on the dialog. + @param defaultPath + The default path, or the empty string. + @param style + The dialog style. See wxDirDialog + @param pos + Dialog position. Ignored under Windows. + @param size + Dialog size. Ignored under Windows. + @param name + The dialog name, not used. + */ + wxDirDialog(wxWindow* parent, + const wxString& message = "Choose a directory", + const wxString& defaultPath = "", + long style = wxDD_DEFAULT_STYLE, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + const wxString& name = "wxDirCtrl"); + + /** + Destructor. + */ + ~wxDirDialog(); + + /** + Returns the message that will be displayed on the dialog. + */ + wxString GetMessage() const; + + /** + Returns the default or user-selected path. + */ + wxString GetPath() const; + + /** + Sets the message that will be displayed on the dialog. + */ + void SetMessage(const wxString& message); + + /** + Sets the default path. + */ + void SetPath(const wxString& path); + + /** + Shows the dialog, returning wxID_OK if the user pressed OK, and + wxID_CANCEL otherwise. + */ + int ShowModal(); +}; + + + +// ============================================================================ +// Global functions/macros +// ============================================================================ + +/** @ingroup group_funcmacro_dialog */ +//@{ + +/** + Pops up a directory selector dialog. The arguments have the same meaning + as those of wxDirDialog::wxDirDialog(). The message is displayed at the + top, and the default_path, if specified, is set as the initial selection. + + The application must check for an empty return value (if the user pressed + Cancel). For example: + + @code + const wxString& dir = wxDirSelector("Choose a folder"); + if ( !dir.empty() ) + { + ... + } + @endcode + + @header{wx/dirdlg.h} +*/ +wxString wxDirSelector(const wxString& message = wxDirSelectorPromptStr, + const wxString& default_path = "", + long style = 0, + const wxPoint& pos = wxDefaultPosition, + wxWindow* parent = NULL); + +//@} + diff --git a/interface/wx/display.h b/interface/wx/display.h new file mode 100644 index 0000000000..71eeeba4f5 --- /dev/null +++ b/interface/wx/display.h @@ -0,0 +1,128 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: display.h +// Purpose: interface of wxDisplay +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxDisplay + @wxheader{display.h} + + Determines the sizes and locations of displays connected to the system. + + @library{wxcore} + @category{misc} + + @see wxClientDisplayRect(), wxDisplaySize(), wxDisplaySizeMM() +*/ +class wxDisplay +{ +public: + /** + Constructor, setting up a wxDisplay instance with the specified + display. + + @param index + The index of the display to use. This must be non-negative and + lower than the value returned by GetCount(). + */ + wxDisplay(unsigned index = 0); + + /** + Destructor. + */ + ~wxDisplay(); + + /** + Changes the video mode of this display to the mode specified in the + mode parameter. + + If wxDefaultVideoMode is passed in as the mode parameter, the defined + behaviour is that wxDisplay will reset the video mode to the default + mode used by the display. On Windows, the behavior is normal. However, + there are differences on other platforms. On Unix variations using X11 + extensions it should behave as defined, but some irregularities may + occur. + + On wxMac passing in wxDefaultVideoMode as the mode parameter does + nothing. This happens because carbon no longer has access to + @c DMUseScreenPrefs(), an undocumented function that changed the video + mode to the system default by using the system's "scrn" resource. + */ + bool ChangeMode(const wxVideoMode& mode = wxDefaultVideoMode); + + /** + Returns the client area of the display. The client area is the part of + the display available for the normal (non full screen) windows, usually + it is the same as GetGeometry() but it could be less if there is a + taskbar (or equivalent) on this display. + */ + wxRect GetClientArea() const; + + /** + Returns the number of connected displays. + */ + static unsigned GetCount(); + + /** + Returns the current video mode that this display is in. + */ + wxVideoMode GetCurrentMode() const; + + /** + Returns the bit depth of the display whose index was passed to the + constructor. + */ + int GetDepth() const; + + /** + Returns the index of the display on which the given point lies, or + @c wxNOT_FOUND if the point is not on any connected display. + + @param pt + The point to locate. + */ + static int GetFromPoint(const wxPoint& pt); + + /** + Returns the index of the display on which the given window lies. + + If the window is on more than one display it gets the display that + overlaps the window the most. + + Returns @c wxNOT_FOUND if the window is not on any connected display. + + @param win + The window to locate. + */ + static int GetFromWindow(const wxWindow* win); + + /** + Returns the bounding rectangle of the display whose index was passed to + the constructor. + + @see GetClientArea(), wxDisplaySize() + */ + wxRect GetGeometry() const; + + /** + Fills and returns an array with all the video modes that are supported + by this display, or video modes that are supported by this display and + match the mode parameter (if mode is not wxDefaultVideoMode). + */ + wxArrayVideoModes GetModes(const wxVideoMode& mode = wxDefaultVideoMode) const; + + /** + Returns the display's name. A name is not available on all platforms. + */ + wxString GetName() const; + + /** + Returns @true if the display is the primary display. The primary + display is the one whose index is 0. + */ + bool IsPrimary(); +}; + diff --git a/interface/wx/dnd.h b/interface/wx/dnd.h new file mode 100644 index 0000000000..a6d5890f2d --- /dev/null +++ b/interface/wx/dnd.h @@ -0,0 +1,359 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: dnd.h +// Purpose: interface of wxDropSource and wx*DropTarget +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxTextDropTarget + @wxheader{dnd.h} + + A predefined drop target for dealing with text data. + + @library{wxcore} + @category{dnd} + + @see @ref overview_dnd, wxDropSource, wxDropTarget, wxFileDropTarget +*/ +class wxTextDropTarget : public wxDropTarget +{ +public: + /** + Constructor. + */ + wxTextDropTarget(); + + /** + See wxDropTarget::OnDrop(). This function is implemented appropriately + for text, and calls OnDropText(). + */ + virtual bool OnDrop(long x, long y, const void data, size_t size); + + /** + Override this function to receive dropped text. + + @param x + The x coordinate of the mouse. + @param y + The y coordinate of the mouse. + @param data + The data being dropped: a wxString. + + Return @true to accept the data, or @false to veto the operation. + */ + virtual bool OnDropText(wxCoord x, wxCoord y, const wxString& data); +}; + + + +/** + Result returned from a wxDropSource::DoDragDrop() call. +*/ +enum wxDragResult +{ + wxDragError, ///< Error prevented the D&D operation from completing. + wxDragNone, ///< Drag target didn't accept the data. + wxDragCopy, ///< The data was successfully copied. + wxDragMove, ///< The data was successfully moved (MSW only). + wxDragLink, ///< Operation is a drag-link. + wxDragCancel ///< The operation was cancelled by user (not an error). +}; + +/** + @class wxDropTarget + @wxheader{dnd.h} + + This class represents a target for a drag and drop operation. A + wxDataObject can be associated with it and by default, this object will be + filled with the data from the drag source, if the data formats supported by + the data object match the drag source data format. + + There are various virtual handler functions defined in this class which may + be overridden to give visual feedback or react in a more fine-tuned way, + e.g. by not accepting data on the whole window area, but only a small + portion of it. The normal sequence of calls is OnEnter(), OnDragOver() + possibly many times, OnDrop() and finally OnData(). + + @library{wxcore} + @category{dnd} + + @see @ref overview_dnd, @ref overview_dataobject, wxDropSource, + wxTextDropTarget, wxFileDropTarget, wxDataFormat, wxDataObject +*/ +class wxDropTarget +{ +public: + /** + Constructor. @a data is the data to be associated with the drop target. + */ + wxDropTarget(wxDataObject* data = NULL); + + /** + Destructor. Deletes the associated data object, if any. + */ + ~wxDropTarget(); + + /** + This method may only be called from within OnData(). By default, this + method copies the data from the drop source to the wxDataObject + associated with this drop target, calling its wxDataObject::SetData() + method. + */ + virtual void GetData(); + + /** + Called after OnDrop() returns @true. By default this will usually + GetData() and will return the suggested default value @a def. + */ + virtual wxDragResult OnData(wxCoord x, wxCoord y, wxDragResult def); + + /** + Called when the mouse is being dragged over the drop target. By + default, this calls functions return the suggested return value @a def. + + @param x + The x coordinate of the mouse. + @param y + The y coordinate of the mouse. + @param def + Suggested value for return value. Determined by SHIFT or CONTROL + key states. + + @return The desired operation or wxDragNone. This is used for optical + feedback from the side of the drop source, typically in form + of changing the icon. + */ + virtual wxDragResult OnDragOver(wxCoord x, wxCoord y, wxDragResult def); + + /** + Called when the user drops a data object on the target. Return @false + to veto the operation. + + @param x + The x coordinate of the mouse. + @param y + The y coordinate of the mouse. + + @return @true to accept the data, or @false to veto the operation. + */ + virtual bool OnDrop(wxCoord x, wxCoord y); + + /** + Called when the mouse enters the drop target. By default, this calls + OnDragOver(). + + @param x + The x coordinate of the mouse. + @param y + The y coordinate of the mouse. + @param def + Suggested default for return value. Determined by SHIFT or CONTROL + key states. + + @return The desired operation or wxDragNone. This is used for optical + feedback from the side of the drop source, typically in form + of changing the icon. + */ + virtual wxDragResult OnEnter(wxCoord x, wxCoord y, wxDragResult def); + + /** + Called when the mouse leaves the drop target. + */ + virtual void OnLeave(); + + /** + Sets the data wxDataObject associated with the drop target and deletes + any previously associated data object. + */ + void SetDataObject(wxDataObject* data); +}; + + + +/** + @class wxDropSource + @wxheader{dnd.h} + + This class represents a source for a drag and drop operation. + + @library{wxcore} + @category{dnd} + + @see @ref overview_dnd, @ref overview_dataobject, wxDropTarget, + wxTextDropTarget, wxFileDropTarget +*/ +class wxDropSource +{ +public: + /** + This constructor requires that you must call SetData() later. + + Note that the exact type of @a iconCopy and subsequent parameters + differs between wxMSW and wxGTK: these are cursors under Windows but + icons for GTK. You should use the macro wxDROP_ICON() in portable + programs instead of directly using either of these types. + + @param win + The window which initiates the drag and drop operation. + @param iconCopy + The icon or cursor used for feedback for copy operation. + @param iconMove + The icon or cursor used for feedback for move operation. + @param iconNone + The icon or cursor used for feedback when operation can't be done. + */ + wxDropSource(wxWindow* win = NULL, + const wxIconOrCursor& iconCopy = wxNullIconOrCursor, + const wxIconOrCursor& iconMove = wxNullIconOrCursor, + const wxIconOrCursor& iconNone = wxNullIconOrCursor); + /** + Note that the exact type of @a iconCopy and subsequent parameters + differs between wxMSW and wxGTK: these are cursors under Windows but + icons for GTK. You should use the macro wxDROP_ICON() in portable + programs instead of directly using either of these types. + + @param win + The window which initiates the drag and drop operation. + @param iconCopy + The icon or cursor used for feedback for copy operation. + @param iconMove + The icon or cursor used for feedback for move operation. + @param iconNone + The icon or cursor used for feedback when operation can't be done. + */ + wxDropSource(wxDataObject& data, wxWindow* win = NULL, + const wxIconOrCursor& iconCopy = wxNullIconOrCursor, + const wxIconOrCursor& iconMove = wxNullIconOrCursor, + const wxIconOrCursor& iconNone = wxNullIconOrCursor); + + /** + Default constructor. + */ + ~wxDropSource(); + + /** + Starts the drag-and-drop operation which will terminate when the user + releases the mouse. Call this in response to a mouse button press, for + example. + + @param flags + If wxDrag_AllowMove is included in the flags, data may be moved and + not only copied (default). If wxDrag_DefaultMove is specified + (which includes the previous flag), this is even the default + operation. + + @return The operation requested by the user, may be ::wxDragCopy, + ::wxDragMove, ::wxDragLink, ::wxDragCancel or ::wxDragNone if + an error occurred. + */ + virtual wxDragResult DoDragDrop(int flags = wxDrag_CopyOnly); + + /** + Returns the wxDataObject object that has been assigned previously. + */ + wxDataObject* GetDataObject(); + + /** + You may give some custom UI feedback during the drag and drop operation + by overriding this function. It is called on each mouse move, so your + implementation must not be too slow. + + @param effect + The effect to implement. One of ::wxDragCopy, ::wxDragMove, + ::wxDragLink and ::wxDragNone. + @param scrolling + @true if the window is scrolling. MSW only. + + @return @false if you want default feedback, or @true if you implement + your own feedback. The return values is ignored under GTK. + */ + virtual bool GiveFeedback(wxDragResult effect); + + /** + Set the icon to use for a certain drag result. + + @param res + The drag result to set the icon for. + @param cursor + The ion to show when this drag result occurs. + */ + void SetCursor(wxDragResult res, const wxCursor& cursor); + + /** + Sets the data wxDataObject associated with the drop source. This will + not delete any previously associated data. + */ + void SetData(wxDataObject& data); +}; + + + +/** + @class wxFileDropTarget + @wxheader{dnd.h} + + This is a drop target which accepts files (dragged from File Manager or + Explorer). + + @library{wxcore} + @category{dnd} + + @see @ref overview_dnd, wxDropSource, wxDropTarget, wxTextDropTarget +*/ +class wxFileDropTarget : public wxDropTarget +{ +public: + /** + Constructor. + */ + wxFileDropTarget(); + + /** + See wxDropTarget::OnDrop(). This function is implemented appropriately + for files, and calls OnDropFiles(). + */ + virtual bool OnDrop(long x, long y, const void data, size_t size); + + /** + Override this function to receive dropped files. + + @param x + The x coordinate of the mouse. + @param y + The y coordinate of the mouse. + @param filenames + An array of filenames. + + Return @true to accept the data, or @false to veto the operation. + */ + virtual bool OnDropFiles(wxCoord x, wxCoord y, + const wxArrayString& filenames); +}; + + + +// ============================================================================ +// Global functions/macros +// ============================================================================ + +/** @ingroup group_funcmacro_gdi */ +//@{ + +/** + This macro creates either a cursor (MSW) or an icon (elsewhere) with the + given @a name (of type const char*). Under MSW, the cursor is + loaded from the resource file and the icon is loaded from XPM file under + other platforms. + + This macro should be used with wxDropSource::wxDropSource(). + + @return wxCursor on MSW, otherwise returns a wxIcon + + @header{wx/dnd.h} +*/ +#define wxDROP_ICON(name) + +//@} + diff --git a/interface/wx/docmdi.h b/interface/wx/docmdi.h new file mode 100644 index 0000000000..758fba89b6 --- /dev/null +++ b/interface/wx/docmdi.h @@ -0,0 +1,149 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: docmdi.h +// Purpose: interface of wxDocMDIParentFrame and wxDocMDIChildFrame +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxDocMDIParentFrame + @wxheader{docmdi.h} + + The wxDocMDIParentFrame class provides a default top-level frame for + applications using the document/view framework. This class can only be used + for MDI parent frames. + + It cooperates with the wxView, wxDocument, wxDocManager and wxDocTemplate + classes. + + @library{wxcore} + @category{docview} + + @see @ref overview_docview, @ref page_samples_docview, wxMDIParentFrame +*/ +class wxDocMDIParentFrame : public wxMDIParentFrame +{ +public: + //@{ + /** + Constructor. + */ + wxDocMDIParentFrame(); + wxDocMDIParentFrame(wxDocManager* manager, wxFrame* parent, + wxWindowID id, + const wxString& title, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxDEFAULT_FRAME_STYLE, + const wxString& name = "frame"); + //@} + + /** + Destructor. + */ + ~wxDocMDIParentFrame(); + + /** + Creates the window. + */ + bool Create(wxDocManager* manager, wxFrame* parent, + wxWindowID id, const wxString& title, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxDEFAULT_FRAME_STYLE, + const wxString& name = "frame"); + + /** + Deletes all views and documents. If no user input cancelled the + operation, the frame will be destroyed and the application will exit. + + Since understanding how document/view clean-up takes place can be + difficult, the implementation of this function is shown below: + + @code + void wxDocParentFrame::OnCloseWindow(wxCloseEvent& event) + { + if (m_docManager->Clear(!event.CanVeto())) + { + this->Destroy(); + } + else + event.Veto(); + } + @endcode + */ + void OnCloseWindow(wxCloseEvent& event); +}; + + + +/** + @class wxDocMDIChildFrame + @wxheader{docmdi.h} + + The wxDocMDIChildFrame class provides a default frame for displaying + documents on separate windows. This class can only be used for MDI child + frames. + + The class is part of the document/view framework supported by wxWidgets, + and cooperates with the wxView, wxDocument, wxDocManager and wxDocTemplate + classes. + + @library{wxcore} + @category{docview} + + @see @ref overview_docview, @ref page_samples_docview, wxMDIChildFrame +*/ +class wxDocMDIChildFrame : public wxMDIChildFrame +{ +public: + /** + Constructor. + */ + wxDocMDIChildFrame(wxDocument* doc, wxView* view, + wxFrame* parent, wxWindowID id, + const wxString& title, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxDEFAULT_FRAME_STYLE, + const wxString& name = "frame"); + + /** + Destructor. + */ + ~wxDocMDIChildFrame(); + + /** + Returns the document associated with this frame. + */ + wxDocument* GetDocument() const; + + /** + Returns the view associated with this frame. + */ + wxView* GetView() const; + + /** + Sets the currently active view to be the frame's view. You may need + to override (but still call) this function in order to set the keyboard + focus for your subwindow. + */ + void OnActivate(wxActivateEvent event); + + /** + Closes and deletes the current view and document. + */ + void OnCloseWindow(wxCloseEvent& event); + + /** + Sets the document for this frame. + */ + void SetDocument(wxDocument* doc); + + /** + Sets the view for this frame. + */ + void SetView(wxView* view); +}; + diff --git a/interface/wx/docview.h b/interface/wx/docview.h new file mode 100644 index 0000000000..b41ae9b3a8 --- /dev/null +++ b/interface/wx/docview.h @@ -0,0 +1,1475 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: docview.h +// Purpose: interface of various doc/view framework classes +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxDocTemplate + @wxheader{docview.h} + + The wxDocTemplate class is used to model the relationship between a + document class and a view class. + + @library{wxcore} + @category{docview} + + @see @ref overview_docview_wxdoctemplate, wxDocument, wxView +*/ +class wxDocTemplate : public wxObject +{ +public: + /** + Constructor. Create instances dynamically near the start of your + application after creating a wxDocManager instance, and before doing + any document or view operations. + + @param manager + The document manager object which manages this template. + @param descr + A short description of what the template is for. This string will + be displayed in the file filter list of Windows file selectors. + @param filter + An appropriate file filter such as "*.txt". + @param dir + The default directory to use for file selectors. + @param ext + The default file extension (such as "txt"). + @param docTypeName + A name that should be unique for a given type of document, used for + gathering a list of views relevant to a particular document. + @param viewTypeName + A name that should be unique for a given view. + @param docClassInfo + A pointer to the run-time document class information as returned by + the CLASSINFO() macro, e.g. CLASSINFO(MyDocumentClass). If this is + not supplied, you will need to derive a new wxDocTemplate class and + override the CreateDocument() member to return a new document + instance on demand. + @param viewClassInfo + A pointer to the run-time view class information as returned by the + CLASSINFO() macro, e.g. CLASSINFO(MyViewClass). If this is not + supplied, you will need to derive a new wxDocTemplate class and + override the CreateView() member to return a new view instance on + demand. + @param flags + A bit list of the following: + - wxTEMPLATE_VISIBLE - The template may be displayed to the + user in dialogs. + - wxTEMPLATE_INVISIBLE - The template may not be displayed to + the user in dialogs. + - wxDEFAULT_TEMPLATE_FLAGS - Defined as wxTEMPLATE_VISIBLE. + */ + wxDocTemplate(wxDocManager* manager, const wxString& descr, + const wxString& filter, const wxString& dir, + const wxString& ext, const wxString& docTypeName, + const wxString& viewTypeName, + wxClassInfo* docClassInfo = NULL, + wxClassInfo* viewClassInfo = NULL, + long flags = wxDEFAULT_TEMPLATE_FLAGS); + + /** + Destructor. + */ + ~wxDocTemplate(); + + /** + Creates a new instance of the associated document class. If you have + not supplied a wxClassInfo parameter to the template constructor, you + will need to override this function to return an appropriate document + instance. + + This function calls InitDocument() which in turns calls + wxDocument::OnCreate(). + */ + wxDocument* CreateDocument(const wxString& path, long flags = 0); + + /** + Creates a new instance of the associated view class. If you have not + supplied a wxClassInfo parameter to the template constructor, you will + need to override this function to return an appropriate view instance. + */ + wxView* CreateView(wxDocument* doc, long flags = 0); + + /** + Returns the default file extension for the document data, as passed to + the document template constructor. + */ + wxString GetDefaultExtension(); + + /** + Returns the text description of this template, as passed to the + document template constructor. + */ + wxString GetDescription(); + + /** + Returns the default directory, as passed to the document template + constructor. + */ + wxString GetDirectory(); + + /** + Returns a pointer to the document manager instance for which this + template was created. + */ + wxDocManager* GetDocumentManager(); + + /** + Returns the document type name, as passed to the document template + constructor. + */ + wxString GetDocumentName(); + + /** + Returns the file filter, as passed to the document template + constructor. + */ + wxString GetFileFilter(); + + /** + Returns the flags, as passed to the document template constructor. + */ + long GetFlags(); + + /** + Returns the view type name, as passed to the document template + constructor. + */ + wxString GetViewName(); + + /** + Initialises the document, calling wxDocument::OnCreate(). This is + called from CreateDocument(). + */ + bool InitDocument(wxDocument* doc, const wxString& path, long flags = 0); + + /** + Returns @true if the document template can be shown in user dialogs, + @false otherwise. + */ + bool IsVisible(); + + /** + Sets the default file extension. + */ + void SetDefaultExtension(const wxString& ext); + + /** + Sets the template description. + */ + void SetDescription(const wxString& descr); + + /** + Sets the default directory. + */ + void SetDirectory(const wxString& dir); + + /** + Sets the pointer to the document manager instance for which this + template was created. Should not be called by the application. + */ + void SetDocumentManager(wxDocManager* manager); + + /** + Sets the file filter. + */ + void SetFileFilter(const wxString& filter); + + /** + Sets the internal document template flags (see the constructor + description for more details). + */ + void SetFlags(long flags); + + /** + The default extension for files of this type. + */ + wxString m_defaultExt; + + /** + A short description of this template. + */ + wxString m_description; + + /** + The default directory for files of this type. + */ + wxString m_directory; + + /** + Run-time class information that allows document instances to be + constructed dynamically. + */ + wxClassInfo* m_docClassInfo; + + /** + The named type of the document associated with this template. + */ + wxString m_docTypeName; + + /** + A pointer to the document manager for which this template was created. + */ + wxDocTemplate* m_documentManager; + + /** + The file filter (such as "*.txt") to be used in file selector dialogs. + */ + wxString m_fileFilter; + + /** + The flags passed to the constructor. + */ + long m_flags; + + /** + Run-time class information that allows view instances to be constructed + dynamically. + */ + wxClassInfo* m_viewClassInfo; + + /** + The named type of the view associated with this template. + */ + wxString m_viewTypeName; +}; + + + +/** + @class wxDocManager + @wxheader{docview.h} + + The wxDocManager class is part of the document/view framework supported by + wxWidgets, and cooperates with the wxView, wxDocument and wxDocTemplate + classes. + + @library{wxcore} + @category{docview} + + @see @ref overview_docview_wxdocmanager, wxDocument, wxView, wxDocTemplate, + wxFileHistory +*/ +class wxDocManager : public wxEvtHandler +{ +public: + /** + Constructor. Create a document manager instance dynamically near the + start of your application before doing any document or view operations. + + @a flags is currently unused. + + If @a initialize is @true, the Initialize() function will be called to + create a default history list object. If you derive from wxDocManager, + you may wish to call the base constructor with @false, and then call + Initialize() in your own constructor, to allow your own Initialize() or + OnCreateFileHistory functions to be called. + */ + wxDocManager(long flags = wxDEFAULT_DOCMAN_FLAGS, + bool initialize = true); + + /** + Destructor. + */ + ~wxDocManager(); + + /** + Sets the current view. + */ + void ActivateView(wxView* doc, bool activate = true); + + /** + Adds the document to the list of documents. + */ + void AddDocument(wxDocument* doc); + + /** + Adds a file to the file history list, if we have a pointer to an + appropriate file menu. + */ + void AddFileToHistory(const wxString& filename); + + /** + Adds the template to the document manager's template list. + */ + void AssociateTemplate(wxDocTemplate* temp); + + /** + Closes all currently opened documents. + */ + bool CloseDocuments(bool force = true); + + /** + Creates a new document in a manner determined by the @a flags + parameter, which can be: + + - wxDOC_NEW - Creates a fresh document. + - wxDOC_SILENT - Silently loads the given document file. + + If wxDOC_NEW is present, a new document will be created and returned, + possibly after asking the user for a template to use if there is more + than one document template. If wxDOC_SILENT is present, a new document + will be created and the given file loaded into it. If neither of these + flags is present, the user will be presented with a file selector for + the file to load, and the template to use will be determined by the + extension (Windows) or by popping up a template choice list (other + platforms). + + If the maximum number of documents has been reached, this function will + delete the oldest currently loaded document before creating a new one. + */ + wxDocument* CreateDocument(const wxString& path, long flags); + + /** + Creates a new view for the given document. If more than one view is + allowed for the document (by virtue of multiple templates mentioning + the same document type), a choice of view is presented to the user. + */ + wxView* CreateView(wxDocument* doc, long flags); + + /** + Removes the template from the list of templates. + */ + void DisassociateTemplate(wxDocTemplate* temp); + + /** + Appends the files in the history list to all menus managed by the file + history object. + */ + void FileHistoryAddFilesToMenu(); + /** + Appends the files in the history list to the given @a menu only. + */ + void FileHistoryAddFilesToMenu(wxMenu* menu); + + /** + Loads the file history from a config object. + + @see wxConfigBase + */ + void FileHistoryLoad(const wxConfigBase& config); + + /** + Removes the given menu from the list of menus managed by the file + history object. + */ + void FileHistoryRemoveMenu(wxMenu* menu); + + /** + Saves the file history into a config object. This must be called + explicitly by the application. + + @see wxConfigBase + */ + void FileHistorySave(wxConfigBase& resourceFile); + + /** + Use this menu for appending recently-visited document filenames, for + convenient access. Calling this function with a valid menu pointer + enables the history list functionality. + + @note You can add multiple menus using this function, to be managed by + the file history object. + */ + void FileHistoryUseMenu(wxMenu* menu); + + /** + Given a path, try to find template that matches the extension. This is + only an approximate method of finding a template for creating a + document. + */ + wxDocTemplate* FindTemplateForPath(const wxString& path); + + /** + Returns the document associated with the currently active view (if + any). + */ + wxDocument* GetCurrentDocument(); + + /** + Returns the currently active view + */ + wxView* GetCurrentView(); + + /** + Returns a reference to the list of documents. + */ + wxList GetDocuments(); + + /** + Returns a pointer to file history. + */ + wxFileHistory* GetFileHistory(); + + /** + Returns the number of files currently stored in the file history. + */ + size_t GetHistoryFilesCount(); + + /** + Returns the directory last selected by the user when opening a file. + Initially empty. + */ + wxString GetLastDirectory() const; + + /** + Returns the number of documents that can be open simultaneously. + */ + int GetMaxDocsOpen(); + + /** + Returns a reference to the list of associated templates. + */ + wxList GetTemplates(); + + /** + Initializes data; currently just calls OnCreateFileHistory(). + + Some data cannot always be initialized in the constructor because the + programmer must be given the opportunity to override functionality. If + OnCreateFileHistory() was called from the constructor, an overridden + virtual OnCreateFileHistory() would not be called due to C++'s + 'interesting' constructor semantics. In fact Initialize() @e is called + from the wxDocManager constructor, but this can be vetoed by passing + @false to the second argument, allowing the derived class's constructor + to call Initialize(), possibly calling a different + OnCreateFileHistory() from the default. + + The bottom line: if you're not deriving from Initialize(), forget it + and construct wxDocManager with no arguments. + */ + bool Initialize(); + + /** + Return a string containing a suitable default name for a new document. + By default this is implemented by appending an integer counter to the + string @b unnamed but can be overridden in the derived classes to do + something more appropriate. + */ + wxString MakeNewDocumentName(); + + /** + A hook to allow a derived class to create a different type of file + history. Called from Initialize(). + */ + wxFileHistory* OnCreateFileHistory(); + + /** + Closes and deletes the currently active document. + */ + void OnFileClose(wxCommandEvent& event); + + /** + Closes and deletes all the currently opened documents. + */ + void OnFileCloseAll(wxCommandEvent& event); + + /** + Creates a document from a list of templates (if more than one + template). + */ + void OnFileNew(wxCommandEvent& event); + + /** + Creates a new document and reads in the selected file. + */ + void OnFileOpen(wxCommandEvent& event); + + /** + Reverts the current document by calling wxDocument::Revert() for the + current document. + */ + void OnFileRevert(wxCommandEvent& event); + + /** + Saves the current document by calling wxDocument::Save() for the + current document. + */ + void OnFileSave(wxCommandEvent& event); + + /** + Calls wxDocument::SaveAs() for the current document. + */ + void OnFileSaveAs(wxCommandEvent& event); + + /** + Removes the document from the list of documents. + */ + void RemoveDocument(wxDocument* doc); + + /** + Under Windows, pops up a file selector with a list of filters + corresponding to document templates. The wxDocTemplate corresponding to + the selected file's extension is returned. + + On other platforms, if there is more than one document template a + choice list is popped up, followed by a file selector. + + This function is used in CreateDocument(). + */ + wxDocTemplate* SelectDocumentPath(wxDocTemplate** templates, + int noTemplates, wxString& path, + long flags, bool save); + + /** + Returns a document template by asking the user (if there is more than + one template). This function is used in CreateDocument(). + + @param templates + Pointer to an array of templates from which to choose a desired + template. + @param noTemplates + Number of templates being pointed to by the templates pointer. + @param sort + If more than one template is passed in in templates, then this + parameter indicates whether the list of templates that the user + will have to choose from is sorted or not when shown the choice box + dialog. Default is @false. + */ + wxDocTemplate* SelectDocumentType(wxDocTemplate** templates, + int noTemplates, bool sort = false); + + /** + Returns a document template by asking the user (if there is more than + one template), displaying a list of valid views. This function is used + in CreateView(). The dialog normally will not appear because the array + of templates only contains those relevant to the document in question, + and often there will only be one such. + + @param templates + Pointer to an array of templates from which to choose a desired + template. + @param noTemplates + Number of templates being pointed to by the templates pointer. + @param sort + If more than one template is passed in in templates, then this + parameter indicates whether the list of templates that the user + will have to choose from is sorted or not when shown the choice box + dialog. Default is @false. + */ + wxDocTemplate* SelectViewType(wxDocTemplate** templates, + int noTemplates, bool sort = false); + + /** + Sets the directory to be displayed to the user when opening a file. + Initially this is empty. + */ + void SetLastDirectory(const wxString& dir); + + /** + Sets the maximum number of documents that can be open at a time. By + default, this is 10,000. If you set it to 1, existing documents will be + saved and deleted when the user tries to open or create a new one + (similar to the behaviour of Windows Write, for example). Allowing + multiple documents gives behaviour more akin to MS Word and other + Multiple Document Interface applications. + */ + void SetMaxDocsOpen(int n); + + /** + The currently active view. + */ + wxView* m_currentView; + + /** + Stores the integer to be used for the next default document name. + */ + int m_defaultDocumentNameCounter; + + /** + A list of all documents. + */ + wxList m_docs; + + /** + A pointer to an instance of wxFileHistory, which manages the history of + recently-visited files on the File menu. + */ + wxFileHistory* m_fileHistory; + + /** + Stores the flags passed to the constructor. + */ + long m_flags; + + /** + The directory last selected by the user when opening a file. + */ + wxFileHistory* m_fileHistory; + + /** + Stores the maximum number of documents that can be opened before + existing documents are closed. By default, this is 10,000. + */ + int m_maxDocsOpen; +}; + + + +/** + @class wxView + @wxheader{docview.h} + + The view class can be used to model the viewing and editing component of + an application's file-based data. It is part of the document/view framework + supported by wxWidgets, and cooperates with the wxDocument, wxDocTemplate + and wxDocManager classes. + + @library{wxcore} + @category{docview} + + @see @ref overview_docview_wxview, wxDocument, wxDocTemplate, wxDocManager +*/ +class wxView : public wxEvtHandler +{ +public: + /** + Constructor. Define your own default constructor to initialize + application-specific data. + */ + wxView(); + + /** + Destructor. Removes itself from the document's list of views. + */ + ~wxView(); + + /** + Call this from your view frame's wxDocChildFrame::OnActivate() member + to tell the framework which view is currently active. If your windowing + system doesn't call wxDocChildFrame::OnActivate(), you may need to call + this function from any place where you know the view must be active, + and the framework will need to get the current view. + + The prepackaged view frame wxDocChildFrame calls Activate() from its + wxDocChildFrame::OnActivate() member. + + This function calls OnActivateView(). + */ + virtual void Activate(bool activate); + + /** + Closes the view by calling OnClose(). If @a deleteWindow is @true, this + function should delete the window associated with the view. + */ + virtual bool Close(bool deleteWindow = true); + + /** + Gets a pointer to the document associated with the view. + */ + wxDocument* GetDocument() const; + + /** + Returns a pointer to the document manager instance associated with this + view. + */ + wxDocManager* GetDocumentManager() const; + + /** + Gets the frame associated with the view (if any). Note that this + "frame" is not a wxFrame at all in the generic MDI implementation which + uses notebook pages instead of frames and this is why this method + returns a wxWindow and not a wxFrame. + */ + wxWindow* GetFrame(); + + /** + Gets the name associated with the view (passed to the wxDocTemplate + constructor). Not currently used by the framework. + */ + wxString GetViewName() const; + + /** + Called when a view is activated by means of Activate(). The default + implementation does nothing. + */ + virtual void OnActivateView(bool activate, wxView* activeView, + wxView* deactiveView); + + /** + Called when the filename has changed. The default implementation + constructs a suitable title and sets the title of the view frame (if + any). + */ + virtual void OnChangeFilename(); + + /** + Implements closing behaviour. The default implementation calls + wxDocument::Close() to close the associated document. Does not delete + the view. The application may wish to do some cleaning up operations in + this function, @e if a call to wxDocument::Close() succeeded. For + example, if your views all share the same window, you need to + disassociate the window from the view and perhaps clear the window. If + @a deleteWindow is @true, delete the frame associated with the view. + */ + virtual bool OnClose(bool deleteWindow); + + /** + Override this to clean up the view when the document is being closed. + */ + virtual void OnClosingDocument(); + + /** + wxDocManager or wxDocument creates a wxView via a wxDocTemplate. Just + after the wxDocTemplate creates the wxView, it calls OnCreate(). The + wxView can create a wxDocChildFrame (or derived class) in its + wxView::OnCreate() member function. This wxDocChildFrame provides user + interface elements to view and/or edit the contents of the wxDocument. + + By default, simply returns @true. If the function returns @false, the + view will be deleted. + */ + virtual bool OnCreate(wxDocument* doc, long flags); + + /** + If the printing framework is enabled in the library, this function + returns a wxPrintout object for the purposes of printing. It should + create a new object every time it is called; the framework will delete + objects it creates. + + By default, this function returns an instance of wxDocPrintout, which + prints and previews one page by calling OnDraw(). + + Override to return an instance of a class other than wxDocPrintout. + */ + virtual wxPrintout* OnCreatePrintout(); + + /** + Override this function to render the view on the given device context. + */ + virtual void OnDraw(wxDC* dc); + + /** + Called when the view should be updated. + + @param sender + A pointer to the wxView that sent the update request, or @NULL if + no single view requested the update (for instance, when the + document is opened). + @param hint + This is unused currently, but may in future contain + application-specific information for making updating more + efficient. + */ + virtual void OnUpdate(wxView* sender, wxObject* hint); + + /** + Associates the given document with the view. Normally called by the + framework. + */ + void SetDocument(wxDocument* doc); + + /** + Sets the frame associated with this view. The application should call + this if possible, to tell the view about the frame. + + See GetFrame() for the explanation about the mismatch between the + "Frame" in the method name and the type of its parameter. + */ + void SetFrame(wxWindow* frame); + + /** + Sets the view type name. Should only be called by the framework. + */ + void SetViewName(const wxString& name); + + /** + The document associated with this view. There may be more than one view + per document, but there can never be more than one document for one + view. + */ + wxDocument* m_viewDocument; + + /** + Frame associated with the view, if any. + */ + wxFrame* m_viewFrame; + + /** + The view type name given to the wxDocTemplate constructor, copied to + this variable when the view is created. Not currently used by the + framework. + */ + wxString m_viewTypeName; +}; + + + +/** + @class wxDocChildFrame + @wxheader{docview.h} + + The wxDocChildFrame class provides a default frame for displaying documents + on separate windows. This class can only be used for SDI (not MDI) child + frames. + + The class is part of the document/view framework supported by wxWidgets, + and cooperates with the wxView, wxDocument, wxDocManager and wxDocTemplate + classes. + + @library{wxcore} + @category{docview} + + @see @ref overview_docview, @ref page_samples_docview, wxFrame +*/ +class wxDocChildFrame : public wxFrame +{ +public: + /** + Constructor. + */ + wxDocChildFrame(wxDocument* doc, wxView* view, wxFrame* parent, + wxWindowID id, const wxString& title, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxDEFAULT_FRAME_STYLE, + const wxString& name = "frame"); + + /** + Destructor. + */ + ~wxDocChildFrame(); + + /** + Returns the document associated with this frame. + */ + wxDocument* GetDocument() const; + + /** + Returns the view associated with this frame. + */ + wxView* GetView() const; + + /** + Sets the currently active view to be the frame's view. You may need to + override (but still call) this function in order to set the keyboard + focus for your subwindow. + */ + void OnActivate(wxActivateEvent event); + + /** + Closes and deletes the current view and document. + */ + void OnCloseWindow(wxCloseEvent& event); + + /** + Sets the document for this frame. + */ + void SetDocument(wxDocument* doc); + + /** + Sets the view for this frame. + */ + void SetView(wxView* view); + + /** + The document associated with the frame. + */ + wxDocument* m_childDocument; + + /** + The view associated with the frame. + */ + wxView* m_childView; +}; + + + +/** + @class wxDocParentFrame + @wxheader{docview.h} + + The wxDocParentFrame class provides a default top-level frame for + applications using the document/view framework. This class can only be used + for SDI (not MDI) parent frames. + + It cooperates with the wxView, wxDocument, wxDocManager and wxDocTemplate + classes. + + @library{wxcore} + @category{docview} + + @see @ref overview_docview, @ref page_samples_docview, wxFrame +*/ +class wxDocParentFrame : public wxFrame +{ +public: + /** + Default constructor. + */ + wxDocParentFrame(); + /** + Constructor. + */ + wxDocParentFrame(wxDocManager* manager, wxFrame* parent, + wxWindowID id, const wxString& title, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxDEFAULT_FRAME_STYLE, + const wxString& name = "frame"); + + /** + Destructor. + */ + ~wxDocParentFrame(); + + /** + Used in two-step construction. + */ + bool Create(wxDocManager* manager, wxFrame* parent, + wxWindowID id, const wxString& title, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxDEFAULT_FRAME_STYLE, + const wxString& name = "frame"); + + /** + Returns the associated document manager object. + */ + wxDocManager* GetDocumentManager() const; + + /** + Deletes all views and documents. If no user input cancelled the + operation, the frame will be destroyed and the application will exit. + Since understanding how document/view clean-up takes place can be + difficult, the implementation of this function is shown below: + + @code + void wxDocParentFrame::OnCloseWindow(wxCloseEvent& event) + { + if (m_docManager->Clear(!event.CanVeto())) + { + this->Destroy(); + } + else + event.Veto(); + } + @endcode + */ + void OnCloseWindow(wxCloseEvent& event); +}; + + + +/** + @class wxDocument + @wxheader{docview.h} + + The document class can be used to model an application's file-based data. + It is part of the document/view framework supported by wxWidgets, and + cooperates with the wxView, wxDocTemplate and wxDocManager classes. + + @library{wxcore} + @category{docview} + + @see @ref overview_docview, wxView, wxDocTemplate, wxDocManager +*/ +class wxDocument : public wxEvtHandler +{ +public: + /** + Constructor. Define your own default constructor to initialize + application-specific data. + */ + wxDocument(); + + /** + Destructor. Removes itself from the document manager. + */ + ~wxDocument(); + + /** + If the view is not already in the list of views, adds the view and + calls OnChangedViewList(). + */ + virtual bool AddView(wxView* view); + + /** + Closes the document, by calling OnSaveModified() and then (if this + returned @true) OnCloseDocument(). This does not normally delete the + document object, use DeleteAllViews() to do this implicitly. + */ + virtual bool Close(); + + /** + Calls wxView::Close() and deletes each view. Deleting the final view + will implicitly delete the document itself, because the wxView + destructor calls RemoveView(). This in turns calls OnChangedViewList(), + whose default implemention is to save and delete the document if no + views exist. + */ + virtual bool DeleteAllViews(); + + /** + Returns a pointer to the command processor associated with this + document. + + @see wxCommandProcessor + */ + wxCommandProcessor* GetCommandProcessor() const; + + /** + Gets a pointer to the associated document manager. + */ + wxDocManager* GetDocumentManager() const; + + /** + Gets the document type name for this document. See the comment for + @ref m_documentTypeName. + */ + wxString GetDocumentName() const; + + /** + Gets a pointer to the template that created the document. + */ + wxDocTemplate* GetDocumentTemplate() const; + + /** + Intended to return a suitable window for using as a parent for + document-related dialog boxes. By default, uses the frame associated + with the first view. + */ + wxWindow* GetDocumentWindow() const; + + /** + Gets the filename associated with this document, or "" if none is + associated. + */ + wxString GetFilename() const; + + /** + A convenience function to get the first view for a document, because in + many cases a document will only have a single view. + + @see GetViews() + */ + wxView* GetFirstView() const; + + /** + Gets the title for this document. The document title is used for an + associated frame (if any), and is usually constructed by the framework + from the filename. + */ + wxString GetTitle() const; + + /** + Return the document name suitable to be shown to the user. The default + implementation uses the document title, if any, of the name part of the + document filename if it was set or, otherwise, the string @b unnamed. + */ + virtual wxString GetUserReadableName() const; + + /** + Returns the list whose elements are the views on the document. + + @see GetFirstView() + */ + wxList GetViews() const; + + /** + Returns @true if the document has been modified since the last save, + @false otherwise. You may need to override this if your document view + maintains its own record of being modified. + + @see Modify() + */ + virtual bool IsModified() const; + + //@{ + /** + Override this function and call it from your own LoadObject() before + streaming your own data. LoadObject() is called by the framework + automatically when the document contents need to be loaded. + + @note This version of LoadObject() may not exist depending on how + wxWidgets was configured. + */ + virtual istream& LoadObject(istream& stream); + virtual wxInputStream& LoadObject(wxInputStream& stream); + //@} + + /** + Call with @true to mark the document as modified since the last save, + @false otherwise. You may need to override this if your document view + maintains its own record of being modified. + + @see IsModified() + */ + virtual void Modify(bool modify); + + /** + Called when a view is added to or deleted from this document. The + default implementation saves and deletes the document if no views exist + (the last one has just been removed). + */ + virtual void OnChangedViewList(); + + /** + The default implementation calls DeleteContents() (an empty + implementation) and sets the modified flag to @false. Override this to + supply additional behaviour when the document is closed with Close(). + */ + virtual bool OnCloseDocument(); + + /** + Called just after the document object is created to give it a chance to + initialize itself. The default implementation uses the template + associated with the document to create an initial view. If this + function returns @false, the document is deleted. + */ + virtual bool OnCreate(const wxString& path, long flags); + + /** + Override this function if you want a different (or no) command + processor to be created when the document is created. By default, it + returns an instance of wxCommandProcessor. + + @see wxCommandProcessor + */ + virtual wxCommandProcessor* OnCreateCommandProcessor(); + + /** + The default implementation calls OnSaveModified() and DeleteContents(), + makes a default title for the document, and notifies the views that the + filename (in fact, the title) has changed. + */ + virtual bool OnNewDocument(); + + /** + Constructs an input file stream for the given filename (which must not + be empty), and calls LoadObject(). If LoadObject() returns @true, the + document is set to unmodified; otherwise, an error message box is + displayed. The document's views are notified that the filename has + changed, to give windows an opportunity to update their titles. All of + the document's views are then updated. + */ + virtual bool OnOpenDocument(const wxString& filename); + + /** + Constructs an output file stream for the given filename (which must not + be empty), and calls SaveObject(). If SaveObject() returns @true, the + document is set to unmodified; otherwise, an error message box is + displayed. + */ + virtual bool OnSaveDocument(const wxString& filename); + + /** + If the document has been modified, prompts the user to ask if the + changes should be changed. If the user replies Yes, the Save() function + is called. If No, the document is marked as unmodified and the function + succeeds. If Cancel, the function fails. + */ + virtual bool OnSaveModified(); + + /** + Removes the view from the document's list of views, and calls + OnChangedViewList(). + */ + virtual bool RemoveView(wxView* view); + + /** + Saves the document by calling OnSaveDocument() if there is an + associated filename, or SaveAs() if there is no filename. + */ + virtual bool Save(); + + /** + Prompts the user for a file to save to, and then calls + OnSaveDocument(). + */ + virtual bool SaveAs(); + + //@{ + /** + Override this function and call it from your own SaveObject() before + streaming your own data. SaveObject() is called by the framework + automatically when the document contents need to be saved. + + @note This version of SaveObject() may not exist depending on how + wxWidgets was configured. + */ + virtual ostream& SaveObject(ostream& stream); + virtual wxOutputStream& SaveObject(wxOutputStream& stream); + //@} + + /** + Sets the command processor to be used for this document. The document + will then be responsible for its deletion. Normally you should not call + this; override OnCreateCommandProcessor() instead. + + @see wxCommandProcessor + */ + virtual void SetCommandProcessor(wxCommandProcessor* processor); + + /** + Sets the document type name for this document. See the comment for + @ref m_documentTypeName. + */ + void SetDocumentName(const wxString& name); + + /** + Sets the pointer to the template that created the document. Should only + be called by the framework. + */ + void SetDocumentTemplate(wxDocTemplate* templ); + + /** + Sets the filename for this document. Usually called by the framework. + + If @a notifyViews is @true, wxView::OnChangeFilename() is called for + all views. + */ + void SetFilename(const wxString& filename, bool notifyViews = false); + + /** + Sets the title for this document. The document title is used for an + associated frame (if any), and is usually constructed by the framework + from the filename. + */ + void SetTitle(const wxString& title); + + /** + Updates all views. If @a sender is non-@NULL, does not update this + view. @a hint represents optional information to allow a view to + optimize its update. + */ + void UpdateAllViews(wxView* sender = NULL, wxObject* hint = NULL); + +protected: + /** + This method is called by OnSaveDocument() to really save the document + contents to the specified file. + + Base class version creates a file-based stream and calls SaveObject(). + Override this if you need to do something else or prefer not to use + SaveObject() at all. + */ + virtual bool DoSaveDocument(const wxString& file); + + /** + This method is called by OnOpenDocument() to really load the document + contents from the specified file. + + Base class version creates a file-based stream and calls LoadObject(). + Override this if you need to do something else or prefer not to use + LoadObject() at all. + */ + virtual bool DoOpenDocument(const wxString& file); + + /** + A pointer to the command processor associated with this document. + */ + wxCommandProcessor* m_commandProcessor; + + /** + Filename associated with this document ("" if none). + */ + wxString m_documentFile; + + /** + @true if the document has been modified, @false otherwise. + */ + bool m_documentModified; + + /** + A pointer to the template from which this document was created. + */ + wxDocTemplate* m_documentTemplate; + + /** + Document title. The document title is used for an associated frame (if + any), and is usually constructed by the framework from the filename. + */ + wxString m_documentTitle; + + /** + The document type name given to the wxDocTemplate constructor, copied + to this variable when the document is created. If several document + templates are created that use the same document type, this variable is + used in wxDocManager::CreateView() to collate a list of alternative + view types that can be used on this kind of document. Do not change the + value of this variable. + */ + wxString m_documentTypeName; + + /** + List of wxView instances associated with this document. + */ + wxList m_documentViews; +}; + + + +/** + @class wxFileHistory + @wxheader{docview.h} + + The wxFileHistory encapsulates a user interface convenience, the list of + most recently visited files as shown on a menu (usually the File menu). + + wxFileHistory can manage one or more file menus. More than one menu may be + required in an MDI application, where the file history should appear on + each MDI child menu as well as the MDI parent frame. + + @library{wxcore} + @category{docview} + + @see @ref overview_docview, wxDocManager +*/ +class wxFileHistory : public wxObject +{ +public: + /** + Constructor. Pass the maximum number of files that should be stored and + displayed. + + @a idBase defaults to wxID_FILE1 and represents the id given to the + first history menu item. Since menu items can't share the same ID you + should change @a idBase (to one of your own defined IDs) when using + more than one wxFileHistory in your application. + */ + wxFileHistory(size_t maxFiles = 9, wxWindowID idBase = wxID_FILE1); + + /** + Destructor. + */ + ~wxFileHistory(); + + /** + Adds a file to the file history list, if the object has a pointer to an + appropriate file menu. + */ + void AddFileToHistory(const wxString& filename); + + /** + Appends the files in the history list, to all menus managed by the file + history object. + */ + void AddFilesToMenu(); + /** + Appends the files in the history list, to the given menu only. + */ + void AddFilesToMenu(wxMenu* menu); + + /** + Returns the base identifier for the range used for appending items. + */ + wxWindowID GetBaseId() const; + + /** + Returns the number of files currently stored in the file history. + */ + size_t GetCount() const; + + /** + Returns the file at this index (zero-based). + */ + wxString GetHistoryFile(size_t index) const; + + /** + Returns the maximum number of files that can be stored. + */ + int GetMaxFiles() const; + + /** + Returns the list of menus that are managed by this file history object. + + @see UseMenu() + */ + const wxList& GetMenus() const; + + /** + Loads the file history from the given config object. This function + should be called explicitly by the application. + + @see wxConfigBase + */ + void Load(const wxConfigBase& config); + + /** + Removes the specified file from the history. + */ + void RemoveFileFromHistory(size_t i); + + /** + Removes this menu from the list of those managed by this object. + */ + void RemoveMenu(wxMenu* menu); + + /** + Saves the file history into the given config object. This must be + called explicitly by the application. + + @see wxConfigBase + */ + void Save(wxConfigBase& config); + + /** + Sets the base identifier for the range used for appending items. + */ + void SetBaseId(wxWindowID baseId); + + /** + Adds this menu to the list of those menus that are managed by this file + history object. Also see AddFilesToMenu() for initializing the menu + with filenames that are already in the history when this function is + called, as this is not done automatically. + */ + void UseMenu(wxMenu* menu); + + /** + A character array of strings corresponding to the most recently opened + files. + */ + char** m_fileHistory; + + /** + The number of files stored in the history array. + */ + size_t m_fileHistoryN; + + /** + The maximum number of files to be stored and displayed on the menu. + */ + size_t m_fileMaxFiles; + + /** + The file menu used to display the file history list (if enabled). + */ + wxMenu* m_fileMenu; +}; + + + +// ============================================================================ +// Global functions/macros +// ============================================================================ + +/** @ingroup group_funcmacro_file */ +//@{ + +/** + Copies the given file to @a stream. Useful when converting an old + application to use streams (within the document/view framework, for + example). + + @header{wx/docview.h} +*/ +bool wxTransferFileToStream(const wxString& filename, + ostream& stream); + +/** + Copies the given stream to the file @a filename. Useful when converting an + old application to use streams (within the document/view framework, for + example). + + @header{wx/docview.h} +*/ +bool wxTransferStreamToFile(istream& stream, + const wxString& filename); + +//@} + diff --git a/interface/wx/dragimag.h b/interface/wx/dragimag.h new file mode 100644 index 0000000000..9de1317021 --- /dev/null +++ b/interface/wx/dragimag.h @@ -0,0 +1,262 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: dragimag.h +// Purpose: interface of wxDragImage +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxDragImage + @wxheader{dragimag.h} + + This class is used when you wish to drag an object on the screen, and a + simple cursor is not enough. + + On Windows, the Win32 API is used to achieve smooth dragging. On other + platforms, wxGenericDragImage is used. Applications may also prefer to use + wxGenericDragImage on Windows, too. + + @beginWxPythonOnly + wxPython uses wxGenericDragImage on all platforms, but uses the wxDragImage + name. + @endWxPythonOnly + + To use this class, when you wish to start dragging an image, create a + wxDragImage object and store it somewhere you can access it as the drag + progresses. Call BeginDrag() to start, and EndDrag() to stop the drag. To + move the image, initially call Show() and then Move(). If you wish to + update the screen contents during the drag (for example, highlight an item + as in the dragimag sample), first call Hide(), update the screen, call + Move(), and then call Show(). + + You can drag within one window, or you can use full-screen dragging either + across the whole screen, or just restricted to one area of the screen to + save resources. If you want the user to drag between two windows, then you + will need to use full-screen dragging. + + If you wish to draw the image yourself, use wxGenericDragImage and override + DoDrawImage() and GetImageRect(). + + @library{wxcore} + @category{dnd} + + @see @ref page_samples_dragimag +*/ +class wxDragImage : public wxObject +{ +public: + /** + Default constructor. + */ + wxDragImage(); + /** + Constructs a drag image from a bitmap and optional cursor. + + @param image + Bitmap to be used as the drag image. The bitmap can have a mask. + @param cursor + Optional cursor to combine with the image. + @param cursorHotspot + This parameter is deprecated. + */ + wxDragImage(const wxBitmap& image, const wxCursor& cursor = wxNullCursor, + const wxPoint& cursorHotspot = wxPoint(0, 0)); + /** + Constructs a drag image from an icon and optional cursor. + + @param image + Icon to be used as the drag image. + @param cursor + Optional cursor to combine with the image. + @param cursorHotspot + This parameter is deprecated. + + @beginWxPythonOnly + This constructor is called wxDragIcon in wxPython. + @endWxPythonOnly + */ + wxDragImage(const wxIcon& image, const wxCursor& cursor = wxNullCursor, + const wxPoint& cursorHotspot = wxPoint(0, 0)); + /** + Constructs a drag image from a text string and optional cursor. + + @param text + Text used to construct a drag image. + @param cursor + Optional cursor to combine with the image. + @param cursorHotspot + This parameter is deprecated. + + @beginWxPythonOnly + This constructor is called wxDragString in wxPython. + @endWxPythonOnly + */ + wxDragImage(const wxString& text, const wxCursor& cursor = wxNullCursor, + const wxPoint& cursorHotspot = wxPoint(0, 0)); + /** + Constructs a drag image from the text in the given tree control item, + and optional cursor. + + @param treeCtrl + Tree control for constructing a tree drag image. + @param id + Tree control item id. + + @beginWxPythonOnly + This constructor is called wxDragTreeItem in wxPython. + @endWxPythonOnly + */ + wxDragImage(const wxTreeCtrl& treeCtrl, wxTreeItemId& id); + /** + Constructs a drag image from the text in the given list control item, + and optional cursor. + + @param listCtrl + List control for constructing a list drag image. + @param id + List control item id. + + @beginWxPythonOnly + This constructor is called wxDragListItem in wxPython. + @endWxPythonOnly + */ + wxDragImage(const wxListCtrl& listCtrl, long id); + /** + Constructs a drag image an optional cursor. This constructor is only + available for wxGenericDragImage, and can be used when the application + supplies DoDrawImage() and GetImageRect(). + + @param cursor + Optional cursor to combine with the image. + @param cursorHotspot + This parameter is deprecated. + */ + wxDragImage(const wxCursor& cursor = wxNullCursor, + const wxPoint& cursorHotspot = wxPoint(0, 0)); + + /** + Start dragging the image, in a window or full screen. + + You need to then call Show() and Move() to show the image on the + screen. Call EndDrag() when the drag has finished. + + Note that this call automatically calls CaptureMouse(). + + @param hotspot + The location of the drag position relative to the upper-left corner + of the image. + @param window + The window that captures the mouse, and within which the dragging + is limited unless fullScreen is @true. + @param fullScreen + If @true, specifies that the drag will be visible over the full + screen, or over as much of the screen as is specified by rect. Note + that the mouse will still be captured in window. + @param rect + If non-@NULL, specifies the rectangle (in screen coordinates) that + bounds the dragging operation. Specifying this can make the + operation more efficient by cutting down on the area under + consideration, and it can also make a visual difference since the + drag is clipped to this area. + */ + bool BeginDrag(const wxPoint& hotspot, wxWindow* window, + bool fullScreen = false, wxRect* rect = NULL); + /** + Start dragging the image, using the first window to capture the mouse + and the second to specify the bounding area. This form is equivalent to + using the first form, but more convenient than working out the bounding + rectangle explicitly. + + You need to then call Show() and Move() to show the image on the + screen. Call EndDrag() when the drag has finished. + + Note that this call automatically calls CaptureMouse(). + + @param hotspot + The location of the drag position relative to the upper-left corner + of the image. + @param window + The window that captures the mouse, and within which the dragging + is limited. + @param boundingWindow + Specifies the area within which the drag occurs. + */ + bool BeginDrag(const wxPoint& hotspot, wxWindow* window, + wxWindow* boundingWindow); + + /** + Draws the image on the device context with top-left corner at the given + position. + + This function is only available with wxGenericDragImage, to allow + applications to draw their own image instead of using an actual bitmap. + If you override this function, you must also override GetImageRect(). + */ + virtual bool DoDrawImage(wxDC& dc, const wxPoint& pos); + + /** + Call this when the drag has finished. + + @note This function automatically releases mouse capture. + */ + bool EndDrag(); + + /** + Returns the rectangle enclosing the image, assuming that the image is + drawn with its top-left corner at the given point. + + This function is available in wxGenericDragImage only, and may be + overridden (together with DoDrawImage()) to provide a virtual drawing + capability. + */ + virtual wxRect GetImageRect(const wxPoint& pos) const; + + /** + Hides the image. You may wish to call this before updating the window + contents (perhaps highlighting an item). Then call Move() and Show(). + */ + bool Hide(); + + /** + Call this to move the image to a new position. The image will only be + shown if Show() has been called previously (for example at the start of + the drag). + + @param pt + The position in client coordinates (relative to the window + specified in BeginDrag()). + + You can move the image either when the image is hidden or shown, but in + general dragging will be smoother if you move the image when it is + shown. + */ + bool Move(const wxPoint& pt); + + /** + Shows the image. Call this at least once when dragging. + */ + bool Show(); + + /** + Override this if you wish to draw the window contents to the backing + bitmap yourself. This can be desirable if you wish to avoid flicker by + not having to redraw the updated window itself just before dragging, + which can cause a flicker just as the drag starts. Instead, paint the + drag image's backing bitmap to show the appropriate graphic @e minus + the objects to be dragged, and leave the window itself to be updated by + the drag image. This can provide eerily smooth, flicker-free drag + behaviour. + + The default implementation copies the window contents to the backing + bitmap. A new implementation will normally copy information from + another source, such as from its own backing bitmap if it has one, or + directly from internal data structures. + + This function is available in wxGenericDragImage only. + */ + bool UpdateBackingFromWindow(wxDC& windowDC, wxMemoryDC& destDC, + const wxRect& sourceRect, + const wxRect& destRect) const; +}; + diff --git a/interface/wx/dynarray.h b/interface/wx/dynarray.h new file mode 100644 index 0000000000..d5d16b352c --- /dev/null +++ b/interface/wx/dynarray.h @@ -0,0 +1,772 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: dynarray.h +// Purpose: interface of wxArray +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @wxheader{dynarray.h} + + This section describes the so called @e "dynamic arrays". This is a C + array-like type safe data structure i.e. the member access time is constant + (and not linear according to the number of container elements as for linked + lists). However, these arrays are dynamic in the sense that they will + automatically allocate more memory if there is not enough of it for adding + a new element. They also perform range checking on the index values but in + debug mode only, so please be sure to compile your application in debug + mode to use it (see @ref overview_debugging for details). So, unlike the + arrays in some other languages, attempt to access an element beyond the + arrays bound doesn't automatically expand the array but provokes an + assertion failure instead in debug build and does nothing (except possibly + crashing your program) in the release build. + + The array classes were designed to be reasonably efficient, both in terms + of run-time speed and memory consumption and the executable size. The speed + of array item access is, of course, constant (independent of the number of + elements) making them much more efficient than linked lists (wxList). + Adding items to the arrays is also implemented in more or less constant + time, but the price is preallocating the memory in advance. In the + "memory management" function section, you may find some useful hints about + optimizing wxArray memory usage. As for executable size, all wxArray + functions are inline, so they do not take @e any space at all. + + wxWidgets has three different kinds of array. All of them derive from + wxBaseArray class which works with untyped data and can not be used + directly. The standard macros WX_DEFINE_ARRAY(), WX_DEFINE_SORTED_ARRAY() + and WX_DEFINE_OBJARRAY() are used to define a new class deriving from it. + The classes declared will be called in this documentation wxArray, + wxSortedArray and wxObjArray but you should keep in mind that no classes + with such names actually exist, each time you use one of the + WX_DEFINE_XXXARRAY() macros, you define a class with a new name. In fact, + these names are "template" names and each usage of one of the macros + mentioned above creates a template specialization for the given element + type. + + wxArray is suitable for storing integer types and pointers which it does + not treat as objects in any way, i.e. the element pointed to by the pointer + is not deleted when the element is removed from the array. It should be + noted that all of wxArray's functions are inline, so it costs strictly + nothing to define as many array types as you want (either in terms of the + executable size or the speed) as long as at least one of them is defined + and this is always the case because wxArrays are used by wxWidgets + internally. This class has one serious limitation: it can only be used for + storing integral types (bool, char, short, int, long and their unsigned + variants) or pointers (of any kind). An attempt to use with objects of + @c sizeof() greater than @c sizeof(long) will provoke a runtime assertion + failure, however declaring a wxArray of floats will not (on the machines + where @c "sizeof(float) <= sizeof(long)"), yet it will @b not work, please + use wxObjArray for storing floats and doubles. + + wxSortedArray is a wxArray variant which should be used when searching in + the array is a frequently used operation. It requires you to define an + additional function for comparing two elements of the array element type + and always stores its items in the sorted order (according to this + function). Thus, its Index() function execution time is @c "O(log(N))" + instead of @c "O(N)" for the usual arrays but the Add() method is slower: + it is @c "O(log(N))" instead of constant time (neglecting time spent in + memory allocation routine). However, in a usual situation elements are + added to an array much less often than searched inside it, so wxSortedArray + may lead to huge performance improvements compared to wxArray. Finally, it + should be noticed that, as wxArray, wxSortedArray can be only used for + storing integral types or pointers. + + wxObjArray class treats its elements like "objects". It may delete them + when they are removed from the array (invoking the correct destructor) and + copies them using the objects copy constructor. In order to implement this + behaviour the definition of the wxObjArray arrays is split in two parts: + first, you should declare the new wxObjArray class using the + WX_DECLARE_OBJARRAY() macro and then you must include the file defining the + implementation of template type: @ and define the array + class with the WX_DEFINE_OBJARRAY() macro from a point where the full (as + opposed to 'forward') declaration of the array elements class is in scope. + As it probably sounds very complicated here is an example: + + @code + #include + + // We must forward declare the array because it is used + // inside the class declaration. + class MyDirectory; + class MyFile; + + // This defines two new types: ArrayOfDirectories and ArrayOfFiles which + // can be now used as shown below. + WX_DECLARE_OBJARRAY(MyDirectory, ArrayOfDirectories); + WX_DECLARE_OBJARRAY(MyFile, ArrayOfFiles); + + class MyDirectory + { + // ... + ArrayOfDirectories m_subdirectories; // All subdirectories + ArrayOfFiles m_files; // All files in this directory + }; + + // ... + + // Now that we have MyDirectory declaration in scope we may finish the + // definition of ArrayOfDirectories -- note that this expands into some C++ + // code and so should only be compiled once (i.e., don't put this in the + // header, but into a source file or you will get linking errors) + #include // This is a magic incantation which must be done! + WX_DEFINE_OBJARRAY(ArrayOfDirectories); + + // that's all! + @endcode + + It is not as elegant as writing this: + + @code + typedef std::vector ArrayOfDirectories; + @endcode + + But is not that complicated and allows the code to be compiled with any, + however dumb, C++ compiler in the world. + + Remember to include @ just before each + WX_DEFINE_OBJARRAY() ocurrence in your code, even if you have several in + the same file. + + Things are much simpler for wxArray and wxSortedArray however: it is enough + just to write: + + @code + WX_DEFINE_ARRAY_INT(int, ArrayOfInts); + WX_DEFINE_SORTED_ARRAY_INT(int, ArrayOfSortedInts); + @endcode + + There is only one @c DEFINE macro and no need for separate @c DECLARE one. + For the arrays of the primitive types, the macros + @c WX_DEFINE_ARRAY_CHAR/SHORT/INT/SIZE_T/LONG/DOUBLE should be used + depending on the sizeof of the values (notice that storing values of + smaller type, e.g. shorts, in an array of larger one, e.g. @c ARRAY_INT, + does not work on all architectures!). + + + @section array_macros Macros for Template Array Definition + + To use an array you must first define the array class. This is done with + the help of the macros in this section. The class of array elements must be + (at least) forward declared for WX_DEFINE_ARRAY(), WX_DEFINE_SORTED_ARRAY() + and WX_DECLARE_OBJARRAY() macros and must be fully declared before you use + WX_DEFINE_OBJARRAY() macro. + + - WX_DEFINE_ARRAY() + - WX_DEFINE_EXPORTED_ARRAY() + - WX_DEFINE_USER_EXPORTED_ARRAY() + - WX_DEFINE_SORTED_ARRAY() + - WX_DEFINE_SORTED_EXPORTED_ARRAY() + - WX_DEFINE_SORTED_USER_EXPORTED_ARRAY() + - WX_DECLARE_EXPORTED_OBJARRAY() + - WX_DECLARE_USER_EXPORTED_OBJARRAY() + - WX_DEFINE_OBJARRAY() + - WX_DEFINE_EXPORTED_OBJARRAY() + - WX_DEFINE_USER_EXPORTED_OBJARRAY() + + To slightly complicate the matters even further, the operator "->" defined + by default for the array iterators by these macros only makes sense if the + array element type is not a pointer itself and, although it still works, + this provokes warnings from some compilers and to avoid them you should use + the @c _PTR versions of the macros above. For example, to define an array + of pointers to @c double you should use: + + @code + WX_DEFINE_ARRAY_PTR(double *, MyArrayOfDoublePointers); + @endcode + + Note that the above macros are generally only useful for wxObject types. + There are separate macros for declaring an array of a simple type, such as + an int. + + The following simple types are supported: + - @c int + - @c long + - @c size_t + - @c double + + To create an array of a simple type, simply append the type you want in + CAPS to the array definition. + + For example, you'd use one of the following variants for an integer array: + + - WX_DEFINE_ARRAY_INT() + - WX_DEFINE_EXPORTED_ARRAY_INT() + - WX_DEFINE_USER_EXPORTED_ARRAY_INT() + - WX_DEFINE_SORTED_ARRAY_INT() + - WX_DEFINE_SORTED_EXPORTED_ARRAY_INT() + - WX_DEFINE_SORTED_USER_EXPORTED_ARRAY_INT() + + + @library{wxbase} + @category{containers} + + @see @ref overview_container, wxList, wxVector +*/ +class wxArray +{ +public: + /** + @name Constructors and Destructors + + Array classes are 100% C++ objects and as such they have the + appropriate copy constructors and assignment operators. Copying wxArray + just copies the elements but copying wxObjArray copies the arrays + items. However, for memory-efficiency sake, neither of these classes + has virtual destructor. It is not very important for wxArray which has + trivial destructor anyhow, but it does mean that you should avoid + deleting wxObjArray through a wxBaseArray pointer (as you would never + use wxBaseArray anyhow it shouldn't be a problem) and that you should + not derive your own classes from the array classes. + */ + //@{ + + /** + Default constructor. + */ + wxArray(); + /** + Default constructor initializes an empty array object. + */ + wxObjArray(); + /** + There is no default constructor for wxSortedArray classes - you must + initialize it with a function to use for item comparison. It is a + function which is passed two arguments of type @c T where @c T is the + array element type and which should return a negative, zero or positive + value according to whether the first element passed to it is less than, + equal to or greater than the second one. + */ + wxSortedArray(int (*)(T first, T second)compareFunction); + + /** + Performs a shallow array copy (i.e. doesn't copy the objects pointed to + even if the source array contains the items of pointer type). + */ + wxArray(const wxArray& array); + /** + Performs a shallow array copy (i.e. doesn't copy the objects pointed to + even if the source array contains the items of pointer type). + */ + wxSortedArray(const wxSortedArray& array); + /** + Performs a deep copy (i.e. the array element are copied too). + */ + wxObjArray(const wxObjArray& array); + + /** + Performs a shallow array copy (i.e. doesn't copy the objects pointed to + even if the source array contains the items of pointer type). + */ + wxArray& operator=(const wxArray& array); + /** + Performs a shallow array copy (i.e. doesn't copy the objects pointed to + even if the source array contains the items of pointer type). + */ + wxSortedArray& operator=(const wxSortedArray& array); + /** + Performs a deep copy (i.e. the array element are copied too). + */ + wxObjArray& operator=(const wxObjArray& array); + + /** + This destructor does not delete all the items owned by the array, you + may use the WX_CLEAR_ARRAY() macro for this. + */ + ~wxArray(); + /** + This destructor does not delete all the items owned by the array, you + may use the WX_CLEAR_ARRAY() macro for this. + */ + ~wxSortedArray(); + /** + This destructor deletes all the items owned by the array. + */ + ~wxObjArray(); + + //@} + + + /** + @name Memory Management + + Automatic array memory management is quite trivial: the array starts by + preallocating some minimal amount of memory (defined by + @c WX_ARRAY_DEFAULT_INITIAL_SIZE) and when further new items exhaust + already allocated memory it reallocates it adding 50% of the currently + allocated amount, but no more than some maximal number which is defined + by the @c ARRAY_MAXSIZE_INCREMENT constant. Of course, this may lead to + some memory being wasted (@c ARRAY_MAXSIZE_INCREMENT in the worst case, + i.e. 4Kb in the current implementation), so the Shrink() function is + provided to deallocate the extra memory. The Alloc() function can also + be quite useful if you know in advance how many items you are going to + put in the array and will prevent the array code from reallocating the + memory more times than needed. + */ + //@{ + + /** + Preallocates memory for a given number of array elements. It is worth + calling when the number of items which are going to be added to the + array is known in advance because it will save unneeded memory + reallocation. If the array already has enough memory for the given + number of items, nothing happens. In any case, the existing contents of + the array is not modified. + */ + void Alloc(size_t count); + + /** + Frees all memory unused by the array. If the program knows that no new + items will be added to the array it may call Shrink() to reduce its + memory usage. However, if a new item is added to the array, some extra + memory will be allocated again. + */ + void Shrink(); + + //@} + + + /** + @name Number of Elements and Simple Item Access + + Functions in this section return the total number of array elements and + allow to retrieve them - possibly using just the C array indexing [] + operator which does exactly the same as the Item() method. + */ + //@{ + + /** + Return the number of items in the array. + */ + size_t GetCount() const; + + /** + Returns @true if the array is empty, @false otherwise. + */ + bool IsEmpty() const; + + /** + Returns the item at the given position in the array. If @a index is out + of bounds, an assert failure is raised in the debug builds but nothing + special is done in the release build. + + The returned value is of type "reference to the array element type" for + all of the array classes. + */ + T& Item(size_t index) const; + + /** + Returns the last element in the array, i.e. is the same as calling + "Item(GetCount() - 1)". An assert failure is raised in the debug mode + if the array is empty. + + The returned value is of type "reference to the array element type" for + all of the array classes. + */ + T& Last() const; + + //@} + + + /** + @name Adding Items + */ + //@{ + + /** + Appends the given number of @a copies of the @a item to the array + consisting of the elements of type @c T. + + This version is used with wxArray. + + You may also use WX_APPEND_ARRAY() macro to append all elements of one + array to another one but it is more efficient to use the @a copies + parameter and modify the elements in place later if you plan to append + a lot of items. + */ + void Add(T item, size_t copies = 1); + /** + Appends the @a item to the array consisting of the elements of type + @c T. + + This version is used with wxSortedArray, returning the index where + @a item is stored. + */ + size_t Add(T item); + /** + Appends the @a item to the array consisting of the elements of type + @c T. + + This version is used with wxObjArray. The array will take ownership of + the @item, deleting it when the item is deleted from the array. Note + that you cannot append more than one pointer as reusing it would lead + to deleting it twice (or more) resulting in a crash. + + You may also use WX_APPEND_ARRAY() macro to append all elements of one + array to another one but it is more efficient to use the @a copies + parameter and modify the elements in place later if you plan to append + a lot of items. + */ + void Add(T* item); + /** + Appends the given number of @a copies of the @a item to the array + consisting of the elements of type @c T. + + This version is used with wxObjArray. The array will make a copy of the + item and will not take ownership of the original item. + + You may also use WX_APPEND_ARRAY() macro to append all elements of one + array to another one but it is more efficient to use the @a copies + parameter and modify the elements in place later if you plan to append + a lot of items. + */ + void Add(T& item, size_t copies = 1); + + /** + Inserts the given @a item into the array in the specified @e index + position. + + Be aware that you will set out the order of the array if you give a + wrong position. + + This function is useful in conjunction with IndexForInsert() for a + common operation of "insert only if not found". + */ + void AddAt(T item, size_t index); + + /** + Insert the given number of @a copies of the @a item into the array + before the existing item @a n - thus, @e Insert(something, 0u) will + insert an item in such way that it will become the first array element. + + wxSortedArray doesn't have this function because inserting in wrong + place would break its sorted condition. + + Please see Add() for an explanation of the differences between the + overloaded versions of this function. + */ + void Insert(T item, size_t n, size_t copies = 1); + /** + Insert the @a item into the array before the existing item @a n - thus, + @e Insert(something, 0u) will insert an item in such way that it will + become the first array element. + + wxSortedArray doesn't have this function because inserting in wrong + place would break its sorted condition. + + Please see Add() for an explanation of the differences between the + overloaded versions of this function. + */ + void Insert(T* item, size_t n); + /** + Insert the given number of @a copies of the @a item into the array + before the existing item @a n - thus, @e Insert(something, 0u) will + insert an item in such way that it will become the first array element. + + wxSortedArray doesn't have this function because inserting in wrong + place would break its sorted condition. + + Please see Add() for an explanation of the differences between the + overloaded versions of this function. + */ + void Insert(T& item, size_t n, size_t copies = 1); + + /** + This function ensures that the number of array elements is at least + @a count. If the array has already @a count or more items, nothing is + done. Otherwise, @a count - GetCount() elements are added and + initialized to the value @a defval. + + @see GetCount() + */ + void SetCount(size_t count, T defval = T(0)); + + //@} + + + /** + @name Removing Items + */ + //@{ + + /** + This function does the same as Empty() and additionally frees the + memory allocated to the array. + */ + void Clear(); + + /** + Removes the element from the array, but unlike Remove(), it doesn't + delete it. The function returns the pointer to the removed element. + */ + T* Detach(size_t index); + + /** + Empties the array. For wxObjArray classes, this destroys all of the + array elements. For wxArray and wxSortedArray this does nothing except + marking the array of being empty - this function does not free the + allocated memory, use Clear() for this. + */ + void Empty(); + + /** + Removes an element from the array by value: the first item of the array + equal to @a item is removed, an assert failure will result from an + attempt to remove an item which doesn't exist in the array. + + When an element is removed from wxObjArray it is deleted by the array - + use Detach() if you don't want this to happen. On the other hand, when + an object is removed from a wxArray nothing happens - you should delete + it manually if required: + + @code + T *item = array[n]; + delete item; + array.Remove(n); + @endcode + + See also WX_CLEAR_ARRAY() macro which deletes all elements of a wxArray + (supposed to contain pointers). + */ + Remove(T item); + + /** + Removes @a count elements starting at @a index from the array. When an + element is removed from wxObjArray it is deleted by the array - use + Detach() if you don't want this to happen. On the other hand, when an + object is removed from a wxArray nothing happens - you should delete it + manually if required: + + @code + T *item = array[n]; + delete item; + array.RemoveAt(n); + @endcode + + See also WX_CLEAR_ARRAY() macro which deletes all elements of a wxArray + (supposed to contain pointers). + */ + RemoveAt(size_t index, size_t count = 1); + + //@} + + + /** + @name Searching and Sorting + */ + //@{ + + /** + This version of Index() is for wxArray and wxObjArray only. + + Searches the element in the array, starting from either beginning or + the end depending on the value of @a searchFromEnd parameter. + @c wxNOT_FOUND is returned if the element is not found, otherwise the + index of the element is returned. + + @note Even for wxObjArray classes, the operator "==" of the elements in + the array is @b not used by this function. It searches exactly + the given element in the array and so will only succeed if this + element had been previously added to the array, but fail even if + another, identical, element is in the array. + */ + int Index(T& item, bool searchFromEnd = false) const; + /** + This version of Index() is for wxSortedArray only. + + Searches the element in the array, starting from either beginning or + the end depending on the value of @a searchFromEnd parameter. + @c wxNOT_FOUND is returned if the element is not found, otherwise the + index of the element is returned. + */ + const int Index(T& item) const; + + /** + Search for a place to insert @a item into the sorted array (binary + search). The index returned is just before the first existing item that + is greater or equal (according to the compare function) to the given + @a item. + + You have to do extra work to know if the @a item already exists in + array. + + This function is useful in conjunction with AddAt() for a common + operation of "insert only if not found". + */ + size_t IndexForInsert(T item) const; + + /** + The notation @c "CMPFUNCT" should be read as if we had the following + declaration: + + @code + template int CMPFUNC(T *first, T *second); + @endcode + + Where @e T is the type of the array elements. I.e. it is a function + returning @e int which is passed two arguments of type @e T*. + + Sorts the array using the specified compare function: this function + should return a negative, zero or positive value according to whether + the first element passed to it is less than, equal to or greater than + the second one. + + wxSortedArray doesn't have this function because it is always sorted. + */ + void Sort(CMPFUNC compareFunction); + + //@} +}; + + +/** + This macro may be used to append all elements of the @a other array to the + @a array. The two arrays must be of the same type. +*/ +#define WX_APPEND_ARRAY(wxArray& array, wxArray& other) + +/** + This macro may be used to delete all elements of the array before emptying + it. It can not be used with wxObjArrays - but they will delete their + elements anyway when you call Empty(). +*/ +#define WX_CLEAR_ARRAY(wxArray& array) + +//@{ +/** + This macro declares a new object array class named @a name and containing + the elements of type @e T. + + An exported array is used when compiling wxWidgets as a DLL under Windows + and the array needs to be visible outside the DLL. An user exported array + needed for exporting an array from a user DLL. + + Example: + + @code + class MyClass; + WX_DECLARE_OBJARRAY(MyClass, wxArrayOfMyClass); // note: not "MyClass *"! + @endcode + + You must use WX_DEFINE_OBJARRAY() macro to define the array class, + otherwise you would get link errors. +*/ +#define WX_DECLARE_OBJARRAY(T, name) +#define WX_DECLARE_EXPORTED_OBJARRAY(T, name) +#define WX_DECLARE_USER_EXPORTED_OBJARRAY(T, name) +//@} + +//@{ +/** + This macro defines a new array class named @a name and containing the + elements of type @a T. + + An exported array is used when compiling wxWidgets as a DLL under Windows + and the array needs to be visible outside the DLL. An user exported array + needed for exporting an array from a user DLL. + + Example: + + @code + WX_DEFINE_ARRAY_INT(int, MyArrayInt); + + class MyClass; + WX_DEFINE_ARRAY(MyClass *, ArrayOfMyClass); + @endcode + + Note that wxWidgets predefines the following standard array classes: + @b wxArrayInt, @b wxArrayLong, @b wxArrayShort, @b wxArrayDouble, + @b wxArrayPtrVoid. +*/ +#define WX_DEFINE_ARRAY(T, name) +#define WX_DEFINE_EXPORTED_ARRAY(T, name) +#define WX_DEFINE_USER_EXPORTED_ARRAY(T, name, exportspec) +//@} + +//@{ +/** + This macro defines the methods of the array class @a name not defined by + the WX_DECLARE_OBJARRAY() macro. You must include the file + @ before using this macro and you must have the full + declaration of the class of array elements in scope! If you forget to do + the first, the error will be caught by the compiler, but, unfortunately, + many compilers will not give any warnings if you forget to do the second - + but the objects of the class will not be copied correctly and their real + destructor will not be called. + + An exported array is used when compiling wxWidgets as a DLL under Windows + and the array needs to be visible outside the DLL. An user exported array + needed for exporting an array from a user DLL. + + Example of usage: + + @code + // first declare the class! + class MyClass + { + public: + MyClass(const MyClass&); + + // ... + + virtual ~MyClass(); + }; + + #include + WX_DEFINE_OBJARRAY(wxArrayOfMyClass); + @endcode +*/ +#define WX_DEFINE_OBJARRAY(name) +#define WX_DEFINE_EXPORTED_OBJARRAY(name) +#define WX_DEFINE_USER_EXPORTED_OBJARRAY(name) +//@} + +//@{ +/** + This macro defines a new sorted array class named @a name and containing + the elements of type @e T. + + An exported array is used when compiling wxWidgets as a DLL under Windows + and the array needs to be visible outside the DLL. An user exported array + needed for exporting an array from a user DLL. + + Example: + + @code + WX_DEFINE_SORTED_ARRAY_INT(int, MySortedArrayInt); + + class MyClass; + WX_DEFINE_SORTED_ARRAY(MyClass *, ArrayOfMyClass); + @endcode + + You will have to initialize the objects of this class by passing a + comparison function to the array object constructor like this: + + @code + int CompareInts(int n1, int n2) + { + return n1 - n2; + } + + MySortedArrayInt sorted(CompareInts); + + int CompareMyClassObjects(MyClass *item1, MyClass *item2) + { + // sort the items by their address... + return Stricmp(item1->GetAddress(), item2->GetAddress()); + } + + ArrayOfMyClass another(CompareMyClassObjects); + @endcode +*/ +#define WX_DEFINE_SORTED_ARRAY(T, name) +#define WX_DEFINE_SORTED_EXPORTED_ARRAY(T, name) +#define WX_DEFINE_SORTED_USER_EXPORTED_ARRAY(T, name) +//@} + +/** + This macro may be used to prepend all elements of the @a other array to the + @a array. The two arrays must be of the same type. +*/ +#define WX_PREPEND_ARRAY(wxArray& array, wxArray& other) + diff --git a/interface/wx/dynlib.h b/interface/wx/dynlib.h new file mode 100644 index 0000000000..3392ef4f19 --- /dev/null +++ b/interface/wx/dynlib.h @@ -0,0 +1,259 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: dynlib.h +// Purpose: interface of wxDynamicLibrary and wxDynamicLibraryDetails +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxDynamicLibraryDetails + @wxheader{dynlib.h} + + This class is used for the objects returned by the + wxDynamicLibrary::ListLoaded() method and contains the information about a + single module loaded into the address space of the current process. A + module in this context may be either a dynamic library or the main program + itself. + + @library{wxbase} + @category{appmanagement} +*/ +class wxDynamicLibraryDetails +{ +public: + /** + Retrieves the load address and the size of this module. + + @param addr + The pointer to the location to return load address in, may be + @NULL. + @param len + Pointer to the location to return the size of this module in + memory in, may be @NULL. + + @return @true if the load address and module size were retrieved, + @false if this information is not available. + */ + bool GetAddress(void** addr, size_t len) const; + + /** + Returns the base name of this module, e.g. @c "kernel32.dll" or + @c "libc-2.3.2.so". + */ + wxString GetName() const; + + /** + Returns the full path of this module if available, e.g. + @c "c:\windows\system32\kernel32.dll" or @c "/lib/libc-2.3.2.so". + */ + wxString GetPath() const; + + /** + Returns the version of this module, e.g. @c "5.2.3790.0" or @c "2.3.2". + The returned string is empty if the version information is not + available. + */ + wxString GetVersion() const; +}; + + + +/** + Dynamic library category used with wxDynamicLibrary::CanonicalizeName(). +*/ +enum wxDynamicLibraryCategory +{ + wxDL_LIBRARY, ///< Standard library. + wxDL_MODULE ///< Loadable module/plugin. +}; + +/** + Dynamic library plugin category used with + wxDynamicLibrary::CanonicalizePluginName(). +*/ +enum wxPluginCategory +{ + wxDL_PLUGIN_GUI, ///< Plugin that uses GUI classes. + wxDL_PLUGIN_BASE ///< wxBase-only plugin. +}; + +/** + @class wxDynamicLibrary + @wxheader{dynlib.h} + + wxDynamicLibrary is a class representing dynamically loadable library + (Windows DLL, shared library under Unix etc.). Just create an object of + this class to load a library and don't worry about unloading it -- it will + be done in the objects destructor automatically. + + The following flags can be used with wxDynamicLibrary() or Load(): + + @beginStyleTable + @style{wxDL_LAZY} + Equivalent of RTLD_LAZY under Unix, ignored elsewhere. + @style{wxDL_NOW} + Equivalent of RTLD_NOW under Unix, ignored elsewhere. + @style{wxDL_GLOBAL} + Equivalent of RTLD_GLOBAL under Unix, ignored elsewhere. + @style{wxDL_VERBATIM} + Don't try to append the appropriate extension to the library name + (this is done by default). + @style{wxDL_DEFAULT} + Default flags, same as wxDL_NOW currently. + @style{wxDL_QUIET} + Don't log an error message if the library couldn't be loaded. + @endStyleTable + + @library{wxbase} + @category{appmanagement} +*/ +class wxDynamicLibrary +{ +public: + /** + Default constructor. + */ + wxDynamicLibrary(); + /** + Constructor. Calls Load() with the given @a name. + */ + wxDynamicLibrary(const wxString& name, int flags = wxDL_DEFAULT); + + /** + Returns the platform-specific full name for the library called @a name. + E.g. it adds a @c ".dll" extension under Windows and @c "lib" prefix + and @c ".so", @c ".sl" or @c ".dylib" extension under Unix. + + @see CanonicalizePluginName() + */ + static wxString CanonicalizeName(const wxString& name, + wxDynamicLibraryCategory cat = wxDL_LIBRARY); + + /** + This function does the same thing as CanonicalizeName() but for + wxWidgets plugins. The only difference is that compiler and version + information are added to the name to ensure that the plugin which is + going to be loaded will be compatible with the main program. + */ + static wxString CanonicalizePluginName(const wxString& name, + wxPluginCategory cat = wxDL_PLUGIN_GUI); + + /** + Detaches this object from its library handle, i.e. the object will not + unload the library any longer in its destructor but it is now the + callers responsibility to do this using Unload(). + */ + wxDllType Detach(); + + /** + Return a valid handle for the main program itself or @NULL if symbols + from the main program can't be loaded on this platform. + */ + static wxDllType GetProgramHandle(); + + /** + Returns pointer to symbol @a name in the library or @NULL if the + library contains no such symbol. + + @see wxDYNLIB_FUNCTION() + */ + void* GetSymbol(const wxString& name) const; + + /** + This function is available only under Windows as it is only useful when + dynamically loading symbols from standard Windows DLLs. Such functions + have either @c 'A' (in ANSI build) or @c 'W' (in Unicode, or wide + character build) suffix if they take string parameters. Using this + function, you can use just the base name of the function and the + correct suffix is appended automatically depending on the current + build. Otherwise, this method is identical to GetSymbol(). + */ + void* GetSymbolAorW(const wxString& name) const; + + /** + Returns @true if the symbol with the given @a name is present in the + dynamic library, @false otherwise. Unlike GetSymbol(), this function + doesn't log an error message if the symbol is not found. + + @since 2.5.4 + */ + bool HasSymbol(const wxString& name) const; + + /** + Returns @true if the library was successfully loaded, @false otherwise. + */ + bool IsLoaded() const; + + /** + This static method returns a wxArray containing the details of all + modules loaded into the address space of the current project. The array + elements are objects of the type: wxDynamicLibraryDetails. The array + will be empty if an error occurred. + + This method is currently implemented only under Win32 and Linux and is + useful mostly for diagnostics purposes. + */ + static wxDynamicLibraryDetailsArray ListLoaded(); + + /** + Loads DLL with the given @a name into memory. The @a flags argument can + be a combination of the styles outlined in the class description. + + Returns @true if the library was successfully loaded, @false otherwise. + */ + bool Load(const wxString& name, int flags = wxDL_DEFAULT); + + /** + Unloads the library from memory. wxDynamicLibrary object automatically + calls this method from its destructor if it had been successfully + loaded. + */ + void Unload(); + /** + Unloads the library from memory. wxDynamicLibrary object automatically + calls this method from its destructor if it had been successfully + loaded. + + This version of Unload() is only used if you need to keep the library + in memory during a longer period of time than the scope of the + wxDynamicLibrary object. In this case you may call Detach() and store + the handle somewhere and call this static method later to unload it. + */ + static void Unload(wxDllType handle); +}; + + + +// ============================================================================ +// Global functions/macros +// ============================================================================ + +/** @ingroup group_funcmacro_misc */ +//@{ + +/** + When loading a function from a DLL you always have to cast the returned + void * pointer to the correct type and, even more annoyingly, you + have to repeat this type twice if you want to declare and define a function + pointer all in one line. + + This macro makes this slightly less painful by allowing you to specify the + type only once, as the first parameter, and creating a variable of this + type named after the function but with @c pfn prefix and initialized with + the function @a name from the wxDynamicLibrary @a dynlib. + + @param type + The type of the function. + @param name + The name of the function to load, not a string (without quotes, it is + quoted automatically by the macro). + @param dynlib + The library to load the function from. + + @header{wx/dynlib.h} +*/ +#define wxDYNLIB_FUNCTION(type, name, dynlib) + +//@} + diff --git a/interface/wx/editlbox.h b/interface/wx/editlbox.h new file mode 100644 index 0000000000..ae0dcb2c22 --- /dev/null +++ b/interface/wx/editlbox.h @@ -0,0 +1,98 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: editlbox.h +// Purpose: interface of wxEditableListBox +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxEditableListBox + @wxheader{editlbox.h} + + An editable listbox is composite control that lets the user easily enter, + delete and reorder a list of strings. + + @beginStyleTable + @style{wxEL_ALLOW_NEW} + Allows the user to enter new strings. + @style{wxEL_ALLOW_EDIT} + Allows the user to edit existing strings. + @style{wxEL_ALLOW_DELETE} + Allows the user to delete existing strings. + @style{wxEL_NO_REORDER} + Does not allow the user to reorder the strings. + @style{wxEL_DEFAULT_STYLE} + Default style: wxEL_ALLOW_NEW|wxEL_ALLOW_EDIT|wxEL_ALLOW_DELETE. + @endStyleTable + + @library{wxadv} + @category{ctrl} + + @see wxListBox +*/ +class wxEditableListBox : public wxPanel +{ +public: + /** + Default ctor. + */ + wxEditableListBox(); + + /** + Constructor, creating and showing a list box. + + @param parent + Parent window. Must not be @NULL. + @param id + Window identifier. The value wxID_ANY indicates a default value. + @param label + The text shown just before the list control. + @param pos + Window position. + @param size + Window size. If wxDefaultSize is specified then the window is sized + appropriately. + @param style + Window style. See wxEditableListBox. + @param name + Window name. + + @see Create() + */ + wxEditableListBox(wxWindow* parent, wxWindowID id, + const wxString& label, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxEL_DEFAULT_STYLE, + const wxString& name = "editableListBox"); + + /** + Destructor, destroying the list box. + */ + ~wxEditableListBox(); + + /** + Creates the editable listbox for two-step construction. + See wxEditableListBox() for further details. + */ + bool Create(wxWindow* parent, wxWindowID id, + const wxString& label, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxEL_DEFAULT_STYLE, + const wxString& name = "editableListBox"); + + /** + Replaces current contents with given strings. + */ + void SetStrings(const wxArrayString& strings); + + + /** + Returns in the given array the current contents of the control + (the array will be erased before control's contents are appended). + */ + void GetSelections(wxArrayString& strings) const; +}; + diff --git a/interface/wx/encconv.h b/interface/wx/encconv.h new file mode 100644 index 0000000000..a7821321ce --- /dev/null +++ b/interface/wx/encconv.h @@ -0,0 +1,187 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: encconv.h +// Purpose: interface of wxEncodingConverter +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxEncodingConverter + @wxheader{encconv.h} + + This class is capable of converting strings between two 8-bit encodings/charsets. + It can also convert from/to Unicode (but only if you compiled wxWidgets + with wxUSE_WCHAR_T set to 1). + + Only a limited subset of encodings is supported by wxEncodingConverter: + @c wxFONTENCODING_ISO8859_1..15, @c wxFONTENCODING_CP1250..1257 and + @c wxFONTENCODING_KOI8. + + @note + + Please use wxMBConv classes instead if possible. wxCSConv has much better + support for various encodings than wxEncodingConverter. + wxEncodingConverter is useful only if you rely on wxCONVERT_SUBSTITUTE mode + of operation (see wxEncodingConverter::Init()). + + @library{wxbase} + @category{misc} + + @see wxFontMapper, wxMBConv, @ref overview_nonenglish +*/ +class wxEncodingConverter : public wxObject +{ +public: + /** + Constructor. + */ + wxEncodingConverter(); + + /** + Return @true if (any text in) multibyte encoding @a encIn can be converted to + another one (@a encOut) losslessly. + + Do not call this method with @c wxFONTENCODING_UNICODE as either parameter, + it doesn't make sense (always works in one sense and always depends + on the text to convert in the other). + */ + static bool CanConvert(wxFontEncoding encIn, + wxFontEncoding encOut); + + /** + @name Conversion functions + + @{ + */ + /** + Convert input string according to settings passed to Init() and writes + the result to output. + + All the Convert() function overloads return @true if the conversion was + lossless and @false if at least one of the characters couldn't be converted + was and replaced with '?' in the output. + + Note that if @c wxCONVERT_SUBSTITUTE was passed to Init(), substitution is + considered a lossless operation. + + @note You must call Init() before using this method! + + @note wchar_t versions of the method are not available if wxWidgets was + compiled with @c wxUSE_WCHAR_T set to 0. + */ + bool Convert(const char* input, char* output) const; + bool Convert(const wchar_t* input, wchar_t* output) const; + bool Convert(const char* input, wchar_t* output) const; + bool Convert(const wchar_t* input, char* output) const; + + /** + Convert input string according to settings passed to Init() in-place, + i.e. write the result to the same memory area. + + See the Convert(const char*,char*) const overload for more info. + */ + bool Convert(char* str) const; + bool Convert(wchar_t* str) const; + + /** + Convert a wxString and return a new wxString object. + + See the Convert(const char*,char*) const overload for more info. + */ + wxString Convert(const wxString& input) const; + //@} + + + /** + Similar to GetPlatformEquivalents(), but this one will return ALL + equivalent encodings, regardless of the platform, and including itself. + + This platform's encodings are before others in the array. + And again, if @a enc is in the array, it is the very first item in it. + */ + static wxFontEncodingArray GetAllEquivalents(wxFontEncoding enc); + + /** + Return equivalents for given font that are used under given platform. + + Supported platforms: + @li wxPLATFORM_UNIX + @li wxPLATFORM_WINDOWS + @li wxPLATFORM_OS2 + @li wxPLATFORM_MAC + @li wxPLATFORM_CURRENT + + wxPLATFORM_CURRENT means the platform this binary was compiled for. + + Examples: + + @verbatim + current platform enc returned value + ---------------------------------------------- + unix CP1250 {ISO8859_2} + unix ISO8859_2 {ISO8859_2} + windows ISO8859_2 {CP1250} + unix CP1252 {ISO8859_1,ISO8859_15} + @endverbatim + + Equivalence is defined in terms of convertibility: two encodings are + equivalent if you can convert text between then without losing + information (it may - and will - happen that you lose special chars + like quotation marks or em-dashes but you shouldn't lose any diacritics + and language-specific characters when converting between equivalent encodings). + + Remember that this function does @b NOT check for presence of + fonts in system. It only tells you what are most suitable + encodings. (It usually returns only one encoding.) + + @note Note that argument enc itself may be present in the returned array, + so that you can, as a side-effect, detect whether the encoding is + native for this platform or not. + + @note Convert() is not limited to converting between equivalent encodings, + it can convert between two arbitrary encodings. + + @note If @a enc is present in the returned array, then it is always the first + item of it. + + @note Please note that the returned array may contain no items at all. + */ + static wxFontEncodingArray GetPlatformEquivalents(wxFontEncoding enc, + int platform = wxPLATFORM_CURRENT); + + /** + Initialize the conversion. + + Both output or input encoding may be wxFONTENCODING_UNICODE, but only + if wxUSE_ENCODING is set to 1. + + All subsequent calls to Convert() will interpret its argument + as a string in @a input_enc encoding and will output string in + @a output_enc encoding. + + You must call this method before calling Convert. You may call + it more than once in order to switch to another conversion. + + @a method affects behaviour of Convert() in case input character + cannot be converted because it does not exist in output encoding: + + @li @b wxCONVERT_STRICT: follow behaviour of GNU Recode - just copy + unconvertible characters to output and don't change them + (its integer value will stay the same) + @li @b wxCONVERT_SUBSTITUTE: try some (lossy) substitutions - e.g. + replace unconvertible latin capitals with acute by ordinary + capitals, replace en-dash or em-dash by '-' etc. + + Both modes guarantee that output string will have same length + as input string. + + @return @false if given conversion is impossible, @true otherwise + (conversion may be impossible either if you try to convert + to Unicode with non-Unicode build of wxWidgets or if input + or output encoding is not supported). + */ + bool Init(wxFontEncoding input_enc, wxFontEncoding output_enc, + int method = wxCONVERT_STRICT); +}; + diff --git a/interface/wx/event.h b/interface/wx/event.h new file mode 100644 index 0000000000..8c051f00d8 --- /dev/null +++ b/interface/wx/event.h @@ -0,0 +1,3390 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: event.h +// Purpose: interface of wxEventHandler, wxEventBlocker and many +// wxEvent-derived classes +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + + + +/** + @class wxEvent + @wxheader{event.h} + + An event is a structure holding information about an event passed to a + callback or member function. + + wxEvent used to be a multipurpose event object, and is an abstract base class + for other event classes (see below). + + For more information about events, see the @ref overview_eventhandling overview. + + @beginWxPerlOnly + In wxPerl custom event classes should be derived from + @c Wx::PlEvent and @c Wx::PlCommandEvent. + @endWxPerlOnly + + @library{wxbase} + @category{events} + + @see wxCommandEvent, wxMouseEvent +*/ +class wxEvent : public wxObject +{ +public: + /** + Constructor. Should not need to be used directly by an application. + */ + wxEvent(int id = 0, wxEventType eventType = wxEVT_NULL); + + /** + Returns a copy of the event. + + Any event that is posted to the wxWidgets event system for later action + (via wxEvtHandler::AddPendingEvent or wxPostEvent()) must implement + this method. + + All wxWidgets events fully implement this method, but any derived events + implemented by the user should also implement this method just in case they + (or some event derived from them) are ever posted. + + All wxWidgets events implement a copy constructor, so the easiest way of + implementing the Clone function is to implement a copy constructor for + a new event (call it MyEvent) and then define the Clone function like this: + + @code + wxEvent *Clone() const { return new MyEvent(*this); } + @endcode + */ + virtual wxEvent* Clone() const = 0; + + /** + Returns the object (usually a window) associated with the event, if any. + */ + wxObject* GetEventObject() const; + + /** + Returns the identifier of the given event type, such as @c wxEVT_COMMAND_BUTTON_CLICKED. + */ + wxEventType GetEventType() const; + + /** + Returns the identifier associated with this event, such as a button command id. + */ + int GetId() const; + + /** + Returns @true if the event handler should be skipped, @false otherwise. + */ + bool GetSkipped() const; + + /** + Gets the timestamp for the event. The timestamp is the time in milliseconds + since some fixed moment (not necessarily the standard Unix Epoch, so only + differences between the timestamps and not their absolute values usually make sense). + */ + long GetTimestamp() const; + + /** + Returns @true if the event is or is derived from wxCommandEvent else it returns @false. + + @note exists only for optimization purposes. + */ + bool IsCommandEvent() const; + + /** + Sets the propagation level to the given value (for example returned from an + earlier call to wxEvent::StopPropagation). + */ + void ResumePropagation(int propagationLevel); + + /** + Sets the originating object. + */ + void SetEventObject(wxObject* object); + + /** + Sets the event type. + */ + void SetEventType(wxEventType type); + + /** + Sets the identifier associated with this event, such as a button command id. + */ + void SetId(int id); + + /** + Sets the timestamp for the event. + */ + void SetTimestamp(long = 0); + + /** + Test if this event should be propagated or not, i.e. if the propagation level + is currently greater than 0. + */ + bool ShouldPropagate() const; + + /** + This method can be used inside an event handler to control whether further + event handlers bound to this event will be called after the current one returns. + + Without Skip() (or equivalently if Skip(@false) is used), the event will not + be processed any more. If Skip(@true) is called, the event processing system + continues searching for a further handler function for this event, even though + it has been processed already in the current handler. + + In general, it is recommended to skip all non-command events to allow the + default handling to take place. The command events are, however, normally not + skipped as usually a single command such as a button click or menu item + selection must only be processed by one handler. + */ + void Skip(bool skip = true); + + /** + Stop the event from propagating to its parent window. + + Returns the old propagation level value which may be later passed to + ResumePropagation() to allow propagating the event again. + */ + int StopPropagation(); + +protected: + /** + Indicates how many levels the event can propagate. + + This member is protected and should typically only be set in the constructors + of the derived classes. It may be temporarily changed by StopPropagation() + and ResumePropagation() and tested with ShouldPropagate(). + + The initial value is set to either @c wxEVENT_PROPAGATE_NONE (by default) + meaning that the event shouldn't be propagated at all or to + @c wxEVENT_PROPAGATE_MAX (for command events) meaning that it should be + propagated as much as necessary. + + Any positive number means that the event should be propagated but no more than + the given number of times. E.g. the propagation level may be set to 1 to + propagate the event to its parent only, but not to its grandparent. + */ + int m_propagationLevel; +}; + +/** + @class wxEventBlocker + @wxheader{event.h} + + This class is a special event handler which allows to discard + any event (or a set of event types) directed to a specific window. + + Example: + + @code + void MyWindow::DoSomething() + { + { + // block all events directed to this window while + // we do the 1000 FunctionWhichSendsEvents() calls + wxEventBlocker blocker(this); + + for ( int i = 0; i 1000; i++ ) + FunctionWhichSendsEvents(i); + + } // ~wxEventBlocker called, old event handler is restored + + // the event generated by this call will be processed: + FunctionWhichSendsEvents(0) + } + @endcode + + @library{wxcore} + @category{events} + + @see @ref overview_eventhandling, wxEvtHandler +*/ +class wxEventBlocker : public wxEvtHandler +{ +public: + /** + Constructs the blocker for the given window and for the given event type. + + If @a type is @c wxEVT_ANY, then all events for that window are blocked. + You can call Block() after creation to add other event types to the list + of events to block. + + Note that the @a win window @b must remain alive until the + wxEventBlocker object destruction. + */ + wxEventBlocker(wxWindow* win, wxEventType = wxEVT_ANY); + + /** + Destructor. The blocker will remove itself from the chain of event handlers for + the window provided in the constructor, thus restoring normal processing of events. + */ + virtual ~wxEventBlocker(); + + /** + Adds to the list of event types which should be blocked the given @a eventType. + */ + void Block(wxEventType eventType); +}; + + + +/** + @class wxEvtHandler + @wxheader{event.h} + + A class that can handle events from the windowing system. + wxWindow (and therefore all window classes) are derived from this class. + + When events are received, wxEvtHandler invokes the method listed in the + event table using itself as the object. When using multiple inheritance + it is imperative that the wxEvtHandler(-derived) class be the first + class inherited such that the "this" pointer for the overall object + will be identical to the "this" pointer for the wxEvtHandler portion. + + @library{wxbase} + @category{events} + + @see @ref overview_eventhandling +*/ +class wxEvtHandler : public wxObject +{ +public: + /** + Constructor. + */ + wxEvtHandler(); + + /** + Destructor. + + If the handler is part of a chain, the destructor will unlink itself and + restore the previous and next handlers so that they point to each other. + */ + virtual ~wxEvtHandler(); + + /** + Queue event for a later processing. + + This method is similar to ProcessEvent() but while the latter is + synchronous, i.e. the event is processed immediately, before the + function returns, this one is asynchronous and returns immediately + while the event will be processed at some later time (usually during + the next event loop iteration). + + Another important difference is that this method takes ownership of the + @a event parameter, i.e. it will delete it itself. This implies that + the event should be allocated on the heap and that the pointer can't be + used any more after the function returns (as it can be deleted at any + moment). + + QueueEvent() can be used for inter-thread communication from the worker + threads to the main thread, it is safe in the sense that it uses + locking internally and avoids the problem mentioned in AddPendingEvent() + documentation by ensuring that the @a event object is not used by the + calling thread any more. Care should still be taken to avoid that some + fields of this object are used by it, notably any wxString members of + the event object must not be shallow copies of another wxString object + as this would result in them still using the same string buffer behind + the scenes. For example + @code + void FunctionInAWorkerThread(const wxString& str) + { + wxCommandEvent* evt = new wxCommandEvent; + + // NOT evt->SetString(str) as this would be a shallow copy + evt->SetString(str.c_str()); // make a deep copy + + wxTheApp->QueueEvent( evt ); + } + @endcode + + Finally notice that this method automatically wakes up the event loop + if it is currently idle by calling ::wxWakeUpIdle() so there is no need + to do it manually when using it. + + @since 2.9.0 + + @param event + A heap-allocated event to be queued, QueueEvent() takes ownership + of it. This parameter shouldn't be @c NULL. + */ + virtual void QueueEvent(wxEvent *event); + + /** + Post an event to be processed later. + + This function is similar to QueueEvent() but can't be used to post + events from worker threads for the event objects with wxString fields + (i.e. in practice most of them) because of an unsafe use of the same + wxString object which happens because the wxString field in the + original @a event object and its copy made internally by this function + share the same string buffer internally. Use QueueEvent() to avoid + this. + + A copy of event is made by the function, so the original can be deleted + as soon as function returns (it is common that the original is created + on the stack). This requires that the wxEvent::Clone() method be + implemented by event so that it can be duplicated and stored until it + gets processed. + + @param event + Event to add to the pending events queue. + */ + virtual void AddPendingEvent(const wxEvent& event); + + /** + Connects the given function dynamically with the event handler, id and event type. + This is an alternative to the use of static event tables. + + See the @ref page_samples_event sample for usage. + + This specific overload allows you to connect an event handler to a @e range + of @e source IDs. + Do not confuse @e source IDs with event @e types: source IDs identify the + event generator objects (typically wxMenuItem or wxWindow objects) while the + event @e type identify which type of events should be handled by the + given @e function (an event generator object may generate many different + types of events!). + + @param id + The first ID of the identifier range to be associated with the event + handler function. + @param lastId + The last ID of the identifier range to be associated with the event + handler function. + @param eventType + The event type to be associated with this event handler. + @param function + The event handler function. Note that this function should + be explicitly converted to the correct type which can be done using a macro + called @c wxFooEventHandler for the handler for any @c wxFooEvent. + @param userData + Data to be associated with the event table entry. + @param eventSink + Object whose member function should be called. + If this is @NULL, @c *this will be used. + */ + void Connect(int id, int lastId, wxEventType eventType, + wxObjectEventFunction function, + wxObject* userData = NULL, + wxEvtHandler* eventSink = NULL); + + /** + See the Connect(int, int, wxEventType, wxObjectEventFunction, wxObject*, wxEvtHandler*) + overload for more info. + + This overload can be used to attach an event handler to a single source ID: + + Example: + @code + frame->Connect( wxID_EXIT, + wxEVT_COMMAND_MENU_SELECTED, + wxCommandEventHandler(MyFrame::OnQuit) ); + @endcode + */ + void Connect(int id, wxEventType eventType, + wxObjectEventFunction function, + wxObject* userData = NULL, + wxEvtHandler* eventSink = NULL); + + /** + See the Connect(int, int, wxEventType, wxObjectEventFunction, wxObject*, wxEvtHandler*) + overload for more info. + + This overload will connect the given event handler so that regardless of the + ID of the event source, the handler will be called. + */ + void Connect(wxEventType eventType, + wxObjectEventFunction function, + wxObject* userData = NULL, + wxEvtHandler* eventSink = NULL); + + /** + Disconnects the given function dynamically from the event handler, using the + specified parameters as search criteria and returning @true if a matching + function has been found and removed. + + This method can only disconnect functions which have been added using the + Connect() method. There is no way to disconnect functions connected using + the (static) event tables. + + @param eventType + The event type associated with this event handler. + @param function + The event handler function. + @param userData + Data associated with the event table entry. + @param eventSink + Object whose member function should be called. + */ + bool Disconnect(wxEventType eventType = wxEVT_NULL, + wxObjectEventFunction function = NULL, + wxObject* userData = NULL, + wxEvtHandler* eventSink = NULL); + + /** + See the Disconnect(wxEventType, wxObjectEventFunction, wxObject*, wxEvtHandler*) + overload for more info. + + This overload takes the additional @a id parameter. + */ + bool Disconnect(int id = wxID_ANY, + wxEventType eventType = wxEVT_NULL, + wxObjectEventFunction function = NULL, + wxObject* userData = NULL, + wxEvtHandler* eventSink = NULL); + + /** + See the Disconnect(wxEventType, wxObjectEventFunction, wxObject*, wxEvtHandler*) + overload for more info. + + This overload takes an additional range of source IDs. + */ + bool Disconnect(int id, int lastId = wxID_ANY, + wxEventType eventType = wxEVT_NULL, + wxObjectEventFunction function = NULL, + wxObject* userData = NULL, + wxEvtHandler* eventSink = NULL); + + /** + Returns user-supplied client data. + + @remarks Normally, any extra data the programmer wishes to associate with + the object should be made available by deriving a new class with + new data members. + + @see SetClientData() + */ + void* GetClientData() const; + + /** + Returns a pointer to the user-supplied client data object. + + @see SetClientObject(), wxClientData + */ + wxClientData* GetClientObject() const; + + /** + Returns @true if the event handler is enabled, @false otherwise. + + @see SetEvtHandlerEnabled() + */ + bool GetEvtHandlerEnabled() const; + + /** + Returns the pointer to the next handler in the chain. + + @see SetNextHandler(), GetPreviousHandler(), SetPreviousHandler(), + wxWindow::PushEventHandler, wxWindow::PopEventHandler + */ + wxEvtHandler* GetNextHandler() const; + + /** + Returns the pointer to the previous handler in the chain. + + @see SetPreviousHandler(), GetNextHandler(), SetNextHandler(), + wxWindow::PushEventHandler, wxWindow::PopEventHandler + */ + wxEvtHandler* GetPreviousHandler() const; + + /** + Processes an event, searching event tables and calling zero or more suitable + event handler function(s). + + Normally, your application would not call this function: it is called in the + wxWidgets implementation to dispatch incoming user interface events to the + framework (and application). + + However, you might need to call it if implementing new functionality + (such as a new control) where you define new event types, as opposed to + allowing the user to override virtual functions. + + An instance where you might actually override the ProcessEvent function is where + you want to direct event processing to event handlers not normally noticed by + wxWidgets. For example, in the document/view architecture, documents and views + are potential event handlers. When an event reaches a frame, ProcessEvent will + need to be called on the associated document and view in case event handler functions + are associated with these objects. The property classes library (wxProperty) also + overrides ProcessEvent for similar reasons. + + The normal order of event table searching is as follows: + -# If the object is disabled (via a call to wxEvtHandler::SetEvtHandlerEnabled) + the function skips to step (6). + -# If the object is a wxWindow, ProcessEvent() is recursively called on the + window's wxValidator. If this returns @true, the function exits. + -# SearchEventTable() is called for this event handler. If this fails, the base + class table is tried, and so on until no more tables exist or an appropriate + function was found, in which case the function exits. + -# The search is applied down the entire chain of event handlers (usually the + chain has a length of one). If this succeeds, the function exits. + -# If the object is a wxWindow and the event is a wxCommandEvent, ProcessEvent() + is recursively applied to the parent window's event handler. + If this returns true, the function exits. + -# Finally, ProcessEvent() is called on the wxApp object. + + @param event + Event to process. + + @return @true if a suitable event handler function was found and + executed, and the function did not call wxEvent::Skip. + + @see SearchEventTable() + */ + virtual bool ProcessEvent(wxEvent& event); + + /** + Processes an event by calling ProcessEvent() and handles any exceptions + that occur in the process. + If an exception is thrown in event handler, wxApp::OnExceptionInMainLoop is called. + + @param event + Event to process. + + @return @true if the event was processed, @false if no handler was found + or an exception was thrown. + + @see wxWindow::HandleWindowEvent + */ + bool SafelyProcessEvent(wxEvent& event); + + /** + Searches the event table, executing an event handler function if an appropriate + one is found. + + @param table + Event table to be searched. + @param event + Event to be matched against an event table entry. + + @return @true if a suitable event handler function was found and + executed, and the function did not call wxEvent::Skip. + + @remarks This function looks through the object's event table and tries + to find an entry that will match the event. + An entry will match if: + @li The event type matches, and + @li the identifier or identifier range matches, or the event table + entry's identifier is zero. + If a suitable function is called but calls wxEvent::Skip, this + function will fail, and searching will continue. + + @see ProcessEvent() + */ + virtual bool SearchEventTable(wxEventTable& table, + wxEvent& event); + + /** + Sets user-supplied client data. + + @param data + Data to be associated with the event handler. + + @remarks Normally, any extra data the programmer wishes to associate + with the object should be made available by deriving a new + class with new data members. You must not call this method + and SetClientObject on the same class - only one of them. + + @see GetClientData() + */ + void SetClientData(void* data); + + /** + Set the client data object. Any previous object will be deleted. + + @see GetClientObject(), wxClientData + */ + void SetClientObject(wxClientData* data); + + /** + Enables or disables the event handler. + + @param enabled + @true if the event handler is to be enabled, @false if it is to be disabled. + + @remarks You can use this function to avoid having to remove the event + handler from the chain, for example when implementing a + dialog editor and changing from edit to test mode. + + @see GetEvtHandlerEnabled() + */ + void SetEvtHandlerEnabled(bool enabled); + + /** + Sets the pointer to the next handler. + + @param handler + Event handler to be set as the next handler. + + @see GetNextHandler(), SetPreviousHandler(), GetPreviousHandler(), + wxWindow::PushEventHandler, wxWindow::PopEventHandler + */ + void SetNextHandler(wxEvtHandler* handler); + + /** + Sets the pointer to the previous handler. + + @param handler + Event handler to be set as the previous handler. + */ + void SetPreviousHandler(wxEvtHandler* handler); +}; + + +/** + @class wxKeyEvent + @wxheader{event.h} + + This event class contains information about keypress (character) events. + + Notice that there are three different kinds of keyboard events in wxWidgets: + key down and up events and char events. The difference between the first two + is clear - the first corresponds to a key press and the second to a key + release - otherwise they are identical. Just note that if the key is + maintained in a pressed state you will typically get a lot of (automatically + generated) down events but only one up so it is wrong to assume that there is + one up event corresponding to each down one. + + Both key events provide untranslated key codes while the char event carries + the translated one. The untranslated code for alphanumeric keys is always + an upper case value. For the other keys it is one of @c WXK_XXX values + from the @ref page_keycodes. + The translated key is, in general, the character the user expects to appear + as the result of the key combination when typing the text into a text entry + zone, for example. + + A few examples to clarify this (all assume that CAPS LOCK is unpressed + and the standard US keyboard): when the @c 'A' key is pressed, the key down + event key code is equal to @c ASCII A == 65. But the char event key code + is @c ASCII a == 97. On the other hand, if you press both SHIFT and + @c 'A' keys simultaneously , the key code in key down event will still be + just @c 'A' while the char event key code parameter will now be @c 'A' + as well. + + Although in this simple case it is clear that the correct key code could be + found in the key down event handler by checking the value returned by + wxKeyEvent::ShiftDown(), in general you should use @c EVT_CHAR for this as + for non-alphanumeric keys the translation is keyboard-layout dependent and + can only be done properly by the system itself. + + Another kind of translation is done when the control key is pressed: for + example, for CTRL-A key press the key down event still carries the + same key code @c 'a' as usual but the char event will have key code of 1, + the ASCII value of this key combination. + + You may discover how the other keys on your system behave interactively by + running the @ref page_samples_text wxWidgets sample and pressing some keys + in any of the text controls shown in it. + + @b Tip: be sure to call @c event.Skip() for events that you don't process in + key event function, otherwise menu shortcuts may cease to work under Windows. + + @note If a key down (@c EVT_KEY_DOWN) event is caught and the event handler + does not call @c event.Skip() then the corresponding char event + (@c EVT_CHAR) will not happen. + This is by design and enables the programs that handle both types of + events to be a bit simpler. + + @note For Windows programmers: The key and char events in wxWidgets are + similar to but slightly different from Windows @c WM_KEYDOWN and + @c WM_CHAR events. In particular, Alt-x combination will generate a + char event in wxWidgets (unless it is used as an accelerator). + + + @beginEventTable{wxKeyEvent} + @event{EVT_KEY_DOWN(func)} + Process a wxEVT_KEY_DOWN event (any key has been pressed). + @event{EVT_KEY_UP(func)} + Process a wxEVT_KEY_UP event (any key has been released). + @event{EVT_CHAR(func)} + Process a wxEVT_CHAR event. + @endEventTable + + @library{wxcore} + @category{events} +*/ +class wxKeyEvent : public wxEvent +{ +public: + /** + Constructor. + Currently, the only valid event types are @c wxEVT_CHAR and @c wxEVT_CHAR_HOOK. + */ + wxKeyEvent(wxEventType keyEventType = wxEVT_NULL); + + /** + Returns @true if the Alt key was down at the time of the key event. + + Notice that GetModifiers() is easier to use correctly than this function + so you should consider using it in new code. + */ + bool AltDown() const; + + /** + CMD is a pseudo key which is the same as Control for PC and Unix + platforms but the special APPLE (a.k.a as COMMAND) key under Macs: + it makes often sense to use it instead of, say, ControlDown() because Cmd + key is used for the same thing under Mac as Ctrl elsewhere (but Ctrl still + exists, just not used for this purpose under Mac). So for non-Mac platforms + this is the same as ControlDown() and under Mac this is the same as MetaDown(). + */ + bool CmdDown() const; + + /** + Returns @true if the control key was down at the time of the key event. + + Notice that GetModifiers() is easier to use correctly than this function + so you should consider using it in new code. + */ + bool ControlDown() const; + + /** + Returns the virtual key code. ASCII events return normal ASCII values, + while non-ASCII events return values such as @b WXK_LEFT for the left cursor + key. See @ref page_keycodes for a full list of the virtual key codes. + + Note that in Unicode build, the returned value is meaningful only if the + user entered a character that can be represented in current locale's default + charset. You can obtain the corresponding Unicode character using GetUnicodeKey(). + */ + int GetKeyCode() const; + + /** + Return the bitmask of modifier keys which were pressed when this event + happened. See @ref page_keymodifiers for the full list of modifiers. + + Notice that this function is easier to use correctly than, for example, + ControlDown() because when using the latter you also have to remember to + test that none of the other modifiers is pressed: + + @code + if ( ControlDown() && !AltDown() && !ShiftDown() && !MetaDown() ) + ... handle Ctrl-XXX ... + @endcode + + and forgetting to do it can result in serious program bugs (e.g. program + not working with European keyboard layout where ALTGR key which is seen by + the program as combination of CTRL and ALT is used). On the other hand, + you can simply write: + + @code + if ( GetModifiers() == wxMOD_CONTROL ) + ... handle Ctrl-XXX ... + @endcode + + with this function. + */ + int GetModifiers() const; + + //@{ + /** + Obtains the position (in client coordinates) at which the key was pressed. + */ + wxPoint GetPosition() const; + void GetPosition(long* x, long* y) const; + //@} + + /** + Returns the raw key code for this event. This is a platform-dependent scan code + which should only be used in advanced applications. + + @note Currently the raw key codes are not supported by all ports, use + @ifdef_ wxHAS_RAW_KEY_CODES to determine if this feature is available. + */ + wxUint32 GetRawKeyCode() const; + + /** + Returns the low level key flags for this event. The flags are + platform-dependent and should only be used in advanced applications. + + @note Currently the raw key flags are not supported by all ports, use + @ifdef_ wxHAS_RAW_KEY_CODES to determine if this feature is available. + */ + wxUint32 GetRawKeyFlags() const; + + /** + Returns the Unicode character corresponding to this key event. + + This function is only available in Unicode build, i.e. when + @c wxUSE_UNICODE is 1. + */ + wxChar GetUnicodeKey() const; + + /** + Returns the X position (in client coordinates) of the event. + */ + wxCoord GetX() const; + + /** + Returns the Y position (in client coordinates) of the event. + */ + wxCoord GetY() const; + + /** + Returns @true if either CTRL or ALT keys was down at the time of the + key event. + + Note that this function does not take into account neither SHIFT nor + META key states (the reason for ignoring the latter is that it is + common for NUMLOCK key to be configured as META under X but the key + presses even while NUMLOCK is on should be still processed normally). + */ + bool HasModifiers() const; + + /** + Returns @true if the Meta key was down at the time of the key event. + + Notice that GetModifiers() is easier to use correctly than this function + so you should consider using it in new code. + */ + bool MetaDown() const; + + /** + Returns @true if the shift key was down at the time of the key event. + + Notice that GetModifiers() is easier to use correctly than this function + so you should consider using it in new code. + */ + bool ShiftDown() const; +}; + + + +/** + @class wxJoystickEvent + @wxheader{event.h} + + This event class contains information about joystick events, particularly + events received by windows. + + @beginEventTable{wxJoystickEvent} + @style{EVT_JOY_BUTTON_DOWN(func)} + Process a wxEVT_JOY_BUTTON_DOWN event. + @style{EVT_JOY_BUTTON_UP(func)} + Process a wxEVT_JOY_BUTTON_UP event. + @style{EVT_JOY_MOVE(func)} + Process a wxEVT_JOY_MOVE event. + @style{EVT_JOY_ZMOVE(func)} + Process a wxEVT_JOY_ZMOVE event. + @style{EVT_JOYSTICK_EVENTS(func)} + Processes all joystick events. + @endEventTable + + @library{wxcore} + @category{events} + + @see wxJoystick +*/ +class wxJoystickEvent : public wxEvent +{ +public: + /** + Constructor. + */ + wxJoystickEvent(wxEventType eventType = wxEVT_NULL, int state = 0, + int joystick = wxJOYSTICK1, + int change = 0); + + /** + Returns @true if the event was a down event from the specified button + (or any button). + + @param button + Can be @c wxJOY_BUTTONn where @c n is 1, 2, 3 or 4; or @c wxJOY_BUTTON_ANY to + indicate any button down event. + */ + bool ButtonDown(int button = wxJOY_BUTTON_ANY) const; + + /** + Returns @true if the specified button (or any button) was in a down state. + + @param button + Can be @c wxJOY_BUTTONn where @c n is 1, 2, 3 or 4; or @c wxJOY_BUTTON_ANY to + indicate any button down event. + */ + bool ButtonIsDown(int button = wxJOY_BUTTON_ANY) const; + + /** + Returns @true if the event was an up event from the specified button + (or any button). + + @param button + Can be @c wxJOY_BUTTONn where @c n is 1, 2, 3 or 4; or @c wxJOY_BUTTON_ANY to + indicate any button down event. + */ + bool ButtonUp(int button = wxJOY_BUTTON_ANY) const; + + /** + Returns the identifier of the button changing state. + + This is a @c wxJOY_BUTTONn identifier, where @c n is one of 1, 2, 3, 4. + */ + int GetButtonChange() const; + + /** + Returns the down state of the buttons. + + This is a @c wxJOY_BUTTONn identifier, where @c n is one of 1, 2, 3, 4. + */ + int GetButtonState() const; + + /** + Returns the identifier of the joystick generating the event - one of + wxJOYSTICK1 and wxJOYSTICK2. + */ + int GetJoystick() const; + + /** + Returns the x, y position of the joystick event. + */ + wxPoint GetPosition() const; + + /** + Returns the z position of the joystick event. + */ + int GetZPosition() const; + + /** + Returns @true if this was a button up or down event + (@e not 'is any button down?'). + */ + bool IsButton() const; + + /** + Returns @true if this was an x, y move event. + */ + bool IsMove() const; + + /** + Returns @true if this was a z move event. + */ + bool IsZMove() const; +}; + + + +/** + @class wxScrollWinEvent + @wxheader{event.h} + + A scroll event holds information about events sent from scrolling windows. + + + @beginEventTable{wxScrollWinEvent} + You can use the EVT_SCROLLWIN* macros for intercepting scroll window events + from the receiving window. + @event{EVT_SCROLLWIN(func)} + Process all scroll events. + @event{EVT_SCROLLWIN_TOP(func)} + Process wxEVT_SCROLLWIN_TOP scroll-to-top events. + @event{EVT_SCROLLWIN_BOTTOM(func)} + Process wxEVT_SCROLLWIN_BOTTOM scroll-to-bottom events. + @event{EVT_SCROLLWIN_LINEUP(func)} + Process wxEVT_SCROLLWIN_LINEUP line up events. + @event{EVT_SCROLLWIN_LINEDOWN(func)} + Process wxEVT_SCROLLWIN_LINEDOWN line down events. + @event{EVT_SCROLLWIN_PAGEUP(func)} + Process wxEVT_SCROLLWIN_PAGEUP page up events. + @event{EVT_SCROLLWIN_PAGEDOWN(func)} + Process wxEVT_SCROLLWIN_PAGEDOWN page down events. + @event{EVT_SCROLLWIN_THUMBTRACK(func)} + Process wxEVT_SCROLLWIN_THUMBTRACK thumbtrack events + (frequent events sent as the user drags the thumbtrack). + @event{EVT_SCROLLWIN_THUMBRELEASE(func)} + Process wxEVT_SCROLLWIN_THUMBRELEASE thumb release events. + @endEventTable + + + @library{wxcore} + @category{events} + + @see wxScrollEvent, @ref overview_eventhandling +*/ +class wxScrollWinEvent : public wxEvent +{ +public: + /** + Constructor. + */ + wxScrollWinEvent(wxEventType commandType = wxEVT_NULL, int pos = 0, + int orientation = 0); + + /** + Returns wxHORIZONTAL or wxVERTICAL, depending on the orientation of the + scrollbar. + + @todo wxHORIZONTAL and wxVERTICAL should go in their own enum + */ + int GetOrientation() const; + + /** + Returns the position of the scrollbar for the thumb track and release events. + + Note that this field can't be used for the other events, you need to query + the window itself for the current position in that case. + */ + int GetPosition() const; +}; + + + +/** + @class wxSysColourChangedEvent + @wxheader{event.h} + + This class is used for system colour change events, which are generated + when the user changes the colour settings using the control panel. + This is only appropriate under Windows. + + @remarks + The default event handler for this event propagates the event to child windows, + since Windows only sends the events to top-level windows. + If intercepting this event for a top-level window, remember to call the base + class handler, or to pass the event on to the window's children explicitly. + + @beginEventTable{wxSysColourChangedEvent} + @event{EVT_SYS_COLOUR_CHANGED(func)} + Process a wxEVT_SYS_COLOUR_CHANGED event. + @endEventTable + + @library{wxcore} + @category{events} + + @see @ref overview_eventhandling +*/ +class wxSysColourChangedEvent : public wxEvent +{ +public: + /** + Constructor. + */ + wxSysColourChangedEvent(); +}; + + + +/** + @class wxWindowCreateEvent + @wxheader{event.h} + + This event is sent just after the actual window associated with a wxWindow + object has been created. + + Since it is derived from wxCommandEvent, the event propagates up + the window hierarchy. + + @beginEventTable{wxWindowCreateEvent} + @event{EVT_WINDOW_CREATE(func)} + Process a wxEVT_CREATE event. + @endEventTable + + @library{wxcore} + @category{events} + + @see @ref overview_eventhandling, wxWindowDestroyEvent +*/ +class wxWindowCreateEvent : public wxCommandEvent +{ +public: + /** + Constructor. + */ + wxWindowCreateEvent(wxWindow* win = NULL); +}; + + + +/** + @class wxPaintEvent + @wxheader{event.h} + + A paint event is sent when a window's contents needs to be repainted. + + Please notice that in general it is impossible to change the drawing of a + standard control (such as wxButton) and so you shouldn't attempt to handle + paint events for them as even if it might work on some platforms, this is + inherently not portable and won't work everywhere. + + @remarks + Note that in a paint event handler, the application must always create a + wxPaintDC object, even if you do not use it. Otherwise, under MS Windows, + refreshing for this and other windows will go wrong. + For example: + @code + void MyWindow::OnPaint(wxPaintEvent& event) + { + wxPaintDC dc(this); + + DrawMyDocument(dc); + } + @endcode + You can optimize painting by retrieving the rectangles that have been damaged + and only repainting these. The rectangles are in terms of the client area, + and are unscrolled, so you will need to do some calculations using the current + view position to obtain logical, scrolled units. + Here is an example of using the wxRegionIterator class: + @code + // Called when window needs to be repainted. + void MyWindow::OnPaint(wxPaintEvent& event) + { + wxPaintDC dc(this); + + // Find Out where the window is scrolled to + int vbX,vbY; // Top left corner of client + GetViewStart(&vbX,&vbY); + + int vX,vY,vW,vH; // Dimensions of client area in pixels + wxRegionIterator upd(GetUpdateRegion()); // get the update rect list + + while (upd) + { + vX = upd.GetX(); + vY = upd.GetY(); + vW = upd.GetW(); + vH = upd.GetH(); + + // Alternatively we can do this: + // wxRect rect(upd.GetRect()); + + // Repaint this rectangle + ...some code... + + upd ++ ; + } + } + @endcode + + + @beginEventTable{wxPaintEvent} + @event{EVT_PAINT(func)} + Process a wxEVT_PAINT event. + @endEventTable + + @library{wxcore} + @category{events} + + @see @ref overview_eventhandling +*/ +class wxPaintEvent : public wxEvent +{ +public: + /** + Constructor. + */ + wxPaintEvent(int id = 0); +}; + + + +/** + @class wxMaximizeEvent + @wxheader{event.h} + + An event being sent when a top level window is maximized. Notice that it is + not sent when the window is restored to its original size after it had been + maximized, only a normal wxSizeEvent is generated in this case. + + @beginEventTable{wxMaximizeEvent} + @event{EVT_MAXIMIZE(func)} + Process a wxEVT_MAXIMIZE event. + @endEventTable + + @library{wxcore} + @category{events} + + @see @ref overview_eventhandling, wxTopLevelWindow::Maximize, + wxTopLevelWindow::IsMaximized +*/ +class wxMaximizeEvent : public wxEvent +{ +public: + /** + Constructor. Only used by wxWidgets internally. + */ + wxMaximizeEvent(int id = 0); +}; + +/** + The possibles modes to pass to wxUpdateUIEvent::SetMode(). +*/ +enum wxUpdateUIMode +{ + /** Send UI update events to all windows. */ + wxUPDATE_UI_PROCESS_ALL, + + /** Send UI update events to windows that have + the wxWS_EX_PROCESS_UI_UPDATES flag specified. */ + wxUPDATE_UI_PROCESS_SPECIFIED +}; + + +/** + @class wxUpdateUIEvent + @wxheader{event.h} + + This class is used for pseudo-events which are called by wxWidgets + to give an application the chance to update various user interface elements. + + Without update UI events, an application has to work hard to check/uncheck, + enable/disable, show/hide, and set the text for elements such as menu items + and toolbar buttons. The code for doing this has to be mixed up with the code + that is invoked when an action is invoked for a menu item or button. + + With update UI events, you define an event handler to look at the state of the + application and change UI elements accordingly. wxWidgets will call your member + functions in idle time, so you don't have to worry where to call this code. + + In addition to being a clearer and more declarative method, it also means you don't + have to worry whether you're updating a toolbar or menubar identifier. The same + handler can update a menu item and toolbar button, if the identifier is the same. + Instead of directly manipulating the menu or button, you call functions in the event + object, such as wxUpdateUIEvent::Check. wxWidgets will determine whether such a + call has been made, and which UI element to update. + + These events will work for popup menus as well as menubars. Just before a menu is + popped up, wxMenu::UpdateUI is called to process any UI events for the window that + owns the menu. + + If you find that the overhead of UI update processing is affecting your application, + you can do one or both of the following: + @li Call wxUpdateUIEvent::SetMode with a value of wxUPDATE_UI_PROCESS_SPECIFIED, + and set the extra style wxWS_EX_PROCESS_UI_UPDATES for every window that should + receive update events. No other windows will receive update events. + @li Call wxUpdateUIEvent::SetUpdateInterval with a millisecond value to set the delay + between updates. You may need to call wxWindow::UpdateWindowUI at critical points, + for example when a dialog is about to be shown, in case the user sees a slight + delay before windows are updated. + + Note that although events are sent in idle time, defining a wxIdleEvent handler + for a window does not affect this because the events are sent from wxWindow::OnInternalIdle + which is always called in idle time. + + wxWidgets tries to optimize update events on some platforms. + On Windows and GTK+, events for menubar items are only sent when the menu is about + to be shown, and not in idle time. + + + @beginEventTable{wxUpdateUIEvent} + @event{EVT_UPDATE_UI(id, func)} + Process a wxEVT_UPDATE_UI event for the command with the given id. + @event{EVT_UPDATE_UI_RANGE(id1, id2, func)} + Process a wxEVT_UPDATE_UI event for any command with id included in the given range. + @endEventTable + + @library{wxcore} + @category{events} + + @see @ref overview_eventhandling +*/ +class wxUpdateUIEvent : public wxCommandEvent +{ +public: + /** + Constructor. + */ + wxUpdateUIEvent(wxWindowID commandId = 0); + + /** + Returns @true if it is appropriate to update (send UI update events to) + this window. + + This function looks at the mode used (see wxUpdateUIEvent::SetMode), + the wxWS_EX_PROCESS_UI_UPDATES flag in @a window, the time update events + were last sent in idle time, and the update interval, to determine whether + events should be sent to this window now. By default this will always + return @true because the update mode is initially wxUPDATE_UI_PROCESS_ALL + and the interval is set to 0; so update events will be sent as often as + possible. You can reduce the frequency that events are sent by changing the + mode and/or setting an update interval. + + @see ResetUpdateTime(), SetUpdateInterval(), SetMode() + */ + static bool CanUpdate(wxWindow* window); + + /** + Check or uncheck the UI element. + */ + void Check(bool check); + + /** + Enable or disable the UI element. + */ + void Enable(bool enable); + + /** + Returns @true if the UI element should be checked. + */ + bool GetChecked() const; + + /** + Returns @true if the UI element should be enabled. + */ + bool GetEnabled() const; + + /** + Static function returning a value specifying how wxWidgets will send update + events: to all windows, or only to those which specify that they will process + the events. + + @see SetMode() + */ + static wxUpdateUIMode GetMode(); + + /** + Returns @true if the application has called Check(). + For wxWidgets internal use only. + */ + bool GetSetChecked() const; + + /** + Returns @true if the application has called Enable(). + For wxWidgets internal use only. + */ + bool GetSetEnabled() const; + + /** + Returns @true if the application has called Show(). + For wxWidgets internal use only. + */ + bool GetSetShown() const; + + /** + Returns @true if the application has called SetText(). + For wxWidgets internal use only. + */ + bool GetSetText() const; + + /** + Returns @true if the UI element should be shown. + */ + bool GetShown() const; + + /** + Returns the text that should be set for the UI element. + */ + wxString GetText() const; + + /** + Returns the current interval between updates in milliseconds. + The value -1 disables updates, 0 updates as frequently as possible. + + @see SetUpdateInterval(). + */ + static long GetUpdateInterval(); + + /** + Used internally to reset the last-updated time to the current time. + + It is assumed that update events are normally sent in idle time, so this + is called at the end of idle processing. + + @see CanUpdate(), SetUpdateInterval(), SetMode() + */ + static void ResetUpdateTime(); + + /** + Specify how wxWidgets will send update events: to all windows, or only to + those which specify that they will process the events. + + @param mode + this parameter may be one of the ::wxUpdateUIMode enumeration values. + The default mode is wxUPDATE_UI_PROCESS_ALL. + */ + static void SetMode(wxUpdateUIMode mode); + + /** + Sets the text for this UI element. + */ + void SetText(const wxString& text); + + /** + Sets the interval between updates in milliseconds. + + Set to -1 to disable updates, or to 0 to update as frequently as possible. + The default is 0. + + Use this to reduce the overhead of UI update events if your application + has a lot of windows. If you set the value to -1 or greater than 0, + you may also need to call wxWindow::UpdateWindowUI at appropriate points + in your application, such as when a dialog is about to be shown. + */ + static void SetUpdateInterval(long updateInterval); + + /** + Show or hide the UI element. + */ + void Show(bool show); +}; + + + +/** + @class wxClipboardTextEvent + @wxheader{event.h} + + This class represents the events generated by a control (typically a + wxTextCtrl but other windows can generate these events as well) when its + content gets copied or cut to, or pasted from the clipboard. + + There are three types of corresponding events wxEVT_COMMAND_TEXT_COPY, + wxEVT_COMMAND_TEXT_CUT and wxEVT_COMMAND_TEXT_PASTE. + + If any of these events is processed (without being skipped) by an event + handler, the corresponding operation doesn't take place which allows to + prevent the text from being copied from or pasted to a control. It is also + possible to examine the clipboard contents in the PASTE event handler and + transform it in some way before inserting in a control -- for example, + changing its case or removing invalid characters. + + Finally notice that a CUT event is always preceded by the COPY event which + makes it possible to only process the latter if it doesn't matter if the + text was copied or cut. + + @note + These events are currently only generated by wxTextCtrl under GTK+. + They are generated by all controls under Windows. + + @beginEventTable{wxClipboardTextEvent} + @event{EVT_TEXT_COPY(id, func)} + Some or all of the controls content was copied to the clipboard. + @event{EVT_TEXT_CUT(id, func)} + Some or all of the controls content was cut (i.e. copied and + deleted). + @event{EVT_TEXT_PASTE(id, func)} + Clipboard content was pasted into the control. + @endEventTable + + + @library{wxcore} + @category{events} + + @see wxClipboard +*/ +class wxClipboardTextEvent : public wxCommandEvent +{ +public: + /** + Constructor. + */ + wxClipboardTextEvent(wxEventType commandType = wxEVT_NULL, int id = 0); +}; + + + +/** + @class wxMouseEvent + @wxheader{event.h} + + This event class contains information about the events generated by the mouse: + they include mouse buttons press and release events and mouse move events. + + All mouse events involving the buttons use @c wxMOUSE_BTN_LEFT for the + left mouse button, @c wxMOUSE_BTN_MIDDLE for the middle one and + @c wxMOUSE_BTN_RIGHT for the right one. And if the system supports more + buttons, the @c wxMOUSE_BTN_AUX1 and @c wxMOUSE_BTN_AUX2 events + can also be generated. Note that not all mice have even a middle button so a + portable application should avoid relying on the events from it (but the right + button click can be emulated using the left mouse button with the control key + under Mac platforms with a single button mouse). + + For the @c wxEVT_ENTER_WINDOW and @c wxEVT_LEAVE_WINDOW events + purposes, the mouse is considered to be inside the window if it is in the + window client area and not inside one of its children. In other words, the + parent window receives @c wxEVT_LEAVE_WINDOW event not only when the + mouse leaves the window entirely but also when it enters one of its children. + + @note Note that under Windows CE mouse enter and leave events are not natively + supported by the system but are generated by wxWidgets itself. This has several + drawbacks: the LEAVE_WINDOW event might be received some time after the mouse + left the window and the state variables for it may have changed during this time. + + @note Note the difference between methods like wxMouseEvent::LeftDown and + wxMouseEvent::LeftIsDown: the former returns @true when the event corresponds + to the left mouse button click while the latter returns @true if the left + mouse button is currently being pressed. For example, when the user is dragging + the mouse you can use wxMouseEvent::LeftIsDown to test whether the left mouse + button is (still) depressed. Also, by convention, if wxMouseEvent::LeftDown + returns @true, wxMouseEvent::LeftIsDown will also return @true in wxWidgets + whatever the underlying GUI behaviour is (which is platform-dependent). + The same applies, of course, to other mouse buttons as well. + + + @beginEventTable{wxMouseEvent} + @event{EVT_LEFT_DOWN(func)} + Process a wxEVT_LEFT_DOWN event. The handler of this event should normally + call event.Skip() to allow the default processing to take place as otherwise + the window under mouse wouldn't get the focus. + @event{EVT_LEFT_UP(func)} + Process a wxEVT_LEFT_UP event. + @event{EVT_LEFT_DCLICK(func)} + Process a wxEVT_LEFT_DCLICK event. + @event{EVT_MIDDLE_DOWN(func)} + Process a wxEVT_MIDDLE_DOWN event. + @event{EVT_MIDDLE_UP(func)} + Process a wxEVT_MIDDLE_UP event. + @event{EVT_MIDDLE_DCLICK(func)} + Process a wxEVT_MIDDLE_DCLICK event. + @event{EVT_RIGHT_DOWN(func)} + Process a wxEVT_RIGHT_DOWN event. + @event{EVT_RIGHT_UP(func)} + Process a wxEVT_RIGHT_UP event. + @event{EVT_RIGHT_DCLICK(func)} + Process a wxEVT_RIGHT_DCLICK event. + @event{EVT_MOUSE_AUX1_DOWN(func)} + Process a wxEVT_MOUSE_AUX1_DOWN event. + @event{EVT_MOUSE_AUX1_UP(func)} + Process a wxEVT_MOUSE_AUX1_UP event. + @event{EVT_MOUSE_AUX1_DCLICK(func)} + Process a wxEVT_MOUSE_AUX1_DCLICK event. + @event{EVT_MOUSE_AUX2_DOWN(func)} + Process a wxEVT_MOUSE_AUX2_DOWN event. + @event{EVT_MOUSE_AUX2_UP(func)} + Process a wxEVT_MOUSE_AUX2_UP event. + @event{EVT_MOUSE_AUX2_DCLICK(func)} + Process a wxEVT_MOUSE_AUX2_DCLICK event. + @event{EVT_MOTION(func)} + Process a wxEVT_MOTION event. + @event{EVT_ENTER_WINDOW(func)} + Process a wxEVT_ENTER_WINDOW event. + @event{EVT_LEAVE_WINDOW(func)} + Process a wxEVT_LEAVE_WINDOW event. + @event{EVT_MOUSEWHEEL(func)} + Process a wxEVT_MOUSEWHEEL event. + @event{EVT_MOUSE_EVENTS(func)} + Process all mouse events. + @endEventTable + + @library{wxcore} + @category{events} + + @see wxKeyEvent::CmdDown +*/ +class wxMouseEvent : public wxEvent +{ +public: + /** + Constructor. Valid event types are: + + @li wxEVT_ENTER_WINDOW + @li wxEVT_LEAVE_WINDOW + @li wxEVT_LEFT_DOWN + @li wxEVT_LEFT_UP + @li wxEVT_LEFT_DCLICK + @li wxEVT_MIDDLE_DOWN + @li wxEVT_MIDDLE_UP + @li wxEVT_MIDDLE_DCLICK + @li wxEVT_RIGHT_DOWN + @li wxEVT_RIGHT_UP + @li wxEVT_RIGHT_DCLICK + @li wxEVT_MOUSE_AUX1_DOWN + @li wxEVT_MOUSE_AUX1_UP + @li wxEVT_MOUSE_AUX1_DCLICK + @li wxEVT_MOUSE_AUX2_DOWN + @li wxEVT_MOUSE_AUX2_UP + @li wxEVT_MOUSE_AUX2_DCLICK + @li wxEVT_MOTION + @li wxEVT_MOUSEWHEEL + */ + wxMouseEvent(wxEventType mouseEventType = wxEVT_NULL); + + /** + Returns @true if the Alt key was down at the time of the event. + */ + bool AltDown() const; + + /** + Returns @true if the event was a first extra button double click. + */ + bool Aux1DClick() const; + + /** + Returns @true if the first extra button mouse button changed to down. + */ + bool Aux1Down() const; + + /** + Returns @true if the first extra button mouse button is currently down, + independent of the current event type. + */ + bool Aux1IsDown() const; + + /** + Returns @true if the first extra button mouse button changed to up. + */ + bool Aux1Up() const; + + /** + Returns @true if the event was a second extra button double click. + */ + bool Aux2DClick() const; + + /** + Returns @true if the second extra button mouse button changed to down. + */ + bool Aux2Down() const; + + /** + Returns @true if the second extra button mouse button is currently down, + independent of the current event type. + */ + bool Aux2IsDown() const; + + /** + Returns @true if the second extra button mouse button changed to up. + */ + bool Aux2Up() const; + + /** + Returns @true if the identified mouse button is changing state. + Valid values of @a button are: + + @li @c wxMOUSE_BTN_LEFT: check if left button was pressed + @li @c wxMOUSE_BTN_MIDDLE: check if middle button was pressed + @li @c wxMOUSE_BTN_RIGHT: check if right button was pressed + @li @c wxMOUSE_BTN_AUX1: check if the first extra button was pressed + @li @c wxMOUSE_BTN_AUX2: check if the second extra button was pressed + @li @c wxMOUSE_BTN_ANY: check if any button was pressed + + @todo introduce wxMouseButton enum + */ + bool Button(int button) const; + + /** + If the argument is omitted, this returns @true if the event was a mouse + double click event. Otherwise the argument specifies which double click event + was generated (see Button() for the possible values). + */ + bool ButtonDClick(int but = wxMOUSE_BTN_ANY) const; + + /** + If the argument is omitted, this returns @true if the event was a mouse + button down event. Otherwise the argument specifies which button-down event + was generated (see Button() for the possible values). + */ + bool ButtonDown(int = wxMOUSE_BTN_ANY) const; + + /** + If the argument is omitted, this returns @true if the event was a mouse + button up event. Otherwise the argument specifies which button-up event + was generated (see Button() for the possible values). + */ + bool ButtonUp(int = wxMOUSE_BTN_ANY) const; + + /** + Same as MetaDown() under Mac, same as ControlDown() elsewhere. + + @see wxKeyEvent::CmdDown + */ + bool CmdDown() const; + + /** + Returns @true if the control key was down at the time of the event. + */ + bool ControlDown() const; + + /** + Returns @true if this was a dragging event (motion while a button is depressed). + + @see Moving() + */ + bool Dragging() const; + + /** + Returns @true if the mouse was entering the window. + + @see Leaving() + */ + bool Entering() const; + + /** + Returns the mouse button which generated this event or @c wxMOUSE_BTN_NONE + if no button is involved (for mouse move, enter or leave event, for example). + Otherwise @c wxMOUSE_BTN_LEFT is returned for the left button down, up and + double click events, @c wxMOUSE_BTN_MIDDLE and @c wxMOUSE_BTN_RIGHT + for the same events for the middle and the right buttons respectively. + */ + int GetButton() const; + + /** + Returns the number of mouse clicks for this event: 1 for a simple click, 2 + for a double-click, 3 for a triple-click and so on. + + Currently this function is implemented only in wxMac and returns -1 for the + other platforms (you can still distinguish simple clicks from double-clicks as + they generate different kinds of events however). + + @since 2.9.0 + */ + int GetClickCount() const; + + /** + Returns the configured number of lines (or whatever) to be scrolled per + wheel action. Defaults to three. + */ + int GetLinesPerAction() const; + + /** + Returns the logical mouse position in pixels (i.e. translated according to the + translation set for the DC, which usually indicates that the window has been + scrolled). + */ + wxPoint GetLogicalPosition(const wxDC& dc) const; + + //@{ + /** + Sets *x and *y to the position at which the event occurred. + Returns the physical mouse position in pixels. + + Note that if the mouse event has been artificially generated from a special + keyboard combination (e.g. under Windows when the "menu" key is pressed), the + returned position is ::wxDefaultPosition. + */ + wxPoint GetPosition() const; + void GetPosition(wxCoord* x, wxCoord* y) const; + void GetPosition(long* x, long* y) const; + //@} + + /** + Get wheel delta, normally 120. + + This is the threshold for action to be taken, and one such action + (for example, scrolling one increment) should occur for each delta. + */ + int GetWheelDelta() const; + + /** + Get wheel rotation, positive or negative indicates direction of rotation. + + Current devices all send an event when rotation is at least +/-WheelDelta, but + finer resolution devices can be created in the future. + + Because of this you shouldn't assume that one event is equal to 1 line, but you + should be able to either do partial line scrolling or wait until several + events accumulate before scrolling. + */ + int GetWheelRotation() const; + + /** + Returns X coordinate of the physical mouse event position. + */ + wxCoord GetX() const; + + /** + Returns Y coordinate of the physical mouse event position. + */ + wxCoord GetY() const; + + /** + Returns @true if the event was a mouse button event (not necessarily a button + down event - that may be tested using ButtonDown()). + */ + bool IsButton() const; + + /** + Returns @true if the system has been setup to do page scrolling with + the mouse wheel instead of line scrolling. + */ + bool IsPageScroll() const; + + /** + Returns @true if the mouse was leaving the window. + + @see Entering(). + */ + bool Leaving() const; + + /** + Returns @true if the event was a left double click. + */ + bool LeftDClick() const; + + /** + Returns @true if the left mouse button changed to down. + */ + bool LeftDown() const; + + /** + Returns @true if the left mouse button is currently down, independent + of the current event type. + + Please notice that it is not the same as LeftDown() which returns @true if the + event was generated by the left mouse button being pressed. Rather, it simply + describes the state of the left mouse button at the time when the event was + generated (so while it will be @true for a left click event, it can also be @true + for a right click if it happened while the left mouse button was pressed). + + This event is usually used in the mouse event handlers which process "move + mouse" messages to determine whether the user is (still) dragging the mouse. + */ + bool LeftIsDown() const; + + /** + Returns @true if the left mouse button changed to up. + */ + bool LeftUp() const; + + /** + Returns @true if the Meta key was down at the time of the event. + */ + bool MetaDown() const; + + /** + Returns @true if the event was a middle double click. + */ + bool MiddleDClick() const; + + /** + Returns @true if the middle mouse button changed to down. + */ + bool MiddleDown() const; + + /** + Returns @true if the middle mouse button is currently down, independent + of the current event type. + */ + bool MiddleIsDown() const; + + /** + Returns @true if the middle mouse button changed to up. + */ + bool MiddleUp() const; + + /** + Returns @true if this was a motion event and no mouse buttons were pressed. + If any mouse button is held pressed, then this method returns @false and + Dragging() returns @true. + */ + bool Moving() const; + + /** + Returns @true if the event was a right double click. + */ + bool RightDClick() const; + + /** + Returns @true if the right mouse button changed to down. + */ + bool RightDown() const; + + /** + Returns @true if the right mouse button is currently down, independent + of the current event type. + */ + bool RightIsDown() const; + + /** + Returns @true if the right mouse button changed to up. + */ + bool RightUp() const; + + /** + Returns @true if the shift key was down at the time of the event. + */ + bool ShiftDown() const; +}; + + + +/** + @class wxDropFilesEvent + @wxheader{event.h} + + This class is used for drop files events, that is, when files have been dropped + onto the window. This functionality is currently only available under Windows. + + The window must have previously been enabled for dropping by calling + wxWindow::DragAcceptFiles(). + + Important note: this is a separate implementation to the more general drag and drop + implementation documented in the @ref overview_dnd. It uses the older, Windows + message-based approach of dropping files. + + @beginEventTable{wxDropFilesEvent} + @event{EVT_DROP_FILES(func)} + Process a wxEVT_DROP_FILES event. + @endEventTable + + @onlyfor{wxmsw} + + @library{wxcore} + @category{events} + + @see @ref overview_eventhandling +*/ +class wxDropFilesEvent : public wxEvent +{ +public: + /** + Constructor. + */ + wxDropFilesEvent(wxEventType id = 0, int noFiles = 0, + wxString* files = NULL); + + /** + Returns an array of filenames. + */ + wxString* GetFiles() const; + + /** + Returns the number of files dropped. + */ + int GetNumberOfFiles() const; + + /** + Returns the position at which the files were dropped. + Returns an array of filenames. + */ + wxPoint GetPosition() const; +}; + + + +/** + @class wxCommandEvent + @wxheader{event.h} + + This event class contains information about command events, which originate + from a variety of simple controls. + + More complex controls, such as wxTreeCtrl, have separate command event classes. + + @beginEventTable{wxCommandEvent} + @event{EVT_COMMAND(id, event, func)} + Process a command, supplying the window identifier, command event identifier, + and member function. + @event{EVT_COMMAND_RANGE(id1, id2, event, func)} + Process a command for a range of window identifiers, supplying the minimum and + maximum window identifiers, command event identifier, and member function. + @event{EVT_BUTTON(id, func)} + Process a wxEVT_COMMAND_BUTTON_CLICKED command, which is generated by a wxButton control. + @event{EVT_CHECKBOX(id, func)} + Process a wxEVT_COMMAND_CHECKBOX_CLICKED command, which is generated by a wxCheckBox control. + @event{EVT_CHOICE(id, func)} + Process a wxEVT_COMMAND_CHOICE_SELECTED command, which is generated by a wxChoice control. + @event{EVT_COMBOBOX(id, func)} + Process a wxEVT_COMMAND_COMBOBOX_SELECTED command, which is generated by a wxComboBox control. + @event{EVT_LISTBOX(id, func)} + Process a wxEVT_COMMAND_LISTBOX_SELECTED command, which is generated by a wxListBox control. + @event{EVT_LISTBOX_DCLICK(id, func)} + Process a wxEVT_COMMAND_LISTBOX_DOUBLECLICKED command, which is generated by a wxListBox control. + @event{EVT_MENU(id, func)} + Process a wxEVT_COMMAND_MENU_SELECTED command, which is generated by a menu item. + @event{EVT_MENU_RANGE(id1, id2, func)} + Process a wxEVT_COMMAND_MENU_RANGE command, which is generated by a range of menu items. + @event{EVT_CONTEXT_MENU(func)} + Process the event generated when the user has requested a popup menu to appear by + pressing a special keyboard key (under Windows) or by right clicking the mouse. + @event{EVT_RADIOBOX(id, func)} + Process a wxEVT_COMMAND_RADIOBOX_SELECTED command, which is generated by a wxRadioBox control. + @event{EVT_RADIOBUTTON(id, func)} + Process a wxEVT_COMMAND_RADIOBUTTON_SELECTED command, which is generated by a wxRadioButton control. + @event{EVT_SCROLLBAR(id, func)} + Process a wxEVT_COMMAND_SCROLLBAR_UPDATED command, which is generated by a wxScrollBar + control. This is provided for compatibility only; more specific scrollbar event macros + should be used instead (see wxScrollEvent). + @event{EVT_SLIDER(id, func)} + Process a wxEVT_COMMAND_SLIDER_UPDATED command, which is generated by a wxSlider control. + @event{EVT_TEXT(id, func)} + Process a wxEVT_COMMAND_TEXT_UPDATED command, which is generated by a wxTextCtrl control. + @event{EVT_TEXT_ENTER(id, func)} + Process a wxEVT_COMMAND_TEXT_ENTER command, which is generated by a wxTextCtrl control. + Note that you must use wxTE_PROCESS_ENTER flag when creating the control if you want it + to generate such events. + @event{EVT_TEXT_MAXLEN(id, func)} + Process a wxEVT_COMMAND_TEXT_MAXLEN command, which is generated by a wxTextCtrl control + when the user tries to enter more characters into it than the limit previously set + with SetMaxLength(). + @event{EVT_TOGGLEBUTTON(id, func)} + Process a wxEVT_COMMAND_TOGGLEBUTTON_CLICKED event. + @event{EVT_TOOL(id, func)} + Process a wxEVT_COMMAND_TOOL_CLICKED event (a synonym for wxEVT_COMMAND_MENU_SELECTED). + Pass the id of the tool. + @event{EVT_TOOL_RANGE(id1, id2, func)} + Process a wxEVT_COMMAND_TOOL_CLICKED event for a range of identifiers. Pass the ids of the tools. + @event{EVT_TOOL_RCLICKED(id, func)} + Process a wxEVT_COMMAND_TOOL_RCLICKED event. Pass the id of the tool. + @event{EVT_TOOL_RCLICKED_RANGE(id1, id2, func)} + Process a wxEVT_COMMAND_TOOL_RCLICKED event for a range of ids. Pass the ids of the tools. + @event{EVT_TOOL_ENTER(id, func)} + Process a wxEVT_COMMAND_TOOL_ENTER event. Pass the id of the toolbar itself. + The value of wxCommandEvent::GetSelection() is the tool id, or -1 if the mouse cursor + has moved off a tool. + @event{EVT_COMMAND_LEFT_CLICK(id, func)} + Process a wxEVT_COMMAND_LEFT_CLICK command, which is generated by a control (Windows 95 and NT only). + @event{EVT_COMMAND_LEFT_DCLICK(id, func)} + Process a wxEVT_COMMAND_LEFT_DCLICK command, which is generated by a control (Windows 95 and NT only). + @event{EVT_COMMAND_RIGHT_CLICK(id, func)} + Process a wxEVT_COMMAND_RIGHT_CLICK command, which is generated by a control (Windows 95 and NT only). + @event{EVT_COMMAND_SET_FOCUS(id, func)} + Process a wxEVT_COMMAND_SET_FOCUS command, which is generated by a control (Windows 95 and NT only). + @event{EVT_COMMAND_KILL_FOCUS(id, func)} + Process a wxEVT_COMMAND_KILL_FOCUS command, which is generated by a control (Windows 95 and NT only). + @event{EVT_COMMAND_ENTER(id, func)} + Process a wxEVT_COMMAND_ENTER command, which is generated by a control. + @endEventTable + + @library{wxcore} + @category{events} +*/ +class wxCommandEvent : public wxEvent +{ +public: + /** + Constructor. + */ + wxCommandEvent(wxEventType commandEventType = 0, int id = 0); + + /** + Returns client data pointer for a listbox or choice selection event + (not valid for a deselection). + */ + void* GetClientData() const; + + /** + Returns client object pointer for a listbox or choice selection event + (not valid for a deselection). + */ + wxClientData* GetClientObject() const; + + /** + Returns extra information dependant on the event objects type. + + If the event comes from a listbox selection, it is a boolean + determining whether the event was a selection (@true) or a + deselection (@false). A listbox deselection only occurs for + multiple-selection boxes, and in this case the index and string values + are indeterminate and the listbox must be examined by the application. + */ + long GetExtraLong() const; + + /** + Returns the integer identifier corresponding to a listbox, choice or + radiobox selection (only if the event was a selection, not a deselection), + or a boolean value representing the value of a checkbox. + */ + int GetInt() const; + + /** + Returns item index for a listbox or choice selection event (not valid for + a deselection). + */ + int GetSelection() const; + + /** + Returns item string for a listbox or choice selection event. If one + or several items have been deselected, returns the index of the first + deselected item. If some items have been selected and others deselected + at the same time, it will return the index of the first selected item. + */ + wxString GetString() const; + + /** + This method can be used with checkbox and menu events: for the checkboxes, the + method returns @true for a selection event and @false for a deselection one. + For the menu events, this method indicates if the menu item just has become + checked or unchecked (and thus only makes sense for checkable menu items). + + Notice that this method can not be used with wxCheckListBox currently. + */ + bool IsChecked() const; + + /** + For a listbox or similar event, returns @true if it is a selection, @false + if it is a deselection. If some items have been selected and others deselected + at the same time, it will return @true. + */ + bool IsSelection() const; + + /** + Sets the client data for this event. + */ + void SetClientData(void* clientData); + + /** + Sets the client object for this event. The client object is not owned by the + event object and the event object will not delete the client object in its destructor. + + The client object must be owned and deleted by another object (e.g. a control) + that has longer life time than the event object. + */ + void SetClientObject(wxClientData* clientObject); + + /** + Sets the @b m_extraLong member. + */ + void SetExtraLong(long extraLong); + + /** + Sets the @b m_commandInt member. + */ + void SetInt(int intCommand); + + /** + Sets the @b m_commandString member. + */ + void SetString(const wxString& string); +}; + + + +/** + @class wxActivateEvent + @wxheader{event.h} + + An activate event is sent when a window or application is being activated + or deactivated. + + @beginEventTable{wxActivateEvent} + @event{EVT_ACTIVATE(func)} + Process a wxEVT_ACTIVATE event. + @event{EVT_ACTIVATE_APP(func)} + Process a wxEVT_ACTIVATE_APP event. + @event{EVT_HIBERNATE(func)} + Process a hibernate event, supplying the member function. This event applies + to wxApp only, and only on Windows SmartPhone and PocketPC. + It is generated when the system is low on memory; the application should free + up as much memory as possible, and restore full working state when it receives + a wxEVT_ACTIVATE or wxEVT_ACTIVATE_APP event. + @endEventTable + + + @library{wxcore} + @category{events} + + @see @ref overview_eventhandling, wxApp::IsActive +*/ +class wxActivateEvent : public wxEvent +{ +public: + /** + Constructor. + */ + wxActivateEvent(wxEventType eventType = wxEVT_NULL, bool active = true, + int id = 0); + + /** + Returns @true if the application or window is being activated, @false otherwise. + */ + bool GetActive() const; +}; + + + +/** + @class wxContextMenuEvent + @wxheader{event.h} + + This class is used for context menu events, sent to give + the application a chance to show a context (popup) menu. + + Note that if wxContextMenuEvent::GetPosition returns wxDefaultPosition, this + means that the event originated from a keyboard context button event, and you + should compute a suitable position yourself, for example by calling wxGetMousePosition(). + + When a keyboard context menu button is pressed on Windows, a right-click event + with default position is sent first, and if this event is not processed, the + context menu event is sent. So if you process mouse events and you find your + context menu event handler is not being called, you could call wxEvent::Skip() + for mouse right-down events. + + @beginEventTable{wxContextMenuEvent} + @event{EVT_CONTEXT_MENU(func)} + A right click (or other context menu command depending on platform) has been detected. + @endEventTable + + + @library{wxcore} + @category{events} + + @see wxCommandEvent, @ref overview_eventhandling +*/ +class wxContextMenuEvent : public wxCommandEvent +{ +public: + /** + Constructor. + */ + wxContextMenuEvent(wxEventType id = wxEVT_NULL, int id = 0, + const wxPoint& pos = wxDefaultPosition); + + /** + Returns the position in screen coordinates at which the menu should be shown. + Use wxWindow::ScreenToClient to convert to client coordinates. + + You can also omit a position from wxWindow::PopupMenu in order to use + the current mouse pointer position. + + If the event originated from a keyboard event, the value returned from this + function will be wxDefaultPosition. + */ + const wxPoint& GetPosition() const; + + /** + Sets the position at which the menu should be shown. + */ + void SetPosition(const wxPoint& point); +}; + + + +/** + @class wxEraseEvent + @wxheader{event.h} + + An erase event is sent when a window's background needs to be repainted. + + On some platforms, such as GTK+, this event is simulated (simply generated just + before the paint event) and may cause flicker. It is therefore recommended that + you set the text background colour explicitly in order to prevent flicker. + The default background colour under GTK+ is grey. + + To intercept this event, use the EVT_ERASE_BACKGROUND macro in an event table + definition. + + You must call wxEraseEvent::GetDC and use the returned device context if it is + non-@NULL. If it is @NULL, create your own temporary wxClientDC object. + + @remarks + Use the device context returned by GetDC to draw on, don't create + a wxPaintDC in the event handler. + + @beginEventTable{wxEraseEvent} + @event{EVT_ERASE_BACKGROUND(func)} + Process a wxEVT_ERASE_BACKGROUND event. + @endEventTable + + @library{wxcore} + @category{events} + + @see @ref overview_eventhandling +*/ +class wxEraseEvent : public wxEvent +{ +public: + /** + Constructor. + */ + wxEraseEvent(int id = 0, wxDC* dc = NULL); + + /** + Returns the device context associated with the erase event to draw on. + */ + wxDC* GetDC() const; +}; + + + +/** + @class wxFocusEvent + @wxheader{event.h} + + A focus event is sent when a window's focus changes. The window losing focus + receives a "kill focus" event while the window gaining it gets a "set focus" one. + + Notice that the set focus event happens both when the user gives focus to the + window (whether using the mouse or keyboard) and when it is done from the + program itself using wxWindow::SetFocus. + + @beginEventTable{wxFocusEvent} + @event{EVT_SET_FOCUS(func)} + Process a wxEVT_SET_FOCUS event. + @event{EVT_KILL_FOCUS(func)} + Process a wxEVT_KILL_FOCUS event. + @endEventTable + + @library{wxcore} + @category{events} + + @see @ref overview_eventhandling +*/ +class wxFocusEvent : public wxEvent +{ +public: + /** + Constructor. + */ + wxFocusEvent(wxEventType eventType = wxEVT_NULL, int id = 0); + + /** + Returns the window associated with this event, that is the window which had the + focus before for the @c wxEVT_SET_FOCUS event and the window which is + going to receive focus for the @c wxEVT_KILL_FOCUS one. + + Warning: the window pointer may be @NULL! + */ + wxWindow *GetWindow() const; +}; + + + +/** + @class wxChildFocusEvent + @wxheader{event.h} + + A child focus event is sent to a (parent-)window when one of its child windows + gains focus, so that the window could restore the focus back to its corresponding + child if it loses it now and regains later. + + Notice that child window is the direct child of the window receiving event. + Use wxWindow::FindFocus() to retreive the window which is actually getting focus. + + @beginEventTable{wxChildFocusEvent} + @event{EVT_CHILD_FOCUS(func)} + Process a wxEVT_CHILD_FOCUS event. + @endEventTable + + @library{wxcore} + @category{events} + + @see @ref overview_eventhandling +*/ +class wxChildFocusEvent : public wxCommandEvent +{ +public: + /** + Constructor. + + @param win + The direct child which is (or which contains the window which is) receiving + the focus. + */ + wxChildFocusEvent(wxWindow* win = NULL); + + /** + Returns the direct child which receives the focus, or a (grand-)parent of the + control receiving the focus. + + To get the actually focused control use wxWindow::FindFocus. + */ + wxWindow *GetWindow() const; +}; + + + +/** + @class wxMouseCaptureLostEvent + @wxheader{event.h} + + An mouse capture lost event is sent to a window that obtained mouse capture, + which was subsequently loss due to "external" event, for example when a dialog + box is shown or if another application captures the mouse. + + If this happens, this event is sent to all windows that are on capture stack + (i.e. called CaptureMouse, but didn't call ReleaseMouse yet). The event is + not sent if the capture changes because of a call to CaptureMouse or + ReleaseMouse. + + This event is currently emitted under Windows only. + + @beginEventTable{wxMouseCaptureLostEvent} + @event{EVT_MOUSE_CAPTURE_LOST(func)} + Process a wxEVT_MOUSE_CAPTURE_LOST event. + @endEventTable + + @onlyfor{wxmsw} + + @library{wxcore} + @category{events} + + @see wxMouseCaptureChangedEvent, @ref overview_eventhandling, + wxWindow::CaptureMouse, wxWindow::ReleaseMouse, wxWindow::GetCapture +*/ +class wxMouseCaptureLostEvent : public wxEvent +{ +public: + /** + Constructor. + */ + wxMouseCaptureLostEvent(wxWindowID windowId = 0); +}; + + + +/** + @class wxNotifyEvent + @wxheader{event.h} + + This class is not used by the event handlers by itself, but is a base class + for other event classes (such as wxNotebookEvent). + + It (or an object of a derived class) is sent when the controls state is being + changed and allows the program to wxNotifyEvent::Veto() this change if it wants + to prevent it from happening. + + @library{wxcore} + @category{events} + + @see wxNotebookEvent +*/ +class wxNotifyEvent : public wxCommandEvent +{ +public: + /** + Constructor (used internally by wxWidgets only). + */ + wxNotifyEvent(wxEventType eventType = wxEVT_NULL, int id = 0); + + /** + This is the opposite of Veto(): it explicitly allows the event to be processed. + For most events it is not necessary to call this method as the events are allowed + anyhow but some are forbidden by default (this will be mentioned in the corresponding + event description). + */ + void Allow(); + + /** + Returns @true if the change is allowed (Veto() hasn't been called) or @false + otherwise (if it was). + */ + bool IsAllowed() const; + + /** + Prevents the change announced by this event from happening. + + It is in general a good idea to notify the user about the reasons for vetoing + the change because otherwise the applications behaviour (which just refuses to + do what the user wants) might be quite surprising. + */ + void Veto(); +}; + + + + +/** + Indicates how a wxHelpEvent was generated. +*/ +enum wxHelpEventOrigin +{ + wxHE_ORIGIN_UNKNOWN = -1, /**< unrecognized event source. */ + wxHE_ORIGIN_KEYBOARD, /**< event generated from F1 key press. */ + + /** event generated by wxContextHelp or from the [?] button on + the title bar (Windows). */ + wxHE_ORIGIN_HELPBUTTON +}; + +/** + @class wxHelpEvent + @wxheader{event.h} + + A help event is sent when the user has requested context-sensitive help. + This can either be caused by the application requesting context-sensitive help mode + via wxContextHelp, or (on MS Windows) by the system generating a WM_HELP message when + the user pressed F1 or clicked on the query button in a dialog caption. + + A help event is sent to the window that the user clicked on, and is propagated + up the window hierarchy until the event is processed or there are no more event + handlers. + + The application should call wxEvent::GetId to check the identity of the + clicked-on window, and then either show some suitable help or call wxEvent::Skip() + if the identifier is unrecognised. + + Calling Skip is important because it allows wxWidgets to generate further + events for ancestors of the clicked-on window. Otherwise it would be impossible to + show help for container windows, since processing would stop after the first window + found. + + @beginEventTable{wxHelpEvent} + @event{EVT_HELP(id, func)} + Process a wxEVT_HELP event. + @event{EVT_HELP_RANGE(id1, id2, func)} + Process a wxEVT_HELP event for a range of ids. + @endEventTable + + @library{wxcore} + @category{events} + + @see wxContextHelp, wxDialog, @ref overview_eventhandling +*/ +class wxHelpEvent : public wxCommandEvent +{ +public: + /** + Constructor. + */ + wxHelpEvent(wxEventType type = wxEVT_NULL, + wxWindowID winid = 0, + const wxPoint& pt = wxDefaultPosition, + wxHelpEventOrigin origin = wxHE_ORIGIN_UNKNOWN); + + /** + Returns the origin of the help event which is one of the ::wxHelpEventOrigin + values. + + The application may handle events generated using the keyboard or mouse + differently, e.g. by using wxGetMousePosition() for the mouse events. + + @see SetOrigin() + */ + wxHelpEventOrigin GetOrigin() const; + + /** + Returns the left-click position of the mouse, in screen coordinates. + This allows the application to position the help appropriately. + */ + const wxPoint& GetPosition() const; + + /** + Set the help event origin, only used internally by wxWidgets normally. + + @see GetOrigin() + */ + void SetOrigin(wxHelpEventOrigin); + + /** + Sets the left-click position of the mouse, in screen coordinates. + */ + void SetPosition(const wxPoint& pt); +}; + + + +/** + @class wxScrollEvent + @wxheader{event.h} + + A scroll event holds information about events sent from stand-alone + scrollbars (see wxScrollBar) and sliders (see wxSlider). + + Note that scrolled windows send the wxScrollWinEvent which does not derive from + wxCommandEvent, but from wxEvent directly - don't confuse these two kinds of + events and use the event table macros mentioned below only for the scrollbar-like + controls. + + @section wxscrollevent_diff The difference between EVT_SCROLL_THUMBRELEASE and EVT_SCROLL_CHANGED + + The EVT_SCROLL_THUMBRELEASE event is only emitted when actually dragging the thumb + using the mouse and releasing it (This EVT_SCROLL_THUMBRELEASE event is also followed + by an EVT_SCROLL_CHANGED event). + + The EVT_SCROLL_CHANGED event also occurs when using the keyboard to change the thumb + position, and when clicking next to the thumb (In all these cases the EVT_SCROLL_THUMBRELEASE + event does not happen). + + In short, the EVT_SCROLL_CHANGED event is triggered when scrolling/ moving has finished + independently of the way it had started. Please see the widgets sample ("Slider" page) + to see the difference between EVT_SCROLL_THUMBRELEASE and EVT_SCROLL_CHANGED in action. + + @remarks + Note that unless specifying a scroll control identifier, you will need to test for scrollbar + orientation with wxScrollEvent::GetOrientation, since horizontal and vertical scroll events + are processed using the same event handler. + + @beginEventTable{wxScrollEvent} + You can use EVT_COMMAND_SCROLL... macros with window IDs for when intercepting + scroll events from controls, or EVT_SCROLL... macros without window IDs for + intercepting scroll events from the receiving window -- except for this, the + macros behave exactly the same. + @event{EVT_SCROLL(func)} + Process all scroll events. + @event{EVT_SCROLL_TOP(func)} + Process wxEVT_SCROLL_TOP scroll-to-top events (minimum position). + @event{EVT_SCROLL_BOTTOM(func)} + Process wxEVT_SCROLL_BOTTOM scroll-to-bottom events (maximum position). + @event{EVT_SCROLL_LINEUP(func)} + Process wxEVT_SCROLL_LINEUP line up events. + @event{EVT_SCROLL_LINEDOWN(func)} + Process wxEVT_SCROLL_LINEDOWN line down events. + @event{EVT_SCROLL_PAGEUP(func)} + Process wxEVT_SCROLL_PAGEUP page up events. + @event{EVT_SCROLL_PAGEDOWN(func)} + Process wxEVT_SCROLL_PAGEDOWN page down events. + @event{EVT_SCROLL_THUMBTRACK(func)} + Process wxEVT_SCROLL_THUMBTRACK thumbtrack events (frequent events sent as the + user drags the thumbtrack). + @event{EVT_SCROLL_THUMBRELEASE(func)} + Process wxEVT_SCROLL_THUMBRELEASE thumb release events. + @event{EVT_SCROLL_CHANGED(func)} + Process wxEVT_SCROLL_CHANGED end of scrolling events (MSW only). + @event{EVT_COMMAND_SCROLL(id, func)} + Process all scroll events. + @event{EVT_COMMAND_SCROLL_TOP(id, func)} + Process wxEVT_SCROLL_TOP scroll-to-top events (minimum position). + @event{EVT_COMMAND_SCROLL_BOTTOM(id, func)} + Process wxEVT_SCROLL_BOTTOM scroll-to-bottom events (maximum position). + @event{EVT_COMMAND_SCROLL_LINEUP(id, func)} + Process wxEVT_SCROLL_LINEUP line up events. + @event{EVT_COMMAND_SCROLL_LINEDOWN(id, func)} + Process wxEVT_SCROLL_LINEDOWN line down events. + @event{EVT_COMMAND_SCROLL_PAGEUP(id, func)} + Process wxEVT_SCROLL_PAGEUP page up events. + @event{EVT_COMMAND_SCROLL_PAGEDOWN(id, func)} + Process wxEVT_SCROLL_PAGEDOWN page down events. + @event{EVT_COMMAND_SCROLL_THUMBTRACK(id, func)} + Process wxEVT_SCROLL_THUMBTRACK thumbtrack events (frequent events sent + as the user drags the thumbtrack). + @event{EVT_COMMAND_SCROLL_THUMBRELEASE(func)} + Process wxEVT_SCROLL_THUMBRELEASE thumb release events. + @event{EVT_COMMAND_SCROLL_CHANGED(func)} + Process wxEVT_SCROLL_CHANGED end of scrolling events (MSW only). + @endEventTable + + @library{wxcore} + @category{events} + + @see wxScrollBar, wxSlider, wxSpinButton, wxScrollWinEvent, @ref overview_eventhandling +*/ +class wxScrollEvent : public wxCommandEvent +{ +public: + /** + Constructor. + */ + wxScrollEvent(wxEventType commandType = wxEVT_NULL, int id = 0, int pos = 0, + int orientation = 0); + + /** + Returns wxHORIZONTAL or wxVERTICAL, depending on the orientation of the + scrollbar. + */ + int GetOrientation() const; + + /** + Returns the position of the scrollbar. + */ + int GetPosition() const; +}; + +/** + See wxIdleEvent::SetMode() for more info. +*/ +enum wxIdleMode +{ + /** Send idle events to all windows */ + wxIDLE_PROCESS_ALL, + + /** Send idle events to windows that have the wxWS_EX_PROCESS_IDLE flag specified */ + wxIDLE_PROCESS_SPECIFIED +}; + + +/** + @class wxIdleEvent + @wxheader{event.h} + + This class is used for idle events, which are generated when the system becomes + idle. Note that, unless you do something specifically, the idle events are not + sent if the system remains idle once it has become it, e.g. only a single idle + event will be generated until something else resulting in more normal events + happens and only then is the next idle event sent again. + + If you need to ensure a continuous stream of idle events, you can either use + wxIdleEvent::RequestMore method in your handler or call wxWakeUpIdle() periodically + (for example from a timer event handler), but note that both of these approaches + (and especially the first one) increase the system load and so should be avoided + if possible. + + By default, idle events are sent to all windows (and also wxApp, as usual). + If this is causing a significant overhead in your application, you can call + wxIdleEvent::SetMode with the value wxIDLE_PROCESS_SPECIFIED, and set the + wxWS_EX_PROCESS_IDLE extra window style for every window which should receive + idle events. + + @beginEventTable{wxIdleEvent} + @event{EVT_IDLE(func)} + Process a wxEVT_IDLE event. + @endEventTable + + @library{wxbase} + @category{events} + + @see @ref overview_eventhandling, wxUpdateUIEvent, wxWindow::OnInternalIdle +*/ +class wxIdleEvent : public wxEvent +{ +public: + /** + Constructor. + */ + wxIdleEvent(); + + /** + Returns @true if it is appropriate to send idle events to this window. + + This function looks at the mode used (see wxIdleEvent::SetMode), + and the wxWS_EX_PROCESS_IDLE style in @a window to determine whether idle + events should be sent to this window now. + + By default this will always return @true because the update mode is initially + wxIDLE_PROCESS_ALL. You can change the mode to only send idle events to + windows with the wxWS_EX_PROCESS_IDLE extra window style set. + + @see SetMode() + */ + static bool CanSend(wxWindow* window); + + /** + Static function returning a value specifying how wxWidgets will send idle + events: to all windows, or only to those which specify that they + will process the events. + + @see SetMode(). + */ + static wxIdleMode GetMode(); + + /** + Returns @true if the OnIdle function processing this event requested more + processing time. + + @see RequestMore() + */ + bool MoreRequested() const; + + /** + Tells wxWidgets that more processing is required. + + This function can be called by an OnIdle handler for a window or window event + handler to indicate that wxApp::OnIdle should forward the OnIdle event once + more to the application windows. + + If no window calls this function during OnIdle, then the application will + remain in a passive event loop (not calling OnIdle) until a new event is + posted to the application by the windowing system. + + @see MoreRequested() + */ + void RequestMore(bool needMore = true); + + /** + Static function for specifying how wxWidgets will send idle events: to + all windows, or only to those which specify that they will process the events. + + @param mode + Can be one of the ::wxIdleMode values. + The default is wxIDLE_PROCESS_ALL. + */ + static void SetMode(wxIdleMode mode); +}; + + + +/** + @class wxInitDialogEvent + @wxheader{event.h} + + A wxInitDialogEvent is sent as a dialog or panel is being initialised. + Handlers for this event can transfer data to the window. + + The default handler calls wxWindow::TransferDataToWindow. + + @beginEventTable{wxInitDialogEvent} + @event{EVT_INIT_DIALOG(func)} + Process a wxEVT_INIT_DIALOG event. + @endEventTable + + @library{wxcore} + @category{events} + + @see @ref overview_eventhandling +*/ +class wxInitDialogEvent : public wxEvent +{ +public: + /** + Constructor. + */ + wxInitDialogEvent(int id = 0); +}; + + + +/** + @class wxWindowDestroyEvent + @wxheader{event.h} + + This event is sent from the wxWindow destructor wxWindow::~wxWindow() when a + window is destroyed. + + When a class derived from wxWindow is destroyed its destructor will have + already run by the time this event is sent. Therefore this event will not + usually be received at all. + + To receive this event wxEvtHandler::Connect() must be used (using an event + table macro will not work). Since it is received after the destructor has run, + an object should not handle its own wxWindowDestroyEvent, but it can be used + to get notification of the destruction of another window. + + @library{wxcore} + @category{events} + + @see @ref overview_eventhandling, wxWindowCreateEvent +*/ +class wxWindowDestroyEvent : public wxCommandEvent +{ +public: + /** + Constructor. + */ + wxWindowDestroyEvent(wxWindow* win = NULL); +}; + + +/** + The possible flag values for a wxNavigationKeyEvent. +*/ +enum wxNavigationKeyEventFlags +{ + wxNKEF_IS_BACKWARD = 0x0000, + wxNKEF_IS_FORWARD = 0x0001, + wxNKEF_WINCHANGE = 0x0002, + wxNKEF_FROMTAB = 0x0004 +}; + + +/** + @class wxNavigationKeyEvent + @wxheader{event.h} + + This event class contains information about navigation events, + generated by navigation keys such as tab and page down. + + This event is mainly used by wxWidgets implementations. + A wxNavigationKeyEvent handler is automatically provided by wxWidgets + when you make a class into a control container with the macro + WX_DECLARE_CONTROL_CONTAINER. + + @beginEventTable{wxNavigationKeyEvent} + @event{EVT_NAVIGATION_KEY(func)} + Process a navigation key event. + @endEventTable + + @library{wxcore} + @category{events} + + @see wxWindow::Navigate, wxWindow::NavigateIn +*/ +class wxNavigationKeyEvent : public wxEvent +{ +public: + wxNavigationKeyEvent(); + wxNavigationKeyEvent(const wxNavigationKeyEvent& event); + + /** + Returns the child that has the focus, or @NULL. + */ + wxWindow* GetCurrentFocus() const; + + /** + Returns @true if the navigation was in the forward direction. + */ + bool GetDirection() const; + + /** + Returns @true if the navigation event was from a tab key. + This is required for proper navigation over radio buttons. + */ + bool IsFromTab() const; + + /** + Returns @true if the navigation event represents a window change + (for example, from Ctrl-Page Down in a notebook). + */ + bool IsWindowChange() const; + + /** + Sets the current focus window member. + */ + void SetCurrentFocus(wxWindow* currentFocus); + + /** + Sets the direction to forward if @a direction is @true, or backward + if @false. + */ + void SetDirection(bool direction); + + /** + Sets the flags for this event. + The @a flags can be a combination of the ::wxNavigationKeyEventFlags values. + */ + void SetFlags(long flags); + + /** + Marks the navigation event as from a tab key. + */ + void SetFromTab(bool fromTab); + + /** + Marks the event as a window change event. + */ + void SetWindowChange(bool windowChange); +}; + + + +/** + @class wxMouseCaptureChangedEvent + @wxheader{event.h} + + An mouse capture changed event is sent to a window that loses its + mouse capture. This is called even if wxWindow::ReleaseCapture + was called by the application code. Handling this event allows + an application to cater for unexpected capture releases which + might otherwise confuse mouse handling code. + + @onlyfor{wxmsw} + + @beginEventTable{wxMouseCaptureChangedEvent} + @event{EVT_MOUSE_CAPTURE_CHANGED(func)} + Process a wxEVT_MOUSE_CAPTURE_CHANGED event. + @endEventTable + + @library{wxcore} + @category{events} + + @see wxMouseCaptureLostEvent, @ref overview_eventhandling, + wxWindow::CaptureMouse, wxWindow::ReleaseMouse, wxWindow::GetCapture +*/ +class wxMouseCaptureChangedEvent : public wxEvent +{ +public: + /** + Constructor. + */ + wxMouseCaptureChangedEvent(wxWindowID windowId = 0, + wxWindow* gainedCapture = NULL); + + /** + Returns the window that gained the capture, or @NULL if it was a + non-wxWidgets window. + */ + wxWindow* GetCapturedWindow() const; +}; + + + +/** + @class wxCloseEvent + @wxheader{event.h} + + This event class contains information about window and session close events. + + The handler function for EVT_CLOSE is called when the user has tried to close a + a frame or dialog box using the window manager (X) or system menu (Windows). + It can also be invoked by the application itself programmatically, for example by + calling the wxWindow::Close function. + + You should check whether the application is forcing the deletion of the window + using wxCloseEvent::CanVeto. If this is @false, you @e must destroy the window + using wxWindow::Destroy. + + If the return value is @true, it is up to you whether you respond by destroying + the window. + + If you don't destroy the window, you should call wxCloseEvent::Veto to + let the calling code know that you did not destroy the window. + This allows the wxWindow::Close function to return @true or @false depending + on whether the close instruction was honoured or not. + + The EVT_END_SESSION event is slightly different as it is sent by the system + when the user session is ending (e.g. because of log out or shutdown) and + so all windows are being forcefully closed. At least under MSW, after the + handler for this event is executed the program is simply killed by the + system. Because of this, the default handler for this event provided by + wxWidgets calls all the usual cleanup code (including wxApp::OnExit()) so + that it could still be executed and exit()s the process itself, without + waiting for being killed. If this behaviour is for some reason undesirable, + make sure that you define a handler for this event in your wxApp-derived + class and do not call @c event.Skip() in it (but be aware that the system + will still kill your application). + + @beginEventTable{wxCloseEvent} + @event{EVT_CLOSE(func)} + Process a close event, supplying the member function. + This event applies to wxFrame and wxDialog classes. + @event{EVT_QUERY_END_SESSION(func)} + Process a query end session event, supplying the member function. + This event can be handled in wxApp-derived class only. + @event{EVT_END_SESSION(func)} + Process an end session event, supplying the member function. + This event can be handled in wxApp-derived class only. + @endEventTable + + @library{wxcore} + @category{events} + + @see wxWindow::Close, @ref overview_windowdeletion +*/ +class wxCloseEvent : public wxEvent +{ +public: + /** + Constructor. + */ + wxCloseEvent(wxEventType commandEventType = wxEVT_NULL, int id = 0); + + /** + Returns @true if you can veto a system shutdown or a window close event. + Vetoing a window close event is not possible if the calling code wishes to + force the application to exit, and so this function must be called to check this. + */ + bool CanVeto() const; + + /** + Returns @true if the user is just logging off or @false if the system is + shutting down. This method can only be called for end session and query end + session events, it doesn't make sense for close window event. + */ + bool GetLoggingOff() const; + + /** + Sets the 'can veto' flag. + */ + void SetCanVeto(bool canVeto); + + /** + Sets the 'force' flag. + */ + void SetForce(bool force) const; + + /** + Sets the 'logging off' flag. + */ + void SetLoggingOff(bool loggingOff); + + /** + Call this from your event handler to veto a system shutdown or to signal + to the calling application that a window close did not happen. + + You can only veto a shutdown if CanVeto() returns @true. + */ + void Veto(bool veto = true); +}; + + + +/** + @class wxMenuEvent + @wxheader{event.h} + + This class is used for a variety of menu-related events. Note that + these do not include menu command events, which are + handled using wxCommandEvent objects. + + The default handler for wxEVT_MENU_HIGHLIGHT displays help + text in the first field of the status bar. + + @beginEventTable{wxMenuEvent} + @event{EVT_MENU_OPEN(func)} + A menu is about to be opened. On Windows, this is only sent once for each + navigation of the menubar (up until all menus have closed). + @event{EVT_MENU_CLOSE(func)} + A menu has been just closed. + @event{EVT_MENU_HIGHLIGHT(id, func)} + The menu item with the specified id has been highlighted: used to show + help prompts in the status bar by wxFrame + @event{EVT_MENU_HIGHLIGHT_ALL(func)} + A menu item has been highlighted, i.e. the currently selected menu item has changed. + @endEventTable + + @library{wxcore} + @category{events} + + @see wxCommandEvent, @ref overview_eventhandling +*/ +class wxMenuEvent : public wxEvent +{ +public: + /** + Constructor. + */ + wxMenuEvent(wxEventType id = wxEVT_NULL, int id = 0, wxMenu* menu = NULL); + + /** + Returns the menu which is being opened or closed. This method should only be + used with the @c OPEN and @c CLOSE events and even for them the + returned pointer may be @NULL in some ports. + */ + wxMenu* GetMenu() const; + + /** + Returns the menu identifier associated with the event. + This method should be only used with the @c HIGHLIGHT events. + */ + int GetMenuId() const; + + /** + Returns @true if the menu which is being opened or closed is a popup menu, + @false if it is a normal one. + + This method should only be used with the @c OPEN and @c CLOSE events. + */ + bool IsPopup() const; +}; + +/** + @class wxShowEvent + @wxheader{event.h} + + An event being sent when the window is shown or hidden. + + Currently only wxMSW, wxGTK and wxOS2 generate such events. + + @onlyfor{wxmsw,wxgtk,wxos2} + + @beginEventTable{wxShowEvent} + @event{EVT_SHOW(func)} + Process a wxEVT_SHOW event. + @endEventTable + + @library{wxcore} + @category{events} + + @see @ref overview_eventhandling, wxWindow::Show, + wxWindow::IsShown +*/ + +class wxShowEvent : public wxEvent +{ +public: + /** + Constructor. + */ + wxShowEvent(int winid = 0, bool show = false); + + /** + Set whether the windows was shown or hidden. + */ + void SetShow(bool show); + + /** + Return @true if the window has been shown, @false if it has been + hidden. + */ + bool IsShown() const; + + /** + @deprecated This function is deprecated in favour of IsShown(). + */ + bool GetShow() const; +}; + + + +/** + @class wxIconizeEvent + @wxheader{event.h} + + An event being sent when the frame is iconized (minimized) or restored. + + Currently only wxMSW and wxGTK generate such events. + + @onlyfor{wxmsw,wxgtk} + + @beginEventTable{wxIconizeEvent} + @event{EVT_ICONIZE(func)} + Process a wxEVT_ICONIZE event. + @endEventTable + + @library{wxcore} + @category{events} + + @see @ref overview_eventhandling, wxTopLevelWindow::Iconize, + wxTopLevelWindow::IsIconized +*/ +class wxIconizeEvent : public wxEvent +{ +public: + /** + Constructor. + */ + wxIconizeEvent(int id = 0, bool iconized = true); + + /** + Returns @true if the frame has been iconized, @false if it has been + restored. + */ + bool IsIconized() const; + + /** + @deprecated This function is deprecated in favour of IsIconized(). + */ + bool Iconized() const; +}; + + + +/** + @class wxMoveEvent + @wxheader{event.h} + + A move event holds information about move change events. + + @beginEventTable{wxMoveEvent} + @event{EVT_MOVE(func)} + Process a wxEVT_MOVE event, which is generated when a window is moved. + @event{EVT_MOVE_START(func)} + Process a wxEVT_MOVE_START event, which is generated when the user starts + to move or size a window. wxMSW only. + @event{EVT_MOVE_END(func)} + Process a wxEVT_MOVE_END event, which is generated when the user stops + moving or sizing a window. wxMSW only. + @endEventTable + + @library{wxcore} + @category{events} + + @see wxPoint, @ref overview_eventhandling +*/ +class wxMoveEvent : public wxEvent +{ +public: + /** + Constructor. + */ + wxMoveEvent(const wxPoint& pt, int id = 0); + + /** + Returns the position of the window generating the move change event. + */ + wxPoint GetPosition() const; +}; + + +/** + @class wxSizeEvent + @wxheader{event.h} + + A size event holds information about size change events. + + The EVT_SIZE handler function will be called when the window has been resized. + + You may wish to use this for frames to resize their child windows as appropriate. + + Note that the size passed is of the whole window: call wxWindow::GetClientSize + for the area which may be used by the application. + + When a window is resized, usually only a small part of the window is damaged + and you may only need to repaint that area. However, if your drawing depends on the + size of the window, you may need to clear the DC explicitly and repaint the whole window. + In which case, you may need to call wxWindow::Refresh to invalidate the entire window. + + @beginEventTable{wxSizeEvent} + @event{EVT_SIZE(func)} + Process a wxEVT_SIZE event. + @endEventTable + + @library{wxcore} + @category{events} + + @see wxSize, @ref overview_eventhandling +*/ +class wxSizeEvent : public wxEvent +{ +public: + /** + Constructor. + */ + wxSizeEvent(const wxSize& sz, int id = 0); + + /** + Returns the entire size of the window generating the size change event. + */ + wxSize GetSize() const; +}; + + + +/** + @class wxSetCursorEvent + @wxheader{event.h} + + A SetCursorEvent is generated when the mouse cursor is about to be set as a + result of mouse motion. + + This event gives the application the chance to perform specific mouse cursor + processing based on the current position of the mouse within the window. + Use wxSetCursorEvent::SetCursor to specify the cursor you want to be displayed. + + @beginEventTable{wxSetCursorEvent} + @event{EVT_SET_CURSOR(func)} + Process a wxEVT_SET_CURSOR event. + @endEventTable + + @library{wxcore} + @category{events} + + @see ::wxSetCursor, wxWindow::wxSetCursor +*/ +class wxSetCursorEvent : public wxEvent +{ +public: + /** + Constructor, used by the library itself internally to initialize the event + object. + */ + wxSetCursorEvent(wxCoord x = 0, wxCoord y = 0); + + /** + Returns a reference to the cursor specified by this event. + */ + const wxCursor& GetCursor() const; + + /** + Returns the X coordinate of the mouse in client coordinates. + */ + wxCoord GetX() const; + + /** + Returns the Y coordinate of the mouse in client coordinates. + */ + wxCoord GetY() const; + + /** + Returns @true if the cursor specified by this event is a valid cursor. + + @remarks You cannot specify wxNullCursor with this event, as it is not + considered a valid cursor. + */ + bool HasCursor() const; + + /** + Sets the cursor associated with this event. + */ + void SetCursor(const wxCursor& cursor); +}; + + + +// ============================================================================ +// Global functions/macros +// ============================================================================ + +/** @ingroup group_funcmacro_misc */ +//@{ + +/** + In a GUI application, this function posts @a event to the specified @e dest + object using wxEvtHandler::AddPendingEvent(). + + Otherwise, it dispatches @a event immediately using + wxEvtHandler::ProcessEvent(). See the respective documentation for details + (and caveats). Because of limitation of wxEvtHandler::AddPendingEvent() + this function is not thread-safe for event objects having wxString fields, + use wxQueueEvent() instead. + + @header{wx/event.h} +*/ +void wxPostEvent(wxEvtHandler* dest, const wxEvent& event); + +/** + Queue an event for processing on the given object. + + This is a wrapper around wxEvtHandler::QueueEvent(), see its documentation + for more details. + + @header{wx/event.h} + + @param dest + The object to queue the event on, can't be @c NULL. + @param event + The heap-allocated and non-@c NULL event to queue, the function takes + ownership of it. + */ +void wxQueueEvent(wxEvtHandler* dest, wxEvent *event); + +//@} + diff --git a/interface/wx/fdrepdlg.h b/interface/wx/fdrepdlg.h new file mode 100644 index 0000000000..e704d00c4e --- /dev/null +++ b/interface/wx/fdrepdlg.h @@ -0,0 +1,210 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: fdrepdlg.h +// Purpose: interface of wxFindDialogEvent, wxFindReplaceDialog +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + + +/** + See wxFindDialogEvent::GetFlags(). +*/ +enum wxFindReplaceFlags +{ + /** downward search/replace selected (otherwise - upwards) */ + wxFR_DOWN = 1, + + /** whole word search/replace selected */ + wxFR_WHOLEWORD = 2, + + /** case sensitive search/replace selected (otherwise - case insensitive) */ + wxFR_MATCHCASE = 4 +} + + +/** + These flags can be specified in wxFindReplaceDialog ctor or Create(): +*/ +enum wxFindReplaceDialogStyles +{ + /** replace dialog (otherwise find dialog) */ + wxFR_REPLACEDIALOG = 1, + + /** don't allow changing the search direction */ + wxFR_NOUPDOWN = 2, + + /** don't allow case sensitive searching */ + wxFR_NOMATCHCASE = 4, + + /** don't allow whole word searching */ + wxFR_NOWHOLEWORD = 8 +} + + +/** + @class wxFindDialogEvent + @wxheader{fdrepdlg.h} + + wxFindReplaceDialog events + + @beginEventTable{wxFindDialogEvent} + @event{EVT_FIND(id, func)} + Find button was pressed in the dialog. + @event{EVT_FIND_NEXT(id, func)} + Find next button was pressed in the dialog. + @event{EVT_FIND_REPLACE(id, func)} + Replace button was pressed in the dialog. + @event{EVT_FIND_REPLACE_ALL(id, func)} + Replace all button was pressed in the dialog. + @event{EVT_FIND_CLOSE(id, func)} + The dialog is being destroyed, any pointers to it cannot be used any longer. + @endEventTable + + @library{wxcore} + @category{events} +*/ +class wxFindDialogEvent : public wxCommandEvent +{ +public: + /** + Constuctor used by wxWidgets only. + */ + wxFindDialogEvent(wxEventType commandType = wxEVT_NULL, + int id = 0); + + /** + Return the pointer to the dialog which generated this event. + */ + wxFindReplaceDialog* GetDialog() const; + + /** + Return the string to find (never empty). + */ + wxString GetFindString() const; + + /** + Get the currently selected flags: this is the combination of + the ::wxFindReplaceFlags enumeration values. + */ + int GetFlags() const; + + /** + Return the string to replace the search string with (only for replace and + replace all events). + */ + const wxString& GetReplaceString() const; +}; + + + +/** + @class wxFindReplaceData + @wxheader{fdrepdlg.h} + + wxFindReplaceData holds the data for wxFindReplaceDialog. + + It is used to initialize the dialog with the default values and will keep the + last values from the dialog when it is closed. It is also updated each time a + wxFindDialogEvent is generated so instead of using the wxFindDialogEvent + methods you can also directly query this object. + + Note that all @c SetXXX() methods may only be called before showing the + dialog and calling them has no effect later. + + @library{wxcore} + @category{data} +*/ +class wxFindReplaceData : public wxObject +{ +public: + /** + Constuctor initializes the flags to default value (0). + */ + wxFindReplaceData(wxUint32 flags = 0); + + /** + Get the string to find. + */ + const wxString GetFindString(); + + /** + Get the combination of @c wxFindReplaceFlags values. + */ + int GetFlags() const; + + /** + Get the replacement string. + */ + const wxString GetReplaceString(); + + /** + Set the string to find (used as initial value by the dialog). + */ + void SetFindString(const wxString& str); + + /** + Set the flags to use to initialize the controls of the dialog. + */ + void SetFlags(wxUint32 flags); + + /** + Set the replacement string (used as initial value by the dialog). + */ + void SetReplaceString(const wxString& str); +}; + + + +/** + @class wxFindReplaceDialog + @wxheader{fdrepdlg.h} + + wxFindReplaceDialog is a standard modeless dialog which is used to allow the + user to search for some text (and possibly replace it with something else). + + The actual searching is supposed to be done in the owner window which is the + parent of this dialog. Note that it means that unlike for the other standard + dialogs this one @b must have a parent window. Also note that there is no + way to use this dialog in a modal way; it is always, by design and + implementation, modeless. + + Please see the @ref page_samples_dialogs sample for an example of using it. + + @library{wxcore} + @category{cmndlg} +*/ +class wxFindReplaceDialog : public wxDialog +{ +public: + wxFindReplaceDialog(); + + /** + After using default constructor Create() must be called. + + The @a parent and @a data parameters must be non-@NULL. + */ + wxFindReplaceDialog(wxWindow* parent, + wxFindReplaceData* data, + const wxString& title, + int style = 0); + + /** + Destructor. + */ + ~wxFindReplaceDialog(); + + /** + Creates the dialog; use wxWindow::Show to show it on screen. + + The @a parent and @a data parameters must be non-@NULL. + */ + bool Create(wxWindow* parent, wxFindReplaceData* data, + const wxString& title, int style = 0); + + /** + Get the wxFindReplaceData object used by this dialog. + */ + const wxFindReplaceData* GetData() const; +}; + diff --git a/interface/wx/ffile.h b/interface/wx/ffile.h new file mode 100644 index 0000000000..a19619ff9a --- /dev/null +++ b/interface/wx/ffile.h @@ -0,0 +1,246 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: ffile.h +// Purpose: interface of wxFFile +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + + + +/** + Values used for both wxFile and wxFFile. + + @todo make the value names uppercase +*/ +enum wxSeekMode +{ + wxFromStart, + wxFromCurrent, + wxFromEnd +}; + +/** + See wxFFile::GetKind(). +*/ +enum wxFileKind +{ + wxFILE_KIND_UNKNOWN, + wxFILE_KIND_DISK, /**< A file supporting seeking to arbitrary offsets. */ + wxFILE_KIND_TERMINAL, /**< A terminal. */ + wxFILE_KIND_PIPE /**< A pipe. */ +}; + + +/** + @class wxFFile + @wxheader{ffile.h} + + wxFFile implements buffered file I/O. + + This is a very small class designed to minimize the overhead of using it - in fact, + there is hardly any overhead at all, but using it brings you automatic error checking + and hides differences between platforms and compilers. + + It wraps inside it a @c FILE * handle used by standard C IO library (also known as @c stdio). + + @library{wxbase} + @category{file} + + @see wxFFile::IsOpened +*/ +class wxFFile +{ +public: + wxFFile(); + + /** + Opens a file with the given file pointer, which has already been opened. + + @param fp + An existing file descriptor, such as stderr. + */ + wxFFile(FILE* fp); + + /** + Opens a file with the given mode. + As there is no way to return whether the operation was successful or not from + the constructor you should test the return value of IsOpened() to check that it + didn't fail. + + @param filename + The filename. + @param mode + The mode in which to open the file using standard C strings. + Note that you should use "b" flag if you use binary files under Windows + or the results might be unexpected due to automatic newline conversion done + for the text files. + */ + wxFFile(const wxString& filename, const wxString& mode = "r"); + + + /** + Destructor will close the file. + + @note it is not virtual so you should @e not derive from wxFFile! + */ + ~wxFFile(); + + /** + Attaches an existing file pointer to the wxFFile object. + + The descriptor should be already opened and it will be closed by wxFFile object. + */ + void Attach(FILE* fp); + + /** + Closes the file and returns @true on success. + */ + bool Close(); + + /** + Get back a file pointer from wxFFile object -- the caller is responsible for + closing the file if this descriptor is opened. + + IsOpened() will return @false after call to Detach(). + */ + void Detach(); + + /** + Returns @true if the an attempt has been made to read @e past + the end of the file. + + Note that the behaviour of the file descriptor based class wxFile is different as + wxFile::Eof() will return @true here as soon as the last byte of the file has been read. + + Also note that this method may only be called for opened files and may crash if + the file is not opened. + + @todo THIS METHOD MAY CRASH? DOESN'T SOUND GOOD + + @see IsOpened() + */ + bool Eof() const; + + /** + Returns @true if an error has occurred on this file, similar to the standard + @c ferror() function. + + Please note that this method may only be called for opened files and may crash + if the file is not opened. + + @todo THIS METHOD MAY CRASH? DOESN'T SOUND GOOD + + @see IsOpened() + */ + bool Error() const; + + /** + Flushes the file and returns @true on success. + */ + bool Flush(); + + /** + Returns the type of the file. + + @see wxFileKind + */ + wxFileKind GetKind() const; + + /** + Returns @true if the file is opened. + + Most of the methods of this class may only be used for an opened file. + */ + bool IsOpened() const; + + /** + Returns the length of the file. + */ + wxFileOffset Length() const; + + /** + Opens the file, returning @true if successful. + + @param filename + The filename. + @param mode + The mode in which to open the file. + */ + bool Open(const wxString& filename, const wxString& mode = "r"); + + /** + Reads the specified number of bytes into a buffer, returning the actual number read. + + @param buffer + A buffer to receive the data. + @param count + The number of bytes to read. + + @return The number of bytes read. + */ + size_t Read(void* buffer, size_t count); + + /** + Reads the entire contents of the file into a string. + + @param str + String to read data into. + @param conv + Conversion object to use in Unicode build; by default supposes + that file contents is encoded in UTF-8. + + @return @true if file was read successfully, @false otherwise. + */ + bool ReadAll(wxString* str, const wxMBConv& conv = wxConvAuto()); + + /** + Seeks to the specified position and returns @true on success. + + @param ofs + Offset to seek to. + @param mode + One of wxFromStart, wxFromEnd, wxFromCurrent. + */ + bool Seek(wxFileOffset ofs, wxSeekMode mode = wxFromStart); + + /** + Moves the file pointer to the specified number of bytes before the end of the + file and returns @true on success. + + @param ofs + Number of bytes before the end of the file. + */ + bool SeekEnd(wxFileOffset ofs = 0); + + /** + Returns the current position. + */ + wxFileOffset Tell() const; + + /** + Writes the contents of the string to the file, returns @true on success. + + The second argument is only meaningful in Unicode build of wxWidgets when + @a conv is used to convert @a str to multibyte representation. + */ + bool Write(const wxString& str, const wxMBConv& conv = wxConvAuto()); + + /** + Writes the specified number of bytes from a buffer. + + @param buffer + A buffer containing the data. + @param count + The number of bytes to write. + + @return The number of bytes written. + */ + size_t Write(const void* buffer, size_t count); + + /** + Returns the file pointer associated with the file. + */ + FILE* fp() const; +}; + diff --git a/interface/wx/file.h b/interface/wx/file.h new file mode 100644 index 0000000000..cb74e2dfa8 --- /dev/null +++ b/interface/wx/file.h @@ -0,0 +1,325 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: file.h +// Purpose: interface of wxTempFile +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxTempFile + @wxheader{file.h} + + wxTempFile provides a relatively safe way to replace the contents of the + existing file. The name is explained by the fact that it may be also used as + just a temporary file if you don't replace the old file contents. + + Usually, when a program replaces the contents of some file it first opens it for + writing, thus losing all of the old data and then starts recreating it. This + approach is not very safe because during the regeneration of the file bad things + may happen: the program may find that there is an internal error preventing it + from completing file generation, the user may interrupt it (especially if file + generation takes long time) and, finally, any other external interrupts (power + supply failure or a disk error) will leave you without either the original file + or the new one. + + wxTempFile addresses this problem by creating a temporary file which is meant to + replace the original file - but only after it is fully written. So, if the user + interrupts the program during the file generation, the old file won't be lost. + Also, if the program discovers itself that it doesn't want to replace the old + file there is no problem - in fact, wxTempFile will @b not replace the old + file by default, you should explicitly call wxTempFile::Commit + to do it. Calling wxTempFile::Discard explicitly discards any + modifications: it closes and deletes the temporary file and leaves the original + file unchanged. If you don't call neither of Commit() and Discard(), the + destructor will call Discard() automatically. + + To summarize: if you want to replace another file, create an instance of + wxTempFile passing the name of the file to be replaced to the constructor (you + may also use default constructor and pass the file name to + wxTempFile::Open). Then you can wxTempFile::write + to wxTempFile using wxFile-like functions and later call + Commit() to replace the old file (and close this one) or call Discard() to + cancel + the modifications. + + @library{wxbase} + @category{file} +*/ +class wxTempFile +{ +public: + /** + Associates wxTempFile with the file to be replaced and opens it. You should use + IsOpened() to verify if the constructor succeeded. + */ + wxTempFile(const wxString& strName); + + /** + Destructor calls Discard() if temporary file + is still opened. + */ + ~wxTempFile(); + + /** + Validate changes: deletes the old file of name m_strName and renames the new + file to the old name. Returns @true if both actions succeeded. If @false is + returned it may unfortunately mean two quite different things: either that + either the old file couldn't be deleted or that the new file couldn't be renamed + to the old name. + */ + bool Commit(); + + /** + Discard changes: the old file contents is not changed, temporary file is + deleted. + */ + void Discard(); + + /** + Returns @true if the file was successfully opened. + */ + bool IsOpened() const; + + /** + Returns the length of the file. + */ + wxFileOffset Length() const; + + /** + Open the temporary file, returns @true on success, @false if an error + occurred. + @a strName is the name of file to be replaced. The temporary file is always + created in the directory where @a strName is. In particular, if + @a strName doesn't include the path, it is created in the current directory + and the program should have write access to it for the function to succeed. + */ + bool Open(const wxString& strName); + + /** + Seeks to the specified position. + */ + wxFileOffset Seek(wxFileOffset ofs, + wxSeekMode mode = wxFromStart); + + /** + Returns the current position or wxInvalidOffset if file is not opened or if + another + error occurred. + */ + wxFileOffset Tell() const; + + /** + Write to the file, return @true on success, @false on failure. + The second argument is only meaningful in Unicode build of wxWidgets when + @a conv is used to convert @a str to multibyte representation. + */ + bool Write(const wxString& str, + const wxMBConv& conv = wxConvUTF8); +}; + + + +/** + @class wxFile + @wxheader{file.h} + + A wxFile performs raw file I/O. This is a very small class designed to + minimize the overhead of using it - in fact, there is hardly any overhead at + all, but using it brings you automatic error checking and hides differences + between platforms and compilers. wxFile also automatically closes the file in + its destructor making it unnecessary to worry about forgetting to do it. + wxFile is a wrapper around @c file descriptor. - see also + wxFFile for a wrapper around @c FILE structure. + + @c wxFileOffset is used by the wxFile functions which require offsets as + parameter or return them. If the platform supports it, wxFileOffset is a typedef + for a native 64 bit integer, otherwise a 32 bit integer is used for + wxFileOffset. + + @library{wxbase} + @category{file} +*/ +class wxFile +{ +public: + //@{ + /** + Associates the file with the given file descriptor, which has already been + opened. + + @param filename + The filename. + @param mode + The mode in which to open the file. May be one of read(), write() and + wxFile::read_write. + @param fd + An existing file descriptor (see Attach() for the list of predefined + descriptors) + */ + wxFile(); + wxFile(const wxString& filename, + wxFile::OpenMode mode = wxFile::read); + wxFile(int fd); + //@} + + /** + Destructor will close the file. + @note it is not virtual so you should not use wxFile polymorphically. + */ + ~wxFile(); + + /** + This function verifies if we may access the given file in specified mode. Only + values of read() or write() really make sense here. + */ + static bool Access(const wxString& name, OpenMode mode); + + /** + Attaches an existing file descriptor to the wxFile object. Example of predefined + file descriptors are 0, 1 and 2 which correspond to stdin, stdout and stderr + (and + have symbolic names of @b wxFile::fd_stdin, @b wxFile::fd_stdout and @b + wxFile::fd_stderr). + The descriptor should be already opened and it will be closed by wxFile + object. + */ + void Attach(int fd); + + /** + Closes the file. + */ + void Close(); + + /** + Creates a file for writing. If the file already exists, setting @b overwrite to + @true + will ensure it is overwritten. + */ + bool Create(const wxString& filename, bool overwrite = false, + int access = wxS_DEFAULT); + + /** + Get back a file descriptor from wxFile object - the caller is responsible for + closing the file if this + descriptor is opened. IsOpened() will return @false after call to Detach(). + */ + void Detach(); + + /** + Returns @true if the end of the file has been reached. + Note that the behaviour of the file pointer based class + wxFFile is different as wxFFile::Eof + will return @true here only if an attempt has been made to read + @e past the last byte of the file, while wxFile::Eof() will return @true + even before such attempt is made if the file pointer is at the last position + in the file. + Note also that this function doesn't work on unseekable file descriptors + (examples include pipes, terminals and sockets under Unix) and an attempt to + use it will result in an error message in such case. So, to read the entire + file into memory, you should write a loop which uses + Read() repeatedly and tests its return condition instead + of using Eof() as this will not work for special files under Unix. + */ + bool Eof() const; + + /** + Returns @true if the given name specifies an existing regular file (not a + directory or a link) + */ + static bool Exists(const wxString& filename); + + /** + Flushes the file descriptor. + Note that Flush() is not implemented on some Windows compilers + due to a missing fsync function, which reduces the usefulness of this function + (it can still be called but it will do nothing on unsupported compilers). + */ + bool Flush(); + + /** + Returns the type of the file. Possible return values are: + */ + wxFileKind GetKind() const; + + /** + Returns @true if the file has been opened. + */ + bool IsOpened() const; + + /** + Returns the length of the file. + */ + wxFileOffset Length() const; + + /** + Opens the file, returning @true if successful. + + @param filename + The filename. + @param mode + The mode in which to open the file. May be one of read(), write() and + wxFile::read_write. + */ + bool Open(const wxString& filename, + wxFile::OpenMode mode = wxFile::read); + + //@{ + /** + if there was an error. + */ + size_t Read(void* buffer, size_t count); + Parameters Return value + The number of bytes read, or the symbol wxInvalidOffset(); + //@} + + /** + Seeks to the specified position. + + @param ofs + Offset to seek to. + @param mode + One of wxFromStart, wxFromEnd, wxFromCurrent. + + @return The actual offset position achieved, or wxInvalidOffset on + failure. + */ + wxFileOffset Seek(wxFileOffset ofs, + wxSeekMode mode = wxFromStart); + + /** + Moves the file pointer to the specified number of bytes relative to the end of + the file. For example, @c SeekEnd(-5) would position the pointer 5 + bytes before the end. + + @param ofs + Number of bytes before the end of the file. + + @return The actual offset position achieved, or wxInvalidOffset on + failure. + */ + wxFileOffset SeekEnd(wxFileOffset ofs = 0); + + /** + Returns the current position or wxInvalidOffset if file is not opened or if + another + error occurred. + */ + wxFileOffset Tell() const; + + /** + Writes the contents of the string to the file, returns @true on success. + The second argument is only meaningful in Unicode build of wxWidgets when + @a conv is used to convert @a s to multibyte representation. + Note that this method only works with @c NUL-terminated strings, if you want + to write data with embedded @c NULs to the file you should use the other + @ref write() "Write() overload". + */ + bool Write(const wxString& s, const wxMBConv& conv = wxConvUTF8); + + /** + Returns the file descriptor associated with the file. + */ + int fd() const; +}; + diff --git a/interface/wx/fileconf.h b/interface/wx/fileconf.h new file mode 100644 index 0000000000..cdef167a00 --- /dev/null +++ b/interface/wx/fileconf.h @@ -0,0 +1,86 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: fileconf.h +// Purpose: interface of wxFileConfig +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxFileConfig + @wxheader{fileconf.h} + + wxFileConfig implements wxConfigBase interface for + storing and retrieving configuration information using plain text files. The + files have a simple format reminiscent of Windows INI files with lines of the + form @c "key = value" defining the keys and lines of special form + @c "[group]" indicating the start of each group. + + This class is used by default for wxConfig on Unix platforms but may also be + used explicitly if you want to use files and not the registry even under + Windows. + + @library{wxbase} + @category{misc} + + @see wxFileConfig::Save +*/ +class wxFileConfig : public wxConfigBase +{ +public: + /** + Read the config data from the specified stream instead of the associated file, + as usual. + + @see Save() + */ + wxFileConfig(wxInputStream& is, const wxMBConv& conv = wxConvAuto()); + + /** + Return the full path to the file which would be used by wxFileConfig as global, + system-wide, file if it were constructed with @a basename as "global filename" + parameter in the constructor. + + Notice that this function cannot be used if @a basename is already a full path name. + */ + static wxFileName GetGlobalFile(const wxString& basename); + + /** + Return the full path to the file which would be used by wxFileConfig as local, + user-specific, file if it were constructed with @a basename as "local filename" + parameter in the constructor. + + @a style has the same meaning as in @ref wxConfigBase::wxConfigBase "wxConfig constructor" + and can contain any combination of styles but only wxCONFIG_USE_SUBDIR bit is + examined by this function. + + Notice that this function cannot be used if @a basename is already a full path name. + */ + static wxFileName GetLocalFile(const wxString& basename, int style = 0); + + /** + Saves all config data to the given stream, returns @true if data was saved + successfully or @false on error. + + Note the interaction of this function with the internal "dirty flag": the + data is saved unconditionally, i.e. even if the object is not dirty. However + after saving it successfully, the dirty flag is reset so no changes will be + written back to the file this object is associated with until you change its + contents again. + + @see wxConfigBase::Flush + */ + bool Save(wxOutputStream& os, const wxMBConv& conv = wxConvAuto()); + + /** + Allows to set the mode to be used for the config file creation. For example, to + create a config file which is not readable by other users (useful if it stores + some sensitive information, such as passwords), you could use @c SetUmask(0077). + + This function doesn't do anything on non-Unix platforms. + + @see wxCHANGE_UMASK() + */ + void SetUmask(int mode); +}; + diff --git a/interface/wx/filectrl.h b/interface/wx/filectrl.h new file mode 100644 index 0000000000..dfbc382192 --- /dev/null +++ b/interface/wx/filectrl.h @@ -0,0 +1,246 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: filectrl.h +// Purpose: interface of wxFileCtrl +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxFileCtrl + @wxheader{filectrl.h} + + This control allows the user to select a file. + + Two implemetations exist, one for Gtk and another generic one for anything + other than Gtk. It is only available if @c wxUSE_FILECTRL is set to 1. + + @beginStyleTable + @style{wxFC_DEFAULT_STYLE} + The default style: wxFC_OPEN + @style{wxFC_OPEN} + Creates an file control suitable for opening files. Cannot be + combined with wxFC_SAVE. + @style{wxFC_SAVE} + Creates an file control suitable for saving files. Cannot be + combined with wxFC_OPEN. + @style{wxFC_MULTIPLE} + For open control only, Allows selecting multiple files. Cannot be + combined with wxFC_SAVE + @style{wxFC_NOSHOWHIDDEN} + Hides the "Show Hidden Files" checkbox (Generic only) + @endStyleTable + + + @beginEventTable{wxFileCtrlEvent} + @event{EVT_FILECTRL_FILEACTIVATED(id, func)} + The user activated a file(by double-clicking or pressing Enter) + @event{EVT_FILECTRL_SELECTIONCHANGED(id, func)} + The user changed the current selection(by selecting or deselecting a file) + @event{EVT_FILECTRL_FOLDERCHANGED(id, func)} + The current folder of the file control has been changed + @endEventTable + + @nativeimpl{gtk} + + @library{wxbase} + @category{miscwnd} + + @see wxGenericDirCtrl +*/ +class wxFileCtrl : public wxWindow +{ +public: + wxFileCtrl(); + + /** + Constructs the window. + + @param parent + Parent window, must not be non-@NULL. + @param id + The identifier for the control. + @param defaultDirectory + The initial directory shown in the control. Must be + a valid path to a directory or the empty string. + In case it is the empty string, the current working directory is used. + @param defaultFilename + The default filename, or the empty string. + @param wildcard + A wildcard specifying which files can be selected, + such as "*.*" or "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif". + @param style + The window style, see wxFC_* flags. + @param pos + Initial position. + @param size + Initial size. + @param name + Control name. + + @return @true if the control was successfully created or @false if + creation failed. + */ + + wxFileCtrl(wxWindow* parent, wxWindowID id, + const wxString& defaultDirectory = wxEmptyString, + const wxString& defaultFilename = wxEmptyString, + const wxPoint& wildCard = wxFileSelectorDefaultWildcardStr, + long style = wxFC_DEFAULT_STYLE, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + const wxString& name = "filectrl"); + + /** + Create function for two-step construction. See wxFileCtrl() for details. + */ + bool Create(wxWindow* parent, wxWindowID id, + const wxString& defaultDirectory = wxEmptyString, + const wxString& defaultFilename = wxEmptyString, + const wxPoint& wildCard = wxFileSelectorDefaultWildcardStr, + long style = wxFC_DEFAULT_STYLE, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + const wxString& name = "filectrl"); + + /** + Returns the current directory of the file control (i.e. the directory shown by it). + */ + wxString GetDirectory() const; + + /** + Returns the currently selected filename. + + For the controls having the @c wxFC_MULTIPLE style, use GetFilenames() instead. + */ + wxString GetFilename() const; + + /** + Fills the array @a filenames with the filenames only of selected items. + + This function should only be used with the controls having the @c wxFC_MULTIPLE + style, use GetFilename() for the others. + + @remarks filenames is emptied first. + */ + void GetFilenames(wxArrayString& filenames) const; + + /** + Returns the zero-based index of the currently selected filter. + */ + int GetFilterIndex() const; + + /** + Returns the full path (directory and filename) of the currently selected file. + For the controls having the @c wxFC_MULTIPLE style, use GetPaths() instead. + */ + wxString GetPath() const; + + /** + Fills the array @a paths with the full paths of the files chosen. + + This function should be used with the controls having the @c wxFC_MULTIPLE style, + use GetPath() otherwise. + + @remarks paths is emptied first. + */ + void GetPaths(wxArrayString& paths) const; + + /** + Returns the current wildcard. + */ + wxString GetWildcard() const; + + /** + Sets(changes) the current directory displayed in the control. + + @return Returns @true on success, @false otherwise. + */ + bool SetDirectory(const wxString& directory); + + /** + Selects a certain file. + + @return Returns @true on success, @false otherwise + */ + bool SetFilename(const wxString& filename); + + /** + Sets the current filter index, starting from zero. + */ + void SetFilterIndex(int filterIndex); + + /** + Sets the wildcard, which can contain multiple file types, for example: + "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif" + */ + void SetWildcard(const wxString& wildCard); + + /** + Sets whether hidden files and folders are shown or not. + */ + void ShowHidden(const bool show); +}; + + + +/** + @class wxFileCtrlEvent + @wxheader{filectrl.h} + + A file control event holds information about events associated with + wxFileCtrl objects. + + @beginEventTable{wxFileCtrlEvent} + @event{EVT_FILECTRL_FILEACTIVATED(id, func)} + The user activated a file(by double-clicking or pressing Enter) + @event{EVT_FILECTRL_SELECTIONCHANGED(id, func)} + The user changed the current selection(by selecting or deselecting a file) + @event{EVT_FILECTRL_FOLDERCHANGED(id, func)} + The current folder of the file control has been changed + @endEventTable + + @library{wxbase} + @category{events} +*/ +class wxFileCtrlEvent : public wxCommandEvent +{ +public: + /** + Constructor. + */ + wxFileCtrlEvent(wxEventType type, wxObject evtObject, int id); + + /** + Returns the current directory. + + In case of a @b EVT_FILECTRL_FOLDERCHANGED, this method returns the new + directory. + */ + wxString GetDirectory() const; + + /** + Returns the file selected (assuming it is only one file). + */ + wxString GetFile() const; + + /** + Returns the files selected. + + In case of a @b EVT_FILECTRL_SELECTIONCHANGED, this method returns the + files selected after the event. + */ + wxArrayString GetFiles() const; + + /** + Sets the files changed by this event. + */ + void SetFiles(const wxArrayString files); + + + /** + Sets the directory of this event. + */ + void SetDirectory( const wxString &directory ); +}; + diff --git a/interface/wx/filedlg.h b/interface/wx/filedlg.h new file mode 100644 index 0000000000..ada7bba196 --- /dev/null +++ b/interface/wx/filedlg.h @@ -0,0 +1,284 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: filedlg.h +// Purpose: interface of wxFileDialog +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxFileDialog + @wxheader{filedlg.h} + + This class represents the file chooser dialog. + + It pops up a file selector box (native for Windows and GTK2.4+). + + The path and filename are distinct elements of a full file pathname. + If path is "", the current directory will be used. If filename is "", no default + filename will be supplied. The wildcard determines what files are displayed in the + file selector, and file extension supplies a type extension for the required filename. + + @remarks + All implementations of the wxFileDialog provide a wildcard filter. Typing a filename + containing wildcards (*, ?) in the filename text item, and clicking on Ok, will + result in only those files matching the pattern being displayed. + The wildcard may be a specification for multiple types of file with a description + for each, such as: + "BMP and GIF files (*.bmp;*.gif)|*.bmp;*.gif|PNG files (*.png)|*.png" + It must be noted that wildcard support in the native Motif file dialog is quite + limited: only one alternative is supported, and it is displayed without the + descriptive test; "BMP files (*.bmp)|*.bmp" is displayed as "*.bmp", and both + "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif" and "Image files|*.bmp;*.gif" + are errors. + + @beginStyleTable + @style{wxFD_DEFAULT_STYLE} + Equivalent to wxFD_OPEN. + @style{wxFD_OPEN} + This is an open dialog; usually this means that the default + button's label of the dialog is "Open". Cannot be combined with wxFD_SAVE. + @style{wxFD_SAVE} + This is a save dialog; usually this means that the default button's + label of the dialog is "Save". Cannot be combined with wxFD_OPEN. + @style{wxFD_OVERWRITE_PROMPT} + For save dialog only: prompt for a confirmation if a file will be + overwritten. + @style{wxFD_FILE_MUST_EXIST} + For open dialog only: the user may only select files that actually exist. + @style{wxFD_MULTIPLE} + For open dialog only: allows selecting multiple files. + @style{wxFD_CHANGE_DIR} + Change the current working directory to the directory where the + file(s) chosen by the user are. + @style{wxFD_PREVIEW} + Show the preview of the selected files (currently only supported by + wxGTK using GTK+ 2.4 or later). + @endStyleTable + + @library{wxcore} + @category{cmndlg} + + @see @ref overview_wxfiledialog, ::wxFileSelector() +*/ +class wxFileDialog : public wxDialog +{ +public: + /** + Constructor. Use ShowModal() to show the dialog. + + @param parent + Parent window. + @param message + Message to show on the dialog. + @param defaultDir + The default directory, or the empty string. + @param defaultFile + The default filename, or the empty string. + @param wildcard + A wildcard, such as "*.*" or "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif". + Note that the native Motif dialog has some limitations with respect to + wildcards; see the Remarks section above. + @param style + A dialog style. See wxFD_* styles for more info. + @param pos + Dialog position. Not implemented. + @param size + Dialog size. Not implemented. + @param name + Dialog name. Not implemented. + */ + wxFileDialog(wxWindow* parent, + const wxString& message = "Choose a file", + const wxString& defaultDir = "", + const wxString& defaultFile = "", + const wxString& wildcard = ".", + long style = wxFD_DEFAULT_STYLE, + const wxPoint& pos = wxDefaultPosition, + const wxSize& sz = wxDefaultSize, + const wxString& name = "filedlg"); + + /** + Destructor. + */ + ~wxFileDialog(); + + /** + Returns the default directory. + */ + wxString GetDirectory() const; + + /** + If functions SetExtraControlCreator() and ShowModal() were called, + returns the extra window. Otherwise returns @NULL. + */ + wxWindow* GetExtraControl() const; + + /** + Returns the default filename. + */ + wxString GetFilename() const; + + /** + Fills the array @a filenames with the names of the files chosen. + + This function should only be used with the dialogs which have @c wxFD_MULTIPLE style, + use GetFilename() for the others. + + Note that under Windows, if the user selects shortcuts, the filenames + include paths, since the application cannot determine the full path + of each referenced file by appending the directory containing the shortcuts + to the filename. + */ + void GetFilenames(wxArrayString& filenames) const; + + /** + Returns the index into the list of filters supplied, optionally, in the + wildcard parameter. + + Before the dialog is shown, this is the index which will be used when the + dialog is first displayed. + + After the dialog is shown, this is the index selected by the user. + */ + int GetFilterIndex() const; + + /** + Returns the message that will be displayed on the dialog. + */ + wxString GetMessage() const; + + /** + Returns the full path (directory and filename) of the selected file. + */ + wxString GetPath() const; + + /** + Fills the array @a paths with the full paths of the files chosen. + + This function should only be used with the dialogs which have @c wxFD_MULTIPLE style, + use GetPath() for the others. + */ + void GetPaths(wxArrayString& paths) const; + + /** + Returns the file dialog wildcard. + */ + wxString GetWildcard() const; + + /** + Sets the default directory. + */ + void SetDirectory(const wxString& directory); + + /** + Customize file dialog by adding extra window, which is typically placed + below the list of files and above the buttons. + + SetExtraControlCreator() can be called only once, before calling ShowModal(). + + The @c creator function should take pointer to parent window (file dialog) + and should return a window allocated with operator new. + + Supported platforms: wxGTK, wxUniv. + */ + bool SetExtraControlCreator(t_extraControlCreator creator); + + /** + Sets the default filename. + */ + void SetFilename(const wxString& setfilename); + + /** + Sets the default filter index, starting from zero. + */ + void SetFilterIndex(int filterIndex); + + /** + Sets the message that will be displayed on the dialog. + */ + void SetMessage(const wxString& message); + + /** + Sets the path (the combined directory and filename that will be returned when + the dialog is dismissed). + */ + void SetPath(const wxString& path); + + /** + Sets the wildcard, which can contain multiple file types, for example: + "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif". + + Note that the native Motif dialog has some limitations with respect to + wildcards; see the Remarks section above. + */ + void SetWildcard(const wxString& wildCard); + + /** + Shows the dialog, returning wxID_OK if the user pressed OK, and wxID_CANCEL + otherwise. + */ + int ShowModal(); +}; + + + +// ============================================================================ +// Global functions/macros +// ============================================================================ + +/** @ingroup group_funcmacro_dialog */ +//@{ + +/** + Pops up a file selector box. In Windows, this is the common file selector + dialog. In X, this is a file selector box with the same functionality. The + path and filename are distinct elements of a full file pathname. If path + is empty, the current directory will be used. If filename is empty, no + default filename will be supplied. The wildcard determines what files are + displayed in the file selector, and file extension supplies a type + extension for the required filename. Flags may be a combination of + wxFD_OPEN, wxFD_SAVE, wxFD_OVERWRITE_PROMPT or wxFD_FILE_MUST_EXIST. + + @note wxFD_MULTIPLE can only be used with wxFileDialog and not here since + this function only returns a single file name. + + Both the Unix and Windows versions implement a wildcard filter. Typing a + filename containing wildcards (*, ?) in the filename text item, and + clicking on Ok, will result in only those files matching the pattern being + displayed. + + The wildcard may be a specification for multiple types of file with a + description for each, such as: + + @code + "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif" + @endcode + + The application must check for an empty return value (the user pressed + Cancel). For example: + + @code + wxString filename = wxFileSelector("Choose a file to open"); + if ( !filename.empty() ) + { + // work with the file + ... + } + //else: cancelled by user + @endcode + + @header{wx/filedlg.h} +*/ +wxString wxFileSelector(const wxString& message, + const wxString& default_path = "", + const wxString& default_filename = "", + const wxString& default_extension = "", + const wxString& wildcard = ".", + int flags = 0, + wxWindow* parent = NULL, + int x = -1, + int y = -1); + +//@} + diff --git a/interface/wx/filefn.h b/interface/wx/filefn.h new file mode 100644 index 0000000000..533ee9b5a4 --- /dev/null +++ b/interface/wx/filefn.h @@ -0,0 +1,458 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: filefn.h +// Purpose: interface of wxPathList and file functions +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxPathList + @wxheader{filefn.h} + + The path list is a convenient way of storing a number of directories, and + when presented with a filename without a directory, searching for an + existing file in those directories. + + Be sure to look also at wxStandardPaths if you only want to search files in + some standard paths. + + @library{wxbase} + @category{file} + + @see wxArrayString, wxStandardPaths, wxFileName +*/ +class wxPathList : public wxArrayString +{ +public: + wxPathList(); + + /** + Constructs the object calling the Add() function. + */ + wxPathList(const wxArrayString& arr); + + /** + Adds the given directory to the path list, if the @a path is not already in the list. + If the path cannot be normalized for some reason, it returns @false. + + The @a path is always considered to be a directory but no existence checks will be + done on it (because if it doesn't exist, it could be created later and thus result a + valid path when FindValidPath() is called). + + @note if the given path is relative, it won't be made absolute before adding it + (this is why FindValidPath() may return relative paths). + */ + bool Add(const wxString& path); + + /** + Adds all elements of the given array as paths. + */ + void Add(const wxArrayString& arr); + + /** + Finds the value of the given environment variable, and adds all paths + to the path list. + + Useful for finding files in the @c PATH variable, for example. + */ + void AddEnvList(const wxString& env_variable); + + /** + Given a full filename (with path), calls Add() with the path of the file. + */ + bool EnsureFileAccessible(const wxString& filename); + + /** + Like FindValidPath() but this function always returns an absolute path + (eventually prepending the current working directory to the value returned + wxPathList::FindValidPath()) or an empty string. + */ + wxString FindAbsoluteValidPath(const wxString& file) const; + + /** + Searches the given file in all paths stored in this class. + + The first path which concatenated to the given string points to an existing + file (see wxFileExists()) is returned. + + If the file wasn't found in any of the stored paths, an empty string is returned. + + The given string must be a file name, eventually with a path prefix (if the path + prefix is absolute, only its name will be searched); i.e. it must not end with + a directory separator (see wxFileName::GetPathSeparator) otherwise an assertion + will fail. + + The returned path may be relative to the current working directory. + + Note in fact that wxPathList can be used to store both relative and absolute + paths so that if you added relative paths, then the current working directory + (see wxGetCwd() and wxSetWorkingDirectory()) may affect the value returned + by this function! + */ + wxString FindValidPath(const wxString& file) const; +}; + + + +// ============================================================================ +// Global functions/macros +// ============================================================================ + +/** @ingroup group_funcmacro_file */ +//@{ + +/** + Under Unix this macro changes the current process umask to the given value, + unless it is equal to -1 in which case nothing is done, and restores it to + the original value on scope exit. It works by declaring a variable which + sets umask to @a mask in its constructor and restores it in its destructor. + Under other platforms this macro expands to nothing. + + @header{wx/filefn.h} +*/ +#define wxCHANGE_UMASK(int mask) + +/** + This function returns the total number of bytes and number of free bytes on + the disk containing the directory @a path (it should exist). Both @a total + and @a free parameters may be @NULL if the corresponding information is not + needed. + + @since 2.3.2 + + @note The generic Unix implementation depends on the system having the + @c statfs() or @c statvfs() function. + + @return @true on success, @false if an error occurred (for example, the + directory doesn’t exist). + + @header{wx/filefn.h} +*/ +bool wxGetDiskSpace(const wxString& path, + wxLongLong total = NULL, + wxLongLong free = NULL); + +/** + Returns the Windows directory under Windows; other platforms return an + empty string. + + @header{wx/filefn.h} +*/ +wxString wxGetOSDirectory(); + +/** + Parses the @a wildCard, returning the number of filters. Returns 0 if none + or if there's a problem. + + The arrays will contain an equal number of items found before the error. On + platforms where native dialogs handle only one filter per entry, entries in + arrays are automatically adjusted. @a wildCard is in the form: + + @code + "All files (*)|*|Image Files (*.jpeg *.png)|*.jpg;*.png" + @endcode + + @header{wx/filefn.h} +*/ +int wxParseCommonDialogsFilter(const wxString& wildCard, + wxArrayString& descriptions, + wxArrayString& filters); + +/** + Converts a DOS to a Unix filename by replacing backslashes with forward + slashes. + + @header{wx/filefn.h} +*/ +void wxDos2UnixFilename(wxChar* s); + +/** + @warning This function is deprecated, use wxFileName instead. + + Converts a Unix to a DOS filename by replacing forward slashes with + backslashes. + + @header{wx/filefn.h} +*/ +void wxUnix2DosFilename(wxChar* s); + +/** + Returns @true if @a dirname exists and is a directory. + + @header{wx/filefn.h} +*/ +bool wxDirExists(const wxString& dirname); + +/** + @warning This function is obsolete, please use wxFileName::SplitPath() + instead. + + This function splits a full file name into components: the path (including + possible disk/drive specification under Windows), the base name, and the + extension. Any of the output parameters (@a path, @a name or @a ext) may be + @NULL if you are not interested in the value of a particular component. + + wxSplitPath() will correctly handle filenames with both DOS and Unix path + separators under Windows, however it will not consider backslashes as path + separators under Unix (where backslash is a valid character in a filename). + + On entry, @a fullname should be non-@NULL (it may be empty though). + + On return, @a path contains the file path (without the trailing separator), + @a name contains the file name and @c ext contains the file extension + without leading dot. All three of them may be empty if the corresponding + component is. The old contents of the strings pointed to by these + parameters will be overwritten in any case (if the pointers are not @NULL). + + @header{wx/filefn.h} +*/ +void wxSplitPath(const wxString& fullname, + wxString* path, + wxString* name, + wxString* ext); + +/** + Returns time of last modification of given file. + + The function returns (time_t)-1 if an error occurred (e.g. file + not found). + + @header{wx/filefn.h} +*/ +time_t wxFileModificationTime(const wxString& filename); + +/** + Renames @a file1 to @e file2, returning @true if successful. + + If @a overwrite parameter is @true (default), the destination file is + overwritten if it exists, but if @a overwrite is @false, the functions + fails in this case. + + @header{wx/filefn.h} +*/ +bool wxRenameFile(const wxString& file1, + const wxString& file2, + bool overwrite = true); + +/** + Copies @a file1 to @e file2, returning @true if successful. If @a overwrite + parameter is @true (default), the destination file is overwritten if it + exists, but if @a overwrite is @false, the functions fails in this case. + + This function supports resources forks under Mac OS. + + @header{wx/filefn.h} +*/ +bool wxCopyFile(const wxString& file1, + const wxString& file2, + bool overwrite = true); + +/** + Returns @true if the file exists and is a plain file. + + @header{wx/filefn.h} +*/ +bool wxFileExists(const wxString& filename); + +/** + Returns @true if the @a pattern matches the @e text; if @a dot_special is + @true, filenames beginning with a dot are not matched with wildcard + characters. + + @see wxIsWild() + + @header{wx/filefn.h} +*/ +bool wxMatchWild(const wxString& pattern, + const wxString& text, + bool dot_special); + +/** + @warning This function is deprecated, use wxGetCwd() instead. + + Copies the current working directory into the buffer if supplied, or copies + the working directory into new storage (which you must delete yourself) if + the buffer is @NULL. + + @a sz is the size of the buffer if supplied. + + @header{wx/filefn.h} +*/ +wxString wxGetWorkingDirectory(char* buf = NULL, int sz = 1000); + +/** + Returns the directory part of the filename. + + @header{wx/filefn.h} +*/ +wxString wxPathOnly(const wxString& path); + +/** + Returns @true if the pattern contains wildcards. + + @see wxMatchWild() + + @header{wx/filefn.h} +*/ +bool wxIsWild(const wxString& pattern); + +/** + Returns @true if the argument is an absolute filename, i.e. with a slash + or drive name at the beginning. + + @header{wx/filefn.h} +*/ +bool wxIsAbsolutePath(const wxString& filename); + +/** + Returns a string containing the current (or working) directory. + + @header{wx/filefn.h} +*/ +wxString wxGetCwd(); + +/** + Sets the current working directory, returning @true if the operation + succeeded. Under MS Windows, the current drive is also changed if @a dir + contains a drive specification. + + @header{wx/filefn.h} +*/ +bool wxSetWorkingDirectory(const wxString& dir); + +/** + Concatenates @a file1 and @a file2 to @e file3, returning @true if + successful. + + @header{wx/filefn.h} +*/ +bool wxConcatFiles(const wxString& file1, + const wxString& file2, + const wxString& file3); + +/** + Removes @e file, returning @true if successful. + + @header{wx/filefn.h} +*/ +bool wxRemoveFile(const wxString& file); + +/** + Makes the directory @a dir, returning @true if successful. + + @a perm is the access mask for the directory for the systems on which it is + supported (Unix) and doesn't have any effect on the other ones. + + @header{wx/filefn.h} +*/ +bool wxMkdir(const wxString& dir, int perm = 0777); + +/** + Removes the directory @a dir, returning @true if successful. Does not work + under VMS. + + The @a flags parameter is reserved for future use. + + @note There is also a wxRmDir() function which simply wraps the standard + POSIX @c rmdir() function and so return an integer error code instead + of a boolean value (but otherwise is currently identical to + wxRmdir()), don't confuse these two functions. + + @header{wx/filefn.h} +*/ +bool wxRmdir(const wxString& dir, int flags = 0); + +/** + Returns the next file that matches the path passed to wxFindFirstFile(). + + See wxFindFirstFile() for an example. + + @header{wx/filefn.h} +*/ +wxString wxFindNextFile(); + +/** + This function does directory searching; returns the first file that matches + the path @a spec, or the empty string. Use wxFindNextFile() to get the next + matching file. Neither will report the current directory "." or the parent + directory "..". + + @warning As of 2.5.2, these functions are not thread-safe! (they use static + variables). You probably want to use wxDir::GetFirst() or + wxDirTraverser instead. + + @a spec may contain wildcards. + + @a flags may be wxDIR for restricting the query to directories, wxFILE for + files or zero for either. + + For example: + + @code + wxString f = wxFindFirstFile("/home/project/*.*"); + while ( !f.empty() ) + { + ... + f = wxFindNextFile(); + } + @endcode + + @header{wx/filefn.h} +*/ +wxString wxFindFirstFile(const wxString& spec, int flags = 0); + +/** + File kind enumerations returned from wxGetFileKind(). + + @header{wx/filefn.h} +*/ +enum wxFileKind +{ + wxFILE_KIND_UNKNOWN, ///< Unknown file kind, or unable to determine + wxFILE_KIND_DISK, ///< A file supporting seeking to arbitrary offsets + wxFILE_KIND_TERMINAL, ///< A tty + wxFILE_KIND_PIPE ///< A pipe +}; + +//@} + +/** @ingroup group_funcmacro_file */ +//@{ +/** + Returns the type of an open file. Possible return values are enumerations + of ::wxFileKind. + + @header{wx/filefn.h} +*/ +wxFileKind wxGetFileKind(int fd); +wxFileKind wxGetFileKind(FILE* fp); +//@} + +/** @ingroup group_funcmacro_file */ +//@{ +/** + @warning This function is obsolete, please use wxFileName::SplitPath() + instead. + + Returns the filename for a full path. The second form returns a pointer to + temporary storage that should not be deallocated. + + @header{wx/filefn.h} +*/ +wxString wxFileNameFromPath(const wxString& path); +char* wxFileNameFromPath(char* path); +//@} + +/** @ingroup group_funcmacro_file */ +//@{ +/** + @warning This function is obsolete, please use + wxFileName::CreateTempFileName() instead. + + @header{wx/filefn.h} +*/ +char* wxGetTempFileName(const wxString& prefix, char* buf = NULL); +bool wxGetTempFileName(const wxString& prefix, wxString& buf); +//@} + diff --git a/interface/wx/filename.h b/interface/wx/filename.h new file mode 100644 index 0000000000..429cee3a8b --- /dev/null +++ b/interface/wx/filename.h @@ -0,0 +1,1004 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: filename.h +// Purpose: interface of wxFileName +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxFileName + @wxheader{filename.h} + + wxFileName encapsulates a file name. This class serves two purposes: first, it + provides the functions to split the file names into components and to recombine + these components in the full file name which can then be passed to the OS file + functions (and @ref overview_filefunctions "wxWidgets functions" wrapping them). + Second, it includes the functions for working with the files itself. Note that + to change the file data you should use wxFile class instead. + wxFileName provides functions for working with the file attributes. + + When working with directory names (i.e. without filename and extension) + make sure not to misuse the file name part of this class with the last + directory. Instead initialize the wxFileName instance like this: + + @code + wxFileName dirname( "C:\mydir", "" ); + MyMethod( dirname.GetPath() ); + @endcode + + The same can be done using the static method wxFileName::DirName: + + @code + wxFileName dirname = wxFileName::DirName( "C:\mydir" ); + MyMethod( dirname.GetPath() ); + @endcode + + Accordingly, methods dealing with directories or directory names + like wxFileName::IsDirReadable use + wxFileName::GetPath whereas methods dealing + with file names like wxFileName::IsFileReadable + use wxFileName::GetFullPath. + + If it is not known wether a string contains a directory name or + a complete file name (such as when interpreting user input) you need to use + the static function wxFileName::DirExists + (or its identical variants wxDir::Exists and + wxDirExists()) and construct the wxFileName + instance accordingly. This will only work if the directory actually exists, + of course: + + @code + wxString user_input; + // get input from user + + wxFileName fname; + if (wxDirExists(user_input)) + fname.AssignDir( user_input ); + else + fname.Assign( user_input ); + @endcode + + @library{wxbase} + @category{file} + + @see wxFileName::GetCwd +*/ +class wxFileName +{ +public: + //@{ + /** + Constructor from a volume name, a directory name, base file name and extension. + */ + wxFileName(); + wxFileName(const wxFileName& filename); + wxFileName(const wxString& fullpath, + wxPathFormat format = wxPATH_NATIVE); + wxFileName(const wxString& path, const wxString& name, + wxPathFormat format = wxPATH_NATIVE); + wxFileName(const wxString& path, const wxString& name, + const wxString& ext, + wxPathFormat format = wxPATH_NATIVE); + wxFileName(const wxString& volume, const wxString& path, + const wxString& name, + const wxString& ext, + wxPathFormat format = wxPATH_NATIVE); + //@} + + /** + Appends a directory component to the path. This component should contain a + single directory name level, i.e. not contain any path or volume separators nor + should it be empty, otherwise the function does nothing (and generates an + assert failure in debug build). + */ + void AppendDir(const wxString& dir); + + //@{ + /** + Creates the file name from various combinations of data. + */ + void Assign(const wxFileName& filepath); + void Assign(const wxString& fullpath, + wxPathFormat format = wxPATH_NATIVE); + void Assign(const wxString& volume, const wxString& path, + const wxString& name, + const wxString& ext, + bool hasExt, + wxPathFormat format = wxPATH_NATIVE); + void Assign(const wxString& volume, const wxString& path, + const wxString& name, + const wxString& ext, + wxPathFormat format = wxPATH_NATIVE); + void Assign(const wxString& path, const wxString& name, + wxPathFormat format = wxPATH_NATIVE); + void Assign(const wxString& path, const wxString& name, + const wxString& ext, + wxPathFormat format = wxPATH_NATIVE); + //@} + + /** + Makes this object refer to the current working directory on the specified + volume (or current volume if @a volume is empty). + + @see GetCwd() + */ + static void AssignCwd(const wxString& volume = wxEmptyString); + + /** + Sets this file name object to the given directory name. The name and extension + will be empty. + */ + void AssignDir(const wxString& dir, + wxPathFormat format = wxPATH_NATIVE); + + /** + Sets this file name object to the home directory. + */ + void AssignHomeDir(); + + /** + The function calls CreateTempFileName() to + create a temporary file and sets this object to the name of the file. If a + temporary file couldn't be created, the object is put into the + @ref isok() invalid state. + */ + void AssignTempFileName(const wxString& prefix, + wxFile* fileTemp = NULL); + + /** + Reset all components to default, uninitialized state. + */ + void Clear(); + + /** + Removes the extension from the file name resulting in a + file name with no trailing dot. + + @see SetExt(), SetEmptyExt() + */ + void SetClearExt(); + + /** + Returns a temporary file name starting with the given @e prefix. If + the @a prefix is an absolute path, the temporary file is created in this + directory, otherwise it is created in the default system directory for the + temporary files or in the current directory. + If the function succeeds, the temporary file is actually created. If + @a fileTemp is not @NULL, this file will be opened using the name of + the temporary file. When possible, this is done in an atomic way ensuring that + no race condition occurs between the temporary file name generation and opening + it which could often lead to security compromise on the multiuser systems. + If @a fileTemp is @NULL, the file is only created, but not opened. + Under Unix, the temporary file will have read and write permissions for the + owner only to minimize the security problems. + + @param prefix + Prefix to use for the temporary file name construction + @param fileTemp + The file to open or @NULL to just get the name + + @return The full temporary file name or an empty string on error. + */ + static wxString CreateTempFileName(const wxString& prefix, + wxFile* fileTemp = NULL); + + //@{ + /** + Returns @true if the directory with this name exists. + */ + bool DirExists(); + const static bool DirExists(const wxString& dir); + //@} + + /** + Returns the object corresponding to the directory with the given name. + The @a dir parameter may have trailing path separator or not. + */ + static wxFileName DirName(const wxString& dir, + wxPathFormat format = wxPATH_NATIVE); + + /** + These functions allow to examine and modify the individual directories of the + path: + AppendDir() + + InsertDir() + + GetDirCount() + PrependDir() + + RemoveDir() + + RemoveLastDir() + To change the components of the file name individually you can use the + following functions: + GetExt() + + GetName() + + GetVolume() + + HasExt() + + HasName() + + HasVolume() + + SetExt() + + ClearExt() + + SetEmptyExt() + + SetName() + + SetVolume() + */ + + + /** + You can initialize a wxFileName instance using one of the following functions: + @ref wxfilename() "wxFileName constructors" + + Assign() + + AssignCwd() + + AssignDir() + + AssignHomeDir() + + @ref assigntempfilename() AssignHomeTempFileName + + DirName() + + FileName() + + @ref operatorassign() "operator =" + */ + + + /** + wxFileName currently supports the file names in the Unix, DOS/Windows, Mac OS + and VMS formats. Although these formats are quite different, wxFileName tries + to treat them all in the same generic way. It supposes that all file names + consist of the following parts: the volume (also known as drive under Windows + or device under VMS), the path which is a sequence of directory names separated + by the @ref getpathseparators() "path separators" and the full + filename itself which, in turn, is composed from the base file name and the + extension. All of the individual components of the file name may be empty and, + for example, the volume name is always empty under Unix, but if they are all + empty simultaneously, the filename object is considered to be in an invalid + state and IsOk() returns @false for it. + File names can be case-sensitive or not, the function + IsCaseSensitive() allows to determine this. + The rules for determining whether the file name is absolute or relative also + depend on the file name format and the only portable way to answer this + question is to use IsAbsolute() or + IsRelative() method. Note that on Windows, "X:" + refers to the current working directory on drive X. Therefore, a wxFileName + instance constructed from for example "X:dir/file.ext" treats the portion + beyond drive separator as being relative to that directory. + To ensure that the filename is absolute, you may use + MakeAbsolute(). There is also an inverse + function MakeRelativeTo() which undoes + what @ref normalize() Normalize(wxPATH_NORM_DOTS) does. + Other functions returning information about the file format provided by this + class are GetVolumeSeparator(), + IsPathSeparator(). + */ + + + /** + Before doing other tests, you should use IsOk() to + verify that the filename is well defined. If it is, + FileExists() can be used to test whether a file + with such name exists and DirExists() can be used + to test for directory existence. + File names should be compared using SameAs() method + or @ref operatorequal() "operator ==". + For testing basic access modes, you can use: + IsDirWritable() + + IsDirReadable() + + IsFileWritable() + + IsFileReadable() + + IsFileExecutable() + */ + + + //@{ + /** + Returns @true if the file with this name exists. + + @see DirExists() + */ + bool FileExists(); + const static bool FileExists(const wxString& file); + //@} + + /** + Returns the file name object corresponding to the given @e file. This + function exists mainly for symmetry with DirName(). + */ + static wxFileName FileName(const wxString& file, + wxPathFormat format = wxPATH_NATIVE); + + /** + Retrieves the value of the current working directory on the specified volume. If + the volume is empty, the program's current working directory is returned for the + current volume. + + @return The string containing the current working directory or an empty + string on error. + + @see AssignCwd() + */ + static wxString GetCwd(const wxString& volume = ""); + + /** + Returns the number of directories in the file name. + */ + size_t GetDirCount() const; + + /** + Returns the directories in string array form. + */ + const wxArrayString GetDirs() const; + + /** + Returns the file name extension. + */ + wxString GetExt() const; + + /** + Returns the characters that can't be used in filenames and directory names for + the specified format. + */ + static wxString GetForbiddenChars(wxPathFormat format = wxPATH_NATIVE); + + /** + Returns the canonical path format for this platform. + */ + static wxPathFormat GetFormat(wxPathFormat format = wxPATH_NATIVE); + + /** + Returns the full name (including extension but excluding directories). + */ + wxString GetFullName() const; + + /** + Returns the full path with name and extension. + */ + wxString GetFullPath(wxPathFormat format = wxPATH_NATIVE) const; + + /** + Returns the home directory. + */ + static wxString GetHomeDir(); + + //@{ + /** + Returns the size of this file (first form) or the given number of bytes (second + form) + in a human-readable form. + If the size could not be retrieved the @c failmsg string is returned (first + form). + If @c bytes is @c wxInvalidSize or zero, then @c nullsize is returned (second + form). + In case of success, the returned string is a floating-point number with @c + precision decimal digits + followed by the size unit (B, kB, MB, GB, TB: respectively bytes, kilobytes, + megabytes, gigabytes, terabytes). + */ + wxString GetHumanReadableSize(const wxString& failmsg = "Not available", + int precision = 1); + const static wxString GetHumanReadableSize(const wxULongLong& bytes, + const wxString& nullsize = "Not available", + int precision = 1); + //@} + + /** + Return the long form of the path (returns identity on non-Windows platforms) + */ + wxString GetLongPath() const; + + /** + Returns the last time the file was last modified. + */ + wxDateTime GetModificationTime() const; + + /** + Returns the name part of the filename (without extension). + + @see GetFullName() + */ + wxString GetName() const; + + /** + Returns the path part of the filename (without the name or extension). The + possible flags values are: + + @b wxPATH_GET_VOLUME + + Return the path with the volume (does + nothing for the filename formats without volumes), otherwise the path without + volume part is returned. + + @b wxPATH_GET_SEPARATOR + + Return the path with the trailing + separator, if this flag is not given there will be no separator at the end of + the path. + */ + wxString GetPath(int flags = wxPATH_GET_VOLUME, + wxPathFormat format = wxPATH_NATIVE) const; + + /** + Returns the usually used path separator for this format. For all formats but + @c wxPATH_DOS there is only one path separator anyhow, but for DOS there + are two of them and the native one, i.e. the backslash is returned by this + method. + + @see GetPathSeparators() + */ + static wxChar GetPathSeparator(wxPathFormat format = wxPATH_NATIVE); + + /** + Returns the string containing all the path separators for this format. For all + formats but @c wxPATH_DOS this string contains only one character but for + DOS and Windows both @c '/' and @c '\' may be used as + separators. + + @see GetPathSeparator() + */ + static wxString GetPathSeparators(wxPathFormat format = wxPATH_NATIVE); + + /** + Returns the string of characters which may terminate the path part. This is the + same as GetPathSeparators() except for VMS + path format where ] is used at the end of the path part. + */ + static wxString GetPathTerminators(wxPathFormat format = wxPATH_NATIVE); + + /** + Returns the path with the trailing separator, useful for appending the name to + the given path. + This is the same as calling GetPath() + @c (wxPATH_GET_VOLUME | wxPATH_GET_SEPARATOR, format). + */ + wxString GetPathWithSep(wxPathFormat format = wxPATH_NATIVE) const; + + /** + Return the short form of the path (returns identity on non-Windows platforms). + */ + wxString GetShortPath() const; + + //@{ + /** + Returns the size of this file (first form) or the size of the given file + (second form). + If the file does not exist or its size could not be read (because e.g. the file + is locked + by another process) the returned value is @c wxInvalidSize. + */ + wxULongLong GetSize(); + const static wxULongLong GetSize(const wxString& filename); + //@} + + /** + Returns the directory used for temporary files. + */ + static wxString GetTempDir(); + + /** + Returns the last access, last modification and creation times. The last access + time is updated whenever the file is read or written (or executed in the case + of Windows), last modification time is only changed when the file is written + to. Finally, the creation time is indeed the time when the file was created + under Windows and the inode change time under Unix (as it is impossible to + retrieve the real file creation time there anyhow) which can also be changed + by many operations after the file creation. + If no filename or extension is specified in this instance of wxFileName + (and therefore IsDir() returns @true) then + this function will return the directory times of the path specified by + GetPath(), otherwise the file times of the + file specified by GetFullPath(). + Any of the pointers may be @NULL if the corresponding time is not + needed. + + @return @true on success, @false if we failed to retrieve the times. + */ + bool GetTimes(wxDateTime* dtAccess, wxDateTime* dtMod, + wxDateTime* dtCreate) const; + + /** + Returns the string containing the volume for this file name, empty if it + doesn't have one or if the file system doesn't support volumes at all (for + example, Unix). + */ + wxString GetVolume() const; + + /** + Returns the string separating the volume from the path for this format. + */ + static wxString GetVolumeSeparator(wxPathFormat format = wxPATH_NATIVE); + + /** + Returns @true if an extension is present. + */ + bool HasExt() const; + + /** + Returns @true if a name is present. + */ + bool HasName() const; + + /** + Returns @true if a volume specifier is present. + */ + bool HasVolume() const; + + /** + Inserts a directory component before the zero-based position in the directory + list. Please see AppendDir() for important notes. + */ + void InsertDir(size_t before, const wxString& dir); + + /** + Returns @true if this filename is absolute. + */ + bool IsAbsolute(wxPathFormat format = wxPATH_NATIVE); + + /** + Returns @true if the file names of this type are case-sensitive. + */ + static bool IsCaseSensitive(wxPathFormat format = wxPATH_NATIVE); + + /** + Returns @true if this object represents a directory, @false otherwise + (i.e. if it is a file). Note that this method doesn't test whether the + directory or file really exists, you should use + DirExists() or + FileExists() for this. + */ + bool IsDir() const; + + //@{ + /** + Returns @true if the directory component of this instance (or given @e dir) + is an existing directory and this process has read permissions on it. + Read permissions on a directory mean that you can list the directory contents + but it + doesn't imply that you have read permissions on the files contained. + */ + bool IsDirReadable(); + const static bool IsDirReadable(const wxString& dir); + //@} + + //@{ + /** + Returns @true if the directory component of this instance (or given @e dir) + is an existing directory and this process has write permissions on it. + Write permissions on a directory mean that you can create new files in the + directory. + */ + bool IsDirWritable(); + const static bool IsDirWritable(const wxString& dir); + //@} + + //@{ + /** + Returns @true if a file with this name exists and if this process has execute + permissions on it. + */ + bool IsFileExecutable(); + const static bool IsFileExecutable(const wxString& file); + //@} + + //@{ + /** + Returns @true if a file with this name exists and if this process has read + permissions on it. + */ + bool IsFileReadable(); + const static bool IsFileReadable(const wxString& file); + //@} + + //@{ + /** + Returns @true if a file with this name exists and if this process has write + permissions on it. + */ + bool IsFileWritable(); + const static bool IsFileWritable(const wxString& file); + //@} + + /** + Returns @true if the filename is valid, @false if it is not + initialized yet. The assignment functions and + Clear() may reset the object to the uninitialized, + invalid state (the former only do it on failure). + */ + bool IsOk() const; + + /** + Returns @true if the char is a path separator for this format. + */ + static bool IsPathSeparator(wxChar ch, + wxPathFormat format = wxPATH_NATIVE); + + /** + Returns @true if this filename is not absolute. + */ + bool IsRelative(wxPathFormat format = wxPATH_NATIVE); + + /** + On Mac OS, gets the common type and creator for the given extension. + */ + static bool MacFindDefaultTypeAndCreator(const wxString& ext, + wxUint32* type, + wxUint32* creator); + + /** + On Mac OS, registers application defined extensions and their default type and + creator. + */ + static void MacRegisterDefaultTypeAndCreator(const wxString& ext, + wxUint32 type, + wxUint32 creator); + + /** + On Mac OS, looks up the appropriate type and creator from the registration and + then sets it. + */ + bool MacSetDefaultTypeAndCreator(); + + /** + Make the file name absolute. This is a shortcut for + @c wxFileName::Normalize(wxPATH_NORM_DOTS | wxPATH_NORM_ABSOLUTE | + wxPATH_NORM_TILDE, cwd, format). + + @see MakeRelativeTo(), Normalize(), IsAbsolute() + */ + bool MakeAbsolute(const wxString& cwd = wxEmptyString, + wxPathFormat format = wxPATH_NATIVE); + + /** + This function tries to put this file name in a form relative to + + @param pathBase. + In other words, it returns the file name which should be used to access this + file if the current directory were pathBase. + + pathBase + the directory to use as root, current directory is used by + default + @param format + the file name format, native by default + + @return @true if the file name has been changed, @false if we failed to do + anything with it (currently this only happens if the + file name is on a volume different from the volume + specified by pathBase). + + @see Normalize() + */ + bool MakeRelativeTo(const wxString& pathBase = wxEmptyString, + wxPathFormat format = wxPATH_NATIVE); + + //@{ + /** + @param dir + the directory to create + @param parm + the permissions for the newly created directory + @param flags + if the flags contain wxPATH_MKDIR_FULL flag, + try to create each directory in the path and also don't return an error + if the target directory already exists. + + @return Returns @true if the directory was successfully created, @false + otherwise. + */ + bool Mkdir(int perm = 0777, int flags = 0); + static bool Mkdir(const wxString& dir, int perm = 0777, + int flags = 0); + //@} + + /** + Normalize the path. With the default flags value, the path will be + made absolute, without any ".." and "." and all environment + variables will be expanded in it. + + @param flags + The kind of normalization to do with the file name. It can be + any or-combination of the following constants: + + + + + + + wxPATH_NORM_ENV_VARS + + + + + replace env vars with their values + + + + + + wxPATH_NORM_DOTS + + + + + squeeze all .. and . when possible; if there are too many .. and thus they + cannot be all removed, @false will be returned + + + + + + wxPATH_NORM_CASE + + + + + if filesystem is case insensitive, transform to lower case + + + + + + wxPATH_NORM_ABSOLUTE + + + + + make the path absolute prepending cwd + + + + + + wxPATH_NORM_LONG + + + + + make the path the long form + + + + + + wxPATH_NORM_SHORTCUT + + + + + resolve if it is a shortcut (Windows only) + + + + + + wxPATH_NORM_TILDE + + + + + replace ~ and ~user (Unix only) + + + + + + wxPATH_NORM_ALL + + + + + all of previous flags except wxPATH_NORM_CASE + @param cwd + If not empty, this directory will be used instead of current + working directory in normalization (see wxPATH_NORM_ABSOLUTE). + @param format + The file name format to use when processing the paths, native by default. + + @return @true if normalization was successfully or @false otherwise. + */ + bool Normalize(int flags = wxPATH_NORM_ALL, + const wxString& cwd = wxEmptyString, + wxPathFormat format = wxPATH_NATIVE); + + /** + These methods allow to work with the file creation, access and modification + times. Note that not all filesystems under all platforms implement these times + in the same way. For example, the access time under Windows has a resolution of + one day (so it is really the access date and not time). The access time may be + updated when the file is executed or not depending on the platform. + GetModificationTime() + + GetTimes() + + SetTimes() + + Touch() + Other file system operations functions are: + Mkdir() + + Rmdir() + */ + + + /** + Prepends a directory to the file path. Please see + AppendDir() for important notes. + */ + void PrependDir(const wxString& dir); + + /** + Removes the specified directory component from the path. + + @see GetDirCount() + */ + void RemoveDir(size_t pos); + + /** + Removes last directory component from the path. + */ + void RemoveLastDir(); + + //@{ + /** + Deletes the specified directory from the file system. + */ + bool Rmdir(); + static bool Rmdir(const wxString& dir); + //@} + + /** + Compares the filename using the rules of this platform. + */ + bool SameAs(const wxFileName& filepath, + wxPathFormat format = wxPATH_NATIVE) const; + + //@{ + /** + Changes the current working directory. + */ + bool SetCwd(); + static bool SetCwd(const wxString& cwd); + //@} + + /** + Sets the extension of the file name to be an empty extension. + This is different from having no extension at all as the file + name will have a trailing dot after a call to this method. + + @see SetExt(), ClearExt() + */ + void SetEmptyExt(); + + /** + Sets the extension of the file name. Setting an empty string + as the extension will remove the extension resulting in a file + name without a trailing dot, unlike a call to + SetEmptyExt(). + + @see SetEmptyExt(), ClearExt() + */ + void SetExt(const wxString& ext); + + /** + The full name is the file name and extension (but without the path). + */ + void SetFullName(const wxString& fullname); + + /** + Sets the name part (without extension). + + @see SetFullName() + */ + void SetName(const wxString& name); + + /** + Sets the file creation and last access/modification times (any of the pointers + may be @NULL). + */ + bool SetTimes(const wxDateTime* dtAccess, + const wxDateTime* dtMod, + const wxDateTime* dtCreate); + + /** + Sets the volume specifier. + */ + void SetVolume(const wxString& volume); + + //@{ + /** + This function splits a full file name into components: the volume (with the + first version) path (including the volume in the second version), the base name + and the extension. Any of the output parameters (@e volume, @e path, + @a name or @e ext) may be @NULL if you are not interested in the + value of a particular component. Also, @a fullpath may be empty on entry. + On return, @a path contains the file path (without the trailing separator), + @a name contains the file name and @a ext contains the file extension + without leading dot. All three of them may be empty if the corresponding + component is. The old contents of the strings pointed to by these parameters + will be overwritten in any case (if the pointers are not @NULL). + Note that for a filename "foo." the extension is present, as indicated by the + trailing dot, but empty. If you need to cope with such cases, you should use + @a hasExt instead of relying on testing whether @a ext is empty or not. + */ + static void SplitPath(const wxString& fullpath, wxString* volume, + wxString* path, + wxString* name, + wxString* ext, + bool hasExt = NULL, + wxPathFormat format = wxPATH_NATIVE); + static void SplitPath(const wxString& fullpath, + wxString* volume, + wxString* path, + wxString* name, + wxString* ext, + wxPathFormat format = wxPATH_NATIVE); + static void SplitPath(const wxString& fullpath, + wxString* path, + wxString* name, + wxString* ext, + wxPathFormat format = wxPATH_NATIVE); + //@} + + /** + Splits the given @a fullpath into the volume part (which may be empty) and + the pure path part, not containing any volume. + + @see SplitPath() + */ + static void SplitVolume(const wxString& fullpath, + wxString* volume, + wxString* path, + wxPathFormat format = wxPATH_NATIVE); + + /** + Sets the access and modification times to the current moment. + */ + bool Touch(); + + //@{ + /** + Returns @true if the filenames are different. The string @e filenames + is interpreted as a path in the native filename format. + */ + bool operator operator!=(const wxFileName& filename) const; + const bool operator operator!=(const wxString& filename) const; + //@} + + //@{ + /** + Assigns the new value to this filename object. + */ + wxFileName& operator operator=(const wxFileName& filename); + wxFileName& operator operator=(const wxString& filename); + //@} + + //@{ + /** + Returns @true if the filenames are equal. The string @e filenames is + interpreted as a path in the native filename format. + */ + bool operator operator==(const wxFileName& filename) const; + const bool operator operator==(const wxString& filename) const; + //@} +}; + diff --git a/interface/wx/filepicker.h b/interface/wx/filepicker.h new file mode 100644 index 0000000000..2cb91adc97 --- /dev/null +++ b/interface/wx/filepicker.h @@ -0,0 +1,277 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: filepicker.h +// Purpose: interface of wxFilePickerCtrl +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxFilePickerCtrl + @wxheader{filepicker.h} + + This control allows the user to select a file. The generic implementation is + a button which brings up a wxFileDialog when clicked. Native implementation + may differ but this is usually a (small) widget which give access to the + file-chooser + dialog. + It is only available if @c wxUSE_FILEPICKERCTRL is set to 1 (the default). + + @beginStyleTable + @style{wxFLP_DEFAULT_STYLE} + The default style: includes wxFLP_OPEN | wxFLP_FILE_MUST_EXIST and, + under wxMSW only, wxFLP_USE_TEXTCTRL. + @style{wxFLP_USE_TEXTCTRL} + Creates a text control to the left of the picker button which is + completely managed by the wxFilePickerCtrl and which can be used by + the user to specify a path (see SetPath). The text control is + automatically synchronized with button's value. Use functions + defined in wxPickerBase to modify the text control. + @style{wxFLP_OPEN} + Creates a picker which allows the user to select a file to open. + @style{wxFLP_SAVE} + Creates a picker which allows the user to select a file to save. + @style{wxFLP_OVERWRITE_PROMPT} + Can be combined with wxFLP_SAVE only: ask confirmation to the user + before selecting a file. + @style{wxFLP_FILE_MUST_EXIST} + Can be combined with wxFLP_OPEN only: the selected file must be an + existing file. + @style{wxFLP_CHANGE_DIR} + Change current working directory on each user file selection change. + @endStyleTable + + @library{wxcore} + @category{pickers} + + + @see wxFileDialog, wxFileDirPickerEvent +*/ +class wxFilePickerCtrl : public wxPickerBase +{ +public: + /** + Initializes the object and calls Create() with + all the parameters. + */ + wxFilePickerCtrl(wxWindow* parent, wxWindowID id, + const wxString& path = wxEmptyString, + const wxString& message = "Select a file", + const wxString& wildcard = ".", + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxFLP_DEFAULT_STYLE, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "filepickerctrl"); + + /** + @param parent + Parent window, must not be non-@NULL. + @param id + The identifier for the control. + @param path + The initial file shown in the control. Must be a valid path to a file or + the empty string. + @param message + The message shown to the user in the wxFileDialog shown by the control. + @param wildcard + A wildcard which defines user-selectable files (use the same syntax as for + wxFileDialog's wildcards). + @param pos + Initial position. + @param size + Initial size. + @param style + The window style, see wxFLP_* flags. + @param validator + Validator which can be used for additional date checks. + @param name + Control name. + + @return @true if the control was successfully created or @false if + creation failed. + */ + bool Create(wxWindow* parent, wxWindowID id, + const wxString& path = wxEmptyString, + const wxString& message = "Select a file", + const wxString& wildcard = ".", + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxFLP_DEFAULT_STYLE, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "filepickerctrl"); + + /** + Similar to GetPath() but returns the path of + the currently selected file as a wxFileName object. + */ + wxFileName GetFileName() const; + + /** + Returns the absolute path of the currently selected file. + */ + wxString GetPath() const; + + /** + This method does the same thing as SetPath() but + takes a wxFileName object instead of a string. + */ + void SetFileName(const wxFileName& filename); + + /** + Sets the absolute path of the currently selected file. This must be a valid + file if + the @c wxFLP_FILE_MUST_EXIST style was given. + */ + void SetPath(const wxString& filename); +}; + + + +/** + @class wxDirPickerCtrl + @wxheader{filepicker.h} + + This control allows the user to select a directory. The generic implementation + is + a button which brings up a wxDirDialog when clicked. Native implementation + may differ but this is usually a (small) widget which give access to the + dir-chooser + dialog. + It is only available if @c wxUSE_DIRPICKERCTRL is set to 1 (the default). + + @beginStyleTable + @style{wxDIRP_DEFAULT_STYLE} + The default style: includes wxDIRP_DIR_MUST_EXIST and, under wxMSW + only, wxDIRP_USE_TEXTCTRL. + @style{wxDIRP_USE_TEXTCTRL} + Creates a text control to the left of the picker button which is + completely managed by the wxDirPickerCtrl and which can be used by + the user to specify a path (see SetPath). The text control is + automatically synchronized with button's value. Use functions + defined in wxPickerBase to modify the text control. + @style{wxDIRP_DIR_MUST_EXIST} + Creates a picker which allows to select only existing directories. + wxGTK control always adds this flag internally as it does not + support its absence. + @style{wxDIRP_CHANGE_DIR} + Change current working directory on each user directory selection + change. + @endStyleTable + + @library{wxcore} + @category{pickers} + + + @see wxDirDialog, wxFileDirPickerEvent +*/ +class wxDirPickerCtrl : public wxPickerBase +{ +public: + /** + Initializes the object and calls Create() with + all the parameters. + */ + wxDirPickerCtrl(wxWindow* parent, wxWindowID id, + const wxString& path = wxEmptyString, + const wxString& message = "Select a folder", + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxDIRP_DEFAULT_STYLE, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "dirpickerctrl"); + + /** + @param parent + Parent window, must not be non-@NULL. + @param id + The identifier for the control. + @param path + The initial directory shown in the control. Must be a valid path to a + directory or the empty string. + @param message + The message shown to the user in the wxDirDialog shown by the control. + @param pos + Initial position. + @param size + Initial size. + @param style + The window style, see wxDIRP_* flags. + @param validator + Validator which can be used for additional date checks. + @param name + Control name. + + @return @true if the control was successfully created or @false if + creation failed. + */ + bool Create(wxWindow* parent, wxWindowID id, + const wxString& path = wxEmptyString, + const wxString& message = "Select a folder", + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxDIRP_DEFAULT_STYLE, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "dirpickerctrl"); + + /** + Returns the absolute path of the currently selected directory as a wxFileName + object. + This function is equivalent to GetPath() + */ + wxFileName GetDirName() const; + + /** + Returns the absolute path of the currently selected directory. + */ + wxString GetPath() const; + + /** + Just like SetPath() but this function takes a + wxFileName object. + */ + void SetDirName(const wxFileName& dirname); + + /** + Sets the absolute path of (the default converter uses current locale's + charset)the currently selected directory. This must be a valid directory if + @c wxDIRP_DIR_MUST_EXIST style was given. + */ + void SetPath(const wxString& dirname); +}; + + + +/** + @class wxFileDirPickerEvent + @wxheader{filepicker.h} + + This event class is used for the events generated by + wxFilePickerCtrl and by wxDirPickerCtrl. + + @library{wxcore} + @category{FIXME} + + @see wxfilepickerctrl() +*/ +class wxFileDirPickerEvent : public wxCommandEvent +{ +public: + /** + The constructor is not normally used by the user code. + */ + wxFileDirPickerEvent(wxEventType type, wxObject* generator, + int id, + const wxString path); + + /** + Retrieve the absolute path of the file/directory the user has just selected. + */ + wxString GetPath() const; + + /** + Set the absolute path of the file/directory associated with the event. + */ + void SetPath(const wxString& path); +}; + diff --git a/interface/wx/filesys.h b/interface/wx/filesys.h new file mode 100644 index 0000000000..c9d534e86a --- /dev/null +++ b/interface/wx/filesys.h @@ -0,0 +1,450 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: filesys.h +// Purpose: interface of wxFileSystem, wxFileSystemHandler, wxFSFile +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + + +/** + Open Bit Flags +*/ +enum wxFileSystemOpenFlags +{ + wxFS_READ = 1, /**< Open for reading */ + wxFS_SEEKABLE = 4 /**< Returned stream will be seekable */ +}; + + +/** + @class wxFileSystem + @wxheader{filesys.h} + + This class provides an interface for opening files on different file systems. + It can handle absolute and/or local filenames. + + It uses a system of handlers (see wxFileSystemHandler) to provide access to + user-defined virtual file systems. + + @library{wxbase} + @category{vfs} + + @see wxFileSystemHandler, wxFSFile, @ref overview_fs +*/ +class wxFileSystem : public wxObject +{ +public: + /** + Constructor. + */ + wxFileSystem(); + + /** + This static function adds new handler into the list of handlers + (see wxFileSystemHandler) which provide access to virtual FS. + + Note that if two handlers for the same protocol are added, the last + added one takes precedence. + + @note You can call: + @code + wxFileSystem::AddHandler(new My_FS_Handler); + @endcode + This is because (a) AddHandler is a static method, and (b) the + handlers are deleted in wxFileSystem's destructor so that you + don't have to care about it. + */ + static void AddHandler(wxFileSystemHandler handler); + + /** + Sets the current location. @a location parameter passed to OpenFile() is + relative to this path. + + @remarks Unless @a is_dir is @true the @a location parameter is not the + directory name but the name of the file in this directory. + + All these commands change the path to "dir/subdir/": + + @code + ChangePathTo("dir/subdir/xh.htm"); + ChangePathTo("dir/subdir", true); + ChangePathTo("dir/subdir/", true); + @endcode + + Example: + @code + f = fs->OpenFile("hello.htm"); // opens file 'hello.htm' + fs->ChangePathTo("subdir/folder", true); + f = fs->OpenFile("hello.htm"); // opens file 'subdir/folder/hello.htm' !! + @endcode + + @param location + the new location. Its meaning depends on the value of is_dir + @param is_dir + if @true location is new directory. + If @false (the default) location is file in the new directory. + */ + void ChangePathTo(const wxString& location, bool is_dir = false); + + /** + Converts a wxFileName into an URL. + + @see URLToFileName(), wxFileName + */ + static wxString FileNameToURL(const wxFileName& filename); + + /** + Looks for the file with the given name @a file in a colon or semi-colon + (depending on the current platform) separated list of directories in @a path. + + If the file is found in any directory, returns @true and the full path + of the file in @a str, otherwise returns @false and doesn't modify @a str. + + @param str + Receives the full path of the file, must not be @NULL + @param path + wxPATH_SEP-separated list of directories + @param file + the name of the file to look for + */ + bool FindFileInPath(wxString str, const wxString& path, + const wxString& file); + + /** + Works like ::wxFindFirstFile(). + + Returns the name of the first filename (within filesystem's current path) + that matches @a wildcard. + + @param wildcard + The wildcard that the filename must match + @param flags + One of wxFILE (only files), wxDIR (only directories) or 0 (both). + */ + wxString FindFirst(const wxString& wildcard, int flags = 0); + + /** + Returns the next filename that matches the parameters passed to FindFirst(). + */ + wxString FindNext(); + + /** + Returns the actual path (set by wxFileSystem::ChangePathTo). + */ + wxString GetPath(); + + /** + This static function returns @true if there is a registered handler which can + open the given location. + */ + static bool HasHandlerForPath(const wxString& location); + + /** + Opens the file and returns a pointer to a wxFSFile object or @NULL if failed. + + It first tries to open the file in relative scope (based on value passed to + ChangePathTo() method) and then as an absolute path. + + Note that the user is responsible for deleting the returned wxFSFile. + @a flags can be one or more of the ::wxFileSystemOpenFlags values + combined together. + + A stream opened with just the default @e wxFS_READ flag may + or may not be seekable depending on the underlying source. + + Passing @e "wxFS_READ | wxFS_SEEKABLE" for @a flags will back + a stream that is not natively seekable with memory or a file + and return a stream that is always seekable. + */ + wxFSFile* OpenFile(const wxString& location, + int flags = wxFS_READ); + + /** + Converts URL into a well-formed filename. + The URL must use the @c file protocol. + */ + static wxFileName URLToFileName(const wxString& url); +}; + + + +/** + @class wxFSFile + @wxheader{filesys.h} + + This class represents a single file opened by wxFileSystem. + It provides more information than wxWindow's input stream + (stream, filename, mime type, anchor). + + @note Any pointer returned by a method of wxFSFile is valid only as long as + the wxFSFile object exists. For example a call to GetStream() + doesn't @e create the stream but only returns the pointer to it. + In other words after 10 calls to GetStream() you will have obtained + ten identical pointers. + + @library{wxbase} + @category{vfs} + + @see wxFileSystemHandler, wxFileSystem, @ref overview_fs +*/ +class wxFSFile : public wxObject +{ +public: + /** + Constructor. You probably won't use it. See the Note for details. + + It is seldom used by the application programmer but you will need it if + you are writing your own virtual FS. For example you may need something + similar to wxMemoryInputStream, but because wxMemoryInputStream doesn't + free the memory when destroyed and thus passing a memory stream pointer + into wxFSFile constructor would lead to memory leaks, you can write your + own class derived from wxFSFile: + + @code + class wxMyFSFile : public wxFSFile + { + private: + void *m_Mem; + public: + wxMyFSFile(.....) + ~wxMyFSFile() {free(m_Mem);} + // of course dtor is virtual ;-) + }; + @endcode + + If you are not sure of the meaning of these params, see the description + of the GetXXXX() functions. + + @param stream + The input stream that will be used to access data + @param location + The full location (aka filename) of the file + @param mimetype + MIME type of this file. It may be left empty, in which + case the type will be determined from file's extension (location must + not be empty in this case). + @param anchor + Anchor. See GetAnchor() for details. + */ + wxFSFile(wxInputStream stream, const wxString& loc, + const wxString& mimetype, + const wxString& anchor, wxDateTime modif); + + /** + Detaches the stream from the wxFSFile object. That is, the + stream obtained with GetStream() will continue its existance + after the wxFSFile object is deleted. + + You will have to delete the stream yourself. + */ + void DetachStream(); + + /** + Returns anchor (if present). The term of @b anchor can be easily + explained using few examples: + + @verbatim + index.htm#anchor // 'anchor' is anchor + index/wx001.htm // NO anchor here! + archive/main.zip#zip:index.htm#global // 'global' + archive/main.zip#zip:index.htm // NO anchor here! + @endverbatim + + Usually an anchor is presented only if the MIME type is 'text/html'. + But it may have some meaning with other files; for example myanim.avi#200 + may refer to position in animation or reality.wrl#MyView may refer + to a predefined view in VRML. + */ + const wxString& GetAnchor() const; + + /** + Returns full location of the file, including path and protocol. + + Examples: + @verbatim + http://www.wxwidgets.org + http://www.ms.mff.cuni.cz/~vsla8348/wxhtml/archive.zip#zip:info.txt + file:/home/vasek/index.htm + relative-file.htm + @endverbatim + */ + const wxString& GetLocation() const; + + /** + Returns the MIME type of the content of this file. + + It is either extension-based (see wxMimeTypesManager) or extracted from + HTTP protocol Content-Type header. + */ + const wxString& GetMimeType() const; + + /** + Returns time when this file was modified. + */ + wxDateTime GetModificationTime() const; + + /** + Returns pointer to the stream. + + You can use the returned stream to directly access data. + You may suppose that the stream provide Seek and GetSize functionality + (even in the case of the HTTP protocol which doesn't provide + this by default. wxHtml uses local cache to work around + this and to speed up the connection). + */ + wxInputStream* GetStream() const; +}; + + + +/** + @class wxFileSystemHandler + @wxheader{filesys.h} + + Classes derived from wxFileSystemHandler are used to access virtual file systems. + + Its public interface consists of two methods: wxFileSystemHandler::CanOpen + and wxFileSystemHandler::OpenFile. + + It provides additional protected methods to simplify the process + of opening the file: GetProtocol(), GetLeftLocation(), GetRightLocation(), + GetAnchor(), GetMimeTypeFromExt(). + + Please have a look at overview (see wxFileSystem) if you don't know how locations + are constructed. + + Also consult the @ref overview_fs_wxhtmlfs "list of available handlers". + + Note that the handlers are shared by all instances of wxFileSystem. + + @remarks + wxHTML library provides handlers for local files and HTTP or FTP protocol. + + @note + The location parameter passed to OpenFile() or CanOpen() methods is always an + absolute path. You don't need to check the FS's current path. + + @beginWxPerlOnly + In wxPerl, you need to derive your file system handler class + from Wx::PlFileSystemHandler. + @endWxPerlOnly + + @library{wxbase} + @category{vfs} + + @see wxFileSystem, wxFSFile, @ref overview_fs +*/ +class wxFileSystemHandler : public wxObject +{ +public: + /** + Constructor. + */ + wxFileSystemHandler(); + + /** + Returns @true if the handler is able to open this file. This function doesn't + check whether the file exists or not, it only checks if it knows the protocol. + Example: + + @code + bool MyHand::CanOpen(const wxString& location) + { + return (GetProtocol(location) == "http"); + } + @endcode + + Must be overridden in derived handlers. + */ + virtual bool CanOpen(const wxString& location); + + /** + Works like ::wxFindFirstFile(). + + Returns the name of the first filename (within filesystem's current path) + that matches @e wildcard. @a flags may be one of wxFILE (only files), + wxDIR (only directories) or 0 (both). + + This method is only called if CanOpen() returns @true. + */ + virtual wxString FindFirst(const wxString& wildcard, + int flags = 0); + + /** + Returns next filename that matches parameters passed to wxFileSystem::FindFirst. + + This method is only called if CanOpen() returns @true and FindFirst() + returned a non-empty string. + */ + virtual wxString FindNext(); + + /** + Returns the anchor if present in the location. + See wxFSFile::GetAnchor for details. + + Example: + @code + GetAnchor("index.htm#chapter2") == "chapter2" + @endcode + + @note the anchor is NOT part of the left location. + */ + wxString GetAnchor(const wxString& location) const; + + /** + Returns the left location string extracted from @e location. + + Example: + @code + GetLeftLocation("file:myzipfile.zip#zip:index.htm") == "file:myzipfile.zip" + @endcode + */ + wxString GetLeftLocation(const wxString& location) const; + + /** + Returns the MIME type based on @b extension of @a location. + (While wxFSFile::GetMimeType() returns real MIME type - either + extension-based or queried from HTTP.) + + Example: + @code + GetMimeTypeFromExt("index.htm") == "text/html" + @endcode + */ + wxString GetMimeTypeFromExt(const wxString& location); + + /** + Returns the protocol string extracted from @a location. + + Example: + @code + GetProtocol("file:myzipfile.zip#zip:index.htm") == "zip" + @endcode + */ + wxString GetProtocol(const wxString& location) const; + + /** + Returns the right location string extracted from @a location. + + Example: + @code + GetRightLocation("file:myzipfile.zip#zip:index.htm") == "index.htm" + @endcode + */ + wxString GetRightLocation(const wxString& location) const; + + /** + Opens the file and returns wxFSFile pointer or @NULL if failed. + Must be overridden in derived handlers. + + @param fs + Parent FS (the FS from that OpenFile was called). + See the ZIP handler for details of how to use it. + @param location + The absolute location of file. + */ + virtual wxFSFile* OpenFile(wxFileSystem& fs, + const wxString& location); +}; + diff --git a/interface/wx/font.h b/interface/wx/font.h new file mode 100644 index 0000000000..a3eeaba9fe --- /dev/null +++ b/interface/wx/font.h @@ -0,0 +1,748 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: font.h +// Purpose: interface of wxFont +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxFont + @wxheader{font.h} + + A font is an object which determines the appearance of text. Fonts are + used for drawing text to a device context, and setting the appearance of + a window's text. + + This class uses @ref overview_trefcount "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 counting, are not affected. + + You can retrieve the current system font settings with wxSystemSettings. + + wxSystemSettings + + @library{wxcore} + @category{gdi} + + @stdobjects + ::wxNullFont, ::wxNORMAL_FONT, ::wxSMALL_FONT, ::wxITALIC_FONT, ::wxSWISS_FONT + + @see @ref overview_wxfontoverview, wxDC::SetFont, wxDC::DrawText, + wxDC::GetTextExtent, wxFontDialog, wxSystemSettings +*/ +class wxFont : public wxGDIObject +{ +public: + //@{ + /** + Creates a font object with the specified attributes. + + @param pointSize + Size in points. + @param pixelSize + Size in pixels: this is directly supported only under MSW + currently where this constructor can be used directly, under other + platforms a + font with the closest size to the given one is found using binary search and + the static New method must be used. + @param family + Font family, a generic way of referring to fonts without specifying actual + facename. One of: + + + + + + + + wxFONTFAMILY_DEFAULT + + + + + Chooses a default font. + + + + + + wxFONTFAMILY_DECORATIVE + + + + + A decorative font. + + + + + + wxFONTFAMILY_ROMAN + + + + + A formal, serif font. + + + + + + wxFONTFAMILY_SCRIPT + + + + + A handwriting font. + + + + + + wxFONTFAMILY_SWISS + + + + + A sans-serif font. + + + + + + wxFONTFAMILY_MODERN + + + + + A fixed pitch font. + + + + + + wxFONTFAMILY_TELETYPE + + + + + A teletype font. + @param style + One of wxFONTSTYLE_NORMAL, wxFONTSTYLE_SLANT and wxFONTSTYLE_ITALIC. + @param weight + Font weight, sometimes also referred to as font boldness. One of: + + + + + + + + wxFONTWEIGHT_NORMAL + + + + + Normal font. + + + + + + wxFONTWEIGHT_LIGHT + + + + + Light font. + + + + + + wxFONTWEIGHT_BOLD + + + + + Bold font. + @param underline + The value can be @true or @false. At present this has an effect on Windows + and Motif 2.x only. + @param faceName + An optional string specifying the actual typeface to be used. If it is an + empty string, + a default typeface will be chosen based on the family. + @param encoding + An encoding which may be one of + + + + + + + + wxFONTENCODING_SYSTEM + + + + + Default system encoding. + + + + + + wxFONTENCODING_DEFAULT + + + + + Default application encoding: this + is the encoding set by calls to + SetDefaultEncoding and which may be set to, + say, KOI8 to create all fonts by default with KOI8 encoding. Initially, the + default application encoding is the same as default system encoding. + + + + + + wxFONTENCODING_ISO8859_1...15 + + + + + ISO8859 encodings. + + + + + + wxFONTENCODING_KOI8 + + + + + The standard Russian encoding for Internet. + + + + + + wxFONTENCODING_CP1250...1252 + + + + + Windows encodings similar to ISO8859 (but not identical). + + + + + + If the specified encoding isn't available, no font is created + (see also font encoding overview). + + @remarks If the desired font does not exist, the closest match will be + chosen. Under Windows, only scalable TrueType fonts are + used. + */ + wxFont(); + wxFont(const wxFont& font); + wxFont(int pointSize, wxFontFamily family, int style, + wxFontWeight weight, + const bool underline = false, + const wxString& faceName = "", + wxFontEncoding encoding = wxFONTENCODING_DEFAULT); + wxFont(const wxSize& pixelSize, wxFontFamily family, + int style, wxFontWeight weight, + const bool underline = false, + const wxString& faceName = "", + wxFontEncoding encoding = wxFONTENCODING_DEFAULT); + //@} + + /** + Destructor. + See @ref overview_refcountdestruct "reference-counted object destruction" for + more info. + + @remarks Although all remaining fonts are deleted when the application + exits, the application should try to clean up all fonts + itself. This is because wxWidgets cannot know if a + pointer to the font object is stored in an application + data structure, and there is a risk of double deletion. + */ + ~wxFont(); + + /** + Returns the current application's default encoding. + + @see @ref overview_wxfontencodingoverview, SetDefaultEncoding() + */ + static wxFontEncoding GetDefaultEncoding(); + + /** + Returns the typeface name associated with the font, or the empty string if + there is no + typeface information. + + @see SetFaceName() + */ + wxString GetFaceName() const; + + /** + Gets the font family. See SetFamily() for a list of valid + family identifiers. + + @see SetFamily() + */ + wxFontFamily GetFamily() const; + + /** + Returns the platform-dependent string completely describing this font. + Returned string is always non-empty. + Note that the returned string is not meant to be shown or edited by the user: a + typical + use of this function is for serializing in string-form a wxFont object. + + @see SetNativeFontInfo(),GetNativeFontInfoUserDesc() + */ + wxString GetNativeFontInfoDesc() const; + + /** + Returns a user-friendly string for this font object. Returned string is always + non-empty. + Some examples of the formats of returned strings (which are platform-dependent) + are in SetNativeFontInfoUserDesc(). + + @see GetNativeFontInfoDesc() + */ + wxString GetNativeFontInfoUserDesc(); + + /** + Gets the point size. + + @see SetPointSize() + */ + int GetPointSize() const; + + /** + Gets the font style. See wxFont() for a list of valid + styles. + + @see SetStyle() + */ + int GetStyle() const; + + /** + Returns @true if the font is underlined, @false otherwise. + + @see SetUnderlined() + */ + bool GetUnderlined() const; + + /** + Gets the font weight. See wxFont() for a list of valid + weight identifiers. + + @see SetWeight() + */ + wxFontWeight GetWeight() const; + + /** + Returns @true if the font is a fixed width (or monospaced) font, + @false if it is a proportional one or font is invalid. + */ + bool IsFixedWidth() const; + + /** + Returns @true if this object is a valid font, @false otherwise. + */ + bool IsOk() const; + + //@{ + /** + These functions take the same parameters as @ref ctor() wxFont + constructor 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. + */ + static wxFont* New(int pointSize, wxFontFamily family, int style, + wxFontWeight weight, + const bool underline = false, + const wxString& faceName = "", + wxFontEncoding encoding = wxFONTENCODING_DEFAULT); + static wxFont* New(int pointSize, wxFontFamily family, + int flags = wxFONTFLAG_DEFAULT, + const wxString& faceName = "", + wxFontEncoding encoding = wxFONTENCODING_DEFAULT); + static wxFont* New(const wxSize& pixelSize, + wxFontFamily family, + int style, + wxFontWeight weight, + const bool underline = false, + const wxString& faceName = "", + wxFontEncoding encoding = wxFONTENCODING_DEFAULT); + static wxFont* New(const wxSize& pixelSize, + wxFontFamily family, + int flags = wxFONTFLAG_DEFAULT, + const wxString& faceName = "", + wxFontEncoding encoding = wxFONTENCODING_DEFAULT); + //@} + + /** + Sets the default font encoding. + + @see @ref overview_wxfontencodingoverview, GetDefaultEncoding() + */ + static void SetDefaultEncoding(wxFontEncoding encoding); + + /** + Sets the facename for the font. + Returns @true if the given face name exists; @false otherwise. + + @param faceName + A valid facename, which should be on the end-user's system. + + @remarks To avoid portability problems, don't rely on a specific face, + but specify the font family instead or as well. A + suitable font will be found on the end-user's system. + If both the family and the facename are specified, + wxWidgets will first search for the specific face, and + then for a font belonging to the same family. + + @see GetFaceName(), SetFamily() + */ + bool SetFaceName(const wxString& faceName); + + /** + Sets the font family. + + @param family + One of: + + + + + + + + wxFONTFAMILY_DEFAULT + + + + + Chooses a default font. + + + + + + wxFONTFAMILY_DECORATIVE + + + + + A decorative font. + + + + + + wxFONTFAMILY_ROMAN + + + + + A formal, serif font. + + + + + + wxFONTFAMILY_SCRIPT + + + + + A handwriting font. + + + + + + wxFONTFAMILY_SWISS + + + + + A sans-serif font. + + + + + + wxFONTFAMILY_MODERN + + + + + A fixed pitch font. + + + + + + wxFONTFAMILY_TELETYPE + + + + + A teletype font. + + @see GetFamily(), SetFaceName() + */ + void SetFamily(wxFontFamily family); + + /** + Creates the font corresponding to the given native font description string and + returns @true if + the creation was successful. + which must have been previously returned by + GetNativeFontInfoDesc(). If the string is + invalid, font is unchanged. This function is typically used for de-serializing + a wxFont + object previously saved in a string-form. + + @see SetNativeFontInfoUserDesc() + */ + bool SetNativeFontInfo(const wxString& info); + + /** + Creates the font corresponding to the given native font description string and + returns @true if + the creation was successful. + Unlike SetNativeFontInfo(), this function accepts + strings which are user-friendly. + Examples of accepted string formats are: + + Generic syntax + + Example + + on @b wxGTK2: @c [FACE-NAME] [bold] [oblique|italic] [POINTSIZE] + + Monospace bold 10 + + on @b wxMSW: @c [light|bold] [italic] [FACE-NAME] [POINTSIZE] [ENCODING] + + Tahoma 10 WINDOWS-1252 + + on @b wxMac: FIXME + + FIXME + + For more detailed information about the allowed syntaxes you can look at the + documentation of the native API used for font-rendering (e.g. pango_font_description_from_string). + + @see SetNativeFontInfo() + */ + bool SetNativeFontInfoUserDesc(const wxString& info); + + /** + Sets the point size. + + @param pointSize + Size in points. + + @see GetPointSize() + */ + void SetPointSize(int pointSize); + + /** + Sets the font style. + + @param style + One of wxFONTSTYLE_NORMAL, wxFONTSTYLE_SLANT and wxFONTSTYLE_ITALIC. + + @see GetStyle() + */ + void SetStyle(int style); + + /** + Sets underlining. + + @param underlining + @true to underline, @false otherwise. + + @see GetUnderlined() + */ + void SetUnderlined(const bool underlined); + + /** + Sets the font weight. + + @param weight + One of: + + + + + + + + wxFONTWEIGHT_NORMAL + + + + + Normal font. + + + + + + wxFONTWEIGHT_LIGHT + + + + + Light font. + + + + + + wxFONTWEIGHT_BOLD + + + + + Bold font. + + @see GetWeight() + */ + void SetWeight(wxFontWeight weight); + + /** + Inequality operator. + See @ref overview_refcountequality "reference-counted object comparison" for + more info. + */ + bool operator !=(const wxFont& font); + + /** + Assignment operator, using @ref overview_trefcount "reference counting". + */ + wxFont operator =(const wxFont& font); + + /** + Equality operator. + See @ref overview_refcountequality "reference-counted object comparison" for + more info. + */ + bool operator ==(const wxFont& font); +}; + + +/** + An empty wxFont. +*/ +wxFont wxNullFont; + +/** + FIXME +*/ +wxFont wxNORMAL_FONT; + +/** + FIXME +*/ +wxFont wxSMALL_FONT; + +/** + FIXME +*/ +wxFont wxITALIC_FONT; + +/** + FIXME +*/ +wxFont wxSWISS_FONT; + + +/** + @class wxFontList + @wxheader{gdicmn.h} + + A font list is a list containing all fonts which have been created. There + is only one instance of this class: @b wxTheFontList. Use this object to search + for a previously created font of the desired type and create it if not already + found. + In some windowing systems, the font may be a scarce resource, so it is best to + reuse old resources if possible. When an application finishes, all fonts will + be + deleted and their resources freed, eliminating the possibility of 'memory + leaks'. + + @library{wxcore} + @category{gdi} + + @see wxFont +*/ +class wxFontList : public wxList +{ +public: + /** + Constructor. The application should not construct its own font list: + use the object pointer @b wxTheFontList. + */ + wxFontList(); + + /** + Finds a font of the given specification, or creates one and adds it to the + list. See the @ref wxFont::ctor "wxFont constructor" for + details of the arguments. + */ + wxFont* FindOrCreateFont(int point_size, int family, int style, + int weight, + bool underline = false, + const wxString& facename = NULL, + wxFontEncoding encoding = wxFONTENCODING_DEFAULT); +}; + + + +// ============================================================================ +// Global functions/macros +// ============================================================================ + +/** @ingroup group_funcmacro_misc */ +//@{ + +/** + Converts string to a wxFont best represented by the given string. Returns + @true on success. + + @see wxToString(const wxFont&) + + @header{wx/font.h} +*/ +bool wxFromString(const wxString& string, wxFont* font); + +/** + Converts the given wxFont into a string. + + @see wxFromString(const wxString&, wxFont*) + + @header{wx/font.h} +*/ +wxString wxToString(const wxFont& font); + +//@} + diff --git a/interface/wx/fontdlg.h b/interface/wx/fontdlg.h new file mode 100644 index 0000000000..4a5ea24021 --- /dev/null +++ b/interface/wx/fontdlg.h @@ -0,0 +1,93 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: fontdlg.h +// Purpose: interface of wxFontDialog +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxFontDialog + @wxheader{fontdlg.h} + + This class represents the font chooser dialog. + + @library{wxcore} + @category{cmndlg} + + @see Overview(), wxFontData, wxGetFontFromUser() +*/ +class wxFontDialog : public wxDialog +{ +public: + //@{ + /** + Constructor. Pass a parent window, and optionally the + @ref overview_wxfontdata "font data" object to be used to initialize the dialog + controls. If the default constructor is used, + Create() must be called before the dialog can be + shown. + */ + wxFontDialog(); + wxFontDialog(wxWindow* parent); + wxFontDialog(wxWindow* parent, const wxFontData& data); + //@} + + //@{ + /** + Creates the dialog if it the wxFontDialog object had been initialized using the + default constructor. Returns @true on success and @false if an error + occurred. + */ + bool Create(wxWindow* parent); + bool Create(wxWindow* parent, const wxFontData& data); + //@} + + //@{ + /** + Returns the @ref overview_wxfontdata "font data" associated with the font + dialog. + */ + const wxFontData GetFontData(); + const wxFontData& GetFontData(); + //@} + + /** + Shows the dialog, returning @c wxID_OK if the user pressed Ok, and + @c wxID_CANCEL otherwise. + If the user cancels the dialog (ShowModal returns @c wxID_CANCEL), no font + will be created. If the user presses OK, a new wxFont will be created and + stored in the font dialog's wxFontData structure. + */ + int ShowModal(); +}; + + + +// ============================================================================ +// Global functions/macros +// ============================================================================ + +/** @ingroup group_funcmacro_dialog */ +//@{ + +/** + Shows the font selection dialog and returns the font selected by user or + invalid font (use wxFont::IsOk() to test whether a font is valid) if the + dialog was cancelled. + + @param parent + The parent window for the font selection dialog. + @param fontInit + If given, this will be the font initially selected in the dialog. + @param caption + If given, this will be used for the dialog caption. + + @header{wx/fontdlg.h} +*/ +wxFont wxGetFontFromUser(wxWindow* parent, + const wxFont& fontInit, + const wxString& caption = wxEmptyString); + +//@} + diff --git a/interface/wx/fontenum.h b/interface/wx/fontenum.h new file mode 100644 index 0000000000..8cf2da6104 --- /dev/null +++ b/interface/wx/fontenum.h @@ -0,0 +1,85 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: fontenum.h +// Purpose: interface of wxFontEnumerator +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxFontEnumerator + @wxheader{fontenum.h} + + wxFontEnumerator enumerates either all available fonts on the system or only + the ones with given attributes - either only fixed-width (suited for use in + programs such as terminal emulators and the like) or the fonts available in + the given encoding(). + + To do this, you just have to call one of EnumerateXXX() functions - either + wxFontEnumerator::EnumerateFacenames or + wxFontEnumerator::EnumerateEncodings and the + corresponding callback (wxFontEnumerator::OnFacename or + wxFontEnumerator::OnFontEncoding) will be called + repeatedly until either all fonts satisfying the specified criteria are + exhausted or the callback returns @false. + + @library{wxcore} + @category{FIXME} + + @see @ref overview_wxfontencodingoverview, @ref overview_samplefont "Font + sample", wxFont, wxFontMapper +*/ +class wxFontEnumerator +{ +public: + /** + Call OnFontEncoding() for each + encoding supported by the given font - or for each encoding supported by at + least some font if @a font is not specified. + */ + virtual bool EnumerateEncodings(const wxString& font = ""); + + /** + Call OnFacename() for each font which + supports given encoding (only if it is not wxFONTENCODING_SYSTEM) and is of + fixed width (if @a fixedWidthOnly is @true). + Calling this function with default arguments will result in enumerating all + fonts available on the system. + */ + virtual bool EnumerateFacenames(wxFontEncoding encoding = wxFONTENCODING_SYSTEM, + bool fixedWidthOnly = false); + + /** + Return array of strings containing all encodings found by + EnumerateEncodings(). + */ + static wxArrayString GetEncodings(const wxString& facename = ""); + + /** + Return array of strings containing all facenames found by + EnumerateFacenames(). + */ + static wxArrayString GetFacenames(wxFontEncoding encoding = wxFONTENCODING_SYSTEM, + bool fixedWidthOnly = false); + + /** + Returns @true if the given string is valid face name, i.e. it's the face name + of an installed + font and it can safely be used with wxFont::SetFaceName. + */ + static bool IsValidFacename(const wxString& facename); + + /** + Called by EnumerateFacenames() for + each match. Return @true to continue enumeration or @false to stop it. + */ + virtual bool OnFacename(const wxString& font); + + /** + Called by EnumerateEncodings() for + each match. Return @true to continue enumeration or @false to stop it. + */ + virtual bool OnFontEncoding(const wxString& font, + const wxString& encoding); +}; + diff --git a/interface/wx/fontmap.h b/interface/wx/fontmap.h new file mode 100644 index 0000000000..8adbc85135 --- /dev/null +++ b/interface/wx/fontmap.h @@ -0,0 +1,176 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: fontmap.h +// Purpose: interface of wxFontMapper +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxFontMapper + @wxheader{fontmap.h} + + wxFontMapper manages user-definable correspondence between logical font + names and the fonts present on the machine. + + The default implementations of all functions will ask the user if they are + not capable of finding the answer themselves and store the answer in a + config file (configurable via SetConfigXXX functions). This behaviour may + be disabled by giving the value of @false to "interactive" parameter. + + However, the functions will always consult the config file to allow the + user-defined values override the default logic and there is no way to + disable this - which shouldn't be ever needed because if "interactive" was + never @true, the config file is never created anyhow. + + 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. + + @library{wxcore} + @category{misc} + + @see wxEncodingConverter, @ref overview_nonenglishoverview "Writing non-English + applications" +*/ +class wxFontMapper +{ +public: + /** + Default ctor. + */ + wxFontMapper(); + + /** + Virtual dtor for a base class. + */ + ~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 + time than a simple function call. For these reasons, it is almost always a bad + idea to call this function from the event handlers for repeatedly generated + events such as @c EVT_PAINT. + */ + wxFontEncoding CharsetToEncoding(const wxString& charset, + bool interactive = true); + + /** + 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 + GetEncodingName(). + */ + static const wxChar** GetAllEncodingNames(wxFontEncoding encoding); + + //@{ + /** + Find an alternative for the given encoding (which is supposed to not be + 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. + */ + bool GetAltForEncoding(wxFontEncoding encoding, + wxNativeEncodingInfo* info, + const wxString& facename = wxEmptyString, + bool interactive = true); + bool GetAltForEncoding(wxFontEncoding encoding, + wxFontEncoding* alt_encoding, + const wxString& facename = wxEmptyString, + bool interactive = true); + //@} + + /** + 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); + + /** + Return user-readable string describing the given encoding. + */ + 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(). + */ + static wxFontEncoding GetEncodingFromName(const wxString& encoding); + + /** + Return internal string identifier for the encoding (see also + 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 + all supported encodings. + */ + static size_t GetSupportedEncodingsCount(); + + /** + Check whether given encoding is available in given face or not. + If no facename is given, find @e any font in this encoding. + */ + bool IsEncodingAvailable(wxFontEncoding encoding, + const wxString& facename = wxEmptyString); + + /** + Set the current font mapper object and return previous one (may be @NULL). + This method is only useful if you want to plug-in an alternative font mapper + into wxWidgets. + + @see Get() + */ + static wxFontMapper* Set(wxFontMapper* mapper); + + /** + 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(). + */ + void SetConfig(wxConfigBase* config); + + /** + Set the root config path to use (should be an absolute path). + */ + void SetConfigPath(const wxString& prefix); + + /** + The parent window for modal dialogs. + */ + void SetDialogParent(wxWindow* parent); + + /** + The title for the dialogs (note that default is quite reasonable). + */ + void SetDialogTitle(const wxString& title); +}; + diff --git a/interface/wx/fontpicker.h b/interface/wx/fontpicker.h new file mode 100644 index 0000000000..15c540785a --- /dev/null +++ b/interface/wx/fontpicker.h @@ -0,0 +1,153 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: fontpicker.h +// Purpose: interface of wxFontPickerCtrl +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxFontPickerCtrl + @wxheader{fontpicker.h} + + 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. + 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. + @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 + the user to specify a font (see SetSelectedFont). The text control + is automatically synchronized with button's value. Use functions + defined in wxPickerBase to modify the text control. + @style{wxFNTP_FONTDESC_AS_LABEL} + Keeps the label of the button updated with the fontface name and + the font size. E.g. choosing "Times New Roman bold, italic with + size 10" from the fontdialog, will update the label (overwriting + any previous label) with the "Times New Roman, 10" text. + @style{wxFNTP_USEFONT_FOR_LABEL} + Uses the currently selected font to draw the label of the button. + @endStyleTable + + @library{wxcore} + @category{pickers} + + + @see wxFontDialog, wxFontPickerEvent +*/ +class wxFontPickerCtrl : public wxPickerBase +{ +public: + /** + Initializes the object and calls Create() with + all the parameters. + */ + wxFontPickerCtrl(wxWindow* parent, wxWindowID id, + const wxFont& font = wxNullFont, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxFNTP_DEFAULT_STYLE, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "fontpickerctrl"); + + /** + @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. + @param pos + Initial position. + @param size + Initial size. + @param style + The window style, see wxFNTP_* flags. + @param validator + Validator which can be used for additional date checks. + @param name + Control name. + + @return @true if the control was successfully created or @false if + creation failed. + */ + bool Create(wxWindow* parent, wxWindowID id, + const wxFont& font = wxNullFont, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxFNTP_DEFAULT_STYLE, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "fontpickerctrl"); + + /** + Returns the maximum point size value allowed for the user-chosen font. + */ + unsigned int GetMaxPointSize() const; + + /** + Returns the currently selected font. + Note that this function is completely different from wxWindow::GetFont. + */ + wxFont GetSelectedFont() const; + + /** + 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. + */ + void GetMaxPointSize(unsigned int max); + + /** + Sets the currently selected font. + Note that this function is completely different from wxWindow::SetFont. + */ + void SetSelectedFont(const wxFont& font); +}; + + + +/** + @class wxFontPickerEvent + @wxheader{fontpicker.h} + + This event class is used for the events generated by + wxFontPickerCtrl. + + @library{wxcore} + @category{FIXME} + + @see wxFontPickerCtrl +*/ +class wxFontPickerEvent : public wxCommandEvent +{ +public: + /** + The constructor is not normally used by the user code. + */ + wxFontPickerEvent(wxObject* generator, int id, + const wxFont& font); + + /** + Retrieve the font the user has just selected. + */ + wxFont GetFont() const; + + /** + Set the font associated with the event. + */ + void SetFont(const wxFont& f); +}; + diff --git a/interface/wx/frame.h b/interface/wx/frame.h new file mode 100644 index 0000000000..51af4a1666 --- /dev/null +++ b/interface/wx/frame.h @@ -0,0 +1,410 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: frame.h +// Purpose: interface of wxFrame +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxFrame + @wxheader{frame.h} + + A frame is a window whose size and position can (usually) be changed by the user. + + It usually has thick borders and a title bar, and can optionally contain a + menu bar, toolbar and status bar. A frame can contain any window that is not + a frame or dialog. + + A frame that has a status bar and toolbar, created via the CreateStatusBar() and + CreateToolBar() functions, manages these windows and adjusts the value returned + by GetClientSize() to reflect the remaining size available to application windows. + + @remarks An application should normally define an wxCloseEvent handler for the + frame to respond to system close events, for example so that related + data and subwindows can be cleaned up. + + + @section wxframe_defaultevent Default event processing + + wxFrame processes the following events: + + @li @c wxEVT_SIZE: if the frame has exactly one child window, not counting the + status and toolbar, this child is resized to take the entire frame client area. + If two or more windows are present, they should be laid out explicitly either + by manually handling wxEVT_SIZE or using sizers; + @li @c wxEVT_MENU_HIGHLIGHT: the default implementation displays the help string + associated with the selected item in the first pane of the status bar, if there is one. + + + @beginStyleTable + @style{wxDEFAULT_FRAME_STYLE} + Defined as wxMINIMIZE_BOX | wxMAXIMIZE_BOX | wxRESIZE_BORDER | + wxSYSTEM_MENU | wxCAPTION | wxCLOSE_BOX | wxCLIP_CHILDREN. + @style{wxICONIZE} + Display the frame iconized (minimized). Windows only. + @style{wxCAPTION} + Puts a caption on the frame. + @style{wxMINIMIZE} + Identical to wxICONIZE. Windows only. + @style{wxMINIMIZE_BOX} + Displays a minimize box on the frame. + @style{wxMAXIMIZE} + Displays the frame maximized. Windows only. + @style{wxMAXIMIZE_BOX} + Displays a maximize box on the frame. + @style{wxCLOSE_BOX} + Displays a close box on the frame. + @style{wxSTAY_ON_TOP} + Stay on top of all other windows, see also wxFRAME_FLOAT_ON_PARENT. + @style{wxSYSTEM_MENU} + Displays a system menu. + @style{wxRESIZE_BORDER} + Displays a resizeable border around the window. + @style{wxFRAME_TOOL_WINDOW} + Causes a frame with a small titlebar to be created; the frame does + not appear in the taskbar under Windows or GTK+. + @style{wxFRAME_NO_TASKBAR} + Creates an otherwise normal frame but it does not appear in the + taskbar under Windows or GTK+ (note that it will minimize to the + desktop window under Windows which may seem strange to the users + and thus it might be better to use this style only without + wxMINIMIZE_BOX style). In wxGTK, the flag is respected only if GTK+ + is at least version 2.2 and the window manager supports + _NET_WM_STATE_SKIP_TASKBAR hint. Has no effect under other platforms. + @style{wxFRAME_FLOAT_ON_PARENT} + The frame will always be on top of its parent (unlike wxSTAY_ON_TOP). + A frame created with this style must have a non-@NULL parent. + @style{wxFRAME_SHAPED} + Windows with this style are allowed to have their shape changed + with the SetShape() method. + @endStyleTable + + The default frame style is for normal, resizeable frames. + To create a frame which can not be resized by user, you may use the following + combination of styles: + + @code + wxDEFAULT_FRAME_STYLE & ~(wxRESIZE_BORDER | wxRESIZE_BOX | wxMAXIMIZE_BOX) + @endcode + + See also the @ref overview_windowstyles. + + @beginExtraStyleTable + @style{wxFRAME_EX_CONTEXTHELP} + Under Windows, puts a query button on the caption. When pressed, + Windows will go into a context-sensitive help mode and wxWidgets + will send a wxEVT_HELP event if the user clicked on an application + window. Note that this is an extended style and must be set by + calling SetExtraStyle before Create is called (two-step + construction). You cannot use this style together with + wxMAXIMIZE_BOX or wxMINIMIZE_BOX, so you should use + wxDEFAULT_FRAME_STYLE ~ (wxMINIMIZE_BOX | wxMAXIMIZE_BOX) for the + frames having this style (the dialogs don't have a minimize or a + maximize box by default) + @style{wxFRAME_EX_METAL} + On Mac OS X, frames with this style will be shown with a metallic + look. This is an extra style. + @endExtraStyleTable + + @library{wxcore} + @category{managedwnd} + + @see wxMDIParentFrame, wxMDIChildFrame, wxMiniFrame, wxDialog +*/ +class wxFrame : public wxTopLevelWindow +{ +public: + //@{ + /** + Constructor, creating the window. + + @param parent + 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. + @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. + @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. + @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 + individual windows. + + @remarks For Motif, MWM (the Motif Window Manager) should be running for + 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. + */ + ~wxFrame(); + + /** + Centres the frame on the display. + + @param direction + The parameter may be wxHORIZONTAL, wxVERTICAL or wxBOTH. + */ + void Centre(int direction = wxBOTH); + + /** + Used in two-step frame construction. See wxFrame() + for further details. + */ + bool Create(wxWindow* parent, wxWindowID id, + const wxString& title, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxDEFAULT_FRAME_STYLE, + const wxString& name = "frame"); + + /** + Creates a status bar at the bottom of the frame. + + @param number + 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. + @param id + 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. + + @remarks The width of the status bar is the whole width of the frame + (adjusted automatically when resizing), and the height + and text size are chosen by the host windowing system. + + @see SetStatusText(), OnCreateStatusBar(), GetStatusBar() + */ + virtual wxStatusBar* CreateStatusBar(int number = 1, + long style = 0, + wxWindowID id = -1, + const wxString& name = "statusBar"); + + /** + Creates a toolbar at the top or left of the frame. + + @param style + 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. + @param name + The toolbar window name. + + @return A pointer to the toolbar if it was created successfully, @NULL + 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(). + + @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. + */ + wxPoint GetClientAreaOrigin() const; + + /** + Returns a pointer to the menubar currently associated with the frame (if any). + + @see SetMenuBar(), wxMenuBar, wxMenu + */ + wxMenuBar* GetMenuBar() const; + + /** + Returns a pointer to the status bar currently associated with the frame (if + any). + + @see CreateStatusBar(), wxStatusBar + */ + wxStatusBar* GetStatusBar() const; + + /** + Returns the status bar pane used to display menu and toolbar help. + + @see SetStatusBarPane() + */ + int GetStatusBarPane(); + + /** + Returns a pointer to the toolbar currently associated with the frame (if any). + + @see CreateToolBar(), wxToolBar, SetToolBar() + */ + wxToolBar* GetToolBar() const; + + /** + Virtual function called when a status bar is requested by CreateStatusBar(). + + @param number + The number of fields to create. + @param style + The window style. See wxStatusBar for a list + of valid styles. + @param id + The window identifier. If -1, an identifier will be chosen by + wxWidgets. + @param name + The window name. + + @return A status bar object. + + @remarks An application can override this function to return a different + kind of status bar. The default implementation returns + an instance of wxStatusBar. + + @see CreateStatusBar(), wxStatusBar. + */ + virtual wxStatusBar* OnCreateStatusBar(int number, long style, + wxWindowID id, + const wxString& name); + + /** + Virtual function called when a toolbar is requested by CreateToolBar(). + + @param style + 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. + @param name + The toolbar window name. + + @return A toolbar object. + + @remarks An application can override this function to return a different + kind of toolbar. The default implementation returns an + instance of wxToolBar. + + @see CreateToolBar(), wxToolBar. + */ + virtual wxToolBar* OnCreateToolBar(long style, wxWindowID id, + const wxString& name); + + /** + Simulate a menu command. + + @param id + The identifier for a menu item. + */ + void ProcessCommand(int id); + + /** + This function sends a dummy @ref overview_wxsizeevent "size event" to the frame + forcing it to reevaluate its children positions. It is sometimes useful to call + this function after adding or deleting a children after the frame creation or + if a child size changes. + Note that if the frame is using either sizers or constraints for the children + layout, it is enough to call wxWindow::Layout directly and + this function should not be used in this case. + */ + void SendSizeEvent(); + + /** + Tells the frame to show the given menu bar. + + @param menuBar + The menu bar to associate with the frame. + + @remarks If the frame is destroyed, the menu bar and its menus will be + destroyed also, so do not delete the menu bar + explicitly (except by resetting the frame's menu bar to + another frame or @NULL). + + @see GetMenuBar(), wxMenuBar, wxMenu. + */ + void SetMenuBar(wxMenuBar* menuBar); + + /** + Associates a status bar with the frame. + + @see CreateStatusBar(), wxStatusBar, GetStatusBar() + */ + void SetStatusBar(wxStatusBar* statusBar); + + /** + Set the status bar pane used to display menu and toolbar help. + Using -1 disables help display. + */ + void SetStatusBarPane(int n); + + /** + Sets the status bar text and redraws the status bar. + + @param text + The text for the status field. + @param number + The status field (starting from zero). + + @remarks Use an empty string to clear the status bar. + + @see CreateStatusBar(), wxStatusBar + */ + virtual void SetStatusText(const wxString& text, int number = 0); + + /** + Sets the widths of the fields in the status bar. + + @param n + The number of fields in the status bar. It must be the + same used in CreateStatusBar. + @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. + + @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. + */ + virtual void SetStatusWidths(int n, int* widths); + + /** + Associates a toolbar with the frame. + */ + void SetToolBar(wxToolBar* toolBar); +}; + diff --git a/interface/wx/fs_mem.h b/interface/wx/fs_mem.h new file mode 100644 index 0000000000..bef7f52f8d --- /dev/null +++ b/interface/wx/fs_mem.h @@ -0,0 +1,116 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: fs_mem.h +// Purpose: interface of wxMemoryFSHandler +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxMemoryFSHandler + @wxheader{fs_mem.h} + + This wxFileSystem handler can store arbitrary data in memory stream and make + them accessible via an URL. + + It is particularly suitable for storing bitmaps from resources or included XPM + files so that they can be used with wxHTML. + + Filenames are prefixed with @c "memory:", e.g. @c "memory:myfile.html". + + Example: + + @code + #ifndef __WXMSW__ + #include "logo.xpm" + #endif + + void MyFrame::OnAbout(wxCommandEvent&) + { + wxBusyCursor bcur; + wxFileSystem::AddHandler(new wxMemoryFSHandler); + wxMemoryFSHandler::AddFile("logo.pcx", wxBITMAP(logo), wxBITMAP_TYPE_PCX); + wxMemoryFSHandler::AddFile("about.htm", + "About: " + ""); + + wxDialog dlg(this, -1, wxString(_("About"))); + wxBoxSizer *topsizer; + wxHtmlWindow *html; + topsizer = new wxBoxSizer(wxVERTICAL); + html = new wxHtmlWindow(&dlg, -1, wxDefaultPosition, + wxSize(380, 160), wxHW_SCROLLBAR_NEVER); + html->SetBorders(0); + html->LoadPage("memory:about.htm"); + html->SetSize(html->GetInternalRepresentation()->GetWidth(), + html->GetInternalRepresentation()->GetHeight()); + topsizer->Add(html, 1, wxALL, 10); + topsizer->Add(new wxStaticLine(&dlg, -1), 0, wxEXPAND | wxLEFT | wxRIGHT, 10); + topsizer->Add(new wxButton(&dlg, wxID_OK, "Ok"), + 0, wxALL | wxALIGN_RIGHT, 15); + dlg.SetAutoLayout(true); + dlg.SetSizer(topsizer); + topsizer->Fit(&dlg); + dlg.Centre(); + dlg.ShowModal(); + + wxMemoryFSHandler::RemoveFile("logo.pcx"); + wxMemoryFSHandler::RemoveFile("about.htm"); + } + @endcode + + @library{wxbase} + @category{vfs} + + @see wxMemoryFSHandler::AddFileWithMimeType +*/ +class wxMemoryFSHandler : public wxFileSystemHandler +{ +public: + /** + Constructor. + */ + wxMemoryFSHandler(); + + //@{ + /** + Adds a file to the list of the files stored in memory. + + Stored data (bitmap, text or raw data) will be copied into private memory + stream and available under name @c "memory:" + @e filename. + + @note you must use a @a type value (aka image format) that wxWidgets + can save (e.g. JPG, PNG, see wxImage documentation)! + + @see AddFileWithMimeType() + */ + static void AddFile(const wxString& filename, wxImage& image, wxBitmapType type); + static void AddFile(const wxString& filename, const wxBitmap& bitmap, wxBitmapType type); + //@} + + //@{ + /** + Like AddFile(), but lets you explicitly specify added file's MIME type. + + This version should be used whenever you know the MIME type, because it + makes accessing the files faster. + + @since 2.8.5 + + @see AddFile() + */ + static void AddFileWithMimeType(const wxString& filename, + const wxString& textdata, + const wxString& mimetype); + static void AddFileWithMimeType(const wxString& filename, + const void* binarydata, + size_t size, + const wxString& mimetype); + //@} + + /** + Removes a file from memory FS and frees the occupied memory. + */ + static void RemoveFile(const wxString& filename); +}; + diff --git a/interface/wx/gauge.h b/interface/wx/gauge.h new file mode 100644 index 0000000000..d617d7489b --- /dev/null +++ b/interface/wx/gauge.h @@ -0,0 +1,184 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: gauge.h +// Purpose: interface of wxGauge +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxGauge + @wxheader{gauge.h} + + A gauge is a horizontal or vertical bar which shows a quantity (often + time). + + wxGauge supports two working modes: determinate and indeterminate progress. + + The first is the usual working mode (see SetValue() and SetRange()) while + the second can be used when the program is doing some processing but you + don't know how much progress is being done. In this case, you can + periodically call the Pulse() function to make the progress bar switch to + indeterminate mode (graphically it's usually a set of blocks which move or + bounce in the bar control). + + wxGauge supports dynamic switch between these two work modes. + + There are no user commands for the gauge. + + @beginStyleTable + @style{wxGA_HORIZONTAL} + Creates a horizontal gauge. + @style{wxGA_VERTICAL} + Creates a vertical gauge. + @style{wxGA_SMOOTH} + Creates smooth progress bar with one pixel wide update step (not + supported by all platforms). + @endStyleTable + + @library{wxcore} + @category{ctrl} + + + @see wxSlider, wxScrollBar +*/ +class wxGauge : public wxControl +{ +public: + /** + Default constructor. + */ + wxGauge(); + /** + Constructor, creating and showing a gauge. + + @param parent + Window parent. + @param id + Window identifier. + @param range + Integer range (maximum value) of the gauge. It is ignored when the + gauge is used in indeterminate mode. + @param pos + Window position. + @param size + Window size. + @param style + Gauge style. + @param name + Window name. + + @see Create() + */ + wxGauge(wxWindow* parent, wxWindowID id, int range, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxGA_HORIZONTAL, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "gauge"); + + /** + Destructor, destroying the gauge. + */ + ~wxGauge(); + + /** + Creates the gauge for two-step construction. See wxGauge() for further + details. + */ + bool Create(wxWindow* parent, wxWindowID id, int range, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxGA_HORIZONTAL, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "gauge"); + + /** + Returns the width of the 3D bezel face. + + @remarks This method is not implemented (returns 0) for most platforms. + + @see SetBezelFace() + */ + int GetBezelFace() const; + + /** + Returns the maximum position of the gauge. + + @see SetRange() + */ + int GetRange() const; + + /** + Returns the 3D shadow margin width. + + @remarks This method is not implemented (returns 0) for most platforms. + + @see SetShadowWidth() + */ + int GetShadowWidth() const; + + /** + Returns the current position of the gauge. + + @see SetValue() + */ + int GetValue() const; + + /** + Returns @true if the gauge is vertical (has @c wxGA_VERTICAL style) and + @false otherwise. + */ + bool IsVertical() const; + + /** + Switch the gauge to indeterminate mode (if required) and makes the + gauge move a bit to indicate the user that some progress has been made. + + @note After calling this function the value returned by GetValue() is + undefined and thus you need to explicitely call SetValue() if you + want to restore the determinate mode. + */ + void Pulse(); + + /** + Sets the 3D bezel face width. + + @remarks This method is not implemented (doesn't do anything) for most + platforms. + + @see GetBezelFace() + */ + void SetBezelFace(int width); + + /** + Sets the range (maximum value) of the gauge. This function makes the + gauge switch to determinate mode, if it's not already. + + @see GetRange() + */ + void SetRange(int range); + + /** + Sets the 3D shadow width. + + @remarks This method is not implemented (doesn't do anything) for most + platforms. + */ + void SetShadowWidth(int width); + + /** + Sets the position of the gauge. The @a pos must be between 0 and the + gauge range as returned by GetRange(), inclusive. + + This function makes the gauge switch to determinate mode, if it was in + indeterminate mode before. + + @param pos + Position for the gauge level. + + @see GetValue() + */ + void SetValue(int pos); +}; + diff --git a/interface/wx/gbsizer.h b/interface/wx/gbsizer.h new file mode 100644 index 0000000000..30ffb83eab --- /dev/null +++ b/interface/wx/gbsizer.h @@ -0,0 +1,354 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: gbsizer.h +// Purpose: interface of wxGBPosition +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxGBPosition + @wxheader{gbsizer.h} + + This class represents the position of an item in a virtual grid of rows and + columns managed by a wxGridBagSizer. + + @library{wxcore} + @category{winlayout} +*/ +class wxGBPosition +{ +public: + /** + Default constructor, setting the row and column to (0,0). + */ + wxGBPosition(); + /** + Construct a new wxGBPosition, setting the row and column. + */ + wxGBPosition(int row, int col); + + /** + Get the current column value. + */ + int GetCol() const; + + /** + Get the current row value. + */ + int GetRow() const; + + /** + Set a new column value. + */ + void SetCol(int col); + + /** + Set a new row value. + */ + void SetRow(int row); + + /** + Checks if the position is valid. An invalid position is (-1,-1). + */ + bool operator!(const wxGBPosition& p) const; + + /** + Compare equality of two wxGBPositions. + */ + bool operator==(const wxGBPosition& p) const; +}; + + + +/** + @class wxGridBagSizer + @wxheader{gbsizer.h} + + A wxSizer that can lay out items in a virtual grid like a wxFlexGridSizer + but in this case explicit positioning of the items is allowed using + wxGBPosition, and items can optionally span more than one row and/or column + using wxGBSpan. + + @library{wxcore} + @category{winlayout} +*/ +class wxGridBagSizer : public wxFlexGridSizer +{ +public: + /** + Constructor, with optional parameters to specify the gap between the + rows and columns. + */ + wxGridBagSizer(int vgap = 0, int hgap = 0); + + //@{ + /** + Adds the given item to the given position. + + @return A valid pointer if the item was successfully placed at the + given position, or @NULL if something was already there. + */ + wxSizerItem* Add(wxWindow* window, const wxGBPosition& pos, + const wxGBSpan& span = wxDefaultSpan, + int flag = 0, int border = 0, wxObject* userData = NULL); + wxSizerItem* Add(wxSizer* sizer, const wxGBPosition& pos, + const wxGBSpan& span = wxDefaultSpan, + int flag = 0, int border = 0, wxObject* userData = NULL); + wxSizerItem* Add(int width, int height, const wxGBPosition& pos, + const wxGBSpan& span = wxDefaultSpan, + int flag = 0, int border = 0, wxObject* userData = NULL); + wxSizerItem* Add(wxGBSizerItem* item); + //@} + + /** + Called when the managed size of the sizer is needed or when layout + needs done. + */ + wxSize CalcMin(); + + //@{ + /** + Look at all items and see if any intersect (or would overlap) the given + item. Returns @true if so, @false if there would be no overlap. If an + @a excludeItem is given then it will not be checked for intersection, + for example it may be the item we are checking the position of. + */ + bool CheckForIntersection(wxGBSizerItem* item, + wxGBSizerItem* excludeItem = NULL); + bool CheckForIntersection(const wxGBPosition& pos, const wxGBSpan& span, + wxGBSizerItem* excludeItem = NULL); + //@} + + //@{ + /** + Find the sizer item for the given window or subsizer, returns @NULL if + not found. (non-recursive) + */ + wxGBSizerItem* FindItem(wxWindow* window); + wxGBSizerItem* FindItem(wxSizer* sizer); + //@} + + /** + Return the sizer item located at the point given in pt, or @NULL if + there is no item at that point. The (x,y) coordinates in @a pt + correspond to the client coordinates of the window using the sizer for + layout. (non-recursive) + */ + wxGBSizerItem* FindItemAtPoint(const wxPoint& pt); + + /** + Return the sizer item for the given grid cell, or @NULL if there is no + item at that position. (non-recursive) + */ + wxGBSizerItem* FindItemAtPosition(const wxGBPosition& pos); + + /** + Return the sizer item that has a matching user data (it only compares + pointer values) or @NULL if not found. (non-recursive) + */ + wxGBSizerItem* FindItemWithData(const wxObject* userData); + + /** + Get the size of the specified cell, including hgap and vgap. Only valid + after window layout has been performed. + */ + wxSize GetCellSize(int row, int col) const; + + /** + Get the size used for cells in the grid with no item. + */ + wxSize GetEmptyCellSize() const; + + //@{ + /** + Get the grid position of the specified item. + */ + wxGBPosition GetItemPosition(wxWindow* window); + wxGBPosition GetItemPosition(wxSizer* sizer); + wxGBPosition GetItemPosition(size_t index); + //@} + + //@{ + /** + Get the row/col spanning of the specified item. + */ + wxGBSpan GetItemSpan(wxWindow* window); + wxGBSpan GetItemSpan(wxSizer* sizer); + wxGBSpan GetItemSpan(size_t index); + //@} + + /** + Called when the managed size of the sizer is needed or when layout + needs done. + */ + void RecalcSizes(); + + /** + Set the size used for cells in the grid with no item. + */ + void SetEmptyCellSize(const wxSize& sz); + + //@{ + /** + Set the grid position of the specified item. Returns @true on success. + If the move is not allowed (because an item is already there) then + @false is returned. + */ + bool SetItemPosition(wxWindow* window, const wxGBPosition& pos); + bool SetItemPosition(wxSizer* sizer, const wxGBPosition& pos); + bool SetItemPosition(size_t index, const wxGBPosition& pos); + //@} + + //@{ + /** + Set the row/col spanning of the specified item. Returns @true on + success. If the move is not allowed (because an item is already there) + then @false is returned. + */ + bool SetItemSpan(wxWindow* window, const wxGBSpan& span); + bool SetItemSpan(wxSizer* sizer, const wxGBSpan& span); + bool SetItemSpan(size_t index, const wxGBSpan& span); + //@} +}; + + + +/** + @class wxGBSizerItem + @wxheader{gbsizer.h} + + The wxGBSizerItem class is used by the wxGridBagSizer for tracking the + items in the sizer. It adds grid position and spanning information to the + normal wxSizerItem by adding wxGBPosition and wxGBSpan attrbibutes. Most of + the time you will not need to use a wxGBSizerItem directly in your code, + but there are a couple of cases where it is handy. + + @library{wxcore} + @category{winlayout} +*/ +class wxGBSizerItem : public wxSizerItem +{ +public: + /** + Construct a sizer item for tracking a spacer. + */ + wxGBSizerItem(int width, int height, const wxGBPosition& pos, + const wxGBSpan& span, int flag, int border, + wxObject* userData); + /** + Construct a sizer item for tracking a window. + */ + wxGBSizerItem(wxWindow* window, const wxGBPosition& pos, + const wxGBSpan& span, int flag, int border, + wxObject* userData); + /** + Construct a sizer item for tracking a subsizer. + */ + wxGBSizerItem(wxSizer* sizer, const wxGBPosition& pos, + const wxGBSpan& span, int flag, int border, + wxObject* userData); + + /** + Get the row and column of the endpoint of this item. + */ + void GetEndPos(int& row, int& col); + + //@{ + /** + Get the grid position of the item. + */ + wxGBPosition GetPos() const; + void GetPos(int& row, int& col) const; + //@} + + //@{ + /** + Get the row and column spanning of the item. + */ + wxGBSpan GetSpan() const; + void GetSpan(int& rowspan, int& colspan) const; + //@} + + /** + Returns @true if this item and the @a other item instersect. + */ + bool Intersects(const wxGBSizerItem& other); + /** + Returns @true if the given pos/span would intersect with this item. + */ + bool Intersects(const wxGBPosition& pos, const wxGBSpan& span); + + /** + If the item is already a member of a sizer then first ensure that there + is no other item that would intersect with this one at the new + position, then set the new position. Returns @true if the change is + successful and after the next Layout the item will be moved. + */ + bool SetPos(const wxGBPosition& pos); + + /** + If the item is already a member of a sizer then first ensure that there + is no other item that would intersect with this one with its new + spanning size, then set the new spanning. Returns @true if the change + is successful and after the next Layout the item will be resized. + */ + bool SetSpan(const wxGBSpan& span); +}; + + + +/** + @class wxGBSpan + @wxheader{gbsizer.h} + + This class is used to hold the row and column spanning attributes of items + in a wxGridBagSizer. + + @library{wxcore} + @category{winlayout} +*/ +class wxGBSpan +{ +public: + /** + Default constructor, setting the rowspan and colspan to (1,1) meaning + that the item occupies one cell in each direction. + */ + wxGBSpan(); + /** + Construct a new wxGBSpan, setting the @a rowspan and @a colspan. + */ + wxGBSpan(int rowspan, int colspan); + + /** + Get the current colspan value. + */ + int GetColspan() const; + + /** + Get the current rowspan value. + */ + int GetRowspan() const; + + /** + Set a new colspan value. + */ + void SetColspan(int colspan); + + /** + Set a new rowspan value. + */ + void SetRowspan(int rowspan); + + /** + Checks if the span is valid. An invalid span is (-1,-1). + */ + bool operator!(const wxGBSpan& o) const; + + /** + Compare equality of two wxGBSpans. + */ + bool operator==(const wxGBSpan& o) const; +}; + diff --git a/interface/wx/gdicmn.h b/interface/wx/gdicmn.h new file mode 100644 index 0000000000..f415ecf9d8 --- /dev/null +++ b/interface/wx/gdicmn.h @@ -0,0 +1,881 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: gdicmn.h +// Purpose: interface of wxRealPoint +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + + +/** + Bitmap type flags. See wxBitmap and wxImage classes. +*/ +enum wxBitmapType +{ + wxBITMAP_TYPE_INVALID, + wxBITMAP_TYPE_BMP, + wxBITMAP_TYPE_BMP_RESOURCE, + wxBITMAP_TYPE_RESOURCE = wxBITMAP_TYPE_BMP_RESOURCE, + wxBITMAP_TYPE_ICO, + wxBITMAP_TYPE_ICO_RESOURCE, + wxBITMAP_TYPE_CUR, + wxBITMAP_TYPE_CUR_RESOURCE, + wxBITMAP_TYPE_XBM, + wxBITMAP_TYPE_XBM_DATA, + wxBITMAP_TYPE_XPM, + wxBITMAP_TYPE_XPM_DATA, + wxBITMAP_TYPE_TIF, + wxBITMAP_TYPE_TIF_RESOURCE, + wxBITMAP_TYPE_GIF, + wxBITMAP_TYPE_GIF_RESOURCE, + wxBITMAP_TYPE_PNG, + wxBITMAP_TYPE_PNG_RESOURCE, + wxBITMAP_TYPE_JPEG, + wxBITMAP_TYPE_JPEG_RESOURCE, + wxBITMAP_TYPE_PNM, + wxBITMAP_TYPE_PNM_RESOURCE, + wxBITMAP_TYPE_PCX, + wxBITMAP_TYPE_PCX_RESOURCE, + wxBITMAP_TYPE_PICT, + wxBITMAP_TYPE_PICT_RESOURCE, + wxBITMAP_TYPE_ICON, + wxBITMAP_TYPE_ICON_RESOURCE, + wxBITMAP_TYPE_ANI, + wxBITMAP_TYPE_IFF, + wxBITMAP_TYPE_TGA, + wxBITMAP_TYPE_MACCURSOR, + wxBITMAP_TYPE_MACCURSOR_RESOURCE, + wxBITMAP_TYPE_ANY = 50 +}; + +/** + Standard cursors. See wxCursor. +*/ +enum wxStockCursor +{ + wxCURSOR_NONE, + wxCURSOR_ARROW, ///< A standard arrow cursor. + wxCURSOR_RIGHT_ARROW, ///< A standard arrow cursor pointing to the right. + wxCURSOR_BULLSEYE, ///< Bullseye cursor. + wxCURSOR_CHAR, ///< Rectangular character cursor. + wxCURSOR_CROSS, ///< A cross cursor. + wxCURSOR_HAND, ///< A hand cursor. + wxCURSOR_IBEAM, ///< An I-beam cursor (vertical line). + wxCURSOR_LEFT_BUTTON, ///< Represents a mouse with the left button depressed. + wxCURSOR_MAGNIFIER, ///< A magnifier icon. + wxCURSOR_MIDDLE_BUTTON, ///< Represents a mouse with the middle button depressed. + wxCURSOR_NO_ENTRY, ///< A no-entry sign cursor. + wxCURSOR_PAINT_BRUSH, ///< A paintbrush cursor. + wxCURSOR_PENCIL, ///< A pencil cursor. + wxCURSOR_POINT_LEFT, ///< A cursor that points left. + wxCURSOR_POINT_RIGHT, ///< A cursor that points right. + wxCURSOR_QUESTION_ARROW, ///< An arrow and question mark. + wxCURSOR_RIGHT_BUTTON, ///< Represents a mouse with the right button depressed. + wxCURSOR_SIZENESW, ///< A sizing cursor pointing NE-SW. + wxCURSOR_SIZENS, ///< A sizing cursor pointing N-S. + wxCURSOR_SIZENWSE, ///< A sizing cursor pointing NW-SE. + wxCURSOR_SIZEWE, ///< A sizing cursor pointing W-E. + wxCURSOR_SIZING, ///< A general sizing cursor. + wxCURSOR_SPRAYCAN, ///< A spraycan cursor. + wxCURSOR_WAIT, ///< A wait cursor. + wxCURSOR_WATCH, ///< A watch cursor. + wxCURSOR_BLANK, ///< Transparent cursor. + wxCURSOR_DEFAULT, ///< Standard X11 cursor (only in wxGTK). + wxCURSOR_COPY_ARROW , ///< MacOS Theme Plus arrow (only in wxMac). + wxCURSOR_CROSS_REVERSE, ///< Only available on wxX11. + wxCURSOR_DOUBLE_ARROW, ///< Only available on wxX11. + wxCURSOR_BASED_ARROW_UP, ///< Only available on wxX11. + wxCURSOR_BASED_ARROW_DOWN, ///< Only available on wxX11. + wxCURSOR_ARROWWAIT, ///< A wait cursor with a standard arrow. + wxCURSOR_MAX +}; + + + +/** + @class wxRealPoint + @wxheader{gdicmn.h} + + A wxRealPoint is a useful data structure for graphics operations. + + It contains floating point @e x and @e y members. See wxPoint for an + integer version. + + @library{wxcore} + @category{data} + + @see wxPoint +*/ +class wxRealPoint +{ +public: + wxRealPoint(); + + /** + Initializes the point with the given coordinates. + */ + wxRealPoint(double x, double y); + + /** + X coordinate of this point. + */ + double x; + + /** + Y coordinate of this point. + */ + double y; +}; + + + +/** + @class wxRect + @wxheader{gdicmn.h} + + A class for manipulating rectangles. + + @library{wxcore} + @category{data} + + @see wxPoint, wxSize +*/ +class wxRect +{ +public: + /** + Default constructor. + */ + wxRect(); + /** + Creates a wxRect object from @a x, @a y, @a width and @a height values. + */ + wxRect(int x, int y, int width, int height); + /** + Creates a wxRect object from top-left and bottom-right points. + */ + wxRect(const wxPoint& topLeft, const wxPoint& bottomRight); + /** + Creates a wxRect object from position and @a size values. + */ + wxRect(const wxPoint& pos, const wxSize& size); + /** + Creates a wxRect object from @a size values at the origin. + */ + wxRect(const wxSize& size); + + //@{ + /** + Returns the rectangle having the same size as this one but centered + relatively to the given rectangle @a r. By default, rectangle is + centred in both directions but if @a dir includes only @c wxVERTICAL or + only @c wxHORIZONTAL, then it is only centered in this direction while + the other component of its position remains unchanged. + */ + wxRect CentreIn(const wxRect& r, int dir = wxBOTH) const; + wxRect CenterIn(const wxRect& r, int dir = wxBOTH) const; + //@} + + /** + Returns @true if the given point is inside the rectangle (or on its + boundary) and @false otherwise. + */ + bool Contains(int x, int y) const; + /** + Returns @true if the given point is inside the rectangle (or on its + boundary) and @false otherwise. + */ + bool Contains(const wxPoint& pt) const; + /** + Returns @true if the given rectangle is completely inside this + rectangle (or touches its boundary) and @false otherwise. + */ + bool Contains(const wxRect& rect) const; + + //@{ + /** + Decrease the rectangle size. + + This method is the opposite from Inflate(): Deflate(a, b) is equivalent + to Inflate(-a, -b). Please refer to Inflate() for full description. + */ + void Deflate(wxCoord dx, wxCoord dy); + void Deflate(const wxSize& diff); + void Deflate(wxCoord diff); + wxRect Deflate(wxCoord dx, wxCoord dy) const; + //@} + + /** + Gets the bottom point of the rectangle. + */ + int GetBottom() const; + + /** + Gets the position of the bottom left corner. + */ + wxPoint GetBottomLeft() const; + + /** + Gets the position of the bottom right corner. + */ + wxPoint GetBottomRight() const; + + /** + Gets the height member. + */ + int GetHeight() const; + + /** + Gets the left point of the rectangle (the same as GetX()). + */ + int GetLeft() const; + + /** + Gets the position. + */ + wxPoint GetPosition() const; + + /** + Gets the right point of the rectangle. + */ + int GetRight() const; + + /** + Gets the size. + + @see SetSize() + */ + wxSize GetSize() const; + + /** + Gets the top point of the rectangle (the same as GetY()). + */ + int GetTop() const; + + /** + Gets the position of the top left corner of the rectangle, same as + GetPosition(). + */ + wxPoint GetTopLeft() const; + + /** + Gets the position of the top right corner. + */ + wxPoint GetTopRight() const; + + /** + Gets the width member. + */ + int GetWidth() const; + + /** + Gets the x member. + */ + int GetX() const; + + /** + Gets the y member. + */ + int GetY() const; + + //@{ + /** + Increases the size of the rectangle. + + The left border is moved farther left and the right border is moved + farther right by @a dx. The upper border is moved farther up and the + bottom border is moved farther down by @a dy. (Note the the width and + height of the rectangle thus change by 2*dx and 2*dy, respectively.) If + one or both of @a dx and @a dy are negative, the opposite happens: the + rectangle size decreases in the respective direction. + + Inflating and deflating behaves "naturally". Defined more precisely, + that means: + -# "Real" inflates (that is, @a dx and/or @a dy = 0) are not + constrained. Thus inflating a rectangle can cause its upper left + corner to move into the negative numbers. (2.5.4 and older forced + the top left coordinate to not fall below (0, 0), which implied a + forced move of the rectangle.) + -# Deflates are clamped to not reduce the width or height of the + rectangle below zero. In such cases, the top-left corner is + nonetheless handled properly. For example, a rectangle at (10, 10) + with size (20, 40) that is inflated by (-15, -15) will become + located at (20, 25) at size (0, 10). Finally, observe that the width + and height are treated independently. In the above example, the + width is reduced by 20, whereas the height is reduced by the full 30 + (rather than also stopping at 20, when the width reached zero). + + @see Deflate() + */ + void Inflate(wxCoord dx, wxCoord dy); + void Inflate(const wxSize& diff); + void Inflate(wxCoord diff); + wxRect Inflate(wxCoord dx, wxCoord dy) const; + //@} + + //@{ + /** + Modifies the rectangle to contain the overlapping box of this rectangle + and the one passed in as parameter. + */ + wxRect Intersect(const wxRect& rect) const; + wxRect& Intersect(const wxRect& rect); + //@} + + /** + Returns @true if this rectangle has a non-empty intersection with the + rectangle @a rect and @false otherwise. + */ + bool Intersects(const wxRect& rect) const; + + /** + Returns @true if this rectangle has a width or height less than or + equal to 0 and @false otherwise. + */ + bool IsEmpty() const; + + //@{ + /** + Moves the rectangle by the specified offset. If @a dx is positive, the + rectangle is moved to the right, if @a dy is positive, it is moved to the + bottom, otherwise it is moved to the left or top respectively. + */ + void Offset(wxCoord dx, wxCoord dy); + void Offset(const wxPoint& pt); + //@} + + /** + Sets the height. + */ + void SetHeight(int height); + + /** + Sets the size. + + @see GetSize() + */ + void SetSize(const wxSize& s); + + /** + Sets the width. + */ + void SetWidth(int width); + + /** + Sets the x position. + */ + void SetX(int x); + + /** + Sets the y position. + */ + void SetY(int y); + + //@{ + /** + Modifies the rectangle to contain the bounding box of this rectangle + and the one passed in as parameter. + */ + wxRect Union(const wxRect& rect) const; + wxRect& Union(const wxRect& rect); + //@} + + /** + Inequality operator. + */ + bool operator !=(const wxRect& r1, const wxRect& r2); + + //@{ + /** + Like Union(), but doesn't treat empty rectangles specially. + */ + wxRect operator +(const wxRect& r1, const wxRect& r2); + wxRect& operator +=(const wxRect& r); + //@} + + //@{ + /** + Returns the intersection of two rectangles (which may be empty). + */ + wxRect operator *(const wxRect& r1, const wxRect& r2); + wxRect& operator *=(const wxRect& r); + //@} + + /** + Assignment operator. + */ + void operator =(const wxRect& rect); + + /** + Equality operator. + */ + bool operator ==(const wxRect& r1, const wxRect& r2); + + /** + Height member. + */ + int height; + + /** + Width member. + */ + int width; + + /** + x coordinate of the top-level corner of the rectangle. + */ + int x; + + /** + y coordinate of the top-level corner of the rectangle. + */ + int y; +}; + + + +/** + @class wxPoint + @wxheader{gdicmn.h} + + A wxPoint is a useful data structure for graphics operations. + + It contains integer @e x and @e y members. See wxRealPoint for a floating + point version. + + @library{wxcore} + @category{data} + + @stdobjects + ::wxDefaultPosition + + @see wxRealPoint +*/ +class wxPoint +{ +public: + //@{ + /** + Constructs a point. + */ + wxPoint(); + wxPoint(int x, int y); + //@} + + /** + Assignment operator. + */ + void operator =(const wxPoint& pt); + + bool operator ==(const wxPoint& p1, const wxPoint& p2); + bool operator !=(const wxPoint& p1, const wxPoint& p2); + + wxPoint operator +(const wxPoint& p1, const wxPoint& p2); + wxPoint operator -(const wxPoint& p1, const wxPoint& p2); + + wxPoint& operator +=(const wxPoint& pt); + wxPoint& operator -=(const wxPoint& pt); + + wxPoint operator +(const wxPoint& pt, const wxSize& sz); + wxPoint operator -(const wxPoint& pt, const wxSize& sz); + wxPoint operator +(const wxSize& sz, const wxPoint& pt); + wxPoint operator -(const wxSize& sz, const wxPoint& pt); + + wxPoint& operator +=(const wxSize& sz); + wxPoint& operator -=(const wxSize& sz); + + /** + x member. + */ + int x; + + /** + y member. + */ + int y; +}; + +/** + Global istance of a wxPoint initialized with values (-1,-1). +*/ +wxPoint wxDefaultPosition; + + +/** + @class wxColourDatabase + @wxheader{gdicmn.h} + + wxWidgets maintains a database of standard RGB colours for a predefined + set of named colours. The application may add to this set if desired by + using AddColour() and may use it to look up colours by names using Find() + or find the names for the standard colour using FindName(). + + There is one predefined, global instance of this class called + ::wxTheColourDatabase. + + The standard database contains at least the following colours: + + @beginTable + + AQUAMARINE + @n BLACK + @n BLUE + @n BLUE VIOLET + @n BROWN + @n CADET BLUE + @n CORAL + @n CORNFLOWER BLUE + @n CYAN + @n DARK GREY + @n DARK GREEN + @n DARK OLIVE GREEN + @n DARK ORCHID + @n DARK SLATE BLUE + @n DARK SLATE GREY + @n DARK TURQUOISE + @n DIM GREY + + FIREBRICK + @n FOREST GREEN + @n GOLD + @n GOLDENROD + @n GREY + @n GREEN + @n GREEN YELLOW + @n INDIAN RED + @n KHAKI + @n LIGHT BLUE + @n LIGHT GREY + @n LIGHT STEEL BLUE + @n LIME GREEN + @n MAGENTA + @n MAROON + @n MEDIUM AQUAMARINE + @n MEDIUM BLUE + + MEDIUM FOREST GREEN + @n MEDIUM GOLDENROD + @n MEDIUM ORCHID + @n MEDIUM SEA GREEN + @n MEDIUM SLATE BLUE + @n MEDIUM SPRING GREEN + @n MEDIUM TURQUOISE + @n MEDIUM VIOLET RED + @n MIDNIGHT BLUE + @n NAVY + @n ORANGE + @n ORANGE RED + @n ORCHID + @n PALE GREEN + @n PINK + @n PLUM + @n PURPLE + + RED + @n SALMON + @n SEA GREEN + @n SIENNA + @n SKY BLUE + @n SLATE BLUE + @n SPRING GREEN + @n STEEL BLUE + @n TAN + @n THISTLE + @n TURQUOISE + @n VIOLET + @n VIOLET RED + @n WHEAT + @n WHITE + @n YELLOW + @n YELLOW GREEN + + @endTable + + @library{wxcore} + @category{gdi} + + @see wxColour +*/ +class wxColourDatabase +{ +public: + /** + Constructs the colour database. It will be initialized at the first + use. + */ + wxColourDatabase(); + + /** + Adds a colour to the database. If a colour with the same name already + exists, it is replaced. + */ + void AddColour(const wxString& colourName, const wxColour& colour); + + /** + Finds a colour given the name. Returns an invalid colour object (that + is, wxColour::IsOk() will return @false) if the colour wasn't found in + the database. + */ + wxColour Find(const wxString& colourName); + + /** + Finds a colour name given the colour. Returns an empty string if the + colour is not found in the database. + */ + wxString FindName(const wxColour& colour) const; +}; + + +/** + @class wxSize + @wxheader{gdicmn.h} + + A wxSize is a useful data structure for graphics operations. It simply + contains integer @e width and @e height members. + + wxSize is used throughout wxWidgets as well as wxPoint which, although + almost equivalent to wxSize, has a different meaning: wxPoint represents a + position while wxSize represents the size. + + @beginWxPythonOnly + wxPython defines aliases for the @e x and @e y members named @e width and + @e height since it makes much more sense for sizes. + @endWxPythonOnly + + @library{wxcore} + @category{data} + + @stdobjects + ::wxDefaultSize + + @see wxPoint, wxRealPoint +*/ +class wxSize +{ +public: + //@{ + /** + Creates a size object. + */ + wxSize(); + wxSize(int width, int height); + //@} + + //@{ + /** + Decreases the size in both x and y directions. + + @see IncBy() + */ + void DecBy(const wxSize& size); + void DecBy(int dx, int dy); + void DecBy(int d); + //@} + + /** + Decrements this object so that both of its dimensions are not greater + than the corresponding dimensions of the @a size. + + @see IncTo() + */ + void DecTo(const wxSize& size); + + /** + Gets the height member. + */ + int GetHeight() const; + + /** + Gets the width member. + */ + int GetWidth() const; + + //@{ + /** + Increases the size in both x and y directions. + + @see DecBy() + */ + void IncBy(const wxSize& size); + void IncBy(int dx, int dy); + void IncBy(int d); + //@} + + /** + Increments this object so that both of its dimensions are not less than + the corresponding dimensions of the @a size. + + @see DecTo() + */ + void IncTo(const wxSize& size); + + /** + Returns @true if neither of the size object components is equal to -1, + which is used as default for the size values in wxWidgets (hence the + predefined ::wxDefaultSize has both of its components equal to -1). + + This method is typically used before calling SetDefaults(). + */ + bool IsFullySpecified() const; + + /** + Scales the dimensions of this object by the given factors. If you want + to scale both dimensions by the same factor you can also use + operator*=(). + + @return A reference to this object (so that you can concatenate other + operations in the same line). + */ + wxSize& Scale(float xscale, float yscale); + + /** + Sets the width and height members. + */ + void Set(int width, int height); + + /** + Combine this size object with another one replacing the default (i.e. + equal to -1) components of this object with those of the other. It is + typically used like this: + + @code + if ( !size.IsFullySpecified() ) + { + size.SetDefaults(GetDefaultSize()); + } + @endcode + + @see IsFullySpecified() + */ + void SetDefaults(const wxSize& sizeDefault); + + /** + Sets the height. + */ + void SetHeight(int height); + + /** + Sets the width. + */ + void SetWidth(int width); + + /** + Assignment operator. + */ + void operator =(const wxSize& sz); + + bool operator ==(const wxSize& s1, const wxSize& s2); + bool operator !=(const wxSize& s1, const wxSize& s2); + + wxSize operator +(const wxSize& s1, const wxSize& s2); + wxSize operator -(const wxSize& s1, const wxSize& s2); + wxSize& operator +=(const wxSize& sz); + wxSize& operator -=(const wxSize& sz); + + wxSize operator /(const wxSize& sz, int factor); + wxSize operator *(const wxSize& sz, int factor); + wxSize operator *(int factor, const wxSize& sz); + wxSize& operator /=(int factor); + wxSize& operator *=(int factor); +}; + +/** + Global instance of a wxSize object initialized to (-1,-1). +*/ +wxSize wxDefaultSize; + + + + +// ============================================================================ +// Global functions/macros +// ============================================================================ + +/** @ingroup group_funcmacro_gdi */ +//@{ + +/** + This macro loads a bitmap from either application resources (on the + platforms for which they exist, i.e. Windows and OS2) or from an XPM file. + This can help to avoid using @ifdef_ when creating bitmaps. + + @see @ref overview_bitmap, wxICON() + + @header{wx/gdicmn.h} +*/ +#define wxBITMAP(bitmapName) + +/** + This macro loads an icon from either application resources (on the + platforms for which they exist, i.e. Windows and OS2) or from an XPM file. + This can help to avoid using @ifdef_ when creating icons. + + @see @ref overview_bitmap, wxBITMAP() + + @header{wx/gdicmn.h} +*/ +wxICON(); + +/** + Returns @true if the display is colour, @false otherwise. + + @header{wx/gdicmn.h} +*/ +bool wxColourDisplay(); + +/** + Returns the depth of the display (a value of 1 denotes a monochrome + display). + + @header{wx/gdicmn.h} +*/ +int wxDisplayDepth(); + +/** + Globally sets the cursor; only has an effect on Windows, Mac and GTK+. You + should call this function with wxNullCursor to restore the system cursor. + + @see wxCursor, wxWindow::SetCursor() + + @header{wx/gdicmn.h} +*/ +void wxSetCursor(const wxCursor& cursor); + +//@} + +/** @ingroup group_funcmacro_gdi */ +//@{ +/** + Returns the dimensions of the work area on the display. On Windows this + means the area not covered by the taskbar, etc. Other platforms are + currently defaulting to the whole display until a way is found to provide + this info for all window managers, etc. + + @header{wx/gdicmn.h} +*/ +void wxClientDisplayRect(int* x, int* y, int* width, int* height); +wxRect wxGetClientDisplayRect(); +//@} + +/** @ingroup group_funcmacro_gdi */ +//@{ +/** + Returns the display size in pixels. + + @header{wx/gdicmn.h} +*/ +void wxDisplaySize(int* width, int* height); +wxSize wxGetDisplaySize(); +//@} + +/** @ingroup group_funcmacro_gdi */ +//@{ +/** + Returns the display size in millimeters. + + @header{wx/gdicmn.h} +*/ +void wxDisplaySizeMM(int* width, int* height); +wxSize wxGetDisplaySizeMM(); +//@} + diff --git a/interface/wx/gdiobj.h b/interface/wx/gdiobj.h new file mode 100644 index 0000000000..52464ff191 --- /dev/null +++ b/interface/wx/gdiobj.h @@ -0,0 +1,36 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: gdiobj.h +// Purpose: interface of wxGDIObject +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxGDIObject + @wxheader{gdiobj.h} + + This class allows platforms to implement functionality to optimise GDI objects, + such + as wxPen, wxBrush and wxFont. On Windows, the underling GDI objects are a + scarce resource + and are cleaned up when a usage count goes to zero. On some platforms this + class may not have any special functionality. + + Since the functionality of this class is platform-specific, it is not + documented here in detail. + + @library{wxcore} + @category{FIXME} + + @see wxPen, wxBrush, wxFont +*/ +class wxGDIObject : public wxObject +{ +public: + /** + Default constructor. + */ + wxGDIObject(); +}; + diff --git a/interface/wx/generic/helpext.h b/interface/wx/generic/helpext.h new file mode 100644 index 0000000000..57c84afce9 --- /dev/null +++ b/interface/wx/generic/helpext.h @@ -0,0 +1,168 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: helpext.h +// Purpose: interface of wxExtHelpController +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + + +/** + @class wxExtHelpController + @wxheader{help.h} + + This class implements help via an external browser. + It requires the name of a directory containing the documentation + and a file mapping numerical Section numbers to relative URLS. + + The map file contains two or three fields per line: + numeric_id relative_URL [; comment/documentation] + + The numeric_id is the id used to look up the entry in + DisplaySection()/DisplayBlock(). The relative_URL is a filename of + an html file, relative to the help directory. The optional + comment/documentation field (after a ';') is used for keyword + searches, so some meaningful text here does not hurt. + If the documentation itself contains a ';', only the part before + that will be displayed in the listbox, but all of it used for search. + + Lines starting with ';' will be ignored. + + @library{wxadv} + @category{help} + + @see wxHelpController +*/ +class wxExtHelpController : public wxHelpController +{ +public: + wxExtHelpController(wxWindow* parentWindow = NULL); + virtual ~wxExtHelpController(); + + /** + Tell it which browser to use. + The Netscape support will check whether Netscape is already + running (by looking at the .netscape/lock file in the user's + home directory) and tell it to load the page into the existing window. + + @param viewer + The command to call a browser/html viewer. + @param flags + Set this to wxHELP_NETSCAPE if the browser is some variant of Netscape. + */ + virtual void SetViewer(const wxString& viewer = wxEmptyString, + long flags = wxHELP_NETSCAPE); + + /** + This must be called to tell the controller where to find the + documentation. + If a locale is set, look in file/localename, i.e. + If passed "/usr/local/myapp/help" and the current wxLocale is + set to be "de", then look in "/usr/local/myapp/help/de/" + first and fall back to "/usr/local/myapp/help" if that + doesn't exist. + + @param file + NOT a filename, but a directory name. + + @return @true on success + */ + virtual bool Initialize(const wxString& dir, int server); + + /** + This must be called to tell the controller where to find the + documentation. + If a locale is set, look in file/localename, i.e. + If passed "/usr/local/myapp/help" and the current wxLocale is + set to be "de", then look in "/usr/local/myapp/help/de/" + first and fall back to "/usr/local/myapp/help" if that + doesn't exist. + + @param dir + directory name where to fine the help files + + @return @true on success + */ + virtual bool Initialize(const wxString& dir); + + /** + If file is "", reloads file given in Initialize. + + @param file + Name of help directory. + + @return @true on success + */ + virtual bool LoadFile(const wxString& file = wxEmptyString); + + /** + Display list of all help entries. + + @return @true on success + */ + virtual bool DisplayContents(void); + + /** + Display help for id sectionNo. + + @return @true on success + */ + virtual bool DisplaySection(int sectionNo); + + /** + Display help for id sectionNo -- identical with DisplaySection(). + + @return @true on success + */ + virtual bool DisplaySection(const wxString& section); + + /** + Display help for URL (using DisplayHelp) or keyword (using KeywordSearch) + + @return @true on success + */ + virtual bool DisplayBlock(long blockNo); + + /** + Search comment/documentation fields in map file and present a + list to chose from. + + @param k + string to search for, empty string will list all entries + + @return @true on success + */ + virtual bool KeywordSearch(const wxString& k, + wxHelpSearchMode mode = wxHELP_SEARCH_ALL); + + /** + Does nothing. + */ + virtual bool Quit(); + + /** + Does nothing. + */ + virtual void OnQuit(); + + /** + Call the browser using a relative URL. + */ + virtual bool DisplayHelp(const wxString &) ; + + /** + Allows one to override the default settings for the help frame. + */ + virtual void SetFrameParameters(const wxString& title, + const wxSize& size, + const wxPoint& pos = wxDefaultPosition, + bool newFrameEachTime = false); + + /** + Obtains the latest settings used by the help frame and the help frame. + */ + virtual wxFrame *GetFrameParameters(wxSize *size = NULL, + wxPoint *pos = NULL, + bool *newFrameEachTime = NULL); +}; + diff --git a/interface/wx/glcanvas.h b/interface/wx/glcanvas.h new file mode 100644 index 0000000000..c3694c591d --- /dev/null +++ b/interface/wx/glcanvas.h @@ -0,0 +1,271 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: glcanvas.h +// Purpose: interface of wxGLContext +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxGLContext + @wxheader{glcanvas.h} + + An instance of a wxGLContext represents the state of an OpenGL state machine + and the connection between OpenGL and the system. + + The OpenGL state includes everything that can be set with the OpenGL API: + colors, rendering variables, display lists, texture objects, etc. + Although it is possible to have multiple rendering contexts share display lists + in order to save resources, + this method is hardly used today any more, because display lists are only a + tiny fraction of the overall state. + + Therefore, one rendering context is usually used with or bound to multiple + output windows in turn, + so that the application has access to the complete and identical state while + rendering into each window. + + Binding (making current) a rendering context with another instance of a + wxGLCanvas however works only + if the other wxGLCanvas was created with the same attributes as the wxGLCanvas + from which the wxGLContext + was initialized. (This applies to sharing display lists among contexts + analogously.) + + Note that some wxGLContext features are extremely platform-specific - its best + to check your native platform's glcanvas header (on windows include/wx/msw/glcanvas.h) to see what features your native platform provides. + + @library{wxgl} + @category{gl} + + @see wxGLCanvas +*/ +class wxGLContext : public wxObject +{ +public: + /** + Constructor. + + @param win + The canvas that is used to initialize this context. This parameter is + needed only temporarily, + and the caller may do anything with it (e.g. destroy the window) after the + constructor returned. + It will be possible to bind (make current) this context to any other + wxGLCanvas that has been created + with equivalent attributes as win. + @param other + Context to share display lists with or @NULL (the default) for no sharing. + */ + wxGLContext(wxGLCanvas* win, const wxGLContext* other = NULL); + + /** + Makes the OpenGL state that is represented by this rendering context current + with the wxGLCanvas @e win. + Note that @a win can be a different wxGLCanvas window than the one that was + passed to the constructor of this rendering context. + If @e RC is an object of type wxGLContext, the statements @e + RC.SetCurrent(win); and @e win.SetCurrent(RC); are equivalent, + see wxGLCanvas::SetCurrent. + */ + void SetCurrent(const wxGLCanvas& win); +}; + +/** + Constants for use with wxGLCanvas. + + Notice that not all implementation support options such as stereo, + auxiliary buffers, alpha channel, and accumulator buffer, use + wxGLCanvas::IsDisplaySupported() to check for individual attributes support. + */ +enum +{ + /// Use true color palette (on if no attributes at all specified). + WX_GL_RGBA = 1, + + /// Specifies the number of bits for buffer if not WX_GL_RGBA. + WX_GL_BUFFER_SIZE, + + /// Must be followed by 0 for main buffer, >0 for overlay, <0 for underlay. + WX_GL_LEVEL, + + /// Use double buffering if present (on if no attributes specified). + WX_GL_DOUBLEBUFFER, + + /// Use stereoscopic display. + WX_GL_STEREO, + + /// Specifies number of auxiliary buffers. + WX_GL_AUX_BUFFERS, + + /// Use red buffer with most bits (> MIN_RED bits) + WX_GL_MIN_RED, + + /// Use green buffer with most bits (> MIN_GREEN bits) + WX_GL_MIN_GREEN, + + /// Use blue buffer with most bits (> MIN_BLUE bits) + WX_GL_MIN_BLUE, + + /// Use alpha buffer with most bits (> MIN_ALPHA bits) + WX_GL_MIN_ALPHA, + + /// Specifies number of bits for Z-buffer (typically 0, 16 or 32). + WX_GL_DEPTH_SIZE, + + /// Specifies number of bits for stencil buffer. + WX_GL_STENCIL_SIZE, + + /// Specifies minimal number of red accumulator bits. + WX_GL_MIN_ACCUM_RED, + + /// Specifies minimal number of green accumulator bits. + WX_GL_MIN_ACCUM_GREEN, + + /// Specifies minimal number of blue accumulator bits. + WX_GL_MIN_ACCUM_BLUE, + + /// Specifies minimal number of alpha accumulator bits. + WX_GL_MIN_ACCUM_ALPHA, + + /// 1 for multisampling support (antialiasing) + WX_GL_SAMPLE_BUFFERS, + + /// 4 for 2x2 antialising supersampling on most graphics cards + WX_GL_SAMPLES + +}; + +/** + @class wxGLCanvas + @wxheader{glcanvas.h} + + wxGLCanvas is a class for displaying OpenGL graphics. It is always used in + conjunction with wxGLContext as the context can only be + be made current (i.e. active for the OpenGL commands) when it is associated to + a wxGLCanvas. + + More precisely, you first need to create a wxGLCanvas window and then create an + instance of a wxGLContext that is initialized with this + wxGLCanvas and then later use either wxGLCanvas::SetCurrent + with the instance of the wxGLContext or + wxGLContext::SetCurrent with the instance of + the wxGLCanvas (which might be not the same as was used + for the creation of the context) to bind the OpenGL state that is represented + by the rendering context to the canvas, and then finally call + wxGLCanvas::SwapBuffers to swap the buffers of + the OpenGL canvas and thus show your current output. + + Notice that previous versions of wxWidgets used to implicitly create a + wxGLContext inside wxGLCanvas itself. This is still supported in the current + version but is deprecated now and will be removed in the future, please update + your code to create the rendering contexts explicitly. + + To set up the attributes for the canvas (number of bits for the depth buffer, + number of bits for the stencil buffer and so on) you should set up the correct + values of + the @e attribList parameter. The values that should be set up and their + meanings will be described below. + + Notice that OpenGL is not enabled by default. To switch it on, you need to edit + setup.h under Windows and set @c wxUSE_GLCANVAS to 1 (you may also need + to have to add @c opengl32.lib and @c glu32.lib to the list of libraries + your program is linked with). On Unix, pass @c --with-opengl to configure. + + @library{wxgl} + @category{gl} + + @see wxGLContext +*/ +class wxGLCanvas : public wxWindow +{ +public: + /** + Creates a window with the given parameters. Notice that you need to create and + use a wxGLContext to output to this window. + If + + @param attribList is not specified, double buffered RGBA mode is used. + + parent + Pointer to a parent window. + @param id + Window identifier. If -1, will automatically create an identifier. + @param pos + Window position. wxDefaultPosition is (-1, -1) which indicates that + wxWidgets + should generate a default position for the window. + @param size + Window size. wxDefaultSize is (-1, -1) which indicates that wxWidgets should + generate a default size for the window. If no suitable size can be found, + the window will be sized to 20x20 pixels so that the window is visible but obviously not correctly sized. + @param style + Window style. + @param name + Window name. + @param attribList + Array of integers. With this parameter you can set the device + context attributes associated to this window. This array is + zero-terminated: it should be set up with constants described in + the table above. If a constant should be followed by a value, put + it in the next array position. For example, the WX_GL_DEPTH_SIZE + should be followed by the value that indicates the number of bits + for the depth buffer, e.g: + @code + attribList[n++] = WX_GL_DEPTH_SIZE; + attribList[n++] = 32; + attribList[n] = 0; // terminate the list + @endcode + If the attribute list is not specified at all, i.e. if this + parameter is @NULL, the default attributes including @c WX_GL_RGBA + and @c WX_GL_DOUBLEBUFFER are used. But notice that if you do + specify some attributes you also need to explicitly include these + two default attributes in the list if you need them. + @param palette + Palette for indexed colour (i.e. non WX_GL_RGBA) mode. + Ignored under most platforms. + */ + wxGLCanvas(wxWindow* parent, wxWindowID id = wxID_ANY, + const int* attribList = NULL, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0, + const wxString& name = "GLCanvas", + const wxPalette& palette = wxNullPalette); + + /** + Determines if a canvas having the specified attributes is available. + Returns @true if attributes are supported. + + @param attribList + See attribList for wxGLCanvas(). + */ + static bool IsDisplaySupported(const int* attribList = NULL); + + /** + Sets the current colour for this window (using @c glcolor3f()), using the + wxWidgets colour database to find a named colour. + */ + void SetColour(const wxString& colour); + + /** + Makes the OpenGL state that is represented by the OpenGL rendering context + @a context current, i.e. it will be used by all subsequent OpenGL calls. + This is equivalent to wxGLContext::SetCurrent + called with this window as parameter. + Note that this function may only be called when the window is shown on screen, + in particular it can't usually be called from the constructor as the window + isn't yet shown at this moment. + Returns @false if an error occurred. + */ + bool SetCurrent(const wxGLContext context); + + /** + Swaps the double-buffer of this window, making the back-buffer the front-buffer + and vice versa, + so that the output of the previous OpenGL commands is displayed on the window. + Returns @false if an error occurred. + */ + bool SwapBuffers(); +}; + diff --git a/interface/wx/graphics.h b/interface/wx/graphics.h new file mode 100644 index 0000000000..45360115b7 --- /dev/null +++ b/interface/wx/graphics.h @@ -0,0 +1,766 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: graphics.h +// Purpose: interface of wxGraphicsPath +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxGraphicsPath + @wxheader{graphics.h} + + A wxGraphicsPath is a native representation of an geometric path. The contents + are specific an private to the respective renderer. Instances are ref counted and can + therefore be assigned as usual. The only way to get a valid instance is via a + CreatePath call on the graphics context or the renderer instance. + + @library{wxcore} + @category{FIXME} +*/ +class wxGraphicsPath : public wxGraphicsObject +{ +public: + //@{ + /** + + */ + void AddArc(wxDouble x, wxDouble y, wxDouble r, + wxDouble startAngle, + wxDouble endAngle, bool clockwise); + void AddArc(const wxPoint2DDouble& c, wxDouble r, + wxDouble startAngle, + wxDouble endAngle, + bool clockwise); + //@} + + /** + Appends a an arc to two tangents connecting (current) to (x1,y1) and (x1,y1) to + (x2,y2), also a straight line from (current) to (x1,y1). + */ + void AddArcToPoint(wxDouble x1, wxDouble y1, wxDouble x2, + wxDouble y2, + wxDouble r); + + /** + Appends a circle around (x,y) with radius r as a new closed subpath. + */ + void AddCircle(wxDouble x, wxDouble y, wxDouble r); + + //@{ + /** + + */ + void AddCurveToPoint(wxDouble cx1, wxDouble cy1, wxDouble cx2, + wxDouble cy2, + wxDouble x, + wxDouble y); + void AddCurveToPoint(const wxPoint2DDouble& c1, + const wxPoint2DDouble& c2, + const wxPoint2DDouble& e); + //@} + + /** + Appends an ellipse fitting into the passed in rectangle. + */ + void AddEllipse(wxDouble x, wxDouble y, wxDouble w, wxDouble h); + + //@{ + /** + + */ + void AddLineToPoint(wxDouble x, wxDouble y); + void AddLineToPoint(const wxPoint2DDouble& p); + //@} + + /** + Adds another path. + */ + void AddPath(const wxGraphicsPath& path); + + /** + Adds a quadratic Bezier curve from the current point, using a control point and + an end point. + */ + void AddQuadCurveToPoint(wxDouble cx, wxDouble cy, wxDouble x, + wxDouble y); + + /** + Appends a rectangle as a new closed subpath. + */ + void AddRectangle(wxDouble x, wxDouble y, wxDouble w, wxDouble h); + + /** + Appends a rounded rectangle as a new closed subpath. + */ + void AddRoundedRectangle(wxDouble x, wxDouble y, wxDouble w, + wxDouble h, + wxDouble radius); + + /** + Closes the current sub-path. + */ + void CloseSubpath(); + + //@{ + /** + Returns @true if the point is within the path. + */ + bool Contains(const wxPoint2DDouble& c, + int fillStyle = wxODDEVEN_RULE) const; + const bool Contains(wxDouble x, wxDouble y, + int fillStyle = wxODDEVEN_RULE) const; + //@} + + //@{ + /** + Gets the bounding box enclosing all points (possibly including control points). + */ + wxRect2DDouble GetBox() const; + const void GetBox(wxDouble* x, wxDouble* y, wxDouble* w, + wxDouble* h) const; + //@} + + //@{ + /** + Gets the last point of the current path, (0,0) if not yet set. + */ + void GetCurrentPoint(wxDouble* x, wxDouble* y) const; + const wxPoint2DDouble GetCurrentPoint() const; + //@} + + /** + Returns the native path (CGPathRef for Core Graphics, Path pointer for GDIPlus + and a cairo_path_t pointer for cairo). + */ + void* GetNativePath() const; + + //@{ + /** + Begins a new subpath at (x,y) + */ + void MoveToPoint(wxDouble x, wxDouble y); + void MoveToPoint(const wxPoint2DDouble& p); + //@} + + /** + Transforms each point of this path by the matrix. + */ + void Transform(const wxGraphicsMatrix& matrix); + + /** + Gives back the native path returned by GetNativePath() because there might be + some deallocations necessary (eg on cairo the native path returned by + GetNativePath is newly allocated each time). + */ + void UnGetNativePath(void* p) const; +}; + + + +/** + @class wxGraphicsObject + @wxheader{graphics.h} + + This class is the superclass of native graphics objects like pens etc. It + allows reference counting. Not instantiated by user code. + + @library{wxcore} + @category{FIXME} + + @see wxGraphicsBrush, wxGraphicsPen, wxGraphicsMatrix, wxGraphicsPath +*/ +class wxGraphicsObject : public wxObject +{ +public: + /** + Returns the renderer that was used to create this instance, or @NULL if it has + not been initialized yet + */ + wxGraphicsRenderer* GetRenderer() const; + + /** + Is this object valid (@false) or still empty (@true)? + */ + bool IsNull() const; +}; + + + +/** + @class wxGraphicsContext + @wxheader{graphics.h} + + A wxGraphicsContext instance is the object that is drawn upon. It is created by + a renderer using wxGraphicsRenderer::CreateContext(). This can be either directly + using a renderer instance, or indirectly using the static convenience Create() + functions of wxGraphicsContext that always delegate the task to the default renderer. + + @code + void MyCanvas::OnPaint(wxPaintEvent &event) + { + // Create paint DC + wxPaintDC dc(this); + + // Create graphics context from it + wxGraphicsContext *gc = wxGraphicsContext::Create( dc ); + + if (gc) + { + // make a path that contains a circle and some lines + gc->SetPen( *wxRED_PEN ); + wxGraphicsPath path = gc->CreatePath(); + path.AddCircle( 50.0, 50.0, 50.0 ); + path.MoveToPoint(0.0, 50.0); + path.AddLineToPoint(100.0, 50.0); + path.MoveToPoint(50.0, 0.0); + path.AddLineToPoint(50.0, 100.0 ); + path.CloseSubpath(); + path.AddRectangle(25.0, 25.0, 50.0, 50.0); + + gc->StrokePath(path); + + delete gc; + } + } + @endcode + + + @library{wxcore} + @category{FIXME} + + @see wxGraphicsRenderer::CreateContext(), wxGCDC, wxDC +*/ +class wxGraphicsContext : public wxGraphicsObject +{ +public: + /** + Creates a wxGraphicsContext from a wxWindow. + + @see wxGraphicsRenderer::CreateContext() + */ + static wxGraphicsContext* Create( wxWindow* window ) ; + + /** + Creates a wxGraphicsContext from a wxWindowDC + + @see wxGraphicsRenderer::CreateContext() + */ + static wxGraphicsContext* Create( const wxWindowDC& dc) ; + + /** + Creates a wxGraphicsContext from a wxMemoryDC + + @see wxGraphicsRenderer::CreateContext() + */ + static wxGraphicsContext * Create( const wxMemoryDC& dc) ; + + /** + Creates a wxGraphicsContext from a wxPrinterDC. Under + GTK+, this will only work when using the GtkPrint + printing backend which is available since GTK+ 2.10. + + @see wxGraphicsRenderer::CreateContext(), @ref overview_unixprinting "Printing under Unix" + */ + static wxGraphicsContext * Create( const wxPrinterDC& dc) ; + + /** + Clips drawings to the region + */ + void Clip(const wxRegion& region); + + /** + Clips drawings to the rectangle. + */ + void Clip(wxDouble x, wxDouble y, wxDouble w, wxDouble h); + + /** + Concatenates the passed in transform with the current transform of this context + */ + void ConcatTransform(const wxGraphicsMatrix& matrix); + + + /** + Creates a native brush from a wxBrush. + */ + wxGraphicsBrush CreateBrush(const wxBrush& brush) const; + + /** + Creates a native graphics font from a wxFont and a text colour. + */ + wxGraphicsFont CreateFont(const wxFont& font, + const wxColour& col = wxBLACK) const; + + /** + Creates a wxGraphicsContext from a native context. This native context must be + eg a CGContextRef for Core Graphics, a Graphics pointer for GDIPlus or a + cairo_t pointer for cairo. + + @see wxGraphicsRenderer:: CreateContextFromNativeContext + */ + wxGraphicsContext* CreateFromNative(void* context); + + /** + Creates a wxGraphicsContext from a native window. + + @see wxGraphicsRenderer:: CreateContextFromNativeWindow + */ + wxGraphicsContext* CreateFromNativeWindow(void* window); + + /** + Creates a native brush, having a linear gradient, starting at (x1,y1) with + color c1 to (x2,y2) with color c2 + */ + wxGraphicsBrush CreateLinearGradientBrush(wxDouble x1, + wxDouble y1, + wxDouble x2, + wxDouble y2, + const wxColouramp;c1, + const wxColouramp;c2) const; + + /** + Creates a native affine transformation matrix from the passed in values. The + defaults result in an identity matrix. + */ + wxGraphicsMatrix CreateMatrix(wxDouble a = 1.0, wxDouble b = 0.0, + wxDouble c = 0.0, + wxDouble d = 1.0, + wxDouble tx = 0.0, + wxDouble ty = 0.0) const; + + /** + Creates a native graphics path which is initially empty. + */ + wxGraphicsPath CreatePath() const; + + /** + Creates a native pen from a wxPen. + */ + wxGraphicsPen CreatePen(const wxPen& pen) const; + + /** + Creates a native brush, having a radial gradient originating at (xo,yc) with + color oColour and ends on a circle around (xc,yc) with radius r and color cColour + */ + wxGraphicsBrush CreateRadialGradientBrush(wxDouble xo, + wxDouble yo, + wxDouble xc, + wxDouble yc, + wxDouble radius, + const wxColour& oColor, + const wxColour& cColor) const; + + /** + Draws the bitmap. In case of a mono bitmap, this is treated as a mask and the + current brushed is used for filling. + */ + void DrawBitmap(const wxBitmap& bmp, wxDouble x, wxDouble y, + wxDouble w, wxDouble h); + + /** + Draws an ellipse. + */ + void DrawEllipse(wxDouble x, wxDouble y, wxDouble w, wxDouble h); + + /** + Draws the icon. + */ + void DrawIcon(const wxIcon& icon, wxDouble x, wxDouble y, + wxDouble w, wxDouble h); + + /** + Draws a polygon. + */ + void DrawLines(size_t n, const wxPoint2DDouble* points, + int fillStyle = wxODDEVEN_RULE); + + /** + Draws the path by first filling and then stroking. + */ + void DrawPath(const wxGraphicsPath& path, + int fillStyle = wxODDEVEN_RULE); + + /** + Draws a rectangle. + */ + void DrawRectangle(wxDouble x, wxDouble y, wxDouble w, + wxDouble h); + + /** + Draws a rounded rectangle. + */ + void DrawRoundedRectangle(wxDouble x, wxDouble y, wxDouble w, + wxDouble h, + wxDouble radius); + + //@{ + /** + Draws a text at the defined position, at the given angle. + */ + void DrawText(const wxString& str, wxDouble x, wxDouble y, + wxDouble angle); + void DrawText(const wxString& str, wxDouble x, wxDouble y); + //@} + + /** + Fills the path with the current brush. + */ + void FillPath(const wxGraphicsPath& path, + int fillStyle = wxODDEVEN_RULE); + + /** + Returns the native context (CGContextRef for Core Graphics, Graphics pointer + for GDIPlus and cairo_t pointer for cairo). + */ + void* GetNativeContext(); + + /** + Fills the @a widths array with the widths from the beginning of + @a text to the corresponding character of @e text. + */ + void GetPartialTextExtents(const wxString& text, + wxArrayDouble& widths) const; + + /** + Gets the dimensions of the string using the currently selected font. + @e string is the text string to measure, @e w and @e h are + the total width and height respectively, @a descent is the + dimension from the baseline of the font to the bottom of the + descender, and @a externalLeading is any extra vertical space added + to the font by the font designer (usually is zero). + */ + void GetTextExtent(const wxString& text, wxDouble* width, + wxDouble* height, + wxDouble* descent, + wxDouble* externalLeading) const; + + /** + Gets the current transformation matrix of this context. + */ + wxGraphicsMatrix GetTransform() const; + + /** + Resets the clipping to original shape. + */ + void ResetClip(); + + /** + Rotates the current transformation matrix (radians), + */ + void Rotate(wxDouble angle); + + /** + Scales the current transformation matrix. + */ + void Scale(wxDouble xScale, wxDouble yScale); + + //@{ + /** + Sets the brush for filling paths. + */ + void SetBrush(const wxBrush& brush); + void SetBrush(const wxGraphicsBrush& brush); + //@} + + //@{ + /** + Sets the font for drawing text. + */ + void SetFont(const wxFont& font, const wxColour& colour); + void SetFont(const wxGraphicsFont& font); + //@} + + //@{ + /** + Sets the pen used for stroking. + */ + void SetPen(const wxGraphicsPen& pen); + void SetPen(const wxPen& pen); + //@} + + /** + Sets the current transformation matrix of this context + */ + void SetTransform(const wxGraphicsMatrix& matrix); + + /** + Strokes a single line. + */ + void StrokeLine(wxDouble x1, wxDouble y1, wxDouble x2, + wxDouble y2); + + //@{ + /** + Stroke disconnected lines from begin to end points, fastest method available + for this purpose. + */ + void StrokeLines(size_t n, const wxPoint2DDouble* beginPoints, + const wxPoint2DDouble* endPoints); + void StrokeLines(size_t n, const wxPoint2DDouble* points); + //@} + + /** + Strokes along a path with the current pen. + */ + void StrokePath(const wxGraphicsPath& path); + + /** + Translates the current transformation matrix. + */ + void Translate(wxDouble dx, wxDouble dy); +}; + + + +/** + @class wxGraphicsRenderer + @wxheader{graphics.h} + + A wxGraphicsRenderer is the instance corresponding to the rendering engine + used. There may be multiple instances on a system, if there are different + rendering engines present, but there is always only one instance per engine. + This instance is pointed back to by all objects created by it (wxGraphicsContext, + wxGraphicsPath etc) and can be retrieved through their wxGraphicsObject::GetRenderer() + method. Therefore you can create an additional instance of a path etc. by calling + wxGraphicsObject::GetRenderer() and then using the appropriate CreateXXX function + of that renderer. + + @code + wxGraphicsPath *path = // from somewhere + wxGraphicsBrush *brush = path->GetRenderer()->CreateBrush( *wxBLACK_BRUSH ); + @endcode + + @library{wxcore} + @category{FIXME} +*/ +class wxGraphicsRenderer : public wxObject +{ +public: + /** + Creates a wxGraphicsContext from a wxWindow. + */ + virtual wxGraphicsContext* CreateContext(wxWindow* window) = 0; + + /** + Creates a wxGraphicsContext from a wxWindowDC + */ + virtual wxGraphicsContext * CreateContext( const wxWindowDC& dc) = 0 ; + + /** + Creates a wxGraphicsContext from a wxMemoryDC + */ + virtual wxGraphicsContext * CreateContext( const wxMemoryDC& dc) = 0 ; + + /** + Creates a wxGraphicsContext from a wxPrinterDC + */ + virtual wxGraphicsContext * CreateContext( const wxPrinterDC& dc) = 0 ; + + /** + Creates a native brush from a wxBrush. + */ + wxGraphicsBrush CreateBrush(const wxBrush& brush); + + + /** + Creates a wxGraphicsContext from a native context. This native context must be + eg a CGContextRef for Core Graphics, a Graphics pointer for GDIPlus or a cairo_t + pointer for cairo. + */ + wxGraphicsContext* CreateContextFromNativeContext(void* context); + + /** + Creates a wxGraphicsContext from a native window. + */ + wxGraphicsContext* CreateContextFromNativeWindow(void* window); + + /** + Creates a native graphics font from a wxFont and a text colour. + */ + wxGraphicsFont CreateFont(const wxFont& font, + const wxColour& col = wxBLACK); + + /** + Creates a native brush, having a linear gradient, starting at (x1,y1) with + color c1 to (x2,y2) with color c2 + */ + wxGraphicsBrush CreateLinearGradientBrush(wxDouble x1, + wxDouble y1, + wxDouble x2, + wxDouble y2, + const wxColouramp;c1, + const wxColouramp;c2); + + /** + Creates a native affine transformation matrix from the passed in values. The + defaults result in an identity matrix. + */ + wxGraphicsMatrix CreateMatrix(wxDouble a = 1.0, wxDouble b = 0.0, + wxDouble c = 0.0, + wxDouble d = 1.0, + wxDouble tx = 0.0, + wxDouble ty = 0.0); + + /** + Creates a native graphics path which is initially empty. + */ + wxGraphicsPath CreatePath(); + + /** + Creates a native pen from a wxPen. + */ + wxGraphicsPen CreatePen(const wxPen& pen); + + /** + Creates a native brush, having a radial gradient originating at (xo,yc) with + color oColour and ends on a circle around (xc,yc) with radius r and color cColour + */ + wxGraphicsBrush CreateRadialGradientBrush(wxDouble xo, + wxDouble yo, + wxDouble xc, + wxDouble yc, + wxDouble radius, + const wxColour& oColour, + const wxColour& cColour); + + /** + Returns the default renderer on this platform. On OS X this is the Core + Graphics (a.k.a. Quartz 2D) renderer, on MSW the GDIPlus renderer, and on GTK we currently default to the cairo renderer. + */ + static wxGraphicsRenderer* GetDefaultRenderer(); +}; + + + +/** + @class wxGraphicsBrush + @wxheader{graphics.h} + + + @library{wxcore} + @category{FIXME} +*/ +class wxGraphicsBrush : public wxGraphicsObject +{ +public: + +}; + + + +/** + @class wxGraphicsFont + @wxheader{graphics.h} + + + @library{wxcore} + @category{FIXME} +*/ +class wxGraphicsFont : public wxGraphicsObject +{ +public: + +}; + + + +/** + @class wxGraphicsPen + @wxheader{graphics.h} + + + @library{wxcore} + @category{FIXME} +*/ +class wxGraphicsPen : public wxGraphicsObject +{ +public: + +}; + + + +/** + @class wxGraphicsMatrix + @wxheader{graphics.h} + + A wxGraphicsMatrix is a native representation of an affine matrix. The contents + are specific and private to the respective renderer. Instances are ref counted and can therefore be assigned as usual. The only way to get a valid instance is via a CreateMatrix call on the graphics context or the renderer instance. + + @library{wxcore} + @category{FIXME} +*/ +class wxGraphicsMatrix : public wxGraphicsObject +{ +public: + //@{ + /** + + */ + void Concat(const wxGraphicsMatrix* t); + void Concat(const wxGraphicsMatrix& t); + //@} + + /** + Returns the component values of the matrix via the argument pointers. + */ + void Get(wxDouble* a = NULL, wxDouble* b = NULL, wxDouble* c = NULL, + wxDouble* d = NULL, wxDouble* tx = NULL, + wxDouble* ty = NULL) const; + + /** + Returns the native representation of the matrix. For CoreGraphics this is a + CFAffineMatrix pointer. For GDIPlus a Matrix Pointer and for Cairo a cairo_matrix_t pointer. + */ + void* GetNativeMatrix() const; + + /** + Inverts the matrix. + */ + void Invert(); + + /** + Returns @true if the elements of the transformation matrix are equal. + */ + bool IsEqual(const wxGraphicsMatrix& t) const; + + /** + Return @true if this is the identity matrix. + */ + bool IsIdentity() const; + + /** + Rotates this matrix (radians). + */ + void Rotate(wxDouble angle); + + /** + Scales this matrix. + */ + void Scale(wxDouble xScale, wxDouble yScale); + + /** + Sets the matrix to the respective values (default values are the identity + matrix) + */ + void Set(wxDouble a = 1.0, wxDouble b = 0.0, wxDouble c = 0.0, + wxDouble d = 1.0, wxDouble tx = 0.0, + wxDouble ty = 0.0); + + /** + Applies this matrix to a distance (ie. performs all transforms except + translations) + */ + void TransformDistance(wxDouble* dx, wxDouble* dy) const; + + /** + Applies this matrix to a point. + */ + void TransformPoint(wxDouble* x, wxDouble* y) const; + + /** + Translates this matrix. + */ + void Translate(wxDouble dx, wxDouble dy); +}; + diff --git a/interface/wx/grid.h b/interface/wx/grid.h new file mode 100644 index 0000000000..9d1eeb0ebc --- /dev/null +++ b/interface/wx/grid.h @@ -0,0 +1,2812 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: grid.h +// Purpose: interface of wxGridCellFloatRenderer +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxGridCellFloatRenderer + @wxheader{grid.h} + + This class may be used to format floating point data in a cell. + + @library{wxadv} + @category{FIXME} + + @see wxGridCellRenderer, wxGridCellNumberRenderer, wxGridCellStringRenderer, + wxGridCellBoolRenderer +*/ +class wxGridCellFloatRenderer : public wxGridCellStringRenderer +{ +public: + /** + @param width + Minimum number of characters to be shown. + @param precision + Number of digits after the decimal dot. + */ + wxGridCellFloatRenderer(int width = -1, int precision = -1); + + /** + Returns the precision ( see @ref constr() wxGridCellFloatRenderer ). + */ + int GetPrecision() const; + + /** + Returns the width ( see @ref constr() wxGridCellFloatRenderer ). + */ + int GetWidth() const; + + /** + Parameters string format is "width[,precision]". + */ + void SetParameters(const wxString& params); + + /** + Sets the precision ( see @ref constr() wxGridCellFloatRenderer ). + */ + void SetPrecision(int precision); + + /** + Sets the width ( see @ref constr() wxGridCellFloatRenderer ) + */ + void SetWidth(int width); +}; + + + +/** + @class wxGridTableBase + @wxheader{grid.h} + + Grid table classes. + + @library{wxadv} + @category{FIXME} +*/ +class wxGridTableBase : public wxObject +{ +public: + /** + + */ + wxGridTableBase(); + + /** + + */ + ~wxGridTableBase(); + + /** + + */ + bool AppendCols(size_t numCols = 1); + + /** + + */ + bool AppendRows(size_t numRows = 1); + + /** + + */ + bool CanGetValueAs(int row, int col, const wxString& typeName); + + /** + Does this table allow attributes? Default implementation creates + a wxGridCellAttrProvider if necessary. + */ + bool CanHaveAttributes(); + + /** + + */ + bool CanSetValueAs(int row, int col, const wxString& typeName); + + /** + + */ + void Clear(); + + /** + + */ + bool DeleteCols(size_t pos = 0, size_t numCols = 1); + + /** + + */ + bool DeleteRows(size_t pos = 0, size_t numRows = 1); + + /** + by default forwarded to wxGridCellAttrProvider if any. May be + overridden to handle attributes directly in the table. + */ + wxGridCellAttr* GetAttr(int row, int col); + + /** + get the currently used attr provider (may be @NULL) + */ + wxGridCellAttrProvider* GetAttrProvider() const; + + /** + + */ + wxString GetColLabelValue(int col); + + /** + + */ + int GetNumberCols(); + + /** + You must override these functions in a derived table class. + */ + int GetNumberRows(); + + /** + + */ + wxString GetRowLabelValue(int row); + + /** + Data type determination and value access. + */ + wxString GetTypeName(int row, int col); + + /** + + */ + wxString GetValue(int row, int col); + + /** + + */ + bool GetValueAsBool(int row, int col); + + /** + For user defined types + */ + void* GetValueAsCustom(int row, int col, + const wxString& typeName); + + /** + + */ + double GetValueAsDouble(int row, int col); + + /** + + */ + long GetValueAsLong(int row, int col); + + /** + + */ + wxGrid* GetView() const; + + /** + + */ + bool InsertCols(size_t pos = 0, size_t numCols = 1); + + /** + + */ + bool InsertRows(size_t pos = 0, size_t numRows = 1); + + /** + + */ + bool IsEmptyCell(int row, int col); + + /** + these functions take ownership of the pointer + */ + void SetAttr(wxGridCellAttr* attr, int row, int col); + + /** + Attribute handling + give us the attr provider to use - we take ownership of the pointer + */ + void SetAttrProvider(wxGridCellAttrProvider* attrProvider); + + /** + + */ + void SetColAttr(wxGridCellAttr* attr, int col); + + /** + , @e wxString) + */ + void SetColLabelValue() const; + + /** + + */ + void SetRowAttr(wxGridCellAttr* attr, int row); + + /** + , @e wxString) + */ + void SetRowLabelValue() const; + + /** + + */ + void SetValue(int row, int col, const wxString& value); + + /** + + */ + void SetValueAsBool(int row, int col, bool value); + + /** + + */ + void SetValueAsCustom(int row, int col, const wxString& typeName, + void* value); + + /** + + */ + void SetValueAsDouble(int row, int col, double value); + + /** + + */ + void SetValueAsLong(int row, int col, long value); + + /** + Overriding these is optional + */ + void SetView(wxGrid* grid); + + /** + + */ + void UpdateAttrCols(size_t pos, int numCols); + + /** + change row/col number in attribute if needed + */ + void UpdateAttrRows(size_t pos, int numRows); +}; + + + +/** + @class wxGridCellEditor + @wxheader{grid.h} + + This class is responsible for providing and manipulating + the in-place edit controls for the grid. Instances of wxGridCellEditor + (actually, instances of derived classes since it is an abstract class) can be + associated with the cell attributes for individual cells, rows, columns, or + even for the entire grid. + + @library{wxadv} + @category{FIXME} + + @see wxGridCellTextEditor, wxGridCellFloatEditor, wxGridCellBoolEditor, + wxGridCellNumberEditor, wxGridCellChoiceEditor +*/ +class wxGridCellEditor +{ +public: + /** + + */ + wxGridCellEditor(); + + /** + The dtor is private because only DecRef() can delete us. + */ + ~wxGridCellEditor(); + + /** + Fetch the value from the table and prepare the edit control + to begin editing. Set the focus to the edit control. + */ + void BeginEdit(int row, int col, wxGrid* grid); + + /** + Create a new object which is the copy of this one. + */ + wxGridCellEditor* Clone() const; + + /** + Creates the actual edit control. + */ + void Create(wxWindow* parent, wxWindowID id, + wxEvtHandler* evtHandler); + + /** + Final cleanup. + */ + void Destroy(); + + /** + Complete the editing of the current cell. Returns @true if the value has + changed. If necessary, the control may be destroyed. + */ + bool EndEdit(int row, int col, wxGrid* grid); + + /** + Some types of controls on some platforms may need some help + with the Return key. + */ + void HandleReturn(wxKeyEvent& event); + + /** + + */ + bool IsCreated(); + + /** + Draws the part of the cell not occupied by the control: the base class + version just fills it with background colour from the attribute. + */ + void PaintBackground(const wxRect& rectCell, + wxGridCellAttr* attr); + + /** + Reset the value in the control back to its starting value. + */ + void Reset(); + + /** + Size and position the edit control. + */ + void SetSize(const wxRect& rect); + + /** + Show or hide the edit control, use the specified attributes to set + colours/fonts for it. + */ + void Show(bool show, wxGridCellAttr* attr = NULL); + + /** + If the editor is enabled by clicking on the cell, this method will be + called. + */ + void StartingClick(); + + /** + If the editor is enabled by pressing keys on the grid, + this will be called to let the editor do something about + that first key if desired. + */ + void StartingKey(wxKeyEvent& event); +}; + + + +/** + @class wxGridCellTextEditor + @wxheader{grid.h} + + The editor for string/text data. + + @library{wxadv} + @category{FIXME} + + @see wxGridCellEditor, wxGridCellFloatEditor, wxGridCellBoolEditor, + wxGridCellNumberEditor, wxGridCellChoiceEditor +*/ +class wxGridCellTextEditor : public wxGridCellEditor +{ +public: + /** + Default constructor. + */ + wxGridCellTextEditor(); + + /** + The parameters string format is "n" where n is a number representing the + maximum width. + */ + void SetParameters(const wxString& params); +}; + + + +/** + @class wxGridCellStringRenderer + @wxheader{grid.h} + + This class may be used to format string data in a cell; it is the default + for string cells. + + @library{wxadv} + @category{FIXME} + + @see wxGridCellRenderer, wxGridCellNumberRenderer, wxGridCellFloatRenderer, + wxGridCellBoolRenderer +*/ +class wxGridCellStringRenderer : public wxGridCellRenderer +{ +public: + /** + Default constructor + */ + wxGridCellStringRenderer(); +}; + + + +/** + @class wxGridCellChoiceEditor + @wxheader{grid.h} + + The editor for string data allowing to choose from a list of strings. + + @library{wxadv} + @category{FIXME} + + @see wxGridCellEditor, wxGridCellFloatEditor, wxGridCellBoolEditor, + wxGridCellTextEditor, wxGridCellNumberEditor +*/ +class wxGridCellChoiceEditor : public wxGridCellEditor +{ +public: + //@{ + /** + @param count + Number of strings from which the user can choose. + @param choices + An array of strings from which the user can choose. + @param allowOthers + If allowOthers is @true, the user can type a string not in choices array. + */ + wxGridCellChoiceEditor(size_t count = 0, + const wxString choices[] = NULL, + bool allowOthers = false); + wxGridCellChoiceEditor(const wxArrayString& choices, + bool allowOthers = false); + //@} + + /** + Parameters string format is "item1[,item2[...,itemN]]" + */ + void SetParameters(const wxString& params); +}; + + + +/** + @class wxGridEditorCreatedEvent + @wxheader{grid.h} + + + @library{wxadv} + @category{FIXME} +*/ +class wxGridEditorCreatedEvent : public wxCommandEvent +{ +public: + //@{ + /** + + */ + wxGridEditorCreatedEvent(); + wxGridEditorCreatedEvent(int id, wxEventType type, + wxObject* obj, + int row, + int col, + wxControl* ctrl); + //@} + + /** + Returns the column at which the event occurred. + */ + int GetCol(); + + /** + Returns the edit control. + */ + wxControl* GetControl(); + + /** + Returns the row at which the event occurred. + */ + int GetRow(); + + /** + Sets the column at which the event occurred. + */ + void SetCol(int col); + + /** + Sets the edit control. + */ + void SetControl(wxControl* ctrl); + + /** + Sets the row at which the event occurred. + */ + void SetRow(int row); +}; + + + +/** + @class wxGridRangeSelectEvent + @wxheader{grid.h} + + + @library{wxadv} + @category{FIXME} +*/ +class wxGridRangeSelectEvent : public wxNotifyEvent +{ +public: + //@{ + /** + + */ + wxGridRangeSelectEvent(); + wxGridRangeSelectEvent(int id, wxEventType type, + wxObject* obj, + const wxGridCellCoords& topLeft, + const wxGridCellCoords& bottomRight, + bool sel = true, + bool control = false, + bool shift = false, + bool alt = false, + bool meta = false); + //@} + + /** + Returns @true if the Alt key was down at the time of the event. + */ + bool AltDown(); + + /** + Returns @true if the Control key was down at the time of the event. + */ + bool ControlDown(); + + /** + Top left corner of the rectangular area that was (de)selected. + */ + wxGridCellCoords GetBottomRightCoords(); + + /** + Bottom row of the rectangular area that was (de)selected. + */ + int GetBottomRow(); + + /** + Left column of the rectangular area that was (de)selected. + */ + int GetLeftCol(); + + /** + Right column of the rectangular area that was (de)selected. + */ + int GetRightCol(); + + /** + Top left corner of the rectangular area that was (de)selected. + */ + wxGridCellCoords GetTopLeftCoords(); + + /** + Top row of the rectangular area that was (de)selected. + */ + int GetTopRow(); + + /** + Returns @true if the Meta key was down at the time of the event. + */ + bool MetaDown(); + + /** + Returns @true if the area was selected, @false otherwise. + */ + bool Selecting(); + + /** + Returns @true if the Shift key was down at the time of the event. + */ + bool ShiftDown(); +}; + + + +/** + @class wxGridCellRenderer + @wxheader{grid.h} + + This class is responsible for actually drawing the cell + in the grid. You may pass it to the wxGridCellAttr (below) to change the + format of one given cell or to wxGrid::SetDefaultRenderer() to change the + view of all cells. This is an abstract class, and you will normally use one of + the + predefined derived classes or derive your own class from it. + + @library{wxadv} + @category{FIXME} + + @see wxGridCellStringRenderer, wxGridCellNumberRenderer, + wxGridCellFloatRenderer, wxGridCellBoolRenderer +*/ +class wxGridCellRenderer +{ +public: + /** + + */ + wxGridCellRenderer* Clone() const; + + /** + Draw the given cell on the provided DC inside the given rectangle + using the style specified by the attribute and the default or selected + state corresponding to the isSelected value. + This pure virtual function has a default implementation which will + prepare the DC using the given attribute: it will draw the rectangle + with the background colour from attr and set the text colour and font. + */ + void Draw(wxGrid& grid, wxGridCellAttr& attr, wxDC& dc, + const wxRect& rect, int row, int col, + bool isSelected); + + /** + Get the preferred size of the cell for its contents. + */ + wxSize GetBestSize(wxGrid& grid, wxGridCellAttr& attr, wxDC& dc, + int row, int col); +}; + + + +/** + @class wxGridCellNumberEditor + @wxheader{grid.h} + + The editor for numeric integer data. + + @library{wxadv} + @category{FIXME} + + @see wxGridCellEditor, wxGridCellFloatEditor, wxGridCellBoolEditor, + wxGridCellTextEditor, wxGridCellChoiceEditor +*/ +class wxGridCellNumberEditor : public wxGridCellTextEditor +{ +public: + /** + Allows to specify the range for acceptable data; + if min == max == -1, no range checking is done + */ + wxGridCellNumberEditor(int min = -1, int max = -1); + + /** + String representation of the value. + */ + wxString GetString() const; + + /** + If the return value is @true, the editor uses a wxSpinCtrl to get user input, + otherwise it uses a wxTextCtrl. + */ + bool HasRange() const; + + /** + Parameters string format is "min,max". + */ + void SetParameters(const wxString& params); +}; + + + +/** + @class wxGridSizeEvent + @wxheader{grid.h} + + This event class contains information about a row/column resize event. + + @library{wxadv} + @category{FIXME} +*/ +class wxGridSizeEvent : public wxNotifyEvent +{ +public: + //@{ + /** + + */ + wxGridSizeEvent(); + wxGridSizeEvent(int id, wxEventType type, wxObject* obj, + int rowOrCol = -1, + int x = -1, + int y = -1, + bool control = false, + bool shift = false, + bool alt = false, + bool meta = false); + //@} + + /** + Returns @true if the Alt key was down at the time of the event. + */ + bool AltDown(); + + /** + Returns @true if the Control key was down at the time of the event. + */ + bool ControlDown(); + + /** + Position in pixels at which the event occurred. + */ + wxPoint GetPosition(); + + /** + Row or column at that was resized. + */ + int GetRowOrCol(); + + /** + Returns @true if the Meta key was down at the time of the event. + */ + bool MetaDown(); + + /** + Returns @true if the Shift key was down at the time of the event. + */ + bool ShiftDown(); +}; + + + +/** + @class wxGridCellNumberRenderer + @wxheader{grid.h} + + This class may be used to format integer data in a cell. + + @library{wxadv} + @category{FIXME} + + @see wxGridCellRenderer, wxGridCellStringRenderer, wxGridCellFloatRenderer, + wxGridCellBoolRenderer +*/ +class wxGridCellNumberRenderer : public wxGridCellStringRenderer +{ +public: + /** + Default constructor + */ + wxGridCellNumberRenderer(); +}; + + + +/** + @class wxGridCellAttr + @wxheader{grid.h} + + This class can be used to alter the cells' appearance in + the grid by changing their colour/font/... from default. An object of this + class may be returned by wxGridTableBase::GetAttr. + + @library{wxadv} + @category{FIXME} +*/ +class wxGridCellAttr +{ +public: + //@{ + /** + Constructor specifying some of the often used attributes. + */ + wxGridCellAttr(); + wxGridCellAttr(const wxColour& colText, + const wxColour& colBack, + const wxFont& font, + int hAlign, int vAlign); + //@} + + /** + Creates a new copy of this object. + */ + wxGridCellAttr* Clone() const; + + /** + + */ + void DecRef(); + + /** + See SetAlignment() for the returned values. + */ + void GetAlignment(int* hAlign, int* vAlign) const; + + /** + + */ + const wxColour GetBackgroundColour() const; + + /** + + */ + wxGridCellEditor* GetEditor(wxGrid* grid, int row, int col) const; + + /** + + */ + const wxFont GetFont() const; + + /** + + */ + wxGridCellRenderer* GetRenderer(wxGrid* grid, int row, int col) const; + + /** + + */ + const wxColour GetTextColour() const; + + /** + + */ + bool HasAlignment() const; + + /** + + */ + bool HasBackgroundColour() const; + + /** + + */ + bool HasEditor() const; + + /** + + */ + bool HasFont() const; + + /** + + */ + bool HasRenderer() const; + + /** + accessors + */ + bool HasTextColour() const; + + /** + This class is ref counted: it is created with ref count of 1, so + calling DecRef() once will delete it. Calling IncRef() allows to lock + it until the matching DecRef() is called + */ + void IncRef(); + + /** + + */ + bool IsReadOnly() const; + + /** + Sets the alignment. @a hAlign can be one of @c wxALIGN_LEFT, + @c wxALIGN_CENTRE or @c wxALIGN_RIGHT and @a vAlign can be one + of @c wxALIGN_TOP, @c wxALIGN_CENTRE or @c wxALIGN_BOTTOM. + */ + void SetAlignment(int hAlign, int vAlign); + + /** + Sets the background colour. + */ + void SetBackgroundColour(const wxColour& colBack); + + /** + + */ + void SetDefAttr(wxGridCellAttr* defAttr); + + /** + + */ + void SetEditor(wxGridCellEditor* editor); + + /** + Sets the font. + */ + void SetFont(const wxFont& font); + + /** + + */ + void SetReadOnly(bool isReadOnly = true); + + /** + takes ownership of the pointer + */ + void SetRenderer(wxGridCellRenderer* renderer); + + /** + Sets the text colour. + */ + void SetTextColour(const wxColour& colText); +}; + + + +/** + @class wxGridCellBoolRenderer + @wxheader{grid.h} + + This class may be used to format boolean data in a cell. + for string cells. + + @library{wxadv} + @category{FIXME} + + @see wxGridCellRenderer, wxGridCellStringRenderer, wxGridCellFloatRenderer, + wxGridCellNumberRenderer +*/ +class wxGridCellBoolRenderer : public wxGridCellRenderer +{ +public: + /** + Default constructor + */ + wxGridCellBoolRenderer(); +}; + + + +/** + @class wxGridEvent + @wxheader{grid.h} + + This event class contains information about various grid events. + + @library{wxadv} + @category{FIXME} +*/ +class wxGridEvent : public wxNotifyEvent +{ +public: + //@{ + /** + + */ + wxGridEvent(); + wxGridEvent(int id, wxEventType type, wxObject* obj, + int row = -1, int col = -1, + int x = -1, int y = -1, + bool sel = true, + bool control = false, + bool shift = false, + bool alt = false, + bool meta = false); + //@} + + /** + Returns @true if the Alt key was down at the time of the event. + */ + bool AltDown(); + + /** + Returns @true if the Control key was down at the time of the event. + */ + bool ControlDown(); + + /** + Column at which the event occurred. + */ + int GetCol(); + + /** + Position in pixels at which the event occurred. + */ + wxPoint GetPosition(); + + /** + Row at which the event occurred. + */ + int GetRow(); + + /** + Returns @true if the Meta key was down at the time of the event. + */ + bool MetaDown(); + + /** + Returns @true if the user is selecting grid cells, @false -- if + deselecting. + */ + bool Selecting(); + + /** + Returns @true if the Shift key was down at the time of the event. + */ + bool ShiftDown(); +}; + + + +/** + @class wxGridCellFloatEditor + @wxheader{grid.h} + + The editor for floating point numbers data. + + @library{wxadv} + @category{FIXME} + + @see wxGridCellEditor, wxGridCellNumberEditor, wxGridCellBoolEditor, + wxGridCellTextEditor, wxGridCellChoiceEditor +*/ +class wxGridCellFloatEditor : public wxGridCellTextEditor +{ +public: + /** + @param width + Minimum number of characters to be shown. + @param precision + Number of digits after the decimal dot. + */ + wxGridCellFloatEditor(int width = -1, int precision = -1); + + /** + Parameters string format is "width,precision" + */ + void SetParameters(const wxString& params); +}; + + + +/** + @class wxGrid + @wxheader{grid.h} + + wxGrid and its related classes are used for displaying and editing tabular + data. They provide a rich set of features for display, editing, and + interacting with a variety of data sources. For simple applications, and to + help you get started, wxGrid is the only class you need to refer to + directly. It will set up default instances of the other classes and manage + them for you. For more complex applications you can derive your own + classes for custom grid views, grid data tables, cell editors and + renderers. The @ref overview_gridoverview has + examples of simple and more complex applications, explains the + relationship between the various grid classes and has a summary of the + keyboard shortcuts and mouse functions provided by wxGrid. + + wxGrid has been greatly expanded and redesigned for wxWidgets 2.2 + onwards. The new grid classes are reasonably backward-compatible + but there are some exceptions. There are also easier ways of doing many things + compared to + the previous implementation. + + A wxGridTableBase class holds the actual + data to be displayed by a wxGrid class. One or more wxGrid classes + may act as a view for one table class. + The default table class is called wxGridStringTable and + holds an array of strings. An instance of such a class is created + by wxGrid::CreateGrid. + + wxGridCellRenderer is the abstract base + class for rendereing contents in a cell. The following renderers are + predefined: + wxGridCellStringRenderer, + wxGridCellBoolRenderer, + wxGridCellFloatRenderer, + wxGridCellNumberRenderer. The + look of a cell can be further defined using wxGridCellAttr. + An object of this type may be returned by wxGridTableBase::GetAttr. + + wxGridCellEditor is the abstract base + class for editing the value of a cell. The following editors are + predefined: + wxGridCellTextEditor + wxGridCellBoolEditor + wxGridCellChoiceEditor + wxGridCellNumberEditor. + + @library{wxadv} + @category{miscwnd} + + @see @ref overview_gridoverview "wxGrid overview" +*/ +class wxGrid : public wxScrolledWindow +{ +public: + //@{ + /** + Constructor to create a grid object. Call either CreateGrid() or + SetTable() directly after this to initialize the grid before using + it. + */ + wxGrid(); + wxGrid(wxWindow* parent, wxWindowID id, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxWANTS_CHARS, + const wxString& name = wxPanelNameStr); + //@} + + /** + Destructor. This will also destroy the associated grid table unless you passed + a table + object to the grid and specified that the grid should not take ownership of the + table (see wxGrid::SetTable). + */ + ~wxGrid(); + + /** + Appends one or more new columns to the right of the grid and returns @true if + successful. The updateLabels argument is not used at present. + If you are using a derived grid table class you will need to override + wxGridTableBase::AppendCols. See + InsertCols() for further information. + */ + bool AppendCols(int numCols = 1, bool updateLabels = true); + + /** + Appends one or more new rows to the bottom of the grid and returns @true if + successful. The updateLabels argument is not used at present. + If you are using a derived grid table class you will need to override + wxGridTableBase::AppendRows. See + InsertRows() for further information. + */ + bool AppendRows(int numRows = 1, bool updateLabels = true); + + /** + Automatically sets the height and width of all rows and columns to fit their + contents. + */ + void AutoSize(); + + /** + Automatically adjusts width of the column to fit its label. + */ + void AutoSizeColLabelSize(int col); + + /** + Automatically sizes the column to fit its contents. If setAsMin is @true the + calculated width will + also be set as the minimal width for the column. + */ + void AutoSizeColumn(int col, bool setAsMin = true); + + /** + Automatically sizes all columns to fit their contents. If setAsMin is @true the + calculated widths will + also be set as the minimal widths for the columns. + */ + void AutoSizeColumns(bool setAsMin = true); + + /** + Automatically sizes the row to fit its contents. If setAsMin is @true the + calculated height will + also be set as the minimal height for the row. + */ + void AutoSizeRow(int row, bool setAsMin = true); + + /** + Automatically adjusts height of the row to fit its label. + */ + void AutoSizeRowLabelSize(int col); + + /** + Automatically sizes all rows to fit their contents. If setAsMin is @true the + calculated heights will + also be set as the minimal heights for the rows. + */ + void AutoSizeRows(bool setAsMin = true); + + /** + AutoSizeColumn() + + AutoSizeRow() + + AutoSizeColumns() + + AutoSizeRows() + + AutoSize() + + SetColMinimalWidth() + + SetRowMinimalHeight() + + SetColMinimalAcceptableWidth() + + SetRowMinimalAcceptableHeight() + + GetColMinimalAcceptableWidth() + + GetRowMinimalAcceptableHeight() + */ + + + /** + Increments the grid's batch count. When the count is greater than zero + repainting of + the grid is suppressed. Each call to BeginBatch must be matched by a later call + to + EndBatch(). Code that does a lot of grid + modification can be enclosed between BeginBatch and EndBatch calls to avoid + screen flicker. The final EndBatch will cause the grid to be repainted. + + @see wxGridUpdateLocker + */ + void BeginBatch(); + + /** + This function returns the rectangle that encloses the block of cells + limited by TopLeft and BottomRight cell in device coords and clipped + to the client size of the grid window. + */ + wxRect BlockToDeviceRect(const wxGridCellCoords& topLeft, + const wxGridCellCoords& bottomRight) const; + + /** + Returns @true if columns can be moved by dragging with the mouse. Columns can be + moved + by dragging on their labels. + */ + bool CanDragColMove() const; + + /** + Returns @true if columns can be resized by dragging with the mouse. Columns can + be resized + by dragging the edges of their labels. If grid line dragging is enabled they + can also be + resized by dragging the right edge of the column in the grid cell area + (see wxGrid::EnableDragGridSize). + */ + bool CanDragColSize() const; + + /** + Return @true if the dragging of grid lines to resize rows and columns is enabled + or @false otherwise. + */ + bool CanDragGridSize() const; + + /** + Returns @true if rows can be resized by dragging with the mouse. Rows can be + resized + by dragging the edges of their labels. If grid line dragging is enabled they + can also be + resized by dragging the lower edge of the row in the grid cell area + (see wxGrid::EnableDragGridSize). + */ + bool CanDragRowSize() const; + + /** + Returns @true if the in-place edit control for the current grid cell can be used + and + @false otherwise (e.g. if the current cell is read-only). + */ + bool CanEnableCellControl() const; + + /** + Do we have some place to store attributes in? + */ + bool CanHaveAttributes() const; + + /** + EnableDragRowSize() + + EnableDragColSize() + + CanDragRowSize() + + CanDragColSize() + + EnableDragColMove() + + CanDragColMove() + + EnableDragGridSize() + + CanDragGridSize() + + GetColAt() + + SetColPos() + + GetColPos() + + EnableDragCell() + + CanDragCell() + */ + + + //@{ + /** + Return the rectangle corresponding to the grid cell's size and position in + logical + coordinates. + */ + wxRect CellToRect(int row, int col) const; + const wxRect CellToRect(const wxGridCellCoords& coords) const; + //@} + + /** + Clears all data in the underlying grid table and repaints the grid. The table + is not deleted by + this function. If you are using a derived table class then you need to override + wxGridTableBase::Clear for this function to have any effect. + */ + void ClearGrid(); + + /** + Deselects all cells that are currently selected. + */ + void ClearSelection(); + + /** + @ref ctor() wxGrid + + @ref dtor() ~wxGrid + + CreateGrid() + + SetTable() + */ + + + /** + Creates a grid with the specified initial number of rows and columns. + Call this directly after the grid constructor. When you use this + function wxGrid will create and manage a simple table of string values + for you. All of the grid data will be stored in memory. + For applications with more complex data types or relationships, or for + dealing with very large datasets, you should derive your own grid table + class and pass a table object to the grid with SetTable(). + */ + bool CreateGrid(int numRows, int numCols, + wxGrid::wxGridSelectionModes selmode = wxGrid::wxGridSelectCells); + + /** + MoveCursorUp() + + MoveCursorDown() + + MoveCursorLeft() + + MoveCursorRight() + + MoveCursorPageUp() + + MoveCursorPageDown() + + MoveCursorUpBlock() + + MoveCursorDownBlock() + + MoveCursorLeftBlock() + + MoveCursorRightBlock() + */ + + + /** + Deletes one or more columns from a grid starting at the specified position and + returns + @true if successful. The updateLabels argument is not used at present. + If you are using a derived grid table class you will need to override + wxGridTableBase::DeleteCols. See + InsertCols() for further information. + */ + bool DeleteCols(int pos = 0, int numCols = 1, + bool updateLabels = true); + + /** + Deletes one or more rows from a grid starting at the specified position and + returns + @true if successful. The updateLabels argument is not used at present. + If you are using a derived grid table class you will need to override + wxGridTableBase::DeleteRows. See + InsertRows() for further information. + */ + bool DeleteRows(int pos = 0, int numRows = 1, + bool updateLabels = true); + + /** + Disables in-place editing of grid cells. + Equivalent to calling EnableCellEditControl(@false). + */ + void DisableCellEditControl(); + + /** + Disables column moving by dragging with the mouse. Equivalent to passing @false + to + EnableDragColMove(). + */ + void DisableDragColMove(); + + /** + Disables column sizing by dragging with the mouse. Equivalent to passing @false + to + EnableDragColSize(). + */ + void DisableDragColSize(); + + /** + Disable mouse dragging of grid lines to resize rows and columns. Equivalent to + passing + @false to EnableDragGridSize() + */ + void DisableDragGridSize(); + + /** + Disables row sizing by dragging with the mouse. Equivalent to passing @false to + EnableDragRowSize(). + */ + void DisableDragRowSize(); + + /** + Enables or disables in-place editing of grid cell data. The grid will issue + either a + wxEVT_GRID_EDITOR_SHOWN or wxEVT_GRID_EDITOR_HIDDEN event. + */ + void EnableCellEditControl(bool enable = true); + + /** + Enables or disables column moving by dragging with the mouse. + */ + void EnableDragColMove(bool enable = true); + + /** + Enables or disables column sizing by dragging with the mouse. + */ + void EnableDragColSize(bool enable = true); + + /** + Enables or disables row and column resizing by dragging gridlines with the + mouse. + */ + void EnableDragGridSize(bool enable = true); + + /** + Enables or disables row sizing by dragging with the mouse. + */ + void EnableDragRowSize(bool enable = true); + + /** + If the edit argument is @false this function sets the whole grid as read-only. + If the + argument is @true the grid is set to the default state where cells may be + editable. In the + default state you can set single grid cells and whole rows and columns to be + editable or + read-only via + wxGridCellAttribute::SetReadOnly. For single + cells you can also use the shortcut function + SetReadOnly(). + For more information about controlling grid cell attributes see the + wxGridCellAttr cell attribute class and the + @ref overview_gridoverview. + */ + void EnableEditing(bool edit); + + /** + Turns the drawing of grid lines on or off. + */ + void EnableGridLines(bool enable = true); + + /** + Decrements the grid's batch count. When the count is greater than zero + repainting of + the grid is suppressed. Each previous call to + BeginBatch() must be matched by a later call to + EndBatch. Code that does a lot of grid modification can be enclosed between + BeginBatch and EndBatch calls to avoid screen flicker. The final EndBatch will + cause the grid to be repainted. + + @see wxGridUpdateLocker + */ + void EndBatch(); + + /** + Overridden wxWindow method. + */ + void Fit(); + + /** + Causes immediate repainting of the grid. Use this instead of the usual + wxWindow::Refresh. + */ + void ForceRefresh(); + + /** + Returns the number of times that BeginBatch() has been called + without (yet) matching calls to EndBatch(). While + the grid's batch count is greater than zero the display will not be updated. + */ + int GetBatchCount() const; + + /** + Sets the arguments to the horizontal and vertical text alignment values for the + grid cell at the specified location. + Horizontal alignment will be one of wxALIGN_LEFT, wxALIGN_CENTRE or + wxALIGN_RIGHT. + + Vertical alignment will be one of wxALIGN_TOP, wxALIGN_CENTRE or wxALIGN_BOTTOM. + */ + void GetCellAlignment(int row, int col, int* horiz, int* vert) const; + + /** + Returns the background colour of the cell at the specified location. + */ + wxColour GetCellBackgroundColour(int row, int col) const; + + /** + Returns a pointer to the editor for the cell at the specified location. + See wxGridCellEditor and + the @ref overview_gridoverview "wxGrid overview" for more information about + cell editors and renderers. + */ + wxGridCellEditor* GetCellEditor(int row, int col) const; + + /** + Returns the font for text in the grid cell at the specified location. + */ + wxFont GetCellFont(int row, int col) const; + + /** + Returns a pointer to the renderer for the grid cell at the specified location. + See wxGridCellRenderer and + the @ref overview_gridoverview "wxGrid overview" for more information about + cell editors and renderers. + */ + wxGridCellRenderer* GetCellRenderer(int row, int col) const; + + /** + Returns the text colour for the grid cell at the specified location. + */ + wxColour GetCellTextColour(int row, int col) const; + + //@{ + /** + Returns the string contained in the cell at the specified location. For simple + applications where a + grid object automatically uses a default grid table of string values you use + this function together + with SetCellValue() to access cell values. + For more complex applications where you have derived your own grid table class + that contains + various data types (e.g. numeric, boolean or user-defined custom types) then + you only use this + function for those cells that contain string values. + See wxGridTableBase::CanGetValueAs + and the @ref overview_gridoverview "wxGrid overview" for more information. + */ + wxString GetCellValue(int row, int col) const; + const wxString GetCellValue(const wxGridCellCoords& coords) const; + //@} + + /** + Returns the column ID of the specified column position. + */ + int GetColAt(int colPos) const; + + /** + Returns the pen used for vertical grid lines. This virtual function may be + overridden in derived classes in order to change the appearance of individual + grid lines for the given column @e col. + See GetRowGridLinePen() for an example. + */ + wxPen GetColGridLinePen(int col); + + /** + Sets the arguments to the current column label alignment values. + Horizontal alignment will be one of wxALIGN_LEFT, wxALIGN_CENTRE or + wxALIGN_RIGHT. + + Vertical alignment will be one of wxALIGN_TOP, wxALIGN_CENTRE or wxALIGN_BOTTOM. + */ + void GetColLabelAlignment(int* horiz, int* vert) const; + + /** + Returns the current height of the column labels. + */ + int GetColLabelSize() const; + + /** + Returns the specified column label. The default grid table class provides + column labels of + the form A,B...Z,AA,AB...ZZ,AAA... If you are using a custom grid table you can + override + wxGridTableBase::GetColLabelValue to provide + your own labels. + */ + wxString GetColLabelValue(int col) const; + + /** + + */ + int GetColLeft(int col) const; + + /** + This returns the value of the lowest column width that can be handled + correctly. See + member SetColMinimalAcceptableWidth() for details. + */ + int GetColMinimalAcceptableWidth() const; + + /** + Get the minimal width of the given column/row. + */ + int GetColMinimalWidth(int col) const; + + /** + Returns the position of the specified column. + */ + int GetColPos(int colID) const; + + /** + + */ + int GetColRight(int col) const; + + /** + Returns the width of the specified column. + */ + int GetColSize(int col) const; + + /** + Sets the arguments to the current default horizontal and vertical text alignment + values. + Horizontal alignment will be one of wxALIGN_LEFT, wxALIGN_CENTRE or + wxALIGN_RIGHT. + + Vertical alignment will be one of wxALIGN_TOP, wxALIGN_CENTRE or wxALIGN_BOTTOM. + */ + void GetDefaultCellAlignment(int* horiz, int* vert) const; + + /** + Returns the current default background colour for grid cells. + */ + wxColour GetDefaultCellBackgroundColour() const; + + /** + Returns the current default font for grid cell text. + */ + wxFont GetDefaultCellFont() const; + + /** + Returns the current default colour for grid cell text. + */ + wxColour GetDefaultCellTextColour() const; + + /** + Returns the default height for column labels. + */ + int GetDefaultColLabelSize() const; + + /** + Returns the current default width for grid columns. + */ + int GetDefaultColSize() const; + + /** + Returns a pointer to the current default grid cell editor. + See wxGridCellEditor and + the @ref overview_gridoverview "wxGrid overview" for more information about + cell editors and renderers. + */ + wxGridCellEditor* GetDefaultEditor() const; + + //@{ + /** + + */ + wxGridCellEditor* GetDefaultEditorForCell(int row, int col) const; + const wxGridCellEditor* GetDefaultEditorForCell(const wxGridCellCoords& c) const; + //@} + + /** + + */ + wxGridCellEditor* GetDefaultEditorForType(const wxString& typeName) const; + + /** + Returns the pen used for grid lines. This virtual function may be overridden in + derived classes in order to change the appearance of grid lines. Note that + currently the pen width must be 1. + + @see GetColGridLinePen(), GetRowGridLinePen() + */ + wxPen GetDefaultGridLinePen(); + + /** + Returns a pointer to the current default grid cell renderer. + See wxGridCellRenderer and + the @ref overview_gridoverview "wxGrid overview" for more information about + cell editors and renderers. + */ + wxGridCellRenderer* GetDefaultRenderer() const; + + /** + + */ + wxGridCellRenderer* GetDefaultRendererForCell(int row, int col) const; + + /** + + */ + wxGridCellRenderer* GetDefaultRendererForType(const wxString& typeName) const; + + /** + Returns the default width for the row labels. + */ + int GetDefaultRowLabelSize() const; + + /** + Returns the current default height for grid rows. + */ + int GetDefaultRowSize() const; + + /** + Returns the current grid cell column position. + */ + int GetGridCursorCol() const; + + /** + Returns the current grid cell row position. + */ + int GetGridCursorRow() const; + + /** + Returns the colour used for grid lines. + + @see GetDefaultGridLinePen() + */ + wxColour GetGridLineColour() const; + + /** + Returns the colour used for the background of row and column labels. + */ + wxColour GetLabelBackgroundColour() const; + + /** + Returns the font used for row and column labels. + */ + wxFont GetLabelFont() const; + + /** + Returns the colour used for row and column label text. + */ + wxColour GetLabelTextColour() const; + + /** + Returns the total number of grid columns (actually the number of columns in the + underlying grid + table). + */ + int GetNumberCols() const; + + /** + Returns the total number of grid rows (actually the number of rows in the + underlying grid table). + */ + int GetNumberRows() const; + + /** + + */ + wxGridCellAttr* GetOrCreateCellAttr(int row, int col) const; + + /** + Returns the pen used for horizontal grid lines. This virtual function may be + overridden in derived classes in order to change the appearance of individual + grid line for the given row @e row. + Example: + */ + wxPen GetRowGridLinePen(int row); + + /** + Sets the arguments to the current row label alignment values. + Horizontal alignment will be one of wxLEFT, wxCENTRE or wxRIGHT. + + Vertical alignment will be one of wxTOP, wxCENTRE or wxBOTTOM. + */ + void GetRowLabelAlignment(int* horiz, int* vert) const; + + /** + Returns the current width of the row labels. + */ + int GetRowLabelSize() const; + + /** + Returns the specified row label. The default grid table class provides numeric + row labels. + If you are using a custom grid table you can override + wxGridTableBase::GetRowLabelValue to provide + your own labels. + */ + wxString GetRowLabelValue(int row) const; + + /** + This returns the value of the lowest row width that can be handled correctly. + See + member SetRowMinimalAcceptableHeight() for details. + */ + int GetRowMinimalAcceptableHeight() const; + + /** + + */ + int GetRowMinimalHeight(int col) const; + + /** + Returns the height of the specified row. + */ + int GetRowSize(int row) const; + + /** + Returns the number of pixels per horizontal scroll increment. The default is 15. + + @see GetScrollLineY(), SetScrollLineX(), SetScrollLineY() + */ + int GetScrollLineX() const; + + /** + Returns the number of pixels per vertical scroll increment. The default is 15. + + @see GetScrollLineX(), SetScrollLineX(), SetScrollLineY() + */ + int GetScrollLineY() const; + + /** + Returns an array of singly selected cells. + */ + wxGridCellCoordsArray GetSelectedCells() const; + + /** + Returns an array of selected cols. + */ + wxArrayInt GetSelectedCols() const; + + /** + Returns an array of selected rows. + */ + wxArrayInt GetSelectedRows() const; + + /** + Access or update the selection fore/back colours + */ + wxColour GetSelectionBackground() const; + + /** + Returns an array of the bottom right corners of blocks of selected cells, + see GetSelectionBlockTopLeft(). + */ + wxGridCellCoordsArray GetSelectionBlockBottomRight() const; + + /** + Returns an array of the top left corners of blocks of selected cells, + see GetSelectionBlockBottomRight(). + */ + wxGridCellCoordsArray GetSelectionBlockTopLeft() const; + + /** + + */ + wxColour GetSelectionForeground() const; + + /** + Returns the current selection mode, see SetSelectionMode(). + */ + wxGrid::wxGridSelectionModes GetSelectionMode() const; + + /** + Returns a base pointer to the current table object. + */ + wxGridTableBase* GetTable() const; + + /** + Returned number of whole cols visible. + */ + int GetViewWidth() const; + + /** + EnableGridLines() + + GridLinesEnabled() + + SetGridLineColour() + + GetGridLineColour() + + GetDefaultGridLinePen() + + GetRowGridLinePen() + + GetColGridLinePen() + */ + + + /** + Returns @true if drawing of grid lines is turned on, @false otherwise. + */ + bool GridLinesEnabled() const; + + /** + Hides the in-place cell edit control. + */ + void HideCellEditControl(); + + /** + Hides the column labels by calling SetColLabelSize() + with a size of 0. Show labels again by calling that method with + a width greater than 0. + */ + void HideColLabels(); + + /** + Hides the row labels by calling SetRowLabelSize() + with a size of 0. Show labels again by calling that method with + a width greater than 0. + */ + void HideRowLabels(); + + /** + Init the m_colWidths/Rights arrays + */ + void InitColWidths(); + + /** + @note @e never access m_row/col arrays directly because they are created + on demand, @e always use accessor functions instead! + Init the m_rowHeights/Bottoms arrays with default values. + */ + void InitRowHeights(); + + /** + Inserts one or more new columns into a grid with the first new column at the + specified position and returns @true if successful. The updateLabels argument is + not + used at present. + The sequence of actions begins with the grid object requesting the underlying + grid + table to insert new columns. If this is successful the table notifies the grid + and the + grid updates the display. For a default grid (one where you have called + wxGrid::CreateGrid) this process is automatic. If you are + using a custom grid table (specified with wxGrid::SetTable) + then you must override + wxGridTableBase::InsertCols in your derived + table class. + */ + bool InsertCols(int pos = 0, int numCols = 1, + bool updateLabels = true); + + /** + Inserts one or more new rows into a grid with the first new row at the specified + position and returns @true if successful. The updateLabels argument is not used + at + present. + The sequence of actions begins with the grid object requesting the underlying + grid + table to insert new rows. If this is successful the table notifies the grid and + the + grid updates the display. For a default grid (one where you have called + wxGrid::CreateGrid) this process is automatic. If you are + using a custom grid table (specified with wxGrid::SetTable) + then you must override + wxGridTableBase::InsertRows in your derived + table class. + */ + bool InsertRows(int pos = 0, int numRows = 1, + bool updateLabels = true); + + /** + Returns @true if the in-place edit control is currently enabled. + */ + bool IsCellEditControlEnabled() const; + + /** + Returns @true if the current cell has been set to read-only + (see wxGrid::SetReadOnly). + */ + bool IsCurrentCellReadOnly() const; + + /** + Returns @false if the whole grid has been set as read-only or @true otherwise. + See EnableEditing() for more information about + controlling the editing status of grid cells. + */ + bool IsEditable() const; + + //@{ + /** + Is this cell currently selected. + */ + bool IsInSelection(int row, int col) const; + const bool IsInSelection(const wxGridCellCoords& coords) const; + //@} + + /** + Returns @true if the cell at the specified location can't be edited. + See also IsReadOnly(). + */ + bool IsReadOnly(int row, int col) const; + + /** + Returns @true if there are currently rows, columns or blocks of cells selected. + */ + bool IsSelection() const; + + //@{ + /** + Returns @true if a cell is either wholly visible (the default) or at least + partially + visible in the grid window. + */ + bool IsVisible(int row, int col, bool wholeCellVisible = true) const; + const bool IsVisible(const wxGridCellCoords& coords, + bool wholeCellVisible = true) const; + //@} + + //@{ + /** + Brings the specified cell into the visible grid cell area with minimal + scrolling. Does + nothing if the cell is already visible. + */ + void MakeCellVisible(int row, int col); + void MakeCellVisible(const wxGridCellCoords& coords); + //@} + + /** + Moves the grid cursor down by one row. If a block of cells was previously + selected it + will expand if the argument is @true or be cleared if the argument is @false. + */ + bool MoveCursorDown(bool expandSelection); + + /** + Moves the grid cursor down in the current column such that it skips to the + beginning or + end of a block of non-empty cells. If a block of cells was previously selected + it + will expand if the argument is @true or be cleared if the argument is @false. + */ + bool MoveCursorDownBlock(bool expandSelection); + + /** + Moves the grid cursor left by one column. If a block of cells was previously + selected it + will expand if the argument is @true or be cleared if the argument is @false. + */ + bool MoveCursorLeft(bool expandSelection); + + /** + Moves the grid cursor left in the current row such that it skips to the + beginning or + end of a block of non-empty cells. If a block of cells was previously selected + it + will expand if the argument is @true or be cleared if the argument is @false. + */ + bool MoveCursorLeftBlock(bool expandSelection); + + /** + Moves the grid cursor right by one column. If a block of cells was previously + selected it + will expand if the argument is @true or be cleared if the argument is @false. + */ + bool MoveCursorRight(bool expandSelection); + + /** + Moves the grid cursor right in the current row such that it skips to the + beginning or + end of a block of non-empty cells. If a block of cells was previously selected + it + will expand if the argument is @true or be cleared if the argument is @false. + */ + bool MoveCursorRightBlock(bool expandSelection); + + /** + Moves the grid cursor up by one row. If a block of cells was previously + selected it + will expand if the argument is @true or be cleared if the argument is @false. + */ + bool MoveCursorUp(bool expandSelection); + + /** + Moves the grid cursor up in the current column such that it skips to the + beginning or + end of a block of non-empty cells. If a block of cells was previously selected + it + will expand if the argument is @true or be cleared if the argument is @false. + */ + bool MoveCursorUpBlock(bool expandSelection); + + /** + Moves the grid cursor down by some number of rows so that the previous bottom + visible row + becomes the top visible row. + */ + bool MovePageDown(); + + /** + Moves the grid cursor up by some number of rows so that the previous top + visible row + becomes the bottom visible row. + */ + bool MovePageUp(); + + /** + Methods for a registry for mapping data types to Renderers/Editors + */ + void RegisterDataType(const wxString& typeName, + wxGridCellRenderer* renderer, + wxGridCellEditor* editor); + + /** + SetRowLabelValue() + + SetColLabelValue() + + GetRowLabelValue() + + GetColLabelValue() + + SetUseNativeColLabels() + + HideColLabels() + + HideRowLabels() + + SetRowLabelSize() + + SetColLabelSize() + + GetRowLabelSize() + + GetColLabelSize() + + AutoSizeRowLabelSize() + + AutoSizeColLabelSize() + + GetDefaultRowLabelSize() + + GetDefaultColLabelSize() + + SetRowLabelAlignment() + + SetColLabelAlignment() + + GetRowLabelAlignment() + + GetColLabelAlignment() + + SetLabelFont() + + SetLabelTextColour() + + SetLabelBackgroundColour() + + GetLabelFont() + + GetLabelBackgroundColour() + + GetLabelTextColour() + + SetColLabelTextOrientation() + + GetColLabelTextOrientation() + */ + + + /** + Sets the value of the current grid cell to the current in-place edit control + value. + This is called automatically when the grid cursor moves from the current cell + to a + new cell. It is also a good idea to call this function when closing a grid since + any edits to the final cell location will not be saved otherwise. + */ + void SaveEditControlValue(); + + /** + Selects all cells in the grid. + */ + void SelectAll(); + + //@{ + /** + Selects a rectangular block of cells. If addToSelected is @false then any + existing selection will be + deselected; if @true the column will be added to the existing selection. + */ + void SelectBlock(int topRow, int leftCol, int bottomRow, + int rightCol, + bool addToSelected = false); + void SelectBlock(const wxGridCellCoords& topLeft, + const wxGridCellCoords& bottomRight, + bool addToSelected = false); + //@} + + /** + Selects the specified column. If addToSelected is @false then any existing + selection will be + deselected; if @true the column will be added to the existing selection. + */ + void SelectCol(int col, bool addToSelected = false); + + /** + Selects the specified row. If addToSelected is @false then any existing + selection will be + deselected; if @true the row will be added to the existing selection. + */ + void SelectRow(int row, bool addToSelected = false); + + /** + ClearSelection() + + IsSelection() + + SelectAll() + + SelectBlock() + + SelectCol() + + SelectRow() + */ + + + /** + This function returns the rectangle that encloses the selected cells + in device coords and clipped to the client size of the grid window. + */ + wxRect SelectionToDeviceRect() const; + + //@{ + /** + Sets the horizontal and vertical alignment for grid cell text at the specified + location. + Horizontal alignment should be one of wxALIGN_LEFT, wxALIGN_CENTRE or + wxALIGN_RIGHT. + + Vertical alignment should be one of wxALIGN_TOP, wxALIGN_CENTRE or + wxALIGN_BOTTOM. + */ + void SetCellAlignment(int row, int col, int horiz, int vert); + void SetCellAlignment(int align, int row, int col); + //@} + + /** + + */ + void SetCellBackgroundColour(int row, int col, + const wxColour& colour); + + /** + Sets the editor for the grid cell at the specified location. + The grid will take ownership of the pointer. + See wxGridCellEditor and + the @ref overview_gridoverview "wxGrid overview" for more information about + cell editors and renderers. + */ + void SetCellEditor(int row, int col, wxGridCellEditor* editor); + + /** + Sets the font for text in the grid cell at the specified location. + */ + void SetCellFont(int row, int col, const wxFont& font); + + /** + Sets the renderer for the grid cell at the specified location. + The grid will take ownership of the pointer. + See wxGridCellRenderer and + the @ref overview_gridoverview "wxGrid overview" for more information about + cell editors and renderers. + */ + void SetCellRenderer(int row, int col, + wxGridCellRenderer* renderer); + + //@{ + /** + Sets the text colour for the grid cell at the specified location. + */ + void SetCellTextColour(int row, int col, const wxColour& colour); + void SetCellTextColour(const wxColour& val, int row, int col); + void SetCellTextColour(const wxColour& colour); + //@} + + //@{ + /** + Sets the string value for the cell at the specified location. For simple + applications where a + grid object automatically uses a default grid table of string values you use + this function together + with GetCellValue() to access cell values. + For more complex applications where you have derived your own grid table class + that contains + various data types (e.g. numeric, boolean or user-defined custom types) then + you only use this + function for those cells that contain string values. + The last form is for backward compatibility only. + See wxGridTableBase::CanSetValueAs + and the @ref overview_gridoverview "wxGrid overview" for more information. + */ + void SetCellValue(int row, int col, const wxString& s); + void SetCellValue(const wxGridCellCoords& coords, + const wxString& s); + void SetCellValue(const wxString& val, int row, int col); + //@} + + /** + Sets the cell attributes for all cells in the specified column. + For more information about controlling grid cell attributes see the + wxGridCellAttr cell attribute class and the + @ref overview_gridoverview. + */ + void SetColAttr(int col, wxGridCellAttr* attr); + + /** + Sets the specified column to display boolean values. wxGrid displays boolean + values with a checkbox. + */ + void SetColFormatBool(int col); + + /** + Sets the specified column to display data in a custom format. + See the @ref overview_gridoverview "wxGrid overview" for more information on + working + with custom data types. + */ + void SetColFormatCustom(int col, const wxString& typeName); + + /** + Sets the specified column to display floating point values with the given width + and precision. + */ + void SetColFormatFloat(int col, int width = -1, + int precision = -1); + + /** + Sets the specified column to display integer values. + */ + void SetColFormatNumber(int col); + + /** + Sets the horizontal and vertical alignment of column label text. + Horizontal alignment should be one of wxALIGN_LEFT, wxALIGN_CENTRE or + wxALIGN_RIGHT. + Vertical alignment should be one of wxALIGN_TOP, wxALIGN_CENTRE or + wxALIGN_BOTTOM. + */ + void SetColLabelAlignment(int horiz, int vert); + + /** + Sets the height of the column labels. + If @a height equals to @c wxGRID_AUTOSIZE then height is calculated + automatically + so that no label is truncated. Note that this could be slow for a large table. + */ + void SetColLabelSize(int height); + + /** + Set the value for the given column label. If you are using a derived grid table + you must + override wxGridTableBase::SetColLabelValue + for this to have any effect. + */ + void SetColLabelValue(int col, const wxString& value); + + /** + This modifies the minimum column width that can be handled correctly. + Specifying a low value here + allows smaller grid cells to be dealt with correctly. Specifying a value here + which is much smaller + than the actual minimum size will incur a performance penalty in the functions + which perform + grid cell index lookup on the basis of screen coordinates. + This should normally be called when creating the grid because it will not + resize existing columns + with sizes smaller than the value specified here. + */ + void SetColMinimalAcceptableWidth(int width); + + /** + Sets the minimal width for the specified column. This should normally be called + when creating the grid + because it will not resize a column that is already narrower than the minimal + width. + The width argument must be higher than the minimimal acceptable column width, + see + GetColMinimalAcceptableWidth(). + */ + void SetColMinimalWidth(int col, int width); + + /** + Sets the position of the specified column. + */ + void SetColPos(int colID, int newPos); + + /** + Sets the width of the specified column. + This function does not refresh the grid. If you are calling it outside of a + BeginBatch / EndBatch + block you can use ForceRefresh() to see the changes. + Automatically sizes the column to fit its contents. If setAsMin is @true the + calculated width will + also be set as the minimal width for the column. + */ + void SetColSize(int col, int width); + + /** + Sets the default horizontal and vertical alignment for grid cell text. + Horizontal alignment should be one of wxALIGN_LEFT, wxALIGN_CENTRE or + wxALIGN_RIGHT. + Vertical alignment should be one of wxALIGN_TOP, wxALIGN_CENTRE or + wxALIGN_BOTTOM. + */ + void SetDefaultCellAlignment(int horiz, int vert); + + /** + Sets the default background colour for grid cells. + */ + void SetDefaultCellBackgroundColour(const wxColour& colour); + + /** + Sets the default font to be used for grid cell text. + */ + void SetDefaultCellFont(const wxFont& font); + + /** + Sets the current default colour for grid cell text. + */ + void SetDefaultCellTextColour(const wxColour& colour); + + /** + Sets the default width for columns in the grid. This will only affect columns + subsequently added to + the grid unless resizeExistingCols is @true. + */ + void SetDefaultColSize(int width, + bool resizeExistingCols = false); + + /** + Sets the default editor for grid cells. The grid will take ownership of the + pointer. + See wxGridCellEditor and + the @ref overview_gridoverview "wxGrid overview" for more information about + cell editors and renderers. + */ + void SetDefaultEditor(wxGridCellEditor* editor); + + /** + Sets the default renderer for grid cells. The grid will take ownership of the + pointer. + See wxGridCellRenderer and + the @ref overview_gridoverview "wxGrid overview" for more information about + cell editors and renderers. + */ + void SetDefaultRenderer(wxGridCellRenderer* renderer); + + /** + Sets the default height for rows in the grid. This will only affect rows + subsequently added + to the grid unless resizeExistingRows is @true. + */ + void SetDefaultRowSize(int height, + bool resizeExistingRows = false); + + /** + Set the grid cursor to the specified cell. + This function calls MakeCellVisible(). + */ + void SetGridCursor(int row, int col); + + /** + Sets the colour used to draw grid lines. + */ + void SetGridLineColour(const wxColour& colour); + + /** + Sets the background colour for row and column labels. + */ + void SetLabelBackgroundColour(const wxColour& colour); + + /** + Sets the font for row and column labels. + */ + void SetLabelFont(const wxFont& font); + + /** + Sets the colour for row and column label text. + */ + void SetLabelTextColour(const wxColour& colour); + + /** + A grid may occupy more space than needed for its rows/columns. This + function allows to set how big this extra space is + */ + void SetMargins(int extraWidth, int extraHeight); + + /** + Common part of AutoSizeColumn/Row() and GetBestSize() + */ + int SetOrCalcColumnSizes(bool calcOnly, bool setAsMin = true); + + /** + + */ + int SetOrCalcRowSizes(bool calcOnly, bool setAsMin = true); + + /** + Makes the cell at the specified location read-only or editable. + See also IsReadOnly(). + */ + void SetReadOnly(int row, int col, bool isReadOnly = true); + + /** + Sets the cell attributes for all cells in the specified row. + See the wxGridCellAttr class for more information + about controlling cell attributes. + */ + void SetRowAttr(int row, wxGridCellAttr* attr); + + /** + Sets the horizontal and vertical alignment of row label text. + Horizontal alignment should be one of wxALIGN_LEFT, wxALIGN_CENTRE or + wxALIGN_RIGHT. + Vertical alignment should be one of wxALIGN_TOP, wxALIGN_CENTRE or + wxALIGN_BOTTOM. + */ + void SetRowLabelAlignment(int horiz, int vert); + + /** + Sets the width of the row labels. + If @a width equals @c wxGRID_AUTOSIZE then width is calculated automatically + so that no label is truncated. Note that this could be slow for a large table. + */ + void SetRowLabelSize(int width); + + /** + Set the value for the given row label. If you are using a derived grid table + you must + override wxGridTableBase::SetRowLabelValue + for this to have any effect. + */ + void SetRowLabelValue(int row, const wxString& value); + + /** + This modifies the minimum row width that can be handled correctly. Specifying a + low value here + allows smaller grid cells to be dealt with correctly. Specifying a value here + which is much smaller + than the actual minimum size will incur a performance penalty in the functions + which perform + grid cell index lookup on the basis of screen coordinates. + This should normally be called when creating the grid because it will not + resize existing rows + with sizes smaller than the value specified here. + */ + void SetRowMinimalAcceptableHeight(int height); + + /** + Sets the minimal height for the specified row. This should normally be called + when creating the grid + because it will not resize a row that is already shorter than the minimal + height. + The height argument must be higher than the minimimal acceptable row height, see + GetRowMinimalAcceptableHeight(). + */ + void SetRowMinimalHeight(int row, int height); + + /** + Sets the height of the specified row. + This function does not refresh the grid. If you are calling it outside of a + BeginBatch / EndBatch + block you can use ForceRefresh() to see the changes. + Automatically sizes the column to fit its contents. If setAsMin is @true the + calculated width will + also be set as the minimal width for the column. + */ + void SetRowSize(int row, int height); + + /** + Sets the number of pixels per horizontal scroll increment. The default is 15. + Sometimes wxGrid has trouble setting the scrollbars correctly due to rounding + errors: setting this to 1 can help. + + @see GetScrollLineX(), GetScrollLineY(), SetScrollLineY() + */ + void SetScrollLineX(int x); + + /** + Sets the number of pixels per vertical scroll increment. The default is 15. + Sometimes wxGrid has trouble setting the scrollbars correctly due to rounding + errors: setting this to 1 can help. + + @see GetScrollLineX(), GetScrollLineY(), SetScrollLineX() + */ + void SetScrollLineY(int y); + + /** + + */ + void SetSelectionBackground(const wxColour& c); + + /** + + */ + void SetSelectionForeground(const wxColour& c); + + /** + Set the selection behaviour of the grid. + + @param wxGridSelectCells() + The default mode where individual cells are selected. + @param wxGridSelectRows() + Selections will consist of whole rows. + @param wxGridSelectColumns() + Selections will consist of whole columns. + */ + void SetSelectionMode(wxGrid::wxGridSelectionModes selmode); + + /** + Passes a pointer to a custom grid table to be used by the grid. This should be + called + after the grid constructor and before using the grid object. If takeOwnership + is set to + @true then the table will be deleted by the wxGrid destructor. + Use this function instead of CreateGrid() when your + application involves complex or non-string data or data sets that are too large + to fit + wholly in memory. + */ + bool SetTable(wxGridTableBase* table, bool takeOwnership = false, + wxGrid::wxGridSelectionModes selmode = wxGrid::wxGridSelectCells); + + /** + Call this in order to make the column labels use a native look by using + wxRenderer::DrawHeaderButton + internally. There is no equivalent method for drawing row columns as + there is not native look for that. This option is useful when using + wxGrid for displaying tables and not as a spread-sheet. + */ + void SetUseNativeColLabels(bool native = true); + + /** + Displays the in-place cell edit control for the current cell. + */ + void ShowCellEditControl(); + + /** + @param x + The x position to evaluate. + @param clipToMinMax + If @true, rather than returning wxNOT_FOUND, it returns either the first or + last column depending on whether x is too far to the left or right respectively. + */ + int XToCol(int x, bool clipToMinMax = false) const; + + /** + Returns the column whose right hand edge is close to the given logical x + position. + If no column edge is near to this position @c wxNOT_FOUND is returned. + */ + int XToEdgeOfCol(int x) const; + + /** + Returns the row whose bottom edge is close to the given logical y position. + If no row edge is near to this position @c wxNOT_FOUND is returned. + */ + int YToEdgeOfRow(int y) const; + + /** + Returns the grid row that corresponds to the logical y coordinate. Returns + @c wxNOT_FOUND if there is no row at the y position. + */ + int YToRow(int y) const; +}; + + + +/** + @class wxGridCellBoolEditor + @wxheader{grid.h} + + The editor for boolean data. + + @library{wxadv} + @category{FIXME} + + @see wxGridCellEditor, wxGridCellFloatEditor, wxGridCellNumberEditor, + wxGridCellTextEditor, wxGridCellChoiceEditor +*/ +class wxGridCellBoolEditor : public wxGridCellEditor +{ +public: + /** + Default constructor. + */ + wxGridCellBoolEditor(); + + /** + Returns @true if the given @a value is equal to the string representation of + the truth value we currently use (see + wxGridCellBoolEditor::UseStringValues). + */ + static bool IsTrueValue(const wxString& value); + + /** + , wxString&@e valueFalse = _T("")) + This method allows to customize the values returned by GetValue() method for + the cell using this editor. By default, the default values of the arguments are + used, i.e. @c "1" is returned if the cell is checked and an empty string + otherwise, using this method allows to change this. + */ + static void UseStringValues() const; +}; + + + +/** + @class wxGridUpdateLocker + @wxheader{grid.h} + + This small class can be used to prevent wxGrid from redrawing + during its lifetime by calling wxGrid::BeginBatch + in its constructor and wxGrid::EndBatch in its + destructor. It is typically used in a function performing several operations + with a grid which would otherwise result in flicker. For example: + + @code + void MyFrame::Foo() + { + m_grid = new wxGrid(this, ...); + + wxGridUpdateLocker noUpdates(m_grid); + m_grid-AppendColumn(); + ... many other operations with m_grid... + m_grid-AppendRow(); + + // destructor called, grid refreshed + } + @endcode + + Using this class is easier and safer than calling + wxGrid::BeginBatch and wxGrid::EndBatch + because you don't risk not to call the latter (due to an exception for example). + + @library{wxadv} + @category{FIXME} +*/ +class wxGridUpdateLocker +{ +public: + /** + Creates an object preventing the updates of the specified @e grid. The + parameter could be @NULL in which case nothing is done. If @a grid is + non-@NULL then the grid must exist for longer than wxGridUpdateLocker object + itself. + The default constructor could be followed by a call to + Create() to set the + grid object later. + */ + wxGridUpdateLocker(wxGrid* grid = NULL); + + /** + Destructor reenables updates for the grid this object is associated with. + */ + ~wxGridUpdateLocker(); + + /** + This method can be called if the object had been constructed using the default + constructor. It must not be called more than once. + */ + void Create(wxGrid* grid); +}; + diff --git a/interface/wx/hash.h b/interface/wx/hash.h new file mode 100644 index 0000000000..b7bfc1091a --- /dev/null +++ b/interface/wx/hash.h @@ -0,0 +1,107 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: hash.h +// Purpose: interface of wxHashTable +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxHashTable + @wxheader{hash.h} + + @b Please note that this class is retained for backward compatibility + reasons; you should use wxHashMap. + + This class provides hash table functionality for wxWidgets, and for an + application if it wishes. Data can be hashed on an integer or string + key. + + @library{wxbase} + @category{containers} + + @see wxList +*/ +class wxHashTable : public wxObject +{ +public: + /** + Constructor. @a key_type is one of wxKEY_INTEGER, or wxKEY_STRING, + and indicates what sort of keying is required. @a size is optional. + */ + wxHashTable(unsigned int key_type, int size = 1000); + + /** + Destroys the hash table. + */ + ~wxHashTable(); + + /** + The counterpart of @e Next. If the application wishes to iterate + through all the data in the hash table, it can call @e BeginFind and + then loop on @e Next. + */ + void BeginFind(); + + /** + Clears the hash table of all nodes (but as usual, doesn't delete user data). + */ + void Clear(); + + //@{ + /** + Deletes entry in hash table and returns the user's data (if found). + */ + wxObject* Delete(long key); + wxObject* Delete(const wxString& key); + //@} + + /** + If set to @true data stored in hash table will be deleted when hash table object + is destroyed. + */ + void DeleteContents(bool flag); + + //@{ + /** + Gets data from the hash table, using an integer or string key (depending on + which + has table constructor was used). + */ + wxObject* Get(long key); + wxObject* Get(const char* key); + //@} + + /** + Returns the number of elements in the hash table. + */ + size_t GetCount() const; + + /** + Makes an integer key out of a string. An application may wish to make a key + explicitly (for instance when combining two data values to form a key). + */ + long MakeKey(const wxString& string); + + /** + If the application wishes to iterate through all the data in the hash + table, it can call @e BeginFind and then loop on @e Next. This function + returns a @b Node() pointer (or @NULL if there are no more nodes). + The return value is functionally equivalent to @b wxNode but might not be + implemented as a @b wxNode. The user will probably only wish to use the + @b GetData method to retrieve the data; the node may also be deleted. + */ + wxHashTable::Node* Next(); + + //@{ + /** + Inserts data into the hash table, using an integer or string key (depending on + which + has table constructor was used). The key string is copied and stored by the hash + table implementation. + */ + void Put(long key, wxObject* object); + void Put(const char* key, wxObject* object); + //@} +}; + diff --git a/interface/wx/hashmap.h b/interface/wx/hashmap.h new file mode 100644 index 0000000000..bfba745898 --- /dev/null +++ b/interface/wx/hashmap.h @@ -0,0 +1,106 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: hashmap.h +// Purpose: interface of wxHashMap +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxHashMap + @wxheader{hashmap.h} + + This is a simple, type-safe, and reasonably efficient hash map class, + whose interface is a subset of the interface of STL containers. In + particular, the interface is modeled after std::map, and the various, + non-standard, std::hash_map. + + @library{wxbase} + @category{FIXME} +*/ +class wxHashMap +{ +public: + //@{ + /** + Copy constructor. + */ + wxHashMap(size_type size = 10); + wxHashMap(const wxHashMap& map); + //@} + + //@{ + /** + Returns an iterator pointing at the first element of the hash map. + Please remember that hash maps do not guarantee ordering. + */ + const_iterator begin(); + const iterator begin(); + //@} + + /** + Removes all elements from the hash map. + */ + void clear(); + + /** + Counts the number of elements with the given key present in the map. + This function returns only 0 or 1. + */ + size_type count(const key_type& key) const; + + /** + Returns @true if the hash map does not contain any elements, @false otherwise. + */ + bool empty() const; + + //@{ + /** + Returns an iterator pointing at the one-after-the-last element of the hash map. + Please remember that hash maps do not guarantee ordering. + */ + const_iterator end(); + const iterator end(); + //@} + + //@{ + /** + Erases the element pointed to by the iterator. After the deletion + the iterator is no longer valid and must not be used. + */ + size_type erase(const key_type& key); + void erase(iterator it); + void erase(const_iterator it); + //@} + + //@{ + /** + If an element with the given key is present, the functions returns + an iterator pointing at that element, otherwise an invalid iterator + is returned (i.e. hashmap.find( non_existent_key ) == hashmap.end()). + */ + iterator find(const key_type& key) const; + const_iterator find(const key_type& key) const; + //@} + + /** + Inserts the given value in the hash map. The return value is + equivalent to a @c std::pairiterator(), bool; + the iterator points to the inserted element, the boolean value + is @true if @c v was actually inserted. + */ + Insert_Result insert(const value_type& v); + + /** + Use the key as an array subscript. The only difference is that if the + given key is not present in the hash map, an element with the + default @c value_type() is inserted in the table. + */ + mapped_type operator[](const key_type& key); + + /** + Returns the number of elements in the map. + */ + size_type size() const; +}; + diff --git a/interface/wx/hashset.h b/interface/wx/hashset.h new file mode 100644 index 0000000000..1470b29ef0 --- /dev/null +++ b/interface/wx/hashset.h @@ -0,0 +1,99 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: hashset.h +// Purpose: interface of wxHashSet +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxHashSet + @wxheader{hashset.h} + + This is a simple, type-safe, and reasonably efficient hash set class, + whose interface is a subset of the interface of STL containers. In + particular, the interface is modeled after std::set, and the various, + non-standard, std::hash_map. + + @library{wxbase} + @category{FIXME} +*/ +class wxHashSet +{ +public: + //@{ + /** + Copy constructor. + */ + wxHashSet(size_type size = 10); + wxHashSet(const wxHashSet& set); + //@} + + //@{ + /** + Returns an iterator pointing at the first element of the hash set. + Please remember that hash sets do not guarantee ordering. + */ + const_iterator begin(); + const iterator begin(); + //@} + + /** + Removes all elements from the hash set. + */ + void clear(); + + /** + Counts the number of elements with the given key present in the set. + This function returns only 0 or 1. + */ + size_type count(const key_type& key) const; + + /** + Returns @true if the hash set does not contain any elements, @false otherwise. + */ + bool empty() const; + + //@{ + /** + Returns an iterator pointing at the one-after-the-last element of the hash set. + Please remember that hash sets do not guarantee ordering. + */ + const_iterator end(); + const iterator end(); + //@} + + //@{ + /** + Erases the element pointed to by the iterator. After the deletion + the iterator is no longer valid and must not be used. + */ + size_type erase(const key_type& key); + void erase(iterator it); + void erase(const_iterator it); + //@} + + //@{ + /** + If an element with the given key is present, the functions returns + an iterator pointing at that element, otherwise an invalid iterator + is returned (i.e. hashset.find( non_existent_key ) == hashset.end()). + */ + iterator find(const key_type& key) const; + const_iterator find(const key_type& key) const; + //@} + + /** + Inserts the given value in the hash set. The return value is + equivalent to a @c std::pairwxHashMap::iterator, bool; + the iterator points to the inserted element, the boolean value + is @true if @c v was actually inserted. + */ + Insert_Result insert(const value_type& v); + + /** + Returns the number of elements in the set. + */ + size_type size() const; +}; + diff --git a/interface/wx/help.h b/interface/wx/help.h new file mode 100644 index 0000000000..832d8f48a1 --- /dev/null +++ b/interface/wx/help.h @@ -0,0 +1,246 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: help.h +// Purpose: interface of wxHelpController +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxHelpController + @wxheader{help.h} + + This is a family of classes by which + applications may invoke a help viewer to provide on-line help. + + A help controller allows an application to display help, at the contents + or at a particular topic, and shut the help program down on termination. + This avoids proliferation of many instances of the help viewer whenever the + user requests a different topic via the application's menus or buttons. + + Typically, an application will create a help controller instance + when it starts, and immediately call @b Initialize + to associate a filename with it. The help viewer will only get run, however, + just before the first call to display something. + + Most help controller classes actually derive from wxHelpControllerBase and have + names of the form wxXXXHelpController or wxHelpControllerXXX. An + appropriate class is aliased to the name wxHelpController for each platform, as + follows: + + On desktop Windows, wxCHMHelpController is used (MS HTML Help). + On Windows CE, wxWinceHelpController is used. + On all other platforms, wxHtmlHelpController is used if wxHTML is + compiled into wxWidgets; otherwise wxExtHelpController is used (for invoking an + external + browser). + + The remaining help controller classes need to be named + explicitly by an application that wishes to make use of them. + + There are currently the following help controller classes defined: + + wxWinHelpController, for controlling Windows Help. + wxCHMHelpController, for controlling MS HTML Help. To use this, you need to + set wxUSE_MS_HTML_HELP + to 1 in setup.h and have htmlhelp.h header from Microsoft's HTML Help kit (you + don't need + VC++ specific htmlhelp.lib because wxWidgets loads necessary DLL at runtime and + so it + works with all compilers). + wxBestHelpController, for controlling MS HTML Help or, if Microsoft's runtime + is + not available, wxHtmlHelpController. You need to provide + @b both CHM and HTB versions of the help file. For 32bit Windows only. + wxExtHelpController, for controlling external browsers under Unix. + The default browser is Netscape Navigator. The 'help' sample shows its use. + wxWinceHelpController, for controlling a simple @c .htm help controller for + Windows CE applications. + wxHtmlHelpController, a sophisticated help controller using wxHTML(), in + a similar style to the Microsoft HTML Help viewer and using some of the same + files. + Although it has an API compatible with other help controllers, it has more + advanced features, so it is + recommended that you use the specific API for this class instead. Note that if + you + use .zip or .htb formats for your books, you + must add this line to your application initialization: @c + wxFileSystem::AddHandler(new wxArchiveFSHandler); + or nothing will be shown in your help window. + + + @library{wxbase} + @category{help} + + @see wxHtmlHelpController, wxHTML() +*/ +class wxHelpController : public wxObject +{ +public: + /** + Constructs a help instance object, but does not invoke the help viewer. + If you provide a window, it will be used by some help controller classes, such + as + wxCHMHelpController, wxWinHelpController and wxHtmlHelpController, as the + parent for the help window instead of the value of wxApp::GetTopWindow. You can + also change the parent window later with + SetParentWindow(). + */ + wxHelpController(wxWindow* parentWindow = NULL); + + /** + Destroys the help instance, closing down the viewer if it is running. + */ + ~wxHelpController(); + + /** + If the help viewer is not running, runs it and displays the file at the given + block number. + @e WinHelp: Refers to the context number. + @e MS HTML Help: Refers to the context number. + @e External HTML help: the same as for DisplaySection(). + @e wxHtmlHelpController: @e sectionNo is an identifier as specified in the @c + .hhc file. See @ref overview_helpformat "Help files format". + This function is for backward compatibility only, and applications should use + @ref displaysection() wxHelpController instead. + */ + virtual bool DisplayBlock(long blockNo); + + /** + If the help viewer is not running, runs it and displays the + contents. + */ + virtual bool DisplayContents(); + + /** + Displays the section as a popup window using a context id. + Returns @false if unsuccessful or not implemented. + */ + virtual bool DisplayContextPopup(int contextId); + + //@{ + /** + If the help viewer is not running, runs it and displays the given section. + @e WinHelp, MS HTML Help @a sectionNo is a context id. + @e External HTML help: wxExtHelpController implements @a sectionNo as an id in + a map file, which is of the form: + + @e wxHtmlHelpController: @a sectionNo is an identifier as specified in the @c + .hhc file. See @ref overview_helpformat "Help files format". + See also the help sample for notes on how to specify section numbers for + various help file formats. + */ + virtual bool DisplaySection(const wxString& section); + virtual bool DisplaySection(int sectionNo); + //@} + + /** + Displays the text in a popup window, if possible. + Returns @false if unsuccessful or not implemented. + */ + virtual bool DisplayTextPopup(const wxString& text, + const wxPoint& pos); + + /** + wxHtmlHelpController returns the frame, size and position. + For all other help controllers, this function does nothing + and just returns @NULL. + + @param viewer + This defaults to "netscape" for wxExtHelpController. + @param flags + This defaults to wxHELP_NETSCAPE for wxExtHelpController, indicating + that the viewer is a variant of Netscape Navigator. + */ + virtual wxFrame* GetFrameParameters(const wxSize* size = NULL, + const wxPoint* pos = NULL, + bool* newFrameEachTime = NULL); + + /** + Returns the window to be used as the parent for the help window. This window is + used + by wxCHMHelpController, wxWinHelpController and wxHtmlHelpController. + */ + virtual wxWindow* GetParentWindow() const; + + //@{ + /** + Initializes the help instance with a help filename, and optionally a server + socket + number if using wxHelp (now obsolete). Does not invoke the help viewer. + This must be called directly after the help instance object is created and + before + any attempts to communicate with the viewer. + You may omit the file extension and a suitable one will be chosen. For + wxHtmlHelpController, the extensions zip, htb and hhp will be appended while + searching for + a suitable file. For WinHelp, the hlp extension is appended. + */ + virtual bool Initialize(const wxString& file); + virtual bool Initialize(const wxString& file, int server); + //@} + + /** + If the help viewer is not running, runs it, and searches for sections matching + the given keyword. If one match is found, the file is displayed at this + section. The optional parameter allows the search the index + (wxHELP_SEARCH_INDEX) but this currently only supported by the + wxHtmlHelpController. + @e WinHelp, MS HTML Help: If more than one match is found, + the first topic is displayed. + @e External HTML help, simple wxHTML help: If more than one match is found, + a choice of topics is displayed. + @e wxHtmlHelpController: see wxHtmlHelpController::KeywordSearch. + */ + virtual bool KeywordSearch(const wxString& keyWord, + wxHelpSearchMode mode = wxHELP_SEARCH_ALL); + + /** + If the help viewer is not running, runs it and loads the given file. + If the filename is not supplied or is + empty, the file specified in @b Initialize is used. If the viewer is + already displaying the specified file, it will not be reloaded. This + member function may be used before each display call in case the user + has opened another file. + wxHtmlHelpController ignores this call. + */ + virtual bool LoadFile(const wxString& file = ""); + + /** + Overridable member called when this application's viewer is quit by the user. + This does not work for all help controllers. + */ + virtual bool OnQuit(); + + /** + If the viewer is running, quits it by disconnecting. + For Windows Help, the viewer will only close if no other application is using + it. + */ + virtual bool Quit(); + + /** + For wxHtmlHelpController, the title is set (again with %s indicating the + page title) and also the size and position of the frame if the frame is already + open. @a newFrameEachTime is ignored. + For all other help controllers this function has no effect. + */ + virtual void SetFrameParameters(const wxString& title, + const wxSize& size, + const wxPoint& pos = wxDefaultPosition, + bool newFrameEachTime = false); + + /** + Sets the window to be used as the parent for the help window. This is used + by wxCHMHelpController, wxWinHelpController and wxHtmlHelpController. + */ + virtual void SetParentWindow(wxWindow* parentWindow); + + /** + Sets detailed viewer information. So far this is only relevant to + wxExtHelpController. + Some examples of usage: + */ + virtual void SetViewer(const wxString& viewer, long flags); +}; + diff --git a/interface/wx/html/helpctrl.h b/interface/wx/html/helpctrl.h new file mode 100644 index 0000000000..ee3869a63b --- /dev/null +++ b/interface/wx/html/helpctrl.h @@ -0,0 +1,202 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: html/helpctrl.h +// Purpose: interface of wxHtmlHelpController +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxHtmlHelpController + @headerfile helpctrl.h wx/html/helpctrl.h + + This help controller provides an easy way of displaying HTML help in your + application (see @e test sample). The help system is based on @b books + (see wxHtmlHelpController::AddBook). A book is a logical + section of documentation (for example "User's Guide" or "Programmer's Guide" or + "C++ Reference" or "wxWidgets Reference"). The help controller can handle as + many books as you want. + + Although this class has an API compatible with other wxWidgets + help controllers as documented by wxHelpController, it + is recommended that you use the enhanced capabilities of wxHtmlHelpController's + API. + + wxHTML uses Microsoft's HTML Help Workshop project files (.hhp, .hhk, .hhc) as + its + native format. The file format is described here(). + Have a look at docs/html/ directory where sample project files are stored. + + You can use Tex2RTF to produce these files when generating HTML, if you set @b + htmlWorkshopFiles to @b @true in + your tex2rtf.ini file. The commercial tool HelpBlocks (www.helpblocks.com) can + also create these files. + + @library{wxhtml} + @category{help} + + @see @ref overview_wxhelpcontroller "Information about wxBestHelpController", + wxHtmlHelpFrame, wxHtmlHelpDialog, wxHtmlHelpWindow, wxHtmlModalHelp +*/ +class wxHtmlHelpController +{ +public: + /** + Constructor. + */ + wxHtmlHelpController(int style = wxHF_DEFAULT_STYLE, + wxWindow* parentWindow = NULL); + + //@{ + /** + Adds book (@ref overview_helpformat ".hhp file" - HTML Help Workshop project + file) into the list of loaded books. + This must be called at least once before displaying any help. + @a bookFile or @a bookUrl may be either .hhp file or ZIP archive + that contains arbitrary number of .hhp files in + top-level directory. This ZIP archive must have .zip or .htb extension + (the latter stands for "HTML book"). In other words, @c + AddBook(wxFileName("help.zip")) + is possible and is the recommended way. + + @param showWaitMsg + If @true then a decoration-less window with progress message is displayed. + @param bookFile + Help book filename. It is recommended to use this prototype + instead of the one taking URL, because it is less error-prone. + @param bookUrl + Help book URL (note that syntax of filename and URL is + different on most platforms) + */ + bool AddBook(const wxFileName& bookFile, bool showWaitMsg); + bool AddBook(const wxString& bookUrl, bool showWaitMsg); + //@} + + /** + This protected virtual method may be overridden so that when specifying the + wxHF_DIALOG style, the controller + uses a different dialog. + */ + virtual wxHtmlHelpDialog* CreateHelpDialog(wxHtmlHelpData* data); + + /** + This protected virtual method may be overridden so that the controller + uses a different frame. + */ + virtual wxHtmlHelpFrame* CreateHelpFrame(wxHtmlHelpData* data); + + //@{ + /** + This alternative form is used to search help contents by numeric IDs. + */ + void Display(const wxString& x); + void Display(const int id); + //@} + + /** + Displays help window and focuses contents panel. + */ + void DisplayContents(); + + /** + Displays help window and focuses index panel. + */ + void DisplayIndex(); + + /** + Displays help window, focuses search panel and starts searching. Returns @true + if the keyword was found. Optionally it searches through the index (mode = + wxHELP_SEARCH_INDEX), default the content (mode = wxHELP_SEARCH_ALL). + @b Important: KeywordSearch searches only pages listed in .hhc file(s). + You should list all pages in the contents file. + */ + bool KeywordSearch(const wxString& keyword, + wxHelpSearchMode mode = wxHELP_SEARCH_ALL); + + /** + Reads the controller's setting (position of window, etc.) + */ + void ReadCustomization(wxConfigBase* cfg, + wxString path = wxEmptyString); + + /** + Sets the path for storing temporary files - cached binary versions of index and + contents files. These binary + forms are much faster to read. Default value is empty string (empty string means + that no cached data are stored). Note that these files are @e not + deleted when program exits. + Once created these cached files will be used in all subsequent executions + of your application. If cached files become older than corresponding .hhp + file (e.g. if you regenerate documentation) it will be refreshed. + */ + void SetTempDir(const wxString& path); + + /** + Sets format of title of the frame. Must contain exactly one "%s" + (for title of displayed HTML page). + */ + void SetTitleFormat(const wxString& format); + + /** + Associates @a config object with the controller. + If there is associated config object, wxHtmlHelpController automatically + reads and writes settings (including wxHtmlWindow's settings) when needed. + The only thing you must do is create wxConfig object and call UseConfig. + If you do not use @e UseConfig, wxHtmlHelpController will use + default wxConfig object if available (for details see + wxConfigBase::Get and + wxConfigBase::Set). + */ + void UseConfig(wxConfigBase* config, + const wxString& rootpath = wxEmptyString); + + /** + Stores controllers setting (position of window etc.) + */ + void WriteCustomization(wxConfigBase* cfg, + wxString path = wxEmptyString); +}; + + + +/** + @class wxHtmlModalHelp + @headerfile helpctrl.h wx/html/helpctrl.h + + This class uses wxHtmlHelpController + to display help in a modal dialog. This is useful on platforms such as wxMac + where if you display help from a modal dialog, the help window must itself be a + modal + dialog. + + Create objects of this class on the stack, for example: + + @code + // The help can be browsed during the lifetime of this object; when the user + quits + // the help, program execution will continue. + wxHtmlModalHelp help(parent, wxT("help"), wxT("My topic")); + @endcode + + @library{wxhtml} + @category{FIXME} +*/ +class wxHtmlModalHelp +{ +public: + /** + @param parent + is the parent of the dialog. + @param helpFile + is the HTML help file to show. + @param topic + is an optional topic. If this is empty, the help contents will be shown. + @param style + is a combination of the flags described in the wxHtmlHelpController + documentation. + */ + wxHtmlModalHelp(wxWindow* parent, const wxString& helpFile, + const wxString& topic = wxEmptyString, + int style = wxHF_DEFAULT_STYLE | wxHF_DIALOG | wxHF_MODAL); +}; + diff --git a/interface/wx/html/helpdata.h b/interface/wx/html/helpdata.h new file mode 100644 index 0000000000..f124c123a1 --- /dev/null +++ b/interface/wx/html/helpdata.h @@ -0,0 +1,69 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: html/helpdata.h +// Purpose: interface of wxHtmlHelpData +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxHtmlHelpData + @headerfile helpdata.h wx/html/helpdata.h + + This class is used by wxHtmlHelpController + and wxHtmlHelpFrame to access HTML help items. + It is internal class and should not be used directly - except for the case + you're writing your own HTML help controller. + + @library{wxhtml} + @category{FIXME} +*/ +class wxHtmlHelpData : public wxObject +{ +public: + /** + Constructor. + */ + wxHtmlHelpData(); + + /** + Adds new book. @e book is URL (not filename!) of HTML help project (hhp) + or ZIP file that contains arbitrary number of .hhp projects (this zip + file can have either .zip or .htb extension, htb stands for "html book"). + Returns success. + */ + bool AddBook(const wxString& book_url); + + /** + Returns page's URL based on integer ID stored in project. + */ + wxString FindPageById(int id); + + /** + Returns page's URL based on its (file)name. + */ + wxString FindPageByName(const wxString& page); + + /** + Returns array with help books info. + */ + const wxHtmlBookRecArray GetBookRecArray(); + + /** + Returns reference to array with contents entries. + */ + const wxHtmlHelpDataItems GetContentsArray(); + + /** + Returns reference to array with index entries. + */ + const wxHtmlHelpDataItems GetIndexArray(); + + /** + Sets temporary directory where binary cached versions of MS HTML Workshop + files will be stored. (This is turned off by default and you can enable + this feature by setting non-empty temp dir.) + */ + void SetTempDir(const wxString& path); +}; + diff --git a/interface/wx/html/helpdlg.h b/interface/wx/html/helpdlg.h new file mode 100644 index 0000000000..3b689e837d --- /dev/null +++ b/interface/wx/html/helpdlg.h @@ -0,0 +1,82 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: html/helpdlg.h +// Purpose: interface of wxHtmlHelpDialog +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxHtmlHelpDialog + @headerfile helpdlg.h wx/html/helpdlg.h + + This class is used by wxHtmlHelpController + to display help. + It is an internal class and should not be used directly - except for the case + when you're writing your own HTML help controller. + + @library{wxhtml} + @category{FIXME} +*/ +class wxHtmlHelpDialog : public wxFrame +{ +public: + //@{ + /** + Constructor. For the values of @e style, please see the documentation for + wxHtmlHelpController. + */ + wxHtmlHelpDialog(wxHtmlHelpData* data = NULL); + wxHtmlHelpDialog(wxWindow* parent, int wxWindowID, + const wxString& title = wxEmptyString, + int style = wxHF_DEFAULT_STYLE, + wxHtmlHelpData* data = NULL); + //@} + + /** + You may override this virtual method to add more buttons to the help window's + toolbar. @a toolBar is a pointer to the toolbar and @a style is the style + flag as passed to the Create method. + wxToolBar::Realize is called immediately after returning from this function. + */ + virtual void AddToolbarButtons(wxToolBar* toolBar, int style); + + /** + Creates the dialog. See @ref wxhtmlhelpdialog() "the constructor" + for a description of the parameters. + */ + bool Create(wxWindow* parent, wxWindowID id, + const wxString& title = wxEmptyString, + int style = wxHF_DEFAULT_STYLE); + + /** + Returns the help controller associated with the dialog. + */ + wxHtmlHelpController* GetController() const; + + /** + Reads the user's settings for this dialog see + wxHtmlHelpController::ReadCustomization) + */ + void ReadCustomization(wxConfigBase* cfg, + const wxString& path = wxEmptyString); + + /** + Sets the help controller associated with the dialog. + */ + void SetController(wxHtmlHelpController* contoller); + + /** + Sets the dialog's title format. @a format must contain exactly one "%s" + (it will be replaced by the page title). + */ + void SetTitleFormat(const wxString& format); + + /** + Saves the user's settings for this dialog (see + wxHtmlHelpController::WriteCustomization). + */ + void WriteCustomization(wxConfigBase* cfg, + const wxString& path = wxEmptyString); +}; + diff --git a/interface/wx/html/helpfrm.h b/interface/wx/html/helpfrm.h new file mode 100644 index 0000000000..90d084eb5b --- /dev/null +++ b/interface/wx/html/helpfrm.h @@ -0,0 +1,82 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: html/helpfrm.h +// Purpose: interface of wxHtmlHelpFrame +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxHtmlHelpFrame + @headerfile helpfrm.h wx/html/helpfrm.h + + This class is used by wxHtmlHelpController + to display help. + It is an internal class and should not be used directly - except for the case + when you're writing your own HTML help controller. + + @library{wxhtml} + @category{FIXME} +*/ +class wxHtmlHelpFrame : public wxFrame +{ +public: + //@{ + /** + Constructor. For the values of @e style, please see the documentation for + wxHtmlHelpController. + */ + wxHtmlHelpFrame(wxHtmlHelpData* data = NULL); + wxHtmlHelpFrame(wxWindow* parent, int wxWindowID, + const wxString& title = wxEmptyString, + int style = wxHF_DEFAULT_STYLE, + wxHtmlHelpData* data = NULL); + //@} + + /** + You may override this virtual method to add more buttons to the help window's + toolbar. @a toolBar is a pointer to the toolbar and @a style is the style + flag as passed to the Create method. + wxToolBar::Realize is called immediately after returning from this function. + */ + virtual void AddToolbarButtons(wxToolBar* toolBar, int style); + + /** + Creates the frame. See @ref wxhtmlhelpframe() "the constructor" + for a description of the parameters. + */ + bool Create(wxWindow* parent, wxWindowID id, + const wxString& title = wxEmptyString, + int style = wxHF_DEFAULT_STYLE); + + /** + Returns the help controller associated with the frame. + */ + wxHtmlHelpController* GetController() const; + + /** + Reads the user's settings for this frame see + wxHtmlHelpController::ReadCustomization) + */ + void ReadCustomization(wxConfigBase* cfg, + const wxString& path = wxEmptyString); + + /** + Sets the help controller associated with the frame. + */ + void SetController(wxHtmlHelpController* contoller); + + /** + Sets the frame's title format. @a format must contain exactly one "%s" + (it will be replaced by the page title). + */ + void SetTitleFormat(const wxString& format); + + /** + Saves the user's settings for this frame (see + wxHtmlHelpController::WriteCustomization). + */ + void WriteCustomization(wxConfigBase* cfg, + const wxString& path = wxEmptyString); +}; + diff --git a/interface/wx/html/helpwnd.h b/interface/wx/html/helpwnd.h new file mode 100644 index 0000000000..192661a073 --- /dev/null +++ b/interface/wx/html/helpwnd.h @@ -0,0 +1,168 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: html/helpwnd.h +// Purpose: interface of wxHtmlHelpWindow +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxHtmlHelpWindow + @headerfile helpwnd.h wx/html/helpwnd.h + + This class is used by wxHtmlHelpController + to display help within a frame or dialog, but you can use it yourself to create + an embedded HTML help window. + + For example: + + @code + // m_embeddedHelpWindow is a wxHtmlHelpWindow + // m_embeddedHtmlHelp is a wxHtmlHelpController + + // Create embedded HTML Help window + m_embeddedHelpWindow = new wxHtmlHelpWindow; + m_embeddedHtmlHelp.UseConfig(config, rootPath); // Set your own config + object here + m_embeddedHtmlHelp.SetHelpWindow(m_embeddedHelpWindow); + m_embeddedHelpWindow-Create(this, + wxID_ANY, wxDefaultPosition, GetClientSize(), + wxTAB_TRAVERSAL|wxBORDER_NONE, wxHF_DEFAULT_STYLE); + m_embeddedHtmlHelp.AddBook(wxFileName(_T("doc.zip"))); + @endcode + + You should pass the style wxHF_EMBEDDED to the style parameter of + wxHtmlHelpController to allow + the embedded window to be destroyed independently of the help controller. + + @library{wxhtml} + @category{FIXME} +*/ +class wxHtmlHelpWindow : public wxWindow +{ +public: + //@{ + /** + Constructor. + Constructor. For the values of @e helpStyle, please see the documentation for + wxHtmlHelpController. + */ + wxHtmlHelpWindow(wxHtmlHelpData* data = NULL); + wxHtmlHelpWindow(wxWindow* parent, int wxWindowID, + const wxPoint& pos = wxDefaultPosition, + const wxSize& pos = wxDefaultSize, + int style = wxTAB_TRAVERSAL|wxBORDER_NONE, + int helpStyle = wxHF_DEFAULT_STYLE, + wxHtmlHelpData* data = NULL); + //@} + + /** + You may override this virtual method to add more buttons to the help window's + toolbar. @a toolBar is a pointer to the toolbar and @a style is the style + flag as passed to the Create method. + wxToolBar::Realize is called immediately after returning from this function. + See @e samples/html/helpview for an example. + */ + virtual void AddToolbarButtons(wxToolBar* toolBar, int style); + + /** + Creates the help window. See @ref wxhtmlhelpwindow() "the constructor" + for a description of the parameters. + */ + bool Create(wxWindow* parent, wxWindowID id, + const wxPoint& pos = wxDefaultPosition, + const wxSize& pos = wxDefaultSize, + int style = wxTAB_TRAVERSAL|wxBORDER_NONE, + int helpStyle = wxHF_DEFAULT_STYLE, + wxHtmlHelpData* data = NULL); + + /** + Creates contents panel. (May take some time.) + Protected. + */ + void CreateContents(); + + /** + Creates index panel. (May take some time.) + Protected. + */ + void CreateIndex(); + + /** + Creates search panel. + */ + void CreateSearch(); + + //@{ + /** + Displays page x. If not found it will give the user the choice of + searching books. + Looking for the page runs in these steps: + try to locate file named x (if x is for example "doc/howto.htm") + try to open starting page of book x + try to find x in contents (if x is for example "How To ...") + try to find x in index (if x is for example "How To ...") + The second form takes numeric ID as the parameter. + (uses extension to MS format, param name="ID" value=id) + */ + bool Display(const wxString& x); + bool Display(const int id); + //@} + + /** + Displays contents panel. + */ + bool DisplayContents(); + + /** + Displays index panel. + */ + bool DisplayIndex(); + + /** + Returns the wxHtmlHelpData object, which is usually a pointer to the + controller's data. + */ + wxHtmlHelpData* GetData(); + + /** + Search for given keyword. Optionally it searches through the index (mode = + wxHELP_SEARCH_INDEX), default the content (mode = wxHELP_SEARCH_ALL). + */ + bool KeywordSearch(const wxString& keyword, + wxHelpSearchMode mode = wxHELP_SEARCH_ALL); + + /** + Reads the user's settings for this window (see + wxHtmlHelpController::ReadCustomization) + */ + void ReadCustomization(wxConfigBase* cfg, + const wxString& path = wxEmptyString); + + /** + Refresh all panels. This is necessary if a new book was added. + Protected. + */ + void RefreshLists(); + + /** + Sets the frame's title format. @a format must contain exactly one "%s" + (it will be replaced by the page title). + */ + void SetTitleFormat(const wxString& format); + + /** + Associates a wxConfig object with the help window. It is recommended that you + use wxHtmlHelpController::UseConfig instead. + */ + void UseConfig(wxConfigBase* config, + const wxString& rootpath = wxEmptyString); + + /** + Saves the user's settings for this window(see + wxHtmlHelpController::WriteCustomization). + */ + void WriteCustomization(wxConfigBase* cfg, + const wxString& path = wxEmptyString); +}; + diff --git a/interface/wx/html/htmlcell.h b/interface/wx/html/htmlcell.h new file mode 100644 index 0000000000..79c441f684 --- /dev/null +++ b/interface/wx/html/htmlcell.h @@ -0,0 +1,732 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: html/htmlcell.h +// Purpose: interface of wxHtmlColourCell +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxHtmlColourCell + @headerfile htmlcell.h wx/html/htmlcell.h + + This cell changes the colour of either the background or the foreground. + + @library{wxhtml} + @category{FIXME} +*/ +class wxHtmlColourCell : public wxHtmlCell +{ +public: + /** + Constructor. + + @param clr + The color + @param flags + Can be one of following: + + + + + + + wxHTML_CLR_FOREGROUND + + + + + change color of text + + + + + + wxHTML_CLR_BACKGROUND + + + + + change background color + */ + wxHtmlColourCell(wxColour clr, int flags = wxHTML_CLR_FOREGROUND); +}; + + + +/** + @class wxHtmlWidgetCell + @headerfile htmlcell.h wx/html/htmlcell.h + + wxHtmlWidgetCell is a class that provides a connection between HTML cells and + widgets (an object derived + from wxWindow). You can use it to display things like forms, input boxes etc. + in an HTML window. + + wxHtmlWidgetCell takes care of resizing and moving window. + + @library{wxhtml} + @category{FIXME} +*/ +class wxHtmlWidgetCell : public wxHtmlCell +{ +public: + /** + Constructor. + + @param wnd + Connected window. It is parent window must be the wxHtmlWindow object within + which it is displayed! + @param w + Floating width. If non-zero width of wnd window is adjusted so that it is + always w percents of parent container's width. (For example w = 100 means + that the window + will always have same width as parent container) + */ + wxHtmlWidgetCell(wxWindow* wnd, int w = 0); +}; + + + +/** + @class wxHtmlCell + @headerfile htmlcell.h wx/html/htmlcell.h + + Internal data structure. It represents fragments of parsed HTML + page, the so-called @b cell - a word, picture, table, horizontal line and so on. + It is used by wxHtmlWindow and + wxHtmlWinParser to represent HTML page in memory. + + You can divide cells into two groups : @e visible cells with non-zero width and + height and @e helper cells (usually with zero width and height) that + perform special actions such as color or font change. + + @library{wxhtml} + @category{FIXME} + + @see @ref overview_cells "Cells Overview", wxHtmlContainerCell +*/ +class wxHtmlCell : public wxObject +{ +public: + /** + Constructor. + */ + wxHtmlCell(); + + /** + This method is used to adjust pagebreak position. The parameter is + variable that contains y-coordinate of page break (= horizontal line that + should not be crossed by words, images etc.). If this cell cannot be divided + into two pieces (each one on another page) then it moves the pagebreak + few pixels up. + Returns @true if pagebreak was modified, @false otherwise + Usage: + */ + virtual bool AdjustPagebreak(int* pagebreak); + + /** + Renders the cell. + + @param dc + Device context to which the cell is to be drawn + @param x,y + Coordinates of parent's upper left corner (origin). You must + add this to m_PosX,m_PosY when passing coordinates to dc's methods + Example : dc - DrawText("hello", x + m_PosX, y + m_PosY) + @param view_y1 + y-coord of the first line visible in window. This is + used to optimize rendering speed + @param view_y2 + y-coord of the last line visible in window. This is + used to optimize rendering speed + */ + virtual void Draw(wxDC& dc, int x, int y, int view_y1, + int view_y2); + + /** + This method is called instead of Draw() when the + cell is certainly out of the screen (and thus invisible). This is not + nonsense - some tags (like wxHtmlColourCell + or font setter) must be drawn even if they are invisible! + + @param dc + Device context to which the cell is to be drawn + @param x,y + Coordinates of parent's upper left corner. You must + add this to m_PosX,m_PosY when passing coordinates to dc's methods + Example : dc - DrawText("hello", x + m_PosX, y + m_PosY) + */ + virtual void DrawInvisible(wxDC& dc, int x, int y); + + /** + Returns pointer to itself if this cell matches condition (or if any of the cells + following in the list matches), @NULL otherwise. + (In other words if you call top-level container's Find it will + return pointer to the first cell that matches the condition) + It is recommended way how to obtain pointer to particular cell or + to cell of some type (e.g. wxHtmlAnchorCell reacts on + wxHTML_COND_ISANCHOR condition) + + @param condition + Unique integer identifier of condition + @param param + Optional parameters + */ + virtual const wxHtmlCell* Find(int condition, const void* param); + + /** + Returns descent value of the cell (m_Descent member). + See explanation: + */ + int GetDescent() const; + + /** + Returns pointer to the first cell in the list. + You can then use child's GetNext() + method to obtain pointer to the next cell in list. + @note This shouldn't be used by the end user. If you need some way of + finding particular cell in the list, try Find() method + instead. + */ + wxHtmlCell* GetFirstChild(); + + /** + Returns height of the cell (m_Height member). + */ + int GetHeight() const; + + /** + Returns unique cell identifier if there is any, empty string otherwise. + */ + virtual wxString GetId() const; + + /** + Returns hypertext link if associated with this cell or @NULL otherwise. + See wxHtmlLinkInfo. + (Note: this makes sense only for visible tags). + + @param x,y + Coordinates of position where the user pressed mouse button. + These coordinates are used e.g. by COLORMAP. Values are relative to the + upper left corner of THIS cell (i.e. from 0 to m_Width or m_Height) + */ + virtual wxHtmlLinkInfo* GetLink(int x = 0, int y = 0) const; + + /** + Returns cursor to show when mouse pointer is over the cell. + + @param window + interface to the parent HTML window + */ + virtual wxCursor GetMouseCursor(wxHtmlWindowInterface* window); + + /** + Returns pointer to the next cell in list (see htmlcell.h if you're + interested in details). + */ + wxHtmlCell* GetNext() const; + + /** + Returns pointer to parent container. + */ + wxHtmlContainerCell* GetParent() const; + + /** + Returns X position within parent (the value is relative to parent's + upper left corner). The returned value is meaningful only if + parent's Layout() was called before! + */ + int GetPosX() const; + + /** + Returns Y position within parent (the value is relative to parent's + upper left corner). The returned value is meaningful only if + parent's Layout() was called before! + */ + int GetPosY() const; + + /** + Returns width of the cell (m_Width member). + */ + int GetWidth() const; + + /** + This method performs two actions: + adjusts the cell's width according to the fact that maximal possible width is + @e w. + (this has sense when working with horizontal lines, tables etc.) + prepares layout (=fill-in m_PosX, m_PosY (and sometimes m_Height) members) + based on actual width @e w + It must be called before displaying cells structure because + m_PosX and m_PosY are undefined (or invalid) + before calling Layout. + */ + virtual void Layout(int w); + + /** + This function is simple event handler. Each time the user clicks mouse button + over a cell within wxHtmlWindow this method of that + cell is called. Default behavior is to call + wxHtmlWindow::LoadPage. + + @param window + interface to the parent HTML window + @param pos + coordinates of mouse click (this is relative to cell's origin + @param event + mouse event that triggered the call + + @return @true if a link was clicked, @false otherwise. + */ + virtual bool ProcessMouseClick(wxHtmlWindowInterface* window, + const wxPoint& pos, + const wxMouseEvent& event); + + /** + Sets unique cell identifier. Default value is no identifier, i.e. empty string. + */ + void SetId(const wxString& id); + + /** + Sets the hypertext link associated with this cell. (Default value + is wxHtmlLinkInfo("", "") (no link)) + */ + void SetLink(const wxHtmlLinkInfo& link); + + /** + Sets the next cell in the list. This shouldn't be called by user - it is + to be used only by wxHtmlContainerCell::InsertCell. + */ + void SetNext(wxHtmlCell cell); + + /** + Sets parent container of this cell. This is called from + wxHtmlContainerCell::InsertCell. + */ + void SetParent(wxHtmlContainerCell p); + + /** + Sets the cell's position within parent container. + */ + void SetPos(int x, int y); +}; + + + +/** + @class wxHtmlContainerCell + @headerfile htmlcell.h wx/html/htmlcell.h + + The wxHtmlContainerCell class is an implementation of a cell that may + contain more cells in it. It is heavily used in the wxHTML layout algorithm. + + @library{wxhtml} + @category{FIXME} + + @see @ref overview_cells "Cells Overview" +*/ +class wxHtmlContainerCell : public wxHtmlCell +{ +public: + /** + Constructor. @a parent is pointer to parent container or @NULL. + */ + wxHtmlContainerCell(wxHtmlContainerCell parent); + + /** + Returns container's horizontal alignment. + */ + int GetAlignHor() const; + + /** + Returns container's vertical alignment. + */ + int GetAlignVer() const; + + /** + Returns the background colour of the container or @c wxNullColour if no + background + colour is set. + */ + wxColour GetBackgroundColour(); + + /** + Returns the indentation. @a ind is one of the @b wxHTML_INDENT_* constants. + @note You must call GetIndentUnits() + with same @a ind parameter in order to correctly interpret the returned integer + value. + It is NOT always in pixels! + */ + int GetIndent(int ind) const; + + /** + Returns the units of indentation for @a ind where @a ind is one + of the @b wxHTML_INDENT_* constants. + */ + int GetIndentUnits(int ind) const; + + /** + Inserts new cell into the container. + */ + void InsertCell(wxHtmlCell cell); + + /** + Sets the container's alignment (both horizontal and vertical) according to + the values stored in @e tag. (Tags @c ALIGN parameter is extracted.) In fact + it is only a front-end to SetAlignHor() + and SetAlignVer(). + */ + void SetAlign(const wxHtmlTag& tag); + + /** + Sets the container's @e horizontal alignment. During wxHtmlCell::Layout + each line is aligned according to @a al value. + + @param al + new horizontal alignment. May be one of these values: + + + + + + + wxHTML_ALIGN_LEFT + + + + + lines are left-aligned (default) + + + + + + wxHTML_ALIGN_JUSTIFY + + + + + lines are justified + + + + + + wxHTML_ALIGN_CENTER + + + + + lines are centered + + + + + + wxHTML_ALIGN_RIGHT + + + + + lines are right-aligned + */ + void SetAlignHor(int al); + + /** + Sets the container's @e vertical alignment. This is per-line alignment! + + @param al + new vertical alignment. May be one of these values: + + + + + + + wxHTML_ALIGN_BOTTOM + + + + + cells are over the line (default) + + + + + + wxHTML_ALIGN_CENTER + + + + + cells are centered on line + + + + + + wxHTML_ALIGN_TOP + + + + + cells are under the line + */ + void SetAlignVer(int al); + + /** + Sets the background colour for this container. + */ + void SetBackgroundColour(const wxColour& clr); + + /** + Sets the border (frame) colours. A border is a rectangle around the container. + + @param clr1 + Colour of top and left lines + @param clr2 + Colour of bottom and right lines + */ + void SetBorder(const wxColour& clr1, const wxColour& clr2); + + /** + Sets the indentation (free space between borders of container and subcells). + + @param i + Indentation value. + @param what + Determines which of the four borders we're setting. It is OR + combination of following constants: + + + + + + + wxHTML_INDENT_TOP + + + + + top border + + + + + + wxHTML_INDENT_BOTTOM + + + + + bottom + + + + + + wxHTML_INDENT_LEFT + + + + + left + + + + + + wxHTML_INDENT_RIGHT + + + + + right + + + + + + wxHTML_INDENT_HORIZONTAL + + + + + left and right + + + + + + wxHTML_INDENT_VERTICAL + + + + + top and bottom + + + + + + wxHTML_INDENT_ALL + + + + + all 4 borders + @param units + Units of i. This parameter affects interpretation of value. + + + + + + + wxHTML_UNITS_PIXELS + + + + + i is number of pixels + + + + + + wxHTML_UNITS_PERCENT + + + + + i is interpreted as percents of width + of parent container + */ + void SetIndent(int i, int what, int units = wxHTML_UNITS_PIXELS); + + /** + Sets minimal height of the container. + When container's wxHtmlCell::Layout is called, m_Height + is set depending on layout of subcells to the height of area covered + by layed-out subcells. Calling this method guarantees you that the height + of container is never smaller than @a h - even if the subcells cover + much smaller area. + + @param h + The minimal height. + @param align + If height of the container is lower than the minimum height, empty space + must be inserted + somewhere in order to ensure minimal height. This parameter is one of + wxHTML_ALIGN_TOP, + wxHTML_ALIGN_BOTTOM, wxHTML_ALIGN_CENTER. It refers to the contents, not to + the + empty place. + */ + void SetMinHeight(int h, int align = wxHTML_ALIGN_TOP); + + //@{ + /** + Sets floating width adjustment. + The normal behaviour of container is that its width is the same as the width of + parent container (and thus you can have only one sub-container per line). + You can change this by setting FWA. + @a pixel_scale is number of real pixels that equals to 1 HTML pixel. + + @param w + Width of the container. If the value is negative it means + complement to full width of parent container (e.g. + SetWidthFloat(-50, wxHTML_UNITS_PIXELS) sets the width + of container to parent's width minus 50 pixels. This is useful when + creating tables - you can call SetWidthFloat(50) and SetWidthFloat(-50)) + @param units + Units of w This parameter affects the interpretation of value. + + + + + + + wxHTML_UNITS_PIXELS + + + + + w is number of pixels + + + + + + wxHTML_UNITS_PERCENT + + + + + w is interpreted as percents of width + of parent container + @param tag + In the second version of method, w and units + info is extracted from tag's WIDTH parameter. + */ + void SetWidthFloat(int w, int units); + void SetWidthFloat(const wxHtmlTag& tag, + double pixel_scale = 1.0); + //@} +}; + + + +/** + @class wxHtmlLinkInfo + @headerfile htmlcell.h wx/html/htmlcell.h + + This class stores all necessary information about hypertext + links (as represented by @c A tag in HTML documents). In + current implementation it stores URL and target frame name. + @e Note that frames are not currently supported by wxHTML! + + @library{wxhtml} + @category{FIXME} +*/ +class wxHtmlLinkInfo : public wxObject +{ +public: + //@{ + /** + Construct hypertext link from HREF (aka URL) and TARGET (name of target + frame). + */ + wxHtmlLinkInfo(); + wxHtmlLinkInfo(const wxString& href, + const wxString& target = wxEmptyString); + //@} + + /** + Return pointer to event that generated OnLinkClicked event. Valid + only within wxHtmlWindow::OnLinkClicked, + @NULL otherwise. + */ + const wxMouseEvent* GetEvent(); + + /** + Return @e HREF value of the @c A tag. + */ + wxString GetHref(); + + /** + Return pointer to the cell that was clicked. Valid + only within wxHtmlWindow::OnLinkClicked, + @NULL otherwise. + */ + const wxHtmlCell* GetHtmlCell(); + + /** + Return @e TARGET value of the @c A tag (this value + is used to specify in which frame should be the page pointed + by @ref gethref() Href opened). + */ + wxString GetTarget(); +}; + diff --git a/interface/wx/html/htmlfilt.h b/interface/wx/html/htmlfilt.h new file mode 100644 index 0000000000..9a40dbcff1 --- /dev/null +++ b/interface/wx/html/htmlfilt.h @@ -0,0 +1,41 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: html/htmlfilt.h +// Purpose: interface of wxHtmlFilter +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxHtmlFilter + @headerfile htmlfilt.h wx/html/htmlfilt.h + + This class is the parent class of input filters for wxHtmlWindow. + It allows you to read and display files of different file formats. + + @library{wxhtml} + @category{FIXME} + + @see Overview() +*/ +class wxHtmlFilter : public wxObject +{ +public: + /** + Constructor. + */ + wxHtmlFilter(); + + /** + Returns @true if this filter is capable of reading file @e file. + Example: + */ + bool CanRead(const wxFSFile& file); + + /** + Reads the file and returns string with HTML document. + Example: + */ + wxString ReadFile(const wxFSFile& file); +}; + diff --git a/interface/wx/html/htmlpars.h b/interface/wx/html/htmlpars.h new file mode 100644 index 0000000000..1131d385b3 --- /dev/null +++ b/interface/wx/html/htmlpars.h @@ -0,0 +1,270 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: html/htmlpars.h +// Purpose: interface of wxHtmlTagHandler +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxHtmlTagHandler + @headerfile htmlpars.h wx/html/htmlpars.h + + + @library{wxhtml} + @category{html} + + @see Overview(), wxHtmlTag +*/ +class wxHtmlTagHandler : public wxObject +{ +public: + /** + Constructor. + */ + wxHtmlTagHandler(); + + /** + Returns list of supported tags. The list is in uppercase and tags + are delimited by ','. Example : @c "I,B,FONT,P" + */ + virtual wxString GetSupportedTags(); + + /** + This is the core method of each handler. It is called each time + one of supported tags is detected. @a tag contains all necessary + info (see wxHtmlTag for details). + + @return @true if ParseInner was called, @false otherwise. + */ + virtual bool HandleTag(const wxHtmlTag& tag); + + /** + This method calls parser's wxHtmlParser::DoParsing method + for the string between this tag and the paired ending tag: + + In this example, a call to ParseInner (with @a tag pointing to A tag) + will parse 'Hello, world!'. + */ + void ParseInner(const wxHtmlTag& tag); + + /** + Assigns @a parser to this handler. Each @b instance of handler + is guaranteed to be called only from the parser. + */ + virtual void SetParser(wxHtmlParser parser); + + /** + @b wxHtmlParser* m_Parser + This attribute is used to access parent parser. It is protected so that + it can't be accessed by user but can be accessed from derived classes. + */ +}; + + + +/** + @class wxHtmlParser + @headerfile htmlpars.h wx/html/htmlpars.h + + Classes derived from this handle the @b generic parsing of HTML documents: it + scans + the document and divide it into blocks of tags (where one block + consists of beginning and ending tag and of text between these + two tags). + + It is independent from wxHtmlWindow and can be used as stand-alone parser + (Julian Smart's idea of speech-only HTML viewer or wget-like utility - + see InetGet sample for example). + + It uses system of tag handlers to parse the HTML document. Tag handlers + are not statically shared by all instances but are created for each + wxHtmlParser instance. The reason is that the handler may contain + document-specific temporary data used during parsing (e.g. complicated + structures like tables). + + Typically the user calls only the wxHtmlParser::Parse method. + + @library{wxhtml} + @category{html} + + @see @ref overview_cells "Cells Overview", @ref overview_handlers "Tag Handlers + Overview", wxHtmlTag +*/ +class wxHtmlParser +{ +public: + /** + Constructor. + */ + wxHtmlParser(); + + /** + This may (and may not) be overwritten in derived class. + This method is called each time new tag is about to be added. + @a tag contains information about the tag. (See wxHtmlTag + for details.) + Default (wxHtmlParser) behaviour is this: + First it finds a handler capable of handling this tag and then it calls + handler's HandleTag method. + */ + void AddTag(const wxHtmlTag& tag); + + /** + Adds handler to the internal list ( hash table) of handlers. This + method should not be called directly by user but rather by derived class' + constructor. + This adds the handler to this @b instance of wxHtmlParser, not to + all objects of this class! (Static front-end to AddTagHandler is provided + by wxHtmlWinParser). + All handlers are deleted on object deletion. + */ + virtual void AddTagHandler(wxHtmlTagHandler handler); + + /** + Must be overwritten in derived class. + This method is called by DoParsing() + each time a part of text is parsed. @a txt is NOT only one word, it is + substring of input. It is not formatted or preprocessed (so white spaces are + unmodified). + */ + virtual void AddWord(const wxString& txt); + + //@{ + /** + Parses the m_Source from begin_pos to end_pos-1. + (in noparams version it parses whole m_Source) + */ + void DoParsing(int begin_pos, int end_pos); + void DoParsing(); + //@} + + /** + This must be called after DoParsing(). + */ + virtual void DoneParser(); + + /** + Returns pointer to the file system. Because each tag handler has + reference to it is parent parser it can easily request the file by + calling + */ + wxFileSystem* GetFS() const; + + /** + Returns product of parsing. Returned value is result of parsing + of the document. The type of this result depends on internal + representation in derived parser (but it must be derived from wxObject!). + See wxHtmlWinParser for details. + */ + virtual wxObject* GetProduct(); + + /** + Returns pointer to the source being parsed. + */ + wxString* GetSource(); + + /** + Setups the parser for parsing the @a source string. (Should be overridden + in derived class) + */ + virtual void InitParser(const wxString& source); + + /** + Opens given URL and returns @c wxFSFile object that can be used to read data + from it. This method may return @NULL in one of two cases: either the URL doesn't + point to any valid resource or the URL is blocked by overridden implementation + of @e OpenURL in derived class. + + @param type + Indicates type of the resource. Is one of: + + + + + + + wxHTML_URL_PAGE + + + + + Opening a HTML page. + + + + + + wxHTML_URL_IMAGE + + + + + Opening an image. + + + + + + wxHTML_URL_OTHER + + + + + Opening a resource that doesn't fall into + any other category. + @param url + URL being opened. + */ + virtual wxFSFile* OpenURL(wxHtmlURLType type, + const wxString& url); + + /** + Proceeds parsing of the document. This is end-user method. You can simply + call it when you need to obtain parsed output (which is parser-specific) + The method does these things: + calls @ref initparser() InitParser(source) + calls DoParsing() + calls GetProduct() + calls DoneParser() + returns value returned by GetProduct + You shouldn't use InitParser, DoParsing, GetProduct or DoneParser directly. + */ + wxObject* Parse(const wxString& source); + + /** + Restores parser's state before last call to + PushTagHandler(). + */ + void PopTagHandler(); + + /** + Forces the handler to handle additional tags + (not returned by wxHtmlTagHandler::GetSupportedTags). + The handler should already be added to this parser. + + @param handler + the handler + @param tags + List of tags (in same format as GetSupportedTags's return value). The parser + will redirect these tags to handler (until call to PopTagHandler). + */ + void PushTagHandler(wxHtmlTagHandler* handler, + const wxString& tags); + + /** + Sets the virtual file system that will be used to request additional + files. (For example @c IMG tag handler requests wxFSFile with the + image data.) + */ + void SetFS(wxFileSystem fs); + + /** + Call this function to interrupt parsing from a tag handler. No more tags + will be parsed afterward. This function may only be called from + Parse() or any function called + by it (i.e. from tag handlers). + */ + void StopParsing(); +}; + diff --git a/interface/wx/html/htmltag.h b/interface/wx/html/htmltag.h new file mode 100644 index 0000000000..974106a761 --- /dev/null +++ b/interface/wx/html/htmltag.h @@ -0,0 +1,130 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: html/htmltag.h +// Purpose: interface of wxHtmlTag +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxHtmlTag + @headerfile htmltag.h wx/html/htmltag.h + + This class represents a single HTML tag. + It is used by @ref overview_handlers "tag handlers". + + @library{wxhtml} + @category{FIXME} +*/ +class wxHtmlTag +{ +public: + /** + Constructor. You will probably never have to construct a wxHtmlTag object + yourself. Feel free to ignore the constructor parameters. + Have a look at src/html/htmlpars.cpp if you're interested in creating it. + */ + wxHtmlTag(wxHtmlTag* parent, const wxString& source, int pos, + int end_pos, wxHtmlTagsCache* cache, + wxHtmlEntitiesParser* entParser); + + /** + Returns a string containing all parameters. + Example : tag contains @c FONT SIZE=+2 COLOR="#000000". Call to + tag.GetAllParams() would return @c SIZE=+2 COLOR="#000000". + */ + const wxString GetAllParams() const; + + /** + Returns beginning position of the text @e between this tag and paired + ending tag. + See explanation (returned position is marked with '|'): + */ + int GetBeginPos() const; + + /** + Returns ending position of the text @e between this tag and paired + ending tag. + See explanation (returned position is marked with '|'): + */ + int GetEndPos1() const; + + /** + Returns ending position 2 of the text @e between this tag and paired + ending tag. + See explanation (returned position is marked with '|'): + */ + int GetEndPos2() const; + + /** + Returns tag's name. The name is always in uppercase and it doesn't contain + " or '/' characters. (So the name of @c FONT SIZE=+2 tag is "FONT" + and name of @c /table is "TABLE") + */ + wxString GetName() const; + + /** + Returns the value of the parameter. You should check whether the + parameter exists or not (use wxHtmlTag::HasParam) first. + + @param par + The parameter's name. + @param with_quotes + @true if you want to get quotes as well. See example. + */ + wxString GetParam(const wxString& par, bool with_quotes = false) const; + + /** + Interprets tag parameter @a par as colour specification and saves its value + into wxColour variable pointed by @e clr. + Returns @true on success and @false if @a par is not colour specification or + if the tag has no such parameter. + */ + bool GetParamAsColour(const wxString& par, wxColour* clr) const; + + /** + Interprets tag parameter @a par as an integer and saves its value + into int variable pointed by @e value. + Returns @true on success and @false if @a par is not an integer or + if the tag has no such parameter. + */ + bool GetParamAsInt(const wxString& par, int* value) const; + + /** + Returns @true if this tag is paired with ending tag, @false otherwise. + See the example of HTML document: + + In this example tags HTML and BODY have ending tags, first P and BR + doesn't have ending tag while the second P has. The third P tag (which + is ending itself) of course doesn't have ending tag. + */ + bool HasEnding() const; + + /** + Returns @true if the tag has a parameter of the given name. + Example : @c FONT SIZE=+2 COLOR="#FF00FF" has two parameters named + "SIZE" and "COLOR". + + @param par + the parameter you're looking for. + */ + bool HasParam(const wxString& par) const; + + /** + This method scans the given parameter. Usage is exactly the same as sscanf's + usage except that you don't pass a string but a parameter name as the first + argument + and you can only retrieve one value (i.e. you can use only one "%" element + in @e format). + + @param par + The name of the tag you want to query + @param format + scanf()-like format string. + @param value + pointer to a variable to store the value in + */ + wxString ScanParam(const wxString& par, const wxChar* format, + void* value) const; +}; + diff --git a/interface/wx/html/htmlwin.h b/interface/wx/html/htmlwin.h new file mode 100644 index 0000000000..3b6ccc2912 --- /dev/null +++ b/interface/wx/html/htmlwin.h @@ -0,0 +1,483 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: html/htmlwin.h +// Purpose: interface of wxHtmlWindow +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxHtmlWindow + @headerfile htmlwin.h wx/html/htmlwin.h + + wxHtmlWindow is probably the only class you will directly use + unless you want to do something special (like adding new tag + handlers or MIME filters). + + The purpose of this class is to display HTML pages (either local + file or downloaded via HTTP protocol) in a window. The width + of the window is constant - given in the constructor - and virtual height + is changed dynamically depending on page size. + Once the window is created you can set its content by calling + @ref wxHtmlWindow::setpage SetPage(text), + @ref wxHtmlWindow::loadpage LoadPage(filename) or + wxHtmlWindow::LoadFile. + + @beginStyleTable + @style{wxHW_SCROLLBAR_NEVER} + Never display scrollbars, not even when the page is larger than the + window. + @style{wxHW_SCROLLBAR_AUTO} + Display scrollbars only if page's size exceeds window's size. + @style{wxHW_NO_SELECTION} + Don't allow the user to select text. + @endStyleTable + + @library{wxhtml} + @category{html} + + @see wxHtmlLinkEvent, wxHtmlCellEvent +*/ +class wxHtmlWindow : public wxScrolledWindow +{ +public: + //@{ + /** + Constructor. The parameters are the same as wxScrolled::wxScrolled() + constructor. + + @param style + Window style. See wxHtmlWindow. + */ + wxHtmlWindow(); + wxHtmlWindow(wxWindow parent, wxWindowID id = -1, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxHW_DEFAULT_STYLE, + const wxString& name = "htmlWindow"); + //@} + + /** + Adds @ref overview_filters "input filter" to the static list of available + filters. These filters are present by default: + @c text/html MIME type + @c image/* MIME types + Plain Text filter (this filter is used if no other filter matches) + */ + static void AddFilter(wxHtmlFilter filter); + + /** + Appends HTML fragment to currently displayed text and refreshes the window. + + @param source + HTML code fragment + + @return @false if an error occurred, @true otherwise. + */ + bool AppendToPage(const wxString& source); + + /** + Returns pointer to the top-level container. + See also: @ref overview_cells "Cells Overview", + @ref overview_printing + */ + wxHtmlContainerCell* GetInternalRepresentation() const; + + /** + Returns anchor within currently opened page + (see wxHtmlWindow::GetOpenedPage). + If no page is opened or if the displayed page wasn't + produced by call to LoadPage, empty string is returned. + */ + wxString GetOpenedAnchor(); + + /** + Returns full location of the opened page. If no page is opened or if the + displayed page wasn't + produced by call to LoadPage, empty string is returned. + */ + wxString GetOpenedPage(); + + /** + Returns title of the opened page or wxEmptyString if current page does not + contain @c TITLE tag. + */ + wxString GetOpenedPageTitle(); + + /** + Returns the related frame. + */ + wxFrame* GetRelatedFrame() const; + + /** + Moves back to the previous page. (each page displayed using + LoadPage() is stored in history list.) + */ + bool HistoryBack(); + + /** + Returns @true if it is possible to go back in the history (i.e. HistoryBack() + won't fail). + */ + bool HistoryCanBack(); + + /** + Returns @true if it is possible to go forward in the history (i.e. HistoryBack() + won't fail). + */ + bool HistoryCanForward(); + + /** + Clears history. + */ + void HistoryClear(); + + /** + Moves to next page in history. + */ + bool HistoryForward(); + + /** + Loads HTML page from file and displays it. + + @return @false if an error occurred, @true otherwise + + @see LoadPage() + */ + virtual bool LoadFile(const wxFileName& filename); + + /** + Unlike SetPage this function first loads HTML page from @a location + and then displays it. See example: + + @param location + The address of document. See wxFileSystem for details on address format and + behaviour of "opener". + + @return @false if an error occurred, @true otherwise + + @see LoadFile() + */ + virtual bool LoadPage(const wxString& location); + + /** + This method is called when a mouse button is clicked inside wxHtmlWindow. + The default behaviour is to emit a wxHtmlCellEvent + and, if the event was not processed or skipped, call + OnLinkClicked() if the cell contains an + hypertext link. + Overloading this method is deprecated; intercept the event instead. + + @param cell + The cell inside which the mouse was clicked, always a simple + (i.e. non-container) cell + @param x, y + The logical coordinates of the click point + @param event + The mouse event containing other information about the click + + @return @true if a link was clicked, @false otherwise. + */ + virtual bool OnCellClicked(wxHtmlCell cell, wxCoord x, wxCoord y, + const wxMouseEvent& event); + + /** + This method is called when a mouse moves over an HTML cell. + Default behaviour is to emit a wxHtmlCellEvent. + Overloading this method is deprecated; intercept the event instead. + + @param cell + The cell inside which the mouse is currently, always a simple + (i.e. non-container) cell + @param x, y + The logical coordinates of the click point + */ + virtual void OnCellMouseHover(wxHtmlCell cell, wxCoord x, + wxCoord y); + + /** + Called when user clicks on hypertext link. Default behaviour is to emit a + wxHtmlLinkEvent and, if the event was not processed + or skipped, call LoadPage() and do nothing else. + Overloading this method is deprecated; intercept the event instead. + Also see wxHtmlLinkInfo. + */ + virtual void OnLinkClicked(const wxHtmlLinkInfo& link); + + /** + Called when an URL is being opened (either when the user clicks on a link or + an image is loaded). The URL will be opened only if OnOpeningURL returns + @c wxHTML_OPEN. This method is called by + wxHtmlParser::OpenURL. + You can override OnOpeningURL to selectively block some + URLs (e.g. for security reasons) or to redirect them elsewhere. Default + behaviour is to always return @c wxHTML_OPEN. + + @param type + Indicates type of the resource. Is one of + + + + + + + wxHTML_URL_PAGE + + + + + Opening a HTML page. + + + + + + wxHTML_URL_IMAGE + + + + + Opening an image. + + + + + + wxHTML_URL_OTHER + + + + + Opening a resource that doesn't fall into + any other category. + @param url + URL being opened. + @param redirect + Pointer to wxString variable that must be filled with an + URL if OnOpeningURL returns wxHTML_REDIRECT. + */ + virtual wxHtmlOpeningStatus OnOpeningURL(wxHtmlURLType type, + const wxString& url, + wxString* redirect); + + /** + Called on parsing @c TITLE tag. + */ + virtual void OnSetTitle(const wxString& title); + + /** + This reads custom settings from wxConfig. It uses the path 'path' + if given, otherwise it saves info into currently selected path. + The values are stored in sub-path @c wxHtmlWindow + Read values: all things set by SetFonts, SetBorders. + + @param cfg + wxConfig from which you want to read the configuration. + @param path + Optional path in config tree. If not given current path is used. + */ + virtual void ReadCustomization(wxConfigBase cfg, + wxString path = wxEmptyString); + + /** + Selects all text in the window. + + @see SelectLine(), SelectWord() + */ + void SelectAll(); + + /** + Selects the line of text that @a pos points at. Note that @e pos + is relative to the top of displayed page, not to window's origin, use + wxScrolled::CalcUnscrolledPosition() + to convert physical coordinate. + + @see SelectAll(), SelectWord() + */ + void SelectLine(const wxPoint& pos); + + /** + Selects the word at position @e pos. Note that @e pos + is relative to the top of displayed page, not to window's origin, use + wxScrolled::CalcUnscrolledPosition() + to convert physical coordinate. + + @see SelectAll(), SelectLine() + */ + void SelectWord(const wxPoint& pos); + + /** + Returns current selection as plain text. Returns empty string if no text + is currently selected. + */ + wxString SelectionToText(); + + /** + This function sets the space between border of window and HTML contents. See + image: + + @param b + indentation from borders in pixels + */ + void SetBorders(int b); + + /** + This function sets font sizes and faces. + + @param normal_face + This is face name for normal (i.e. non-fixed) font. + It can be either empty string (then the default face is chosen) or + platform-specific face name. Examples are "helvetica" under Unix or + "Times New Roman" under Windows. + @param fixed_face + The same thing for fixed face ( TT../TT ) + @param sizes + This is an array of 7 items of int type. + The values represent size of font with HTML size from -2 to +4 + ( FONT SIZE=-2 to FONT SIZE=+4 ). Default sizes are used if sizes + is @NULL. + */ + void SetFonts(const wxString& normal_face, + const wxString& fixed_face, + const int sizes = NULL); + + /** + Sets HTML page and display it. This won't @b load the page!! + It will display the @e source. See example: + + If you want to load a document from some location use + LoadPage() instead. + + @param source + The HTML document source to be displayed. + + @return @false if an error occurred, @true otherwise. + */ + bool SetPage(const wxString& source); + + /** + Sets the frame in which page title will be displayed. @a format is format of + frame title, e.g. "HtmlHelp : %s". It must contain exactly one %s. This + %s is substituted with HTML page title. + */ + void SetRelatedFrame(wxFrame* frame, const wxString& format); + + /** + @b After calling SetRelatedFrame(), + this sets statusbar slot where messages will be displayed. + (Default is -1 = no messages.) + + @param index + Statusbar slot number (0..n) + */ + void SetRelatedStatusBar(int index); + + /** + @b Sets the associated statusbar where messages will be displayed. + Call this instead of SetRelatedFrame() if you want statusbar updates only, + no changing of the frame title. + + @param statusbar + Statusbar pointer + @param index + Statusbar slot number (0..n) + + @since 2.9.0 + */ + void SetRelatedStatusBar(wxStatusBar* statusbar, int index = 0); + + /** + Returns content of currently displayed page as plain text. + */ + wxString ToText(); + + /** + Saves custom settings into wxConfig. It uses the path 'path' + if given, otherwise it saves info into currently selected path. + Regardless of whether the path is given or not, the function creates sub-path + @c wxHtmlWindow. + Saved values: all things set by SetFonts, SetBorders. + + @param cfg + wxConfig to which you want to save the configuration. + @param path + Optional path in config tree. If not given, the current path is used. + */ + virtual void WriteCustomization(wxConfigBase cfg, + wxString path = wxEmptyString); +}; + + + +/** + @class wxHtmlLinkEvent + @headerfile htmlwin.h wx/html/htmlwin.h + + This event class is used for the events generated by wxHtmlWindow. + + @library{wxhtml} + @category{FIXME} +*/ +class wxHtmlLinkEvent : public wxCommandEvent +{ +public: + /** + The constructor is not normally used by the user code. + */ + wxHyperlinkEvent(int id, const wxHtmlLinkInfo& linkinfo); + + /** + Returns the wxHtmlLinkInfo which contains info about the cell clicked and the + hyperlink it contains. + */ + const wxHtmlLinkInfo GetLinkInfo() const; +}; + + + +/** + @class wxHtmlCellEvent + @headerfile htmlwin.h wx/html/htmlwin.h + + This event class is used for the events generated by wxHtmlWindow. + + @library{wxhtml} + @category{FIXME} +*/ +class wxHtmlCellEvent : public wxCommandEvent +{ +public: + /** + The constructor is not normally used by the user code. + */ + wxHtmlCellEvent(wxEventType commandType, int id, + wxHtmlCell* cell, + const wxPoint& point); + + /** + Returns the wxHtmlCellEvent associated with the event. + */ + wxHtmlCell* GetCell() const; + + /** + Returns @true if @ref setlinkclicked() SetLinkClicked(@true) has previously + been called; + @false otherwise. + */ + bool GetLinkClicked() const; + + /** + Returns the wxPoint associated with the event. + */ + wxPoint GetPoint() const; + + /** + Call this function with @c linkclicked set to @true if the cell which has + been clicked contained a link or + @false otherwise (which is the default). With this function the event handler + can return info to the + wxHtmlWindow which sent the event. + */ + bool SetLinkClicked(bool linkclicked); +}; + diff --git a/interface/wx/html/htmprint.h b/interface/wx/html/htmprint.h new file mode 100644 index 0000000000..7e5cb99a06 --- /dev/null +++ b/interface/wx/html/htmprint.h @@ -0,0 +1,330 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: html/htmprint.h +// Purpose: interface of wxHtmlDCRenderer +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxHtmlDCRenderer + @headerfile htmprint.h wx/html/htmprint.h + + This class can render HTML document into a specified area of a DC. You can use + it + in your own printing code, although use of wxHtmlEasyPrinting + or wxHtmlPrintout is strongly recommended. + + @library{wxhtml} + @category{FIXME} +*/ +class wxHtmlDCRenderer : public wxObject +{ +public: + /** + Constructor. + */ + wxHtmlDCRenderer(); + + /** + Returns the height of the HTML text. This is important if area height (see + wxHtmlDCRenderer::SetSize) + is smaller that total height and thus the page cannot fit into it. In that case + you're supposed to + call Render() as long as its return value is smaller than GetTotalHeight's. + */ + int GetTotalHeight(); + + /** + Renders HTML text to the DC. + + @param x,y + position of upper-left corner of printing rectangle (see SetSize) + @param from + y-coordinate of the very first visible cell + @param dont_render + if @true then this method only returns y coordinate of the next page + and does not output anything + */ + int Render(int x, int y, int from = 0, int dont_render = false); + + /** + Assign DC instance to the renderer. + @a pixel_scale can be used when rendering to high-resolution DCs (e.g. printer) + to adjust size of pixel metrics. + (Many dimensions in HTML are given in pixels -- e.g. image sizes. 300x300 image + would be only one + inch wide on typical printer. With pixel_scale = 3.0 it would be 3 inches.) + */ + void SetDC(wxDC* dc, double pixel_scale = 1.0); + + /** + Sets fonts. See wxHtmlWindow::SetFonts for + detailed description. + See also SetSize(). + */ + void SetFonts(const wxString& normal_face, + const wxString& fixed_face, + const int sizes = NULL); + + /** + Assign text to the renderer. Render() then draws + the text onto DC. + + @param html + HTML text. This is not a filename. + @param basepath + base directory (html string would be stored there if it was in + file). It is used to determine path for loading images, for example. + @param isdir + @false if basepath is filename, @true if it is directory name + (see wxFileSystem for detailed explanation) + */ + void SetHtmlText(const wxString& html, + const wxString& basepath = wxEmptyString, + bool isdir = true); + + /** + Set size of output rectangle, in pixels. Note that you @b can't change + width of the rectangle between calls to wxHtmlDCRenderer::Render! + (You can freely change height.) + */ + void SetSize(int width, int height); +}; + + + +/** + @class wxHtmlEasyPrinting + @headerfile htmprint.h wx/html/htmprint.h + + This class provides very simple interface to printing + architecture. It allows you to print HTML documents using + only a few commands. + + @library{wxhtml} + @category{html} +*/ +class wxHtmlEasyPrinting : public wxObject +{ +public: + /** + Constructor. + + @param name + Name of the printing object. Used by preview frames and setup dialogs. + @param parentWindow + pointer to the window that will own the preview frame and setup dialogs. + May be @NULL. + */ + wxHtmlEasyPrinting(const wxString& name = "Printing", + wxWindow* parentWindow = NULL); + + /** + Returns a pointer to wxPageSetupDialogData instance used by + this class. You can set its parameters (via SetXXXX methods). + */ + wxPageSetupDialogData* GetPageSetupData(); + + /** + Gets the parent window for dialogs. + */ + wxWindow* GetParentWindow() const; + + /** + Returns pointer to wxPrintData instance used by this class. You can + set its parameters (via SetXXXX methods). + */ + wxPrintData* GetPrintData(); + + /** + Display page setup dialog and allows the user to modify settings. + */ + void PageSetup(); + + /** + Preview HTML file. + Returns @false in case of error -- call + wxPrinter::GetLastError to get detailed + information about the kind of the error. + */ + bool PreviewFile(const wxString& htmlfile); + + /** + Preview HTML text (not file!). + Returns @false in case of error -- call + wxPrinter::GetLastError to get detailed + information about the kind of the error. + + @param htmltext + HTML text. + @param basepath + base directory (html string would be stored there if it was in + file). It is used to determine path for loading images, for example. + */ + bool PreviewText(const wxString& htmltext, + const wxString& basepath = wxEmptyString); + + /** + Print HTML file. + Returns @false in case of error -- call + wxPrinter::GetLastError to get detailed + information about the kind of the error. + */ + bool PrintFile(const wxString& htmlfile); + + /** + Print HTML text (not file!). + Returns @false in case of error -- call + wxPrinter::GetLastError to get detailed + information about the kind of the error. + + @param htmltext + HTML text. + @param basepath + base directory (html string would be stored there if it was in + file). It is used to determine path for loading images, for example. + */ + bool PrintText(const wxString& htmltext, + const wxString& basepath = wxEmptyString); + + /** + Sets fonts. See wxHtmlWindow::SetFonts for + detailed description. + */ + void SetFonts(const wxString& normal_face, + const wxString& fixed_face, + const int sizes = NULL); + + /** + Set page footer. The following macros can be used inside it: + @DATE@ is replaced by the current date in default format + @PAGENUM@ is replaced by page number + @PAGESCNT@ is replaced by total number of pages + @TIME@ is replaced by the current time in default format + @TITLE@ is replaced with the title of the document + + @param footer + HTML text to be used as footer. + @param pg + one of wxPAGE_ODD, wxPAGE_EVEN and wxPAGE_ALL constants. + */ + void SetFooter(const wxString& footer, int pg = wxPAGE_ALL); + + /** + Set page header. The following macros can be used inside it: + @DATE@ is replaced by the current date in default format + @PAGENUM@ is replaced by page number + @PAGESCNT@ is replaced by total number of pages + @TIME@ is replaced by the current time in default format + @TITLE@ is replaced with the title of the document + + @param header + HTML text to be used as header. + @param pg + one of wxPAGE_ODD, wxPAGE_EVEN and wxPAGE_ALL constants. + */ + void SetHeader(const wxString& header, int pg = wxPAGE_ALL); + + /** + Sets the parent window for dialogs. + */ + void SetParentWindow(wxWindow* window); +}; + + + +/** + @class wxHtmlPrintout + @headerfile htmprint.h wx/html/htmprint.h + + This class serves as printout class for HTML documents. + + @library{wxhtml} + @category{html} +*/ +class wxHtmlPrintout : public wxPrintout +{ +public: + /** + Constructor. + */ + wxHtmlPrintout(const wxString& title = "Printout"); + + /** + Adds a filter to the static list of filters for wxHtmlPrintout. See + wxHtmlFilter for + further information. + */ + static void AddFilter(wxHtmlFilter* filter); + + /** + Sets fonts. See wxHtmlWindow::SetFonts for + detailed description. + */ + void SetFonts(const wxString& normal_face, + const wxString& fixed_face, + const int sizes = NULL); + + /** + Set page footer. The following macros can be used inside it: + @DATE@ is replaced by the current date in default format + @PAGENUM@ is replaced by page number + @PAGESCNT@ is replaced by total number of pages + @TIME@ is replaced by the current time in default format + @TITLE@ is replaced with the title of the document + + @param footer + HTML text to be used as footer. + @param pg + one of wxPAGE_ODD, wxPAGE_EVEN and wxPAGE_ALL constants. + */ + void SetFooter(const wxString& footer, int pg = wxPAGE_ALL); + + /** + Set page header. The following macros can be used inside it: + @DATE@ is replaced by the current date in default format + @PAGENUM@ is replaced by page number + @PAGESCNT@ is replaced by total number of pages + @TIME@ is replaced by the current time in default format + @TITLE@ is replaced with the title of the document + + @param header + HTML text to be used as header. + @param pg + one of wxPAGE_ODD, wxPAGE_EVEN and wxPAGE_ALL constants. + */ + void SetHeader(const wxString& header, int pg = wxPAGE_ALL); + + /** + Prepare the class for printing this HTML @b file. The file may be located on + any virtual file system or it may be normal file. + */ + void SetHtmlFile(const wxString& htmlfile); + + /** + Prepare the class for printing this HTML text. + + @param html + HTML text. (NOT file!) + @param basepath + base directory (html string would be stored there if it was in + file). It is used to determine path for loading images, for example. + @param isdir + @false if basepath is filename, @true if it is directory name + (see wxFileSystem for detailed explanation) + */ + void SetHtmlText(const wxString& html, + const wxString& basepath = wxEmptyString, + bool isdir = true); + + /** + Sets margins in millimeters. Defaults to 1 inch for margins and 0.5cm for space + between text and header and/or footer + */ + void SetMargins(float top = 25.2, float bottom = 25.2, + float left = 25.2, + float right = 25.2, + float spaces = 5); +}; + diff --git a/interface/wx/html/winpars.h b/interface/wx/html/winpars.h new file mode 100644 index 0000000000..ed5d5348b1 --- /dev/null +++ b/interface/wx/html/winpars.h @@ -0,0 +1,314 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: html/winpars.h +// Purpose: interface of wxHtmlTagsModule +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxHtmlTagsModule + @headerfile winpars.h wx/html/winpars.h + + This class provides easy way of filling wxHtmlWinParser's table of + tag handlers. It is used almost exclusively together with the set of + @ref overview_handlers "TAGS_MODULE_* macros" + + @library{wxhtml} + @category{FIXME} + + @see @ref overview_handlers "Tag Handlers", wxHtmlTagHandler, + wxHtmlWinTagHandler, +*/ +class wxHtmlTagsModule : public wxModule +{ +public: + /** + You must override this method. In most common case its body consists + only of lines of the following type: + + I recommend using the @b TAGS_MODULE_* macros. + + @param parser + Pointer to the parser that requested tables filling. + */ + virtual void FillHandlersTable(wxHtmlWinParser parser); +}; + + + +/** + @class wxHtmlWinTagHandler + @headerfile winpars.h wx/html/winpars.h + + This is basically wxHtmlTagHandler except that + it is extended with protected member m_WParser pointing to + the wxHtmlWinParser object (value of this member is identical + to wxHtmlParser's m_Parser). + + @library{wxhtml} + @category{html} +*/ +class wxHtmlWinTagHandler : public wxHtmlTagHandler +{ +public: + /** + @b wxHtmlWinParser* m_WParser + Value of this attribute is identical to value of m_Parser. The only different + is that m_WParser points to wxHtmlWinParser object while m_Parser + points to wxHtmlParser object. (The same object, but overcast.) + */ +}; + + + +/** + @class wxHtmlWinParser + @headerfile winpars.h wx/html/winpars.h + + This class is derived from wxHtmlParser and + its main goal is to parse HTML input so that it can be displayed in + wxHtmlWindow. It uses a special + wxHtmlWinTagHandler. + + @library{wxhtml} + @category{html} + + @see @ref overview_handlers "Handlers overview" +*/ +class wxHtmlWinParser : public wxHtmlParser +{ +public: + //@{ + /** + Constructor. Don't use the default one, use constructor with + @a wndIface parameter (@a wndIface is a pointer to interface object for + the associated wxHtmlWindow or other HTML rendering + window such as wxHtmlListBox). + */ + wxHtmlWinParser(); + wxHtmlWinParser(wxHtmlWindowInterface wndIface); + //@} + + /** + Adds module() to the list of wxHtmlWinParser tag handler. + */ + static void AddModule(wxHtmlTagsModule module); + + /** + Closes the container, sets actual container to the parent one + and returns pointer to it (see Overview()). + */ + wxHtmlContainerCell* CloseContainer(); + + /** + Creates font based on current setting (see + SetFontSize(), + SetFontBold(), + SetFontItalic(), + SetFontFixed(), + wxHtmlWinParser::SetFontUnderlined) + and returns pointer to it. + If the font was already created only a pointer is returned. + */ + virtual wxFont* CreateCurrentFont(); + + /** + Returns actual text colour. + */ + const wxColour GetActualColor() const; + + /** + Returns default horizontal alignment. + */ + int GetAlign() const; + + /** + Returns (average) char height in standard font. It is used as DC-independent + metrics. + @note This function doesn't return the @e actual height. If you want to + know the height of the current font, call @c GetDC - GetCharHeight(). + */ + int GetCharHeight() const; + + /** + Returns average char width in standard font. It is used as DC-independent + metrics. + @note This function doesn't return the @e actual width. If you want to + know the height of the current font, call @c GetDC - GetCharWidth() + */ + int GetCharWidth() const; + + /** + Returns pointer to the currently opened container (see Overview()). + Common use: + */ + wxHtmlContainerCell* GetContainer() const; + + /** + Returns pointer to the DC used during parsing. + */ + wxDC* GetDC(); + + /** + Returns wxEncodingConverter class used + to do conversion between @ref getinputencoding() "input encoding" + and @ref getoutputencoding() "output encoding". + */ + wxEncodingConverter* GetEncodingConverter() const; + + /** + Returns @true if actual font is bold, @false otherwise. + */ + int GetFontBold() const; + + /** + Returns actual font face name. + */ + wxString GetFontFace() const; + + /** + Returns @true if actual font is fixed face, @false otherwise. + */ + int GetFontFixed() const; + + /** + Returns @true if actual font is italic, @false otherwise. + */ + int GetFontItalic() const; + + /** + Returns actual font size (HTML size varies from -2 to +4) + */ + int GetFontSize() const; + + /** + Returns @true if actual font is underlined, @false otherwise. + */ + int GetFontUnderlined() const; + + /** + Returns input encoding. + */ + wxFontEncoding GetInputEncoding() const; + + /** + Returns actual hypertext link. (This value has a non-empty + @ref wxHtmlLinkInfo::gethref Href string + if the parser is between @c A and @c /A tags, + wxEmptyString otherwise.) + */ + const wxHtmlLinkInfo GetLink() const; + + /** + Returns the colour of hypertext link text. + */ + const wxColour GetLinkColor() const; + + /** + Returns output encoding, i.e. closest match to document's input encoding + that is supported by operating system. + */ + wxFontEncoding GetOutputEncoding() const; + + /** + Returns associated window (wxHtmlWindow). This may be @NULL! (You should always + test if it is non-@NULL. For example @c TITLE handler sets window + title only if some window is associated, otherwise it does nothing) + */ + wxHtmlWindow* GetWindow(); + + /** + Opens new container and returns pointer to it (see Overview()). + */ + wxHtmlContainerCell* OpenContainer(); + + /** + Sets actual text colour. Note: this DOESN'T change the colour! + You must create wxHtmlColourCell yourself. + */ + void SetActualColor(const wxColour& clr); + + /** + Sets default horizontal alignment (see + wxHtmlContainerCell::SetAlignHor.) + Alignment of newly opened container is set to this value. + */ + void SetAlign(int a); + + /** + Allows you to directly set opened container. This is not recommended - you + should use OpenContainer + wherever possible. + */ + wxHtmlContainerCell* SetContainer(wxHtmlContainerCell* c); + + /** + Sets the DC. This must be called before wxHtmlParser::Parse! + @a pixel_scale can be used when rendering to high-resolution + DCs (e.g. printer) to adjust size of pixel metrics. (Many dimensions in + HTML are given in pixels -- e.g. image sizes. 300x300 image would be only one + inch wide on typical printer. With pixel_scale = 3.0 it would be 3 inches.) + */ + virtual void SetDC(wxDC dc, double pixel_scale = 1.0); + + /** + Sets bold flag of actualfont. @a x is either @true of @false. + */ + void SetFontBold(int x); + + /** + Sets current font face to @e face. This affects either fixed size + font or proportional, depending on context (whether the parser is + inside @c TT tag or not). + */ + void SetFontFace(const wxString& face); + + /** + Sets fixed face flag of actualfont. @a x is either @true of @false. + */ + void SetFontFixed(int x); + + /** + Sets italic flag of actualfont. @a x is either @true of @false. + */ + void SetFontItalic(int x); + + /** + Sets actual font size (HTML size varies from 1 to 7) + */ + void SetFontSize(int s); + + /** + Sets underlined flag of actualfont. @a x is either @true of @false. + */ + void SetFontUnderlined(int x); + + /** + Sets fonts. See wxHtmlWindow::SetFonts for + detailed description. + */ + void SetFonts(const wxString& normal_face, + const wxString& fixed_face, + const int sizes = NULL); + + /** + Sets input encoding. The parser uses this information to build conversion + tables from document's encoding to some encoding supported by operating + system. + */ + void SetInputEncoding(wxFontEncoding enc); + + /** + Sets actual hypertext link. Empty link is represented + by wxHtmlLinkInfo with @e Href equal + to wxEmptyString. + */ + void SetLink(const wxHtmlLinkInfo& link); + + /** + Sets colour of hypertext link. + */ + void SetLinkColor(const wxColour& clr); +}; + diff --git a/interface/wx/htmllbox.h b/interface/wx/htmllbox.h new file mode 100644 index 0000000000..150398f04b --- /dev/null +++ b/interface/wx/htmllbox.h @@ -0,0 +1,240 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: htmllbox.h +// Purpose: interface of wxHtmlListBox +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxHtmlListBox + @wxheader{htmllbox.h} + + wxHtmlListBox is an implementation of wxVListBox which + shows HTML content in the listbox rows. This is still an abstract base class + and you will need to derive your own class from it (see htlbox sample for the + example) but you will only need to override a single + wxHtmlListBox::OnGetItem function. + + @library{wxhtml} + @category{ctrl} + + + @see wxSimpleHtmlListBox +*/ +class wxHtmlListBox : public wxVListBox +{ +public: + //@{ + /** + Default constructor, you must call Create() + later. + */ + wxHtmlListBox(wxWindow* parent, wxWindowID id = wxID_ANY, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0, + const wxString& name = wxHtmlListBoxNameStr); + wxHtmlListBox(); + //@} + + /** + Destructor cleans up whatever resources we use. + */ + ~wxHtmlListBox(); + + /** + Creates the control and optionally sets the initial number of items in it + (it may also be set or changed later with + wxVListBox::SetItemCount). + There are no special styles defined for wxHtmlListBox, in particular the + wxListBox styles (with the exception of @c wxLB_MULTIPLE) can not be used here. + Returns @true on success or @false if the control couldn't be created + */ + bool Create(wxWindow* parent, wxWindowID id = wxID_ANY, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0, + const wxString& name = wxHtmlListBoxNameStr); + + //@{ + /** + Returns the wxFileSystem used by the HTML parser of + this object. The file system object is used to resolve the paths in HTML + fragments displayed in the control and you should use + wxFileSystem::ChangePathTo if you use + relative paths for the images or other resources embedded in your HTML. + */ + wxFileSystem GetFileSystem() const; + const wxFileSystem GetFileSystem() const; + //@} + + /** + This virtual function may be overridden to change the appearance of the + background of the selected cells in the same way as + GetSelectedTextColour(). + It should be rarely, if ever, used because + wxVListBox::SetSelectionBackground allows to + change the selection background for all cells at once and doing anything more + fancy is probably going to look strangely. + + @see GetSelectedTextColour() + */ + wxColour GetSelectedTextBgColour(const wxColour& colBg) const; + + /** + This virtual function may be overridden to customize the appearance of the + selected cells. It is used to determine how the colour @a colFg is going to + look inside selection. By default all original colours are completely ignored + and the standard, system-dependent, selection colour is used but the program + may wish to override this to achieve some custom appearance. + + @see GetSelectedTextBgColour(), + wxVListBox::SetSelectionBackground, wxSystemSettings::GetColour + */ + wxColour GetSelectedTextColour(const wxColour& colFg) const; + + /** + This method must be implemented in the derived class and should return + the body (i.e. without @c html nor @c body tags) of the HTML fragment + for the given item. + Note that this function should always return a text fragment for the @a n item + which renders with the same height both when it is selected and when it's not: + i.e. if you call, inside your OnGetItem() implementation, @c IsSelected(n) to + make the items appear differently when they are selected, then you should make + sure + that the returned HTML fragment will render with the same height or else you'll + see some artifacts when the user selects an item. + */ + wxString OnGetItem(size_t n) const; + + /** + This function may be overridden to decorate HTML returned by + OnGetItem(). + */ + wxString OnGetItemMarkup(size_t n) const; + + /** + Called when the user clicks on hypertext link. Does nothing by default. + Overloading this method is deprecated; intercept the event instead. + + @param n + Index of the item containing the link. + @param link + Description of the link. + + @see See also wxHtmlLinkInfo. + */ + virtual void OnLinkClicked(size_t n, const wxHtmlLinkInfo& link); +}; + + + +/** + @class wxSimpleHtmlListBox + @wxheader{htmllbox.h} + + wxSimpleHtmlListBox is an implementation of wxHtmlListBox which + shows HTML content in the listbox rows. + + Unlike wxHtmlListBox, this is not an abstract class and thus it + has the advantage that you can use it without deriving your own class from it. + However, it also has the disadvantage that this is not a virtual control and + thus it's not + well-suited for those cases where you need to show a huge number of items: + every time you + add/insert a string, it will be stored internally and thus will take memory. + + The interface exposed by wxSimpleHtmlListBox fully implements the + wxControlWithItems interface, thus you should refer to + wxControlWithItems's documentation for the API reference + for adding/removing/retrieving items in the listbox. + Also note that the wxVListBox::SetItemCount function is + @c protected in wxSimpleHtmlListBox's context so that you cannot call it + directly, + wxSimpleHtmlListBox will do it for you. + + Note: in case you need to append a lot of items to the control at once, make + sure to use the + @ref wxControlWithItems::append "Append(const wxArrayString )" function. + + Thus the only difference between a wxListBox and a wxSimpleHtmlListBox + is that the latter stores strings which can contain HTML fragments (see the + list of + @ref overview_htmltagssupported "tags supported by wxHTML"). + + Note that the HTML strings you fetch to wxSimpleHtmlListBox should not contain + the @c html + or @c body tags. + + @beginStyleTable + @style{wxHLB_DEFAULT_STYLE} + The default style: wxBORDER_SUNKEN + @style{wxHLB_MULTIPLE} + Multiple-selection list: the user can toggle multiple items on and + off. + @endStyleTable + + @library{wxhtml} + @category{ctrl} + + + @see wxSimpleHtmlListBox::Create +*/ +class wxSimpleHtmlListBox : public wxHtmlListBox +{ +public: + //@{ + /** + Default constructor, you must call Create() + later. + */ + wxHtmlListBox(wxWindow* parent, wxWindowID id, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + int n = 0, + const wxString choices[] = NULL, + long style = wxHLB_DEFAULT_STYLE, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "simpleHtmlListBox"); + wxHtmlListBox(wxWindow* parent, wxWindowID id, + const wxPoint& pos, + const wxSize& size, + const wxArrayString& choices, + long style = wxHLB_DEFAULT_STYLE, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "simpleHtmlListBox"); + See also + wxSimpleHtmlListBox::Create + + wxSimpleHtmlListBox(); + //@} + + /** + Frees the array of stored items and relative client data. + */ + ~wxSimpleHtmlListBox(); + + //@{ + /** + Creates the HTML listbox for two-step construction. + See wxSimpleHtmlListBox() for further details. + */ + bool Create(wxWindow* parent, wxWindowID id, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + int n, + const wxString choices[] = NULL, + long style = wxHLB_DEFAULT_STYLE, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "simpleHtmlListBox"); + bool Create(wxWindow* parent, wxWindowID id, + const wxPoint& pos, + const wxSize& size, + const wxArrayString& choices, + long style = wxHLB_DEFAULT_STYLE, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "simpleHtmlListBox"); + //@} +}; + diff --git a/interface/wx/hyperlink.h b/interface/wx/hyperlink.h new file mode 100644 index 0000000000..5982f6d1ca --- /dev/null +++ b/interface/wx/hyperlink.h @@ -0,0 +1,186 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: hyperlink.h +// Purpose: interface of wxHyperlinkEvent +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxHyperlinkEvent + @wxheader{hyperlink.h} + + This event class is used for the events generated by + wxHyperlinkCtrl. + + @library{wxadv} + @category{FIXME} +*/ +class wxHyperlinkEvent : public wxCommandEvent +{ +public: + /** + The constructor is not normally used by the user code. + */ + wxHyperlinkEvent(wxObject* generator, int id, + const wxString& url); + + /** + Returns the URL of the hyperlink where the user has just clicked. + */ + wxString GetURL() const; + + /** + Sets the URL associated with the event. + */ + void SetURL(const wxString& url); +}; + + + +/** + @class wxHyperlinkCtrl + @wxheader{hyperlink.h} + + This class shows a static text element which links to an URL. + Appearance and behaviour is completely customizable. In fact, when the user + clicks on the hyperlink, a wxHyperlinkEvent is + sent but if that event is not handled (or it's skipped; see + wxEvent::Skip), then a call to + wxLaunchDefaultBrowser() is done with the + hyperlink's URL. + + Note that standard wxWindow functions like wxWindow::SetBackgroundColour, + wxWindow::SetFont, wxWindow::SetCursor, wxWindow::SetLabel can be used to customize appearance of the hyperlink. + + @beginStyleTable + @style{wxHL_ALIGN_LEFT} + Align the text to the left. + @style{wxHL_ALIGN_RIGHT} + Align the text to the right. + @style{wxHL_ALIGN_CENTRE} + Center the text (horizontally). + @style{wxHL_CONTEXTMENU} + Pop up a context menu when the hyperlink is right-clicked. The + context menu contains a "Copy URL" menu item which is automatically + handled by the hyperlink and which just copies in the clipboard the + URL (not the label) of the control. + @style{wxHL_DEFAULT_STYLE} + The default style for wxHyperlinkCtrl: + wxBORDER_NONE|wxHL_CONTEXTMENU|wxHL_ALIGN_CENTRE. + @endStyleTable + + @library{wxadv} + @category{ctrl} + + + @see wxURL, wxHyperlinkEvent +*/ +class wxHyperlinkCtrl : public wxControl +{ +public: + /** + Constructor. See Create() for more info. + */ + wxHyperLink(wxWindow* parent, wxWindowID id, + const wxString& label, + const wxString& url, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxHL_DEFAULT_STYLE, + const wxString& name = "hyperlink"); + + /** + Creates the hyperlink control. + + @param parent + Parent window. Must not be @NULL. + @param id + Window identifier. A value of wxID_ANY indicates a default value. + @param label + The label of the hyperlink. + @param url + The URL associated with the given label. + @param pos + Window position. + @param size + Window size. If the wxDefaultSize is specified then the window is sized + appropriately. + @param style + Window style. See wxHyperlinkCtrl. + @param validator + Window validator. + @param name + Window name. + */ + bool Create(wxWindow* parent, wxWindowID id, + const wxString& label, + const wxString& url, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxHL_DEFAULT_STYLE, + const wxString& name = "hyperlink"); + + /** + Returns the colour used to print the label of the hyperlink when the mouse is + over the control. + */ + wxColour GetHoverColour() const; + + /** + Returns the colour used to print the label when the link has never been clicked + before + (i.e. the link has not been @e visited) and the mouse is not over the control. + */ + wxColour GetNormalColour() const; + + /** + Returns the URL associated with the hyperlink. + */ + wxString GetURL() const; + + /** + Returns @true if the hyperlink has already been clicked by the user at least + one time. + */ + virtual bool GetVisited() const = 0; + + /** + Returns the colour used to print the label when the mouse is not over the + control + and the link has already been clicked before (i.e. the link has been @e + visited). + */ + wxColour GetVisitedColour() const; + + /** + Sets the colour used to print the label of the hyperlink when the mouse is over + the control. + */ + void SetHoverColour(const wxColour& colour); + + /** + Sets the colour used to print the label when the link has never been clicked + before + (i.e. the link has not been @e visited) and the mouse is not over the control. + */ + void SetNormalColour(const wxColour& colour); + + /** + Sets the URL associated with the hyperlink. + */ + void SetURL(const wxString& url); + + /** + Marks the hyperlink as visited (see wxHyperlinkCtrl::SetVisitedColour). + */ + virtual void SetVisited(bool visited = true) = 0; + + /** + Sets the colour used to print the label when the mouse is not over the control + and the link has already been clicked before (i.e. the link has been @e + visited). + */ + void SetVisitedColour(const wxColour& colour); +}; + diff --git a/interface/wx/icon.h b/interface/wx/icon.h new file mode 100644 index 0000000000..acfca50218 --- /dev/null +++ b/interface/wx/icon.h @@ -0,0 +1,321 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: icon.h +// Purpose: interface of wxIcon +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxIcon + @wxheader{icon.h} + + An icon is a small rectangular bitmap usually used for denoting a + minimized application. It differs from a wxBitmap in always + having a mask associated with it for transparent drawing. On some platforms, + icons and bitmaps are implemented identically, since there is no real + distinction between + a wxBitmap with a mask and an icon; and there is no specific icon format on + some platforms (X-based applications usually standardize on XPMs for small + bitmaps + and icons). However, some platforms (such as Windows) make the distinction, so + a separate class is provided. + + @library{wxcore} + @category{gdi} + + @stdobjects + ::wxNullIcon + + @see @ref overview_wxbitmapoverview "Bitmap and icon overview", @ref + overview_supportedbitmapformats "supported bitmap file formats", wxDC::DrawIcon, wxCursor +*/ +class wxIcon : public wxBitmap +{ +public: + //@{ + /** + Loads an icon from the specified location(). + + @param bits + Specifies an array of pixel values. + @param width + Specifies the width of the icon. + @param height + Specifies the height of the icon. + @param desiredWidth + Specifies the desired width of the icon. This + parameter only has an effect in Windows (32-bit) where icon resources can + contain + several icons of different sizes. + @param desiredWidth + Specifies the desired height of the icon. This + parameter only has an effect in Windows (32-bit) where icon resources can + contain + several icons of different sizes. + @param depth + Specifies the depth of the icon. If this is omitted, the display depth of + the + screen is used. + @param name + This can refer to a resource name under MS Windows, or a filename under MS + Windows and X. + Its meaning is determined by the flags parameter. + @param loc + The object describing the location of the native icon, see + wxIconLocation. + @param type + May be one of the following: + + + + + + + + wxBITMAP_TYPE_ICO + + + + + Load a Windows icon file. + + + + + + wxBITMAP_TYPE_ICO_RESOURCE + + + + + Load a Windows icon from the resource database. + + + + + + wxBITMAP_TYPE_GIF + + + + + Load a GIF bitmap file. + + + + + + wxBITMAP_TYPE_XBM + + + + + Load an X bitmap file. + + + + + + wxBITMAP_TYPE_XPM + + + + + Load an XPM bitmap file. + + + + + + The validity of these flags depends on the platform and wxWidgets + configuration. + If all possible wxWidgets settings are used, the Windows platform supports + ICO file, ICO resource, + XPM data, and XPM file. Under wxGTK, the available formats are BMP file, + XPM data, XPM file, and PNG file. + Under wxMotif, the available formats are XBM data, XBM file, XPM data, XPM + file. + + @remarks The first form constructs an icon object with no data; an + assignment or another member function such as Create or + LoadFile must be called subsequently. + */ + wxIcon(); + wxIcon(const wxIcon& icon); + wxIcon(void* data, int type, int width, int height, + int depth = -1); + wxIcon(const char bits[], int width, int height, + int depth = 1); + wxIcon(int width, int height, int depth = -1); + wxIcon(const char* const* bits); + wxIcon(const wxString& name, wxBitmapType type, + int desiredWidth = -1, + int desiredHeight = -1); + wxIcon(const wxIconLocation& loc); + //@} + + /** + Destructor. + See @ref overview_refcountdestruct "reference-counted object destruction" for + more info. + If the application omits to delete the icon explicitly, the icon will be + destroyed automatically by wxWidgets when the application exits. + Do not delete an icon that is selected into a memory device context. + */ + ~wxIcon(); + + /** + Copies @a bmp bitmap to this icon. Under MS Windows the bitmap + must have mask colour set. + + LoadFile() + + Wx::Icon-new( width, height, depth = -1 ) + Wx::Icon-new( name, type, desiredWidth = -1, desiredHeight = -1 ) + Wx::Icon-newFromBits( bits, width, height, depth = 1 ) + Wx::Icon-newFromXPM( data ) + */ + void CopyFromBitmap(const wxBitmap& bmp); + + /** + Gets the colour depth of the icon. A value of 1 indicates a + monochrome icon. + */ + int GetDepth() const; + + /** + Gets the height of the icon in pixels. + */ + int GetHeight() const; + + /** + Gets the width of the icon in pixels. + + @see GetHeight() + */ + int GetWidth() const; + + /** + Returns @true if icon data is present. + */ + bool IsOk() const; + + /** + Loads an icon from a file or resource. + + @param name + Either a filename or a Windows resource name. + The meaning of name is determined by the type parameter. + @param type + One of the following values: + + + + + + + + wxBITMAP_TYPE_ICO + + + + + Load a Windows icon file. + + + + + + wxBITMAP_TYPE_ICO_RESOURCE + + + + + Load a Windows icon from the resource database. + + + + + + wxBITMAP_TYPE_GIF + + + + + Load a GIF bitmap file. + + + + + + wxBITMAP_TYPE_XBM + + + + + Load an X bitmap file. + + + + + + wxBITMAP_TYPE_XPM + + + + + Load an XPM bitmap file. + + + + + + The validity of these flags depends on the platform and wxWidgets + configuration. + + @return @true if the operation succeeded, @false otherwise. + + @see wxIcon() + */ + bool LoadFile(const wxString& name, wxBitmapType type); + + /** + Sets the depth member (does not affect the icon data). + + @param depth + Icon depth. + */ + void SetDepth(int depth); + + /** + Sets the height member (does not affect the icon data). + + @param height + Icon height in pixels. + */ + void SetHeight(int height); + + /** + Sets the width member (does not affect the icon data). + + @param width + Icon width in pixels. + */ + void SetWidth(int width); + + /** + Assignment operator, using @ref overview_trefcount "reference counting". + + @param icon + Icon to assign. + */ + wxIcon operator =(const wxIcon& icon); +}; + +/** + An empty wxIcon. +*/ +wxIcon wxNullIcon; + + diff --git a/interface/wx/iconbndl.h b/interface/wx/iconbndl.h new file mode 100644 index 0000000000..8532db9145 --- /dev/null +++ b/interface/wx/iconbndl.h @@ -0,0 +1,89 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: iconbndl.h +// Purpose: interface of wxIconBundle +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxIconBundle + @wxheader{iconbndl.h} + + This class contains multiple copies of an icon in different sizes, + see also wxDialog::SetIcons and + wxTopLevelWindow::SetIcons. + + @library{wxcore} + @category{FIXME} + + @stdobjects + ::wxNullIconBundle +*/ +class wxIconBundle : public wxGDIObject +{ +public: + //@{ + /** + Copy constructor. + */ + wxIconBundle(); + wxIconBundle(const wxString& file, wxBitmapType type); + wxIconBundle(const wxIcon& icon); + wxIconBundle(const wxIconBundle& ic); + //@} + + /** + Destructor. + */ + ~wxIconBundle(); + + //@{ + /** + Adds the icon to the collection; if the collection already + contains an icon with the same width and height, it is + replaced by the new one. + */ + void AddIcon(const wxString& file, wxBitmapType type); + void AddIcon(const wxIcon& icon); + //@} + + //@{ + /** + Same as GetIcon( wxSize( size, size ) ). + */ + wxIcon GetIcon(const wxSize& size) const; + const wxIcon GetIcon(wxCoord size = -1) const; + //@} + + /** + Returns the icon with exactly the given size or @c wxNullIcon if this + size is not available. + */ + wxIcon GetIconOfExactSize(const wxSize& size) const; + + /** + Returns @true if the bundle doesn't contain any icons, @false otherwise (in + which case a call to GetIcon() with default + parameter should return a valid icon). + */ + bool IsEmpty() const; + + /** + Assignment operator, using @ref overview_trefcount "reference counting". + */ + wxIconBundle operator =(const wxIconBundle& ic); + + /** + Equality operator. This returns @true if two icon bundles are equal. + */ + bool operator ==(const wxIconBundle& ic); +}; + + +/** + An empty wxIconBundle. +*/ +wxIconBundle wxNullIconBundle; + + diff --git a/interface/wx/iconloc.h b/interface/wx/iconloc.h new file mode 100644 index 0000000000..4ed130a56c --- /dev/null +++ b/interface/wx/iconloc.h @@ -0,0 +1,39 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: iconloc.h +// Purpose: interface of wxIconLocation +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxIconLocation + @wxheader{iconloc.h} + + wxIconLocation is a tiny class describing the location of an (external, i.e. + not embedded into the application resources) icon. For most platforms it simply + contains the file name but under some others (notably Windows) the same file + may contain multiple icons and so this class also stores the index of the icon + inside the file. + + In any case, its details should be of no interest to the application code and + most of them are not even documented here (on purpose) as it is only meant to + be used as an opaque class: the application may get the object of this class + from somewhere and the only reasonable thing to do with it later is to create + a wxIcon from it. + + @library{wxbase} + @category{FIXME} + + @see wxIcon, wxFileType::GetIcon +*/ +class wxIconLocation +{ +public: + /** + Returns @true if the object is valid, i.e. was properly initialized, and + @false otherwise. + */ + bool IsOk() const; +}; + diff --git a/interface/wx/image.h b/interface/wx/image.h new file mode 100644 index 0000000000..ef66408ff0 --- /dev/null +++ b/interface/wx/image.h @@ -0,0 +1,1073 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: image.h +// Purpose: interface of wxImageHandler +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxImageHandler + @wxheader{image.h} + + This is the base class for implementing image file loading/saving, and + image creation from data. + It is used within wxImage and is not normally seen by the application. + + If you wish to extend the capabilities of wxImage, derive a class from + wxImageHandler and add the handler using wxImage::AddHandler in your + application initialisation. + + @stdobjects + ::wxNullImage + + @library{wxcore} + @category{FIXME} + + @see wxImage, wxInitAllImageHandlers() + + @todo Document all image handler types, indicating their library. +*/ +class wxImageHandler : public wxObject +{ +public: + /** + Default constructor. In your own default constructor, initialise the members + m_name, m_extension and m_type. + */ + wxImageHandler(); + + /** + Destroys the wxImageHandler object. + */ + ~wxImageHandler(); + + /** + Gets the file extension associated with this handler. + */ + const wxString GetExtension() const; + + /** + If the image file contains more than one image and the image handler is capable + of retrieving these individually, this function will return the number of + available images. + + @param stream + Opened input stream for reading image data. Currently, the stream must + support seeking. + + @return Number of available images. For most image handlers, this is 1 + (exceptions are TIFF and ICO formats). + */ + int GetImageCount(wxInputStream& stream); + + /** + Gets the MIME type associated with this handler. + */ + const wxString GetMimeType() const; + + /** + Gets the name of this handler. + */ + const wxString GetName() const; + + /** + Gets the image type associated with this handler. + */ + wxBitmapType GetType() const; + + /** + Loads a image from a stream, putting the resulting data into @e image. If the + image file contains + more than one image and the image handler is capable of retrieving these + individually, @e index + indicates which image to read from the stream. + + @param image + The image object which is to be affected by this operation. + @param stream + Opened input stream for reading image data. + @param verbose + If set to @true, errors reported by the image handler will produce + wxLogMessages. + @param index + The index of the image in the file (starting from zero). + + @return @true if the operation succeeded, @false otherwise. + + @see wxImage::LoadFile, wxImage::SaveFile, SaveFile() + */ + bool LoadFile(wxImage* image, wxInputStream& stream, + bool verbose = true, int index = 0); + + /** + Saves a image in the output stream. + + @param image + The image object which is to be affected by this operation. + @param stream + Opened output stream for writing the data. + + @return @true if the operation succeeded, @false otherwise. + + @see wxImage::LoadFile, wxImage::SaveFile, LoadFile() + */ + bool SaveFile(wxImage* image, wxOutputStream& stream); + + /** + Sets the handler extension. + + @param extension + Handler extension. + */ + void SetExtension(const wxString& extension); + + /** + Sets the handler MIME type. + + @param mimename + Handler MIME type. + */ + void SetMimeType(const wxString& mimetype); + + /** + Sets the handler name. + + @param name + Handler name. + */ + void SetName(const wxString& name); +}; + + + +/** + @class wxImage + @wxheader{image.h} + + This class encapsulates a platform-independent image. An image can be + created from data, or using wxBitmap::ConvertToImage. An image can be + loaded from a file in a variety of formats, and is extensible to new + formats via image format handlers. Functions are available to set and + get image bits, so it can be used for basic image manipulation. + + A wxImage cannot (currently) be drawn directly to a wxDC. Instead, + a platform-specific wxBitmap object must be created from it using + the wxBitmap::wxBitmap(wxImage,int depth) constructor. + This bitmap can then be drawn in a device context, using wxDC::DrawBitmap. + + One colour value of the image may be used as a mask colour which will lead to + the automatic creation of a wxMask object associated to the bitmap object. + + @library{wxcore} + @category{gdi} + + @stdobjects + ::wxNullImage + + @see wxBitmap, wxInitAllImageHandlers(), wxPixelData +*/ +class wxImage : public wxObject +{ +public: + + /** + Creates an empty wxImage object without an alpha channel. + */ + wxImage(); + + /** + Creates an image with the given size and clears it if requested. + Does not create an alpha channel. + + @param width + Specifies the width of the image. + @param height + Specifies the height of the image. + @clear + Clear the image with zeros. + */ + wxImage(int width, int height, bool clear = true); + + /** + Creates an image from data in memory. If static_data is false + then the wxImage will take ownership of the data and free it + afterwards. For this, it has to be allocated with @e malloc. + + @param width + Specifies the width of the image. + @param height + Specifies the height of the image. + @param data + A pointer to RGB data + @param static_data + Indicates if the data should be free'd after use + + */ + wxImage(int width, int height, unsigned char* data, bool static_data = false); + + /** + Creates an image from data in memory. If static_data is false + then the wxImage will take ownership of the data and free it + afterwards. For this, it has to be allocated with @e malloc. + + @param width + Specifies the width of the image. + @param height + Specifies the height of the image. + @param data + A pointer to RGB data + @param alpha + A pointer to alpha-channel data + @param static_data + Indicates if the data should be free'd after use + + */ + wxImage(int width, int height, unsigned char* data, unsigned char* alpha, bool static_data = false ); + + /** + Creates an image from XPM data. + + @param xpmData + A pointer to XPM image data. + */ + wxImage(const char* const* xpmData); + + /** + Creates an image from a file. + + @param name + Name of the file from which to load the image. + @param type + May be one of the following: + @li wxBITMAP_TYPE_BMP: Load a Windows bitmap file. + @li wxBITMAP_TYPE_GIF: Load a GIF bitmap file. + @li wxBITMAP_TYPE_JPEG: Load a JPEG bitmap file. + @li wxBITMAP_TYPE_PNG: Load a PNG bitmap file. + @li wxBITMAP_TYPE_PCX: Load a PCX bitmap file. + @li wxBITMAP_TYPE_PNM: Load a PNM bitmap file. + @li wxBITMAP_TYPE_TIF: Load a TIFF bitmap file. + @li wxBITMAP_TYPE_TGA: Load a TGA bitmap file. + @li wxBITMAP_TYPE_XPM: Load a XPM bitmap file. + @li wxBITMAP_TYPE_ICO: Load a Windows icon file (ICO). + @li wxBITMAP_TYPE_CUR: Load a Windows cursor file (CUR). + @li wxBITMAP_TYPE_ANI: Load a Windows animated cursor file (ANI). + @li wxBITMAP_TYPE_ANY: Will try to autodetect the format. + @param index + Index of the image to load in the case that the image file contains + multiple images. This is only used by GIF, ICO and TIFF handlers. + The default value (-1) means "choose the default image" and is + interpreted as the first image (index=0) by the GIF and TIFF handler + and as the largest and most colourful one by the ICO handler. + + @remarks Depending on how wxWidgets has been configured, not all formats + may be available. + + @see LoadFile() + */ + wxImage(const wxString& name, wxBitmapType type = wxBITMAP_TYPE_ANY, int index = -1); + + /** + Creates an image from a file using MIME-types to specify the type. + + @param name + Name of the file from which to load the image. + @param type + See above + @param mimetype + MIME type string (for example 'image/jpeg') + @param index + See above + */ + wxImage(const wxString& name, const wxString& mimetype, int index = -1); + + /** + Creates an image from a stream. + + @param stream + Opened input stream from which to load the image. Currently, + the stream must support seeking. + @param type + See above + @param index + See above. + */ + wxImage(wxInputStream& stream, wxBitmapType type = wxBITMAP_TYPE_ANY, int index = -1); + + /** + Creates an image from a stream using MIME-types to specify the type. + + @param stream + Opened input stream from which to load the image. Currently, + the stream must support seeking. + @param mimetype + MIME type string (for example 'image/jpeg') + @param index + See above. + */ + wxImage(wxInputStream& stream, const wxString& mimetype, int index = -1); + + + /** + Destructor. + See @ref overview_refcountdestruct "reference-counted object destruction" for + more info. + */ + ~wxImage(); + + /** + Register an image handler. + */ + static void AddHandler(wxImageHandler* handler); + + /** + Blurs the image in both horizontal and vertical directions by the + specified pixel @e blurRadius. This should not be used when using + a single mask colour for transparency. + + @see BlurHorizontal(), BlurVertical() + */ + wxImage Blur(int blurRadius); + + /** + Blurs the image in the horizontal direction only. This should not be used + when using a single mask colour for transparency. + + @see Blur(), BlurVertical() + */ + wxImage BlurHorizontal(int blurRadius); + + /** + Blurs the image in the vertical direction only. This should not be used + when using a single mask colour for transparency. + + @see Blur(), BlurHorizontal() + */ + wxImage BlurVertical(int blurRadius); + + /** + Returns @true if the current image handlers can read this file + */ + bool CanRead(const wxString& filename); + + /** + Deletes all image handlers. + This function is called by wxWidgets on exit. + */ + static void CleanUpHandlers(); + + /** + Computes the histogram of the image. @a histogram is a reference to + wxImageHistogram object. wxImageHistogram is a specialization of + wxHashMap "template" and is defined as follows: + + @return Returns number of colours in the histogram. + */ + unsigned long ComputeHistogram(wxImageHistogram& histogram) const; + + /** + If the image has alpha channel, this method converts it to mask. All pixels + with alpha value less than @a threshold are replaced with mask colour + and the alpha channel is removed. Mask colour is chosen automatically using + FindFirstUnusedColour(). + If the image image doesn't have alpha channel, + ConvertAlphaToMask does nothing. + + @return @false if FindFirstUnusedColour returns @false, @true otherwise. + */ + bool ConvertAlphaToMask(unsigned char threshold = 128); + + /** + Deprecated, use equivalent @ref wxBitmap::ctor "wxBitmap constructor" + (which takes wxImage and depth as its arguments) instead. + */ + wxBitmap ConvertToBitmap() const; + + /** + Returns a greyscale version of the image. The returned image uses the luminance + component of the original to calculate the greyscale. Defaults to using + ITU-T BT.601 when converting to YUV, where every pixel equals + (R * @e lr) + (G * @e lg) + (B * @e lb). + */ + wxImage ConvertToGreyscale(double lr = 0.299, double lg = 0.587, + double lb = 0.114) const; + + /** + Returns monochromatic version of the image. The returned image has white + colour where the original has @e (r,g,b) colour and black colour + everywhere else. + */ + wxImage ConvertToMono(unsigned char r, unsigned char g, + unsigned char b) const; + + /** + Returns an identical copy of the image. + */ + wxImage Copy() const; + + /** + Creates a fresh image. If @a clear is @true, the new image will be initialized + to black. + Otherwise, the image data will be uninitialized. + + @param width + The width of the image in pixels. + @param height + The height of the image in pixels. + + @return @true if the call succeeded, @false otherwise. + */ + bool Create(int width, int height, bool clear = true); + + /** + Destroys the image data. + */ + void Destroy(); + + /** + @param r,g,b + Pointers to variables to save the colour. + @param startR,startG,startB + Initial values of the colour. Returned colour + will have RGB values equal to or greater than these. + + @return Returns @false if there is no unused colour left, @true on success. + */ + bool FindFirstUnusedColour(unsigned char* r, unsigned char* g, + unsigned char* b, + unsigned char startR = 1, + unsigned char startG = 0, + unsigned char startB = 0); + + //@{ + /** + Finds the handler associated with the given MIME type. + + @param name + The handler name. + @param extension + The file extension, such as "bmp". + @param imageType + The image type, such as wxBITMAP_TYPE_BMP. + @param mimetype + MIME type. + + @return A pointer to the handler if found, @NULL otherwise. + + @see wxImageHandler + */ + static wxImageHandler* FindHandler(const wxString& name); + static wxImageHandler* FindHandler(const wxString& extension, + wxBitmapType imageType); + static wxImageHandler* FindHandler(wxBitmapType imageType); + static wxImageHandler* FindHandlerMime(const wxString& mimetype); + //@} + + /** + Return alpha value at given pixel location. + */ + unsigned char GetAlpha(int x, int y) const; + + /** + Returns pointer to the array storing the alpha values for this image. This + pointer is @NULL for the images without the alpha channel. If the image + does have it, this pointer may be used to directly manipulate the alpha values + which are stored as the RGB ones. + */ + const unsigned char * GetAlpha() const; + + /** + Returns the blue intensity at the given coordinate. + */ + unsigned char GetBlue(int x, int y) const; + + /** + Returns the image data as an array. This is most often used when doing + direct image manipulation. The return value points to an array of + characters in RGBRGBRGB... format in the top-to-bottom, left-to-right + order, that is the first RGB triplet corresponds to the pixel first pixel of + the first row, the second one --- to the second pixel of the first row and so + on until the end of the first row, with second row following after it and so + on. + You should not delete the returned pointer nor pass it to + SetData(). + */ + unsigned char* GetData() const; + + /** + Returns the green intensity at the given coordinate. + */ + unsigned char GetGreen(int x, int y) const; + + /** + Returns the static list of image format handlers. + + @see wxImageHandler + */ + static wxList GetHandlers(); + + /** + Gets the height of the image in pixels. + */ + int GetHeight() const; + + //@{ + /** + If the image file contains more than one image and the image handler is capable + of retrieving these individually, this function will return the number of + available images. + + @param name + Name of the file to query. + @param stream + Opened input stream with image data. Currently, the stream must + support seeking. + @param type + May be one of the following: + @li wxBITMAP_TYPE_BMP: Load a Windows bitmap file. + @li wxBITMAP_TYPE_GIF: Load a GIF bitmap file. + @li wxBITMAP_TYPE_JPEG: Load a JPEG bitmap file. + @li wxBITMAP_TYPE_PNG: Load a PNG bitmap file. + @li wxBITMAP_TYPE_PCX: Load a PCX bitmap file. + @li wxBITMAP_TYPE_PNM: Load a PNM bitmap file. + @li wxBITMAP_TYPE_TIF: Load a TIFF bitmap file. + @li wxBITMAP_TYPE_TGA: Load a TGA bitmap file. + @li wxBITMAP_TYPE_XPM: Load a XPM bitmap file. + @li wxBITMAP_TYPE_ICO: Load a Windows icon file (ICO). + @li wxBITMAP_TYPE_CUR: Load a Windows cursor file (CUR). + @li wxBITMAP_TYPE_ANI: Load a Windows animated cursor file (ANI). + @li wxBITMAP_TYPE_ANY: Will try to autodetect the format. + + @return Number of available images. For most image handlers, this is 1 + (exceptions are TIFF and ICO formats). + */ + static int GetImageCount(const wxString& filename, + wxBitmapType type = wxBITMAP_TYPE_ANY); + static int GetImageCount(wxInputStream& stream, + wxBitmapType type = wxBITMAP_TYPE_ANY); + //@} + + /** + Iterates all registered wxImageHandler objects, and returns a string containing + file extension masks + suitable for passing to file open/save dialog boxes. + + @return The format of the returned string is + "(*.ext1;*.ext2)|*.ext1;*.ext2". + + @see wxImageHandler + */ + static wxString GetImageExtWildcard(); + + /** + Gets the blue value of the mask colour. + */ + unsigned char GetMaskBlue() const; + + /** + Gets the green value of the mask colour. + */ + unsigned char GetMaskGreen() const; + + /** + Gets the red value of the mask colour. + */ + unsigned char GetMaskRed() const; + + /** + Gets a user-defined option. The function is case-insensitive to @e name. + For example, when saving as a JPEG file, the option @b quality is + used, which is a number between 0 and 100 (0 is terrible, 100 is very good). + + @see SetOption(), GetOptionInt(), HasOption() + */ + wxString GetOption(const wxString& name) const; + + /** + Gets a user-defined option as an integer. The function is case-insensitive + to @e name. If the given option is not present, the function returns 0. + Use HasOption() is 0 is a possibly valid value for the option. + Options for wxPNGHandler + @li wxIMAGE_OPTION_PNG_FORMAT: Format for saving a PNG file. + @li wxIMAGE_OPTION_PNG_BITDEPTH: Bit depth for every channel (R/G/B/A). + + Supported values for wxIMAGE_OPTION_PNG_FORMAT: + @li wxPNG_TYPE_COLOUR: Stores RGB image. + @li wxPNG_TYPE_GREY: Stores grey image, converts from RGB. + @li wxPNG_TYPE_GREY_RED: Stores grey image, uses red value as grey. + + @see SetOption(), GetOption() + */ + int GetOptionInt(const wxString& name) const; + + /** + Get the current mask colour or find a suitable unused colour that could be + used as a mask colour. Returns @true if the image currently has a mask. + */ + bool GetOrFindMaskColour(unsigned char r, unsigned char g, + unsigned char b) const; + + /** + Returns the palette associated with the image. Currently the palette is only + used when converting to wxBitmap under Windows. Some of the wxImage handlers + have been modified to set the palette if one exists in the image file (usually + 256 or less colour images in GIF or PNG format). + */ + const wxPalette GetPalette() const; + + /** + Returns the red intensity at the given coordinate. + */ + unsigned char GetRed(int x, int y) const; + + /** + Returns a sub image of the current one as long as the rect belongs entirely to + the image. + */ + wxImage GetSubImage(const wxRect& rect) const; + + /** + Gets the type of image found by LoadFile or specified with SaveFile + @since 2.9.0 + */ + wxBitmapType GetType() const; + + /** + Gets the width of the image in pixels. + + @see GetHeight() + */ + int GetWidth() const; + + /** + Constructor for HSVValue, an object that contains values for hue, saturation + and value which + represent the value of a color. It is used by HSVtoRGB() + and RGBtoHSV(), which + converts between HSV color space and RGB color space. + */ + HSVValue(double h = 0.0, double s = 0.0, double v = 0.0); + + /** + Converts a color in HSV color space to RGB color space. + */ +#define wxImage::RGBValue HSVtoRGB(const HSVValue& hsv) /* implementation is private */ + + /** + Returns @true if this image has alpha channel, @false otherwise. + + @see GetAlpha(), SetAlpha() + */ + bool HasAlpha() const; + + /** + Returns @true if there is a mask active, @false otherwise. + */ + bool HasMask() const; + + /** + Returns @true if the given option is present. The function is case-insensitive + to @e name. + + @see SetOption(), GetOption(), GetOptionInt() + */ + bool HasOption(const wxString& name) const; + + /** + Initializes the image alpha channel data. It is an error to call it + if the image already has alpha data. If it doesn't, alpha data will be + by default initialized to all pixels being fully opaque. But if the image has a + a mask colour, all mask pixels will be completely transparent. + */ + void InitAlpha(); + + /** + Internal use only. Adds standard image format handlers. It only install BMP + for the time being, which is used by wxBitmap. + This function is called by wxWidgets on startup, and shouldn't be called by + the user. + + @see wxImageHandler, wxInitAllImageHandlers(), wxQuantize + */ + static void InitStandardHandlers(); + + /** + Adds a handler at the start of the static list of format handlers. + + @param handler + A new image format handler object. There is usually only one instance + of a given handler class in an application session. + + @see wxImageHandler + */ + static void InsertHandler(wxImageHandler* handler); + + /** + Returns @true if image data is present. + */ + bool IsOk() const; + + /** + Returns @true if the given pixel is transparent, i.e. either has the mask + colour if this image has a mask or if this image has alpha channel and alpha + value of this pixel is strictly less than @e threshold. + */ + bool IsTransparent(int x, int y, unsigned char threshold = 128) const; + + //@{ + /** + Loads an image from an input stream. + + @param name + Name of the file from which to load the image. + @param stream + Opened input stream from which to load the image. Currently, the + stream must support seeking. + @param type + May be one of the following: + @li wxBITMAP_TYPE_BMP: Load a Windows bitmap file. + @li wxBITMAP_TYPE_GIF: Load a GIF bitmap file. + @li wxBITMAP_TYPE_JPEG: Load a JPEG bitmap file. + @li wxBITMAP_TYPE_PNG: Load a PNG bitmap file. + @li wxBITMAP_TYPE_PCX: Load a PCX bitmap file. + @li wxBITMAP_TYPE_PNM: Load a PNM bitmap file. + @li wxBITMAP_TYPE_TIF: Load a TIFF bitmap file. + @li wxBITMAP_TYPE_TGA: Load a TGA bitmap file. + @li wxBITMAP_TYPE_XPM: Load a XPM bitmap file. + @li wxBITMAP_TYPE_ICO: Load a Windows icon file (ICO). + @li wxBITMAP_TYPE_CUR: Load a Windows cursor file (CUR). + @li wxBITMAP_TYPE_ANI: Load a Windows animated cursor file (ANI). + @li wxBITMAP_TYPE_ANY: Will try to autodetect the format. + @param mimetype + MIME type string (for example 'image/jpeg') + @param index + Index of the image to load in the case that the image file contains + multiple images. This is only used by GIF, ICO and TIFF handlers. + The default value (-1) means "choose the default image" and is + interpreted as the first image (index=0) by the GIF and TIFF handler + and as the largest and most colourful one by the ICO handler. + + @return @true if the operation succeeded, @false otherwise. If the + optional index parameter is out of range, @false is + returned and a call to wxLogError() takes place. + + @remarks Depending on how wxWidgets has been configured, not all formats + may be available. + + @see SaveFile() + */ + bool LoadFile(const wxString& name, + wxBitmapType type = wxBITMAP_TYPE_ANY, + int index = -1); + bool LoadFile(const wxString& name, const wxString& mimetype, + int index = -1); + bool LoadFile(wxInputStream& stream, wxBitmapType type, + int index = -1); + bool LoadFile(wxInputStream& stream, + const wxString& mimetype, + int index = -1); + //@} + + /** + Returns a mirrored copy of the image. The parameter @e horizontally + indicates the orientation. + */ + wxImage Mirror(bool horizontally = true) const; + + /** + Copy the data of the given @a image to the specified position in this image. + */ + void Paste(const wxImage& image, int x, int y); + + /** + Constructor for RGBValue, an object that contains values for red, green and + blue which + represent the value of a color. It is used by HSVtoRGB() + and RGBtoHSV(), which + converts between HSV color space and RGB color space. + */ + RGBValue(unsigned char r = 0, unsigned char g = 0, + unsigned char b = 0); + + /** + Converts a color in RGB color space to HSV color space. + */ +#define wxImage::HSVValue RGBtoHSV(const RGBValue& rgb) /* implementation is private */ + + /** + Finds the handler with the given name, and removes it. The handler + is not deleted. + + @param name + The handler name. + + @return @true if the handler was found and removed, @false otherwise. + + @see wxImageHandler + */ + static bool RemoveHandler(const wxString& name); + + /** + Replaces the colour specified by @e r1,g1,b1 by the colour @e r2,g2,b2. + */ + void Replace(unsigned char r1, unsigned char g1, + unsigned char b1, unsigned char r2, + unsigned char g2, unsigned char b2); + + /** + Changes the size of the image in-place by scaling it: after a call to this + function, + the image will have the given width and height. + For a description of the @a quality parameter, see the Scale() function. + Returns the (modified) image itself. + + @see Scale() + */ + wxImage Rescale(int width, int height, + int quality = wxIMAGE_QUALITY_NORMAL); + + /** + Changes the size of the image in-place without scaling it by adding either a + border + with the given colour or cropping as necessary. The image is pasted into a new + image with the given @a size and background colour at the position @e pos + relative to the upper left of the new image. If @a red = green = blue = -1 + then use either the current mask colour if set or find, use, and set a + suitable mask colour for any newly exposed areas. + Returns the (modified) image itself. + + @see Size() + */ + wxImage Resize(const wxSize& size, const wxPoint pos, + int red = -1, int green = -1, + int blue = -1); + + /** + Rotates the image about the given point, by @a angle radians. Passing @true + to @a interpolating results in better image quality, but is slower. If the + image has a mask, then the mask colour is used for the uncovered pixels in the + rotated image background. Else, black (rgb 0, 0, 0) will be used. + Returns the rotated image, leaving this image intact. + */ + wxImage Rotate(double angle, const wxPoint& rotationCentre, + bool interpolating = true, + wxPoint* offsetAfterRotation = NULL); + + /** + Returns a copy of the image rotated 90 degrees in the direction + indicated by @e clockwise. + */ + wxImage Rotate90(bool clockwise = true) const; + + /** + Rotates the hue of each pixel in the image by @e angle, which is a double in + the range of -1.0 to +1.0, where -1.0 corresponds to -360 degrees and +1.0 + corresponds + to +360 degrees. + */ + void RotateHue(double angle); + + //@{ + /** + Saves an image in the given stream. + + @param name + Name of the file to save the image to. + @param stream + Opened output stream to save the image to. + @param type + Currently these types can be used: + @li wxBITMAP_TYPE_BMP: Save a BMP image file. + @li wxBITMAP_TYPE_JPEG: Save a JPEG image file. + @li wxBITMAP_TYPE_PNG: Save a PNG image file. + @li wxBITMAP_TYPE_PCX: Save a PCX image file (tries to save as 8-bit if possible, + falls back to 24-bit otherwise). + @li wxBITMAP_TYPE_PNM: Save a PNM image file (as raw RGB always). + @li wxBITMAP_TYPE_TIFF: Save a TIFF image file. + @li wxBITMAP_TYPE_XPM: Save a XPM image file. + @li wxBITMAP_TYPE_ICO: Save a Windows icon file (ICO) (the size may + be up to 255 wide by 127 high. A single image is saved in 8 colors + at the size supplied). + @li wxBITMAP_TYPE_CUR: Save a Windows cursor file (CUR). + @param mimetype + MIME type. + + @return @true if the operation succeeded, @false otherwise. + + @remarks Depending on how wxWidgets has been configured, not all formats + may be available. + + @see LoadFile() + */ + bool SaveFile(const wxString& name, int type) const; + const bool SaveFile(const wxString& name, + const wxString& mimetype) const; + const bool SaveFile(const wxString& name) const; + const bool SaveFile(wxOutputStream& stream, int type) const; + const bool SaveFile(wxOutputStream& stream, + const wxString& mimetype) const; + //@} + + /** + Returns a scaled version of the image. This is also useful for + scaling bitmaps in general as the only other way to scale bitmaps + is to blit a wxMemoryDC into another wxMemoryDC. + It should be noted that although using wxIMAGE_QUALITY_HIGH produces much nicer + looking results it is a slower method. Downsampling will use the box averaging + method + which seems to operate very fast. If you are upsampling larger images using + this method you will most likely notice that it is a bit slower and in extreme + cases + it will be quite substantially slower as the bicubic algorithm has to process a + lot of + data. + It should also be noted that the high quality scaling may not work as expected + when using a single mask colour for transparency, as the scaling will blur the + image and will therefore remove the mask partially. Using the alpha channel + will work. + Example: + + @param quality + Determines what method to use for resampling the image. + + Can be one of the following: + @li wxIMAGE_QUALITY_NORMAL: Uses the normal default scaling method of + pixel replication + @li wxIMAGE_QUALITY_HIGH: Uses bicubic and box averaging resampling + methods for upsampling and downsampling respectively + + @see Rescale() + */ + wxImage Scale(int width, int height, + int quality = wxIMAGE_QUALITY_NORMAL) const; + + /** + Assigns new data as alpha channel to the image. + If @e static_data is false the data will be + free()'d after use. + */ + void SetAlpha(unsigned char* alpha = NULL, + bool static_data = false); + + /** + Sets the alpha value for the given pixel. This function should only be + called if the image has alpha channel data, use HasAlpha() to + check for this. + */ + void SetAlpha(int x, int y, unsigned char alpha); + + /** + Sets the image data without performing checks. The data given must have + the size (width*height*3) or results will be unexpected. Don't use this + method if you aren't sure you know what you are doing. + The data must have been allocated with @c malloc(), @b NOT with + @c operator new. + After this call the pointer to the data is owned by the wxImage object, + that will be responsible for deleting it. + Do not pass to this function a pointer obtained through + GetData(). + */ + void SetData(unsigned char* data); + + /** + Specifies whether there is a mask or not. The area of the mask is determined by + the current mask colour. + */ + void SetMask(bool hasMask = true); + + /** + Sets the mask colour for this image (and tells the image to use the mask). + */ + void SetMaskColour(unsigned char red, unsigned char green, + unsigned char blue); + + /** + @param mask + The mask image to extract mask shape from. Must have same dimensions as the + image. + @param mr,mg,mb + RGB value of pixels in mask that will be used to create the mask. + + @return Returns @false if mask does not have same dimensions as the image + or if there is no unused colour left. Returns @true if + the mask was successfully applied. + */ + bool SetMaskFromImage(const wxImage& mask, unsigned char mr, + unsigned char mg, + unsigned char mb); + + //@{ + /** + Sets a user-defined option. The function is case-insensitive to @e name. + For example, when saving as a JPEG file, the option @b quality is + used, which is a number between 0 and 100 (0 is terrible, 100 is very good). + + @see GetOption(), GetOptionInt(), HasOption() + */ + void SetOption(const wxString& name, const wxString& value); + void SetOption(const wxString& name, int value); + //@} + + /** + Associates a palette with the image. The palette may be used when converting + wxImage to wxBitmap (MSW only at present) or in file save operations (none as + yet). + */ + void SetPalette(const wxPalette& palette); + + /** + Sets the colour of the pixels within the given rectangle. This routine performs + bounds-checks for the coordinate so it can be considered a safe way to + manipulate the + data. + */ + void SetRGB(wxRect& rect, unsigned char red, + unsigned char green, + unsigned char blue); + + /** + Returns a resized version of this image without scaling it by adding either a + border + with the given colour or cropping as necessary. The image is pasted into a new + image with the given @a size and background colour at the position @e pos + relative to the upper left of the new image. If @a red = green = blue = -1 + then the areas of the larger image not covered by this image are made + transparent by filling them with the image mask colour (which will be allocated + automatically if it isn't currently set). Otherwise, the areas will be filled + with the colour with the specified RGB components. + + @see Resize() + */ + wxImage Size(const wxSize& size, const wxPoint pos, int red = -1, + int green = -1, int blue = -1) const; + + /** + Assignment operator, using @ref overview_trefcount "reference counting". + + @param image + Image to assign. + + @return Returns 'this' object. + */ + wxImage operator =(const wxImage& image); +}; + +// ============================================================================ +// Global functions/macros +// ============================================================================ + +/** @ingroup group_funcmacro_appinitterm */ +//@{ + +/** + Initializes all available image handlers. For a list of available handlers, + see wxImage. + + @see wxImage, wxImageHandler + + @header{wx/image.h} +*/ +void wxInitAllImageHandlers(); + +//@} + diff --git a/interface/wx/imaglist.h b/interface/wx/imaglist.h new file mode 100644 index 0000000000..ca3711c418 --- /dev/null +++ b/interface/wx/imaglist.h @@ -0,0 +1,208 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: imaglist.h +// Purpose: interface of wxImageList +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxImageList + @wxheader{imaglist.h} + + A wxImageList contains a list of images, which are stored in + an unspecified form. Images can have masks for transparent + drawing, and can be made from a variety of sources including bitmaps + and icons. + + wxImageList is used principally in conjunction with wxTreeCtrl and + wxListCtrl classes. + + @library{wxcore} + @category{gdi} + + @see wxTreeCtrl, wxListCtrl +*/ +class wxImageList : public wxObject +{ +public: + //@{ + /** + Constructor specifying the image size, whether image masks should be created, + and the initial size of the list. + + @param width + Width of the images in the list. + @param height + Height of the images in the list. + @param mask + @true if masks should be created for all images. + @param initialCount + The initial size of the list. + + @see Create() + */ + wxImageList(); + wxImageList(int width, int height, bool mask = true, + int initialCount = 1); + //@} + + //@{ + /** + Adds a new image using an icon. + + @param bitmap + Bitmap representing the opaque areas of the image. + @param mask + Monochrome mask bitmap, representing the transparent areas of the image. + @param maskColour + Colour indicating which parts of the image are transparent. + @param icon + Icon to use as the image. + + @return The new zero-based image index. + + @remarks The original bitmap or icon is not affected by the Add + operation, and can be deleted afterwards. + */ + int Add(const wxBitmap& bitmap, + const wxBitmap& mask = wxNullBitmap); + int Add(const wxBitmap& bitmap, const wxColour& maskColour); + int Add(const wxIcon& icon); + //@} + + /** + Initializes the list. See wxImageList() for details. + */ + bool Create(int width, int height, bool mask = true, + int initialCount = 1); + + /** + Draws a specified image onto a device context. + + @param index + Image index, starting from zero. + @param dc + Device context to draw on. + @param x + X position on the device context. + @param y + Y position on the device context. + @param flags + How to draw the image. A bitlist of a selection of the following: + + + + + + + wxIMAGELIST_DRAW_NORMAL + + + + + Draw the image normally. + + + + + + wxIMAGELIST_DRAW_TRANSPARENT + + + + + Draw the image with transparency. + + + + + + wxIMAGELIST_DRAW_SELECTED + + + + + Draw the image in selected state. + + + + + + wxIMAGELIST_DRAW_FOCUSED + + + + + Draw the image in a focused state. + @param solidBackground + For optimisation - drawing can be faster if the function is told + that the background is solid. + */ + bool Draw(int index, wxDC& dc, int x, int y, + int flags = wxIMAGELIST_DRAW_NORMAL, + bool solidBackground = false); + + /** + Returns the bitmap corresponding to the given index. + */ + wxBitmap GetBitmap(int index) const; + + /** + Returns the icon corresponding to the given index. + */ + wxIcon GetIcon(int index) const; + + /** + Returns the number of images in the list. + */ + int GetImageCount() const; + + /** + Retrieves the size of the images in the list. Currently, the @a index + parameter is ignored as all images in the list have the same size. + + @param index + currently unused, should be 0 + @param width + receives the width of the images in the list + @param height + receives the height of the images in the list + + @return @true if the function succeeded, @false if it failed (for example, + if the image list was not yet initialized). + */ + bool GetSize(int index, int& width, int& height) const; + + /** + Removes the image at the given position. + */ + bool Remove(int index); + + /** + Removes all the images in the list. + */ + bool RemoveAll(); + + //@{ + /** + Replaces the existing image with the new image. + + @param bitmap + Bitmap representing the opaque areas of the image. + @param mask + Monochrome mask bitmap, representing the transparent areas of the image. + @param icon + Icon to use as the image. + + @return @true if the replacement was successful, @false otherwise. + + @remarks The original bitmap or icon is not affected by the Replace + operation, and can be deleted afterwards. + */ + bool Replace(int index, const wxBitmap& bitmap, + const wxBitmap& mask = wxNullBitmap); + bool Replace(int index, const wxIcon& icon); + //@} +}; + diff --git a/interface/wx/init.h b/interface/wx/init.h new file mode 100644 index 0000000000..499dbe1eed --- /dev/null +++ b/interface/wx/init.h @@ -0,0 +1,53 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: init.h +// Purpose: interface of global functions +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** @ingroup group_funcmacro_appinitterm */ +//@{ + +/** + This function can be used to perform the initialization of wxWidgets if you + can't use the default initialization code for any reason. + + If the function returns true, the initialization was successful and the + global wxApp object ::wxTheApp has been created. Moreover, wxEntryCleanup() + must be called afterwards. If the function returns false, a catastrophic + initialization error occured and (at least the GUI part of) the library + can't be used at all. + + Notice that parameters @c argc and @c argv may be modified by this + function. + + @header{wx/init.h} +*/ +bool wxEntryStart(int& argc, wxChar** argv); + +/** + See wxEntryStart(int&,wxChar**) for more info about this function. + + This is an additional overload of wxEntryStart() provided under MSW only. + It is meant to be called with the parameters passed to WinMain(). + + @note Under Windows CE platform, and only there, the type of @a pCmdLine is + @c wchar_t *, otherwise it is @c char *, even in Unicode build. + + @header{wx/init.h} +*/ +bool wxEntryStart(HINSTANCE hInstance, + HINSTANCE hPrevInstance = NULL, + char* pCmdLine = NULL, + int nCmdShow = SW_SHOWNORMAL); + +/** + Free resources allocated by a successful call to wxEntryStart(). + + @header{wx/init.h} +*/ +void wxEntryCleanup(); + +//@} + diff --git a/interface/wx/intl.h b/interface/wx/intl.h new file mode 100644 index 0000000000..e71e3ef00f --- /dev/null +++ b/interface/wx/intl.h @@ -0,0 +1,661 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: intl.h +// Purpose: interface of wxLocale +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxLocale + @wxheader{intl.h} + + wxLocale class encapsulates all language-dependent settings and is a + generalization of the C locale concept. + + In wxWidgets this class manages message catalogs which contain the translations + of the strings used to the current language. + + @b wxPerl note: In wxPerl you can't use the '_' function name, so + the @c Wx::Locale module can export the @c gettext and + @c gettext_noop under any given name. + + @code + # this imports gettext ( equivalent to Wx::GetTranslation + # and gettext_noop ( a noop ) + # into your module + use Wx::Locale qw(:default); + + # .... + + # use the functions + print gettext( "Panic!" ); + + button = Wx::Button-new( window, -1, gettext( "Label" ) ); + @endcode + + If you need to translate a lot of strings, then adding gettext( ) around + each one is a long task ( that is why _( ) was introduced ), so just choose + a shorter name for gettext: + + @code + # + use Wx::Locale 'gettext' = 't', + 'gettext_noop' = 'gettext_noop'; + + # ... + + # use the functions + print t( "Panic!!" ); + + # ... + @endcode + + @library{wxbase} + @category{FIXME} + + @see @ref overview_internationalization, @ref overview_sampleinternat "Internat + sample", wxXLocale +*/ +class wxLocale +{ +public: + //@{ + /** + See Init() for parameters description. + The call of this function has several global side effects which you should + understand: first of all, the application locale is changed - note that this + will affect many of standard C library functions such as printf() or strftime(). + Second, this wxLocale object becomes the new current global locale for the + application and so all subsequent calls to wxGetTranslation() will try to + translate the messages using the message catalogs for this locale. + */ + wxLocale(); + wxLocale(int language, + int flags = + wxLOCALE_LOAD_DEFAULT | wxLOCALE_CONV_ENCODING); + wxLocale(const wxString& name, + const wxString& short = wxEmptyString, + const wxString& locale = wxEmptyString, + bool bLoadDefault = true, + bool bConvertEncoding = false); + //@} + + /** + The destructor, like the constructor, also has global side effects: the + previously + set locale is restored and so the changes described in + Init() documentation are rolled back. + */ + ~wxLocale(); + + //@{ + /** + Add a catalog for use with the current locale: it is searched for in standard + places (current directory first, then the system one), but you may also prepend + additional directories to the search path with + AddCatalogLookupPathPrefix(). + All loaded catalogs will be used for message lookup by + GetString() for the current locale. + Returns @true if catalog was successfully loaded, @false otherwise (which might + mean that the catalog is not found or that it isn't in the correct format). + The second form of this method takes two additional arguments, + @a msgIdLanguage and @e msgIdCharset. + @a msgIdLanguage specifies the language of "msgid" strings in source code + (i.e. arguments to GetString(), + wxGetTranslation() and the + _() macro). It is used if AddCatalog cannot find any + catalog for current language: if the language is same as source code language, + then strings from source code are used instead. + @a msgIdCharset lets you specify the charset used for msgids in sources + in case they use 8-bit characters (e.g. German or French strings). This + argument has no effect in Unicode build, because literals in sources are + Unicode strings; you have to use compiler-specific method of setting the right + charset when compiling with Unicode. + By default (i.e. when you use the first form), msgid strings are assumed + to be in English and written only using 7-bit ASCII characters. + If you have to deal with non-English strings or 8-bit characters in the source + code, see the instructions in + @ref overview_nonenglishoverview "Writing non-English applications". + */ + bool AddCatalog(const wxString& domain); + bool AddCatalog(const wxString& domain, + wxLanguage msgIdLanguage, + const wxString& msgIdCharset); + //@} + + /** + Add a prefix to the catalog lookup path: the message catalog files will be + looked up under prefix/lang/LC_MESSAGES, prefix/lang and prefix + (in this order). + This only applies to subsequent invocations of AddCatalog(). + */ + void AddCatalogLookupPathPrefix(const wxString& prefix); + + /** + Adds custom, user-defined language to the database of known languages. This + database is used in conjunction with the first form of + Init(). + wxLanguageInfo is defined as follows: + @e Language should be greater than wxLANGUAGE_USER_DEFINED. + Wx::LanguageInfo-new( language, canonicalName, WinLang, WinSubLang, Description + ) + */ + static void AddLanguage(const wxLanguageInfo& info); + + /** + This function may be used to find the language description structure for the + given locale, specified either as a two letter ISO language code (for example, + "pt"), a language code followed by the country code ("pt_BR") or a full, human + readable, language description ("Portuguese-Brazil"). + Returns the information for the given language or @NULL if this language + is unknown. Note that even if the returned pointer is valid, the caller should + @e not delete it. + + @see GetLanguageInfo() + */ + static wxLanguageInfo* FindLanguageInfo(const wxString& locale); + + /** + Returns the canonical form of current locale name. Canonical form is the + one that is used on UNIX systems: it is a two- or five-letter string in xx or + xx_YY format, where xx is ISO 639 code of language and YY is ISO 3166 code of + the country. Examples are "en", "en_GB", "en_US" or "fr_FR". + This form is internally used when looking up message catalogs. + Compare GetSysName(). + */ + wxString GetCanonicalName() const; + + /** + Returns the header value for header @e header. The search for @a header is case + sensitive. If an @e domain + is passed, this domain is searched. Else all domains will be searched until a + header has been found. + The return value is the value of the header if found. Else this will be empty. + */ + wxString GetHeaderValue(const wxString& header, + const wxString& domain = wxEmptyString) const; + + /** + Returns wxLanguage() constant of current language. + Note that you can call this function only if you used the form of + Init() that takes wxLanguage argument. + */ + int GetLanguage() const; + + /** + Returns a pointer to wxLanguageInfo structure containing information about the + given language or @NULL if this language is unknown. Note that even if the + returned pointer is valid, the caller should @e not delete it. + See AddLanguage() for the wxLanguageInfo + description. + As with Init(), @c wxLANGUAGE_DEFAULT has the + special meaning if passed as an argument to this function and in this case the + result of GetSystemLanguage() is used. + */ + static wxLanguageInfo* GetLanguageInfo(int lang) const; + + /** + Returns English name of the given language or empty string if this + language is unknown. + See GetLanguageInfo() for a remark about + special meaning of @c wxLANGUAGE_DEFAULT. + */ + static wxString GetLanguageName(int lang) const; + + /** + Returns the locale name as passed to the constructor or + Init(). This is full, human-readable name, + e.g. "English" or "French". + */ + const wxString GetLocale() const; + + /** + Returns the current short name for the locale (as given to the constructor or + the Init() function). + */ + const wxString GetName() const; + + //@{ + /** + Retrieves the translation for a string in all loaded domains unless the szDomain + parameter is specified (and then only this catalog/domain is searched). + Returns original string if translation is not available + (in this case an error message is generated the first time + a string is not found; use wxLogNull to suppress it). + The second form is used when retrieving translation of string that has + different singular and plural form in English or different plural forms in some + other language. It takes two extra arguments: @e origString + parameter must contain the singular form of the string to be converted. + It is also used as the key for the search in the catalog. + The @a origString2 parameter is the plural form (in English). + The parameter @a n is used to determine the plural form. If no + message catalog is found @a origString is returned if 'n == 1', + otherwise @e origString2. + See GNU gettext manual for additional information on plural forms handling. + This method is called by the wxGetTranslation() + function and _() macro. + + @remarks Domains are searched in the last to first order, i.e. catalogs + added later override those added before. + */ + const wxString GetString(const wxString& origString, + const wxString& domain = wxEmptyString) const; + const const wxString& GetString(const wxString& origString, + const wxString& origString2, + size_t n, + const wxString& domain = NULL) const; + //@} + + /** + Returns current platform-specific locale name as passed to setlocale(). + Compare GetCanonicalName(). + */ + wxString GetSysName() const; + + /** + Tries to detect the user's default font encoding. + Returns wxFontEncoding() value or + @b wxFONTENCODING_SYSTEM if it couldn't be determined. + */ + static wxFontEncoding GetSystemEncoding() const; + + /** + Tries to detect the name of the user's default font encoding. This string isn't + particularly useful for the application as its form is platform-dependent and + so you should probably use + GetSystemEncoding() instead. + Returns a user-readable string value or an empty string if it couldn't be + determined. + */ + static wxString GetSystemEncodingName() const; + + /** + Tries to detect the user's default language setting. + Returns wxLanguage() value or + @b wxLANGUAGE_UNKNOWN if the language-guessing algorithm failed. + */ + static int GetSystemLanguage() const; + + //@{ + /** + The second form is deprecated, use the first one unless you know what you are + doing. + + @param language + wxLanguage identifier of the locale. + wxLANGUAGE_DEFAULT has special meaning -- wxLocale will use system's + default + language (see GetSystemLanguage). + @param flags + Combination of the following: + + + + + + + + wxLOCALE_LOAD_DEFAULT + + + + + Load the message catalog + for the given locale containing the translations of standard wxWidgets + messages + automatically. + + + + + + wxLOCALE_CONV_ENCODING + + + + + Automatically convert message + catalogs to platform's default encoding. Note that it will do only basic + conversion between well-known pair like iso8859-1 and windows-1252 or + iso8859-2 and windows-1250. See Writing non-English applications for + detailed + description of this behaviour. Note that this flag is meaningless in + Unicode build. + @param name + The name of the locale. Only used in diagnostic messages. + @param short + The standard 2 letter locale abbreviation; it is used as the + directory prefix when looking for the message catalog files. + @param locale + The parameter for the call to setlocale(). Note that it is + platform-specific. + @param bLoadDefault + May be set to @false to prevent loading of the message catalog + for the given locale containing the translations of standard wxWidgets + messages. + This parameter would be rarely used in normal circumstances. + @param bConvertEncoding + May be set to @true to do automatic conversion of message + catalogs to platform's native encoding. Note that it will do only basic + conversion between well-known pair like iso8859-1 and windows-1252 or + iso8859-2 and windows-1250. + See Writing non-English applications for detailed + description of this behaviour. + */ + bool Init(int language = wxLANGUAGE_DEFAULT, + int flags = + wxLOCALE_LOAD_DEFAULT | wxLOCALE_CONV_ENCODING); + bool Init(const wxString& name, + const wxString& short = wxEmptyString, + const wxString& locale = wxEmptyString, + bool bLoadDefault = true, + bool bConvertEncoding = false); + //@} + + /** + Check whether the operating system and/or C run time environment supports + this locale. For example in Windows 2000 and Windows XP, support for many + locales is not installed by default. Returns @true if the locale is + supported. + The argument @a lang is the wxLanguage identifier. To obtain this for a + given a two letter ISO language code, use + FindLanguageInfo() to obtain its + wxLanguageInfo structure. See AddLanguage() for + the wxLanguageInfo description. + + @since 2.7.1. + */ + static bool IsAvailable(int lang); + + /** + Check if the given catalog is loaded, and returns @true if it is. + According to GNU gettext tradition, each catalog + normally corresponds to 'domain' which is more or less the application name. + See also: AddCatalog() + */ + bool IsLoaded(const char* domain) const; + + /** + Returns @true if the locale could be set successfully. + */ + bool IsOk() const; + + /** + See @ref overview_languagecodes "list of recognized language constants". + These constants may be used to specify the language + in Init() and are returned by + GetSystemLanguage(): + */ +}; + + + +/** + @class wxXLocale + @wxheader{intl.h} + + + wxXLocale::wxXLocale + wxXLocale::GetCLocale + wxXLocale::IsOk + + + Introduction + + This class represents a locale object used by so-called xlocale API. Unlike + wxLocale it doesn't provide any non-trivial operations but + simply provides a portable wrapper for POSIX @c locale_t type. It exists + solely to be provided as an argument to various @c wxFoo_l() functions + which are the extensions of the standard locale-dependent functions (hence the + name xlocale). These functions do exactly the same thing as the corresponding + standard @c foo() except that instead of using the global program locale + they use the provided wxXLocale object. For example, if the user runs the + program in French locale, the standard @c printf() function will output + floating point numbers using decimal comma instead of decimal period. If the + program needs to format a floating-point number in a standard format it can + use @c wxPrintf_l(wxXLocale::GetCLocale(), "%g", number) to do it. + Conversely, if a program wanted to output the number in French locale, even if + the current locale is different, it could use wxXLocale(wxLANGUAGE_FRENCH). + + + Availability + + This class is fully implemented only under the platforms where xlocale POSIX + API or equivalent is available. Currently the xlocale API is available under + most of the recent Unix systems (including Linux, various BSD and Mac OS X) and + Microsoft Visual C++ standard library provides a similar API starting from + version 8 (Visual Studio 2005). + + If neither POSIX API nor Microsoft proprietary equivalent are available, this + class is still available but works in degraded mode: the only supported locale + is the C one and attempts to create wxXLocale object for any other locale will + fail. You can use the preprocessor macro @c wxHAS_XLOCALE_SUPPORT to + test if full xlocale API is available or only skeleton C locale support is + present. + + Notice that wxXLocale is new in wxWidgets 2.9.0 and is not compiled in if + @c wxUSE_XLOCALE was set to 0 during the library compilation. + + + Locale-dependent functions + + Currently the following @c _l-functions are available: + + Character classification functions: @c wxIsxxx_l(), e.g. + @c wxIsalpha_l(), @c wxIslower_l() and all the others. + Character transformation functions: @c wxTolower_l() and + @c wxToupper_l() + + We hope to provide many more functions (covering numbers, time and formatted + IO) in the near future. + + @library{wxbase} + @category{FIXME} + + @see wxLocale +*/ +class wxXLocale +{ +public: + //@{ + /** + Creates the locale object corresponding to the specified locale string. The + locale string is system-dependent, use constructor taking wxLanguage for better + portability. + */ + wxLocale(); + wxLocale(wxLanguage lang); + wxLocale(const char* loc); + //@} + + /** + This class is fully implemented only under the platforms where xlocale POSIX + API or equivalent is available. Currently the xlocale API is available under + most of the recent Unix systems (including Linux, various BSD and Mac OS X) and + Microsoft Visual C++ standard library provides a similar API starting from + version 8 (Visual Studio 2005). + If neither POSIX API nor Microsoft proprietary equivalent are available, this + class is still available but works in degraded mode: the only supported locale + is the C one and attempts to create wxXLocale object for any other locale will + fail. You can use the preprocessor macro @c wxHAS_XLOCALE_SUPPORT to + test if full xlocale API is available or only skeleton C locale support is + present. + Notice that wxXLocale is new in wxWidgets 2.9.0 and is not compiled in if + @c wxUSE_XLOCALE was set to 0 during the library compilation. + */ + + + /** + Returns the global object representing the "C" locale. For an even shorter + access to this object a global @c wxCLocale variable (implemented as a + macro) is provided and can be used instead of calling this method. + */ + static wxXLocale GetCLocale(); + + /** + This class represents a locale object used by so-called xlocale API. Unlike + wxLocale it doesn't provide any non-trivial operations but + simply provides a portable wrapper for POSIX @c locale_t type. It exists + solely to be provided as an argument to various @c wxFoo_l() functions + which are the extensions of the standard locale-dependent functions (hence the + name xlocale). These functions do exactly the same thing as the corresponding + standard @c foo() except that instead of using the global program locale + they use the provided wxXLocale object. For example, if the user runs the + program in French locale, the standard @c printf() function will output + floating point numbers using decimal comma instead of decimal period. If the + program needs to format a floating-point number in a standard format it can + use @c wxPrintf_l(wxXLocale::GetCLocale(), "%g", number) to do it. + Conversely, if a program wanted to output the number in French locale, even if + the current locale is different, it could use wxXLocale(wxLANGUAGE_FRENCH). + */ + + + /** + Returns @true if this object is initialized, i.e. represents a valid locale + or + @false otherwise. + */ + bool IsOk() const; + + /** + Currently the following @c _l-functions are available: + Character classification functions: @c wxIsxxx_l(), e.g. + @c wxIsalpha_l(), @c wxIslower_l() and all the others. + Character transformation functions: @c wxTolower_l() and + @c wxToupper_l() + We hope to provide many more functions (covering numbers, time and formatted + IO) in the near future. + + @see wxLocale + */ +}; + + + +// ============================================================================ +// Global functions/macros +// ============================================================================ + +/** @ingroup group_funcmacro_string */ +//@{ + +/** + This macro is identical to _() but for the plural variant of + wxGetTranslation(). + + @return A const wxString. + + @header{wx/intl.h} +*/ +#define wxPLURAL(string, plural, n) + +/** + This macro doesn't do anything in the program code -- it simply expands to + the value of its argument. + + However it does have a purpose which is to mark the literal strings for the + extraction into the message catalog created by @c xgettext program. Usually + this is achieved using _() but that macro not only marks the string for + extraction but also expands into a wxGetTranslation() call which means that + it cannot be used in some situations, notably for static array + initialization. + + Here is an example which should make it more clear: suppose that you have a + static array of strings containing the weekday names and which have to be + translated (note that it is a bad example, really, as wxDateTime already + can be used to get the localized week day names already). If you write: + + @code + static const char * const weekdays[] = { _("Mon"), ..., _("Sun") }; + ... + // use weekdays[n] as usual + @endcode + + The code wouldn't compile because the function calls are forbidden in the + array initializer. So instead you should do this: + + @code + static const char * const weekdays[] = { wxTRANSLATE("Mon"), ..., + wxTRANSLATE("Sun") }; + ... + // use wxGetTranslation(weekdays[n]) + @endcode + + Note that although the code @b would compile if you simply omit + wxTRANSLATE() in the above, it wouldn't work as expected because there + would be no translations for the weekday names in the program message + catalog and wxGetTranslation() wouldn't find them. + + @return A const wxChar*. + + @header{wx/intl.h} +*/ +#define wxTRANSLATE(string) + +/** + This function returns the translation of @a string in the current + @c locale(). If the string is not found in any of the loaded message + catalogs (see @ref overview_i18n), the original string is returned. In + debug build, an error message is logged -- this should help to find the + strings which were not yet translated. If @a domain is specified then only + that domain/catalog is searched for a matching string. As this function is + used very often, an alternative (and also common in Unix world) syntax is + provided: the _() macro is defined to do the same thing as + wxGetTranslation(). + + This function calls wxLocale::GetString(). + + @note This function is not suitable for literal strings in Unicode builds + since the literal strings must be enclosed into _T() or wxT() macro + which makes them unrecognised by @c xgettext, and so they are not + extracted to the message catalog. Instead, use the _() and wxPLURAL() + macro for all literal strings. + + @see wxGetTranslation(const wxString&, const wxString&, size_t, const wxString&) + + @header{wx/intl.h} +*/ +const wxString wxGetTranslation(const wxString& string, + const wxString& domain = wxEmptyString); + +/** + This is an overloaded version of + wxGetTranslation(const wxString&, const wxString&), please see its + documentation for general information. + + This version is used when retrieving translation of string that has + different singular and plural forms in English or different plural forms in + some other language. Like wxGetTranslation(const wxString&,const wxString&), + the @a string parameter must contain the singular form of the string to be + converted and is used as the key for the search in the catalog. The + @a plural parameter is the plural form (in English). The parameter @a n is + used to determine the plural form. If no message catalog is found, + @a string is returned if "n == 1", otherwise @a plural is returned. + + See GNU gettext Manual for additional information on plural forms handling: + + For a shorter alternative see the wxPLURAL() macro. + + This function calls wxLocale::GetString(). + + @header{wx/intl.h} +*/ +const wxString wxGetTranslation(const wxString& string, + const wxString& plural, size_t n, + const wxString& domain = wxEmptyString); + +/** + This macro expands into a call to wxGetTranslation(), so it marks the + message for the extraction by @c xgettext just as wxTRANSLATE() does, but + also returns the translation of the string for the current locale during + execution. + + Don't confuse this with _T()! + + @header{wx/intl.h} +*/ +const wxString _(const wxString& string); + +//@} + diff --git a/interface/wx/ipc.h b/interface/wx/ipc.h new file mode 100644 index 0000000000..c6bd35c787 --- /dev/null +++ b/interface/wx/ipc.h @@ -0,0 +1,350 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: ipc.h +// Purpose: interface of wxConnection +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxConnection + @wxheader{ipc.h} + + A wxConnection object represents the connection between a client + and a server. It is created by making a connection using a + wxClient object, or by the acceptance of a + connection by a wxServer object. The + bulk of a DDE-like (Dynamic Data Exchange) conversation is + controlled by calling members in a @b wxConnection object or + by overriding its members. The actual DDE-based implementation + using wxDDEConnection is available on Windows only, but a + platform-independent, socket-based version of this API is + available using wxTCPConnection, which has the same API. + + An application should normally derive a new connection class from + wxConnection, in order to override the communication event + handlers to do something interesting. + + @library{wxbase} + @category{FIXME} + + @see wxClient, wxServer, @ref overview_ipcoverview "Interprocess communications + overview" +*/ +class wxConnection : public wxObject +{ +public: + //@{ + /** + Constructs a connection object. If no user-defined connection + object is to be derived from wxConnection, then the constructor + should not be called directly, since the default connection + object will be provided on requesting (or accepting) a + connection. However, if the user defines his or her own derived + connection object, the wxServer::OnAcceptConnection + and/or wxClient::OnMakeConnection + members should be replaced by functions which construct the new + connection object. + If the arguments of the wxConnection constructor are void then + the wxConnection object manages its own connection buffer, + allocating memory as needed. A programmer-supplied buffer cannot + be increased if necessary, and the program will assert if it is + not large enough. The programmer-supplied buffer is included + mainly for backwards compatibility. + */ + wxConnection(); + wxConnection(void* buffer, size_t size); + //@} + + //@{ + /** + Called by the server application to advise the client of a change + in the data associated with the given item. Causes the client + connection's OnAdvise() member + to be called. Returns @true if successful. + */ + bool Advise(const wxString& item, const void* data, size_t size, + wxIPCFormat format = wxIPC_PRIVATE); + bool Advise(const wxString& item, const char* data); + bool Advise(const wxString& item, const wchar_t* data); + bool Advise(const wxString& item, const wxString data); + //@} + + /** + Called by the client or server application to disconnect from the + other program; it causes the OnDisconnect() + message to be sent to the corresponding connection object in the + other program. Returns @true if successful or already disconnected. + The application that calls @b Disconnect must explicitly delete + its side of the connection. + */ + bool Disconnect(); + + //@{ + /** + Called by the client application to execute a command on the + server. Can also be used to transfer arbitrary data to the server + (similar to Poke() in + that respect). Causes the server connection's OnExec() + member to be called. Returns @true if successful. + */ + bool Execute(const void* data, size_t size, + wxIPCFormat format = wxIPC_PRIVATE); + bool Execute(const char* data); + bool Execute(const wchar_t* data); + bool Execute(const wxString data); + //@} + + /** + Message sent to the client application when the server notifies + it of a change in the data associated with the given item, using + Advise(). + */ + virtual bool OnAdvise(const wxString& topic, + const wxString& item, + const void* data, + size_t size, + wxIPCFormat format); + + /** + Message sent to the client or server application when the other + application notifies it to end the connection. The default + behaviour is to delete the connection object and return @true, so + applications should generally override @b OnDisconnect + (finally calling the inherited method as well) so that they know + the connection object is no longer available. + */ + virtual bool OnDisconnect(); + + /** + Message sent to the server application when the client notifies + it to execute the given data, using Execute(). + Note that there is no item associated with this message. + */ + virtual bool OnExec(const wxString& topic, const wxString& data); + + /** + Message sent to the server application when the client notifies it to + accept the given data. + */ + virtual bool OnPoke(const wxString& topic, const wxString& item, + const void* data, + size_t size, + wxIPCFormat format); + + /** + Message sent to the server application when the client calls + Request(). The + server's OnRequest() method + should respond by returning a character string, or @NULL to + indicate no data, and setting *size. The character string must of + course persist after the call returns. + */ + virtual const void* OnRequest(const wxString& topic, + const wxString& item, + size_t* size, + wxIPCFormat format); + + /** + Message sent to the server application by the client, when the client + wishes to start an 'advise loop' for the given topic and item. The + server can refuse to participate by returning @false. + */ + virtual bool OnStartAdvise(const wxString& topic, + const wxString& item); + + /** + Message sent to the server application by the client, when the client + wishes to stop an 'advise loop' for the given topic and item. The + server can refuse to stop the advise loop by returning @false, although + this doesn't have much meaning in practice. + */ + virtual bool OnStopAdvise(const wxString& topic, + const wxString& item); + + //@{ + /** + Called by the client application to poke data into the server. + Can be used to transfer arbitrary data to the server. Causes the + server connection's OnPoke() member to + be called. If size is -1 the size is computed from the string + length of data. + Returns @true if successful. + */ + bool Poke(const wxString& item, const void* data, size_t size, + wxIPCFormat format = wxIPC_PRIVATE); + bool Poke(const wxString& item, const char* data); + bool Poke(const wxString& item, const wchar_t* data); + bool Poke(const wxString& item, const wxString data); + //@} + + /** + Called by the client application to request data from the server. + Causes the server connection's OnRequest() + member to be called. Size may be @NULL or a pointer to a variable + to receive the size of the requested item. + Returns a character string (actually a pointer to the + connection's buffer) if successful, @NULL otherwise. This buffer + does not need to be deleted. + */ + const void* Request(const wxString& item, size_t* size, + wxIPCFormat format = wxIPC_TEXT); + + /** + Called by the client application to ask if an advise loop can be + started with the server. Causes the server connection's + OnStartAdvise() + member to be called. Returns @true if the server okays it, @false + otherwise. + */ + bool StartAdvise(const wxString& item); + + /** + Called by the client application to ask if an advise loop can be + stopped. Causes the server connection's OnStopAdvise() + member to be called. Returns @true if the server okays it, @false + otherwise. + */ + bool StopAdvise(const wxString& item); +}; + + + +/** + @class wxClient + @wxheader{ipc.h} + + A wxClient object represents the client part of a client-server + DDE-like (Dynamic Data Exchange) conversation. The actual + DDE-based implementation using wxDDEClient is available on Windows + only, but a platform-independent, socket-based version of this + API is available using wxTCPClient, which has the same API. + + To create a client which can communicate with a suitable server, + you need to derive a class from wxConnection and another from + wxClient. The custom wxConnection class will intercept + communications in a 'conversation' with a server, and the custom + wxClient is required so that a user-overridden + wxClient::OnMakeConnection + member can return a wxConnection of the required class, when a + connection is made. Look at the IPC sample and the + @ref overview_ipcoverview "Interprocess communications overview" for + an example of how to do this. + + @library{wxbase} + @category{FIXME} + + @see wxServer, wxConnection, @ref overview_ipcoverview "Interprocess + communications overview" +*/ +class wxClient : public wxObject +{ +public: + /** + Constructs a client object. + */ + wxClient(); + + /** + Tries to make a connection with a server by host (machine name + under UNIX - use 'localhost' for same machine; ignored when using + native DDE in Windows), service name and topic string. If the + server allows a connection, a wxConnection object will be + returned. The type of wxConnection returned can be altered by + overriding the + OnMakeConnection() + member to return your own derived connection object. + Under Unix, the service name may be either an integer port + identifier in which case an Internet domain socket will be used + for the communications, or a valid file name (which shouldn't + exist and will be deleted afterwards) in which case a Unix domain + socket is created. + @b SECURITY NOTE: Using Internet domain sockets if extremely + insecure for IPC as there is absolutely no access control for + them, use Unix domain sockets whenever possible! + */ + wxConnectionBase* MakeConnection(const wxString& host, + const wxString& service, + const wxString& topic); + + /** + Called by MakeConnection(), by + default this simply returns a new wxConnection object. Override + this method to return a wxConnection descendant customised for the + application. + The advantage of deriving your own connection class is that it + will enable you to intercept messages initiated by the server, + such as wxConnection::OnAdvise. You + may also want to store application-specific data in instances of + the new class. + */ + wxConnectionBase* OnMakeConnection(); + + /** + Returns @true if this is a valid host name, @false otherwise. This always + returns @true under MS Windows. + */ + bool ValidHost(const wxString& host); +}; + + + +/** + @class wxServer + @wxheader{ipc.h} + + A wxServer object represents the server part of a client-server + DDE-like (Dynamic Data Exchange) conversation. The actual + DDE-based implementation using wxDDEServer is available on Windows + only, but a platform-independent, socket-based version of this + API is available using wxTCPServer, which has the same API. + + To create a server which can communicate with a suitable client, + you need to derive a class from wxConnection and another from + wxServer. The custom wxConnection class will intercept + communications in a 'conversation' with a client, and the custom + wxServer is required so that a user-overridden wxServer::OnAcceptConnection + member can return a wxConnection of the required class, when a + connection is made. Look at the IPC sample and the @ref overview_ipcoverview + "Interprocess communications overview" for + an example of how to do this. + + @library{wxbase} + @category{FIXME} + + @see wxClient, wxConnection, IPC, overview() +*/ +class wxServer +{ +public: + /** + Constructs a server object. + */ + wxServer(); + + /** + Registers the server using the given service name. Under Unix, + the service name may be either an integer port identifier in + which case an Internet domain socket will be used for the + communications, or a valid file name (which shouldn't exist and + will be deleted afterwards) in which case a Unix domain socket is + created. @false is returned if the call failed (for example, the + port number is already in use). + */ + bool Create(const wxString& service); + + /** + When a client calls @b MakeConnection, the server receives the + message and this member is called. The application should derive a + member to intercept this message and return a connection object of + either the standard wxConnection type, or (more likely) of a + user-derived type. + If the topic is @b STDIO, the application may wish to refuse the + connection. Under UNIX, when a server is created the + OnAcceptConnection message is always sent for standard input and + output, but in the context of DDE messages it doesn't make a lot + of sense. + */ + virtual wxConnectionBase* OnAcceptConnection(const wxString& topic); +}; + diff --git a/interface/wx/ipcbase.h b/interface/wx/ipcbase.h new file mode 100644 index 0000000000..f8728ccdc4 --- /dev/null +++ b/interface/wx/ipcbase.h @@ -0,0 +1,53 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: ipcbase.h +// Purpose: interface of wxConnectionBase +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +enum wxIPCFormat +{ + wxIPC_INVALID = 0, + wxIPC_TEXT = 1, ///< CF_TEXT + wxIPC_BITMAP = 2, ///< CF_BITMAP + wxIPC_METAFILE = 3, ///< CF_METAFILEPICT + wxIPC_SYLK = 4, + wxIPC_DIF = 5, + wxIPC_TIFF = 6, + wxIPC_OEMTEXT = 7, ///< CF_OEMTEXT + wxIPC_DIB = 8, ///< CF_DIB + wxIPC_PALETTE = 9, + wxIPC_PENDATA = 10, + wxIPC_RIFF = 11, + wxIPC_WAVE = 12, + wxIPC_UTF16TEXT = 13, ///< CF_UNICODE + wxIPC_ENHMETAFILE = 14, + wxIPC_FILENAME = 15, ///< CF_HDROP + wxIPC_LOCALE = 16, + wxIPC_UTF8TEXT = 17, + wxIPC_UTF32TEXT = 18, + wxIPC_UNICODETEXT = wxIPC_UTF16TEXT, + wxIPC_PRIVATE = 20 +}; + +/** + @class wxConnectionBase + @wxheader{ipcbase.h} + + @todo Document this class. + + This class provides base, common functionality shared between + wxDDEConnection, and wxTCPConnection. + + @library{wxbase} + @category{ipc} + + @see wxDDEConnection, wxTCPConnection +*/ +class wxConnectionBase: public wxObject +{ +public: + +}; + diff --git a/interface/wx/joystick.h b/interface/wx/joystick.h new file mode 100644 index 0000000000..d9b739c6ff --- /dev/null +++ b/interface/wx/joystick.h @@ -0,0 +1,272 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: joystick.h +// Purpose: interface of wxJoystick +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxJoystick + @wxheader{joystick.h} + + wxJoystick allows an application to control one or more joysticks. + + @library{wxadv} + @category{FIXME} + + @see wxJoystickEvent +*/ +class wxJoystick : public wxObject +{ +public: + /** + Constructor. @a joystick may be one of wxJOYSTICK1, wxJOYSTICK2, indicating the + joystick + controller of interest. + */ + wxJoystick(int joystick = wxJOYSTICK1); + + /** + Destroys the wxJoystick object. + */ + ~wxJoystick(); + + //@{ + /** + Returns the state of the specified joystick button. + + @param id + The button id to report, from 0 to GetNumberButtons() - 1 + */ + int GetButtonState() const; + const bool GetButtonState(unsigned id) const; + //@} + + /** + Returns the manufacturer id. + */ + int GetManufacturerId() const; + + /** + Returns the movement threshold, the number of steps outside which the joystick + is deemed to have + moved. + */ + int GetMovementThreshold() const; + + /** + Returns the number of axes for this joystick. + */ + int GetNumberAxes() const; + + /** + Returns the number of buttons for this joystick. + */ + int GetNumberButtons() const; + + /** + Returns the number of joysticks currently attached to the computer. + */ + static int GetNumberJoysticks(); + + /** + Returns the point-of-view position, expressed in continuous, one-hundredth of a + degree units. + Returns -1 on error. + */ + int GetPOVCTSPosition() const; + + /** + Returns the point-of-view position, expressed in continuous, one-hundredth of a + degree units, + but limited to return 0, 9000, 18000 or 27000. + Returns -1 on error. + */ + int GetPOVPosition() const; + + /** + Returns the maximum polling frequency. + */ + int GetPollingMax() const; + + /** + Returns the minimum polling frequency. + */ + int GetPollingMin() const; + + //@{ + /** + Returns the position of the specified joystick axis. + + @param axis + The joystick axis to report, from 0 to GetNumberAxes() - 1. + */ + wxPoint GetPosition() const; + const int GetPosition(unsigned axis) const; + //@} + + /** + Returns the product id for the joystick. + */ + int GetProductId() const; + + /** + Returns the product name for the joystick. + */ + wxString GetProductName() const; + + /** + Returns the maximum rudder position. + */ + int GetRudderMax() const; + + /** + Returns the minimum rudder position. + */ + int GetRudderMin() const; + + /** + Returns the rudder position. + */ + int GetRudderPosition() const; + + /** + Returns the maximum U position. + */ + int GetUMax() const; + + /** + Returns the minimum U position. + */ + int GetUMin() const; + + /** + Gets the position of the fifth axis of the joystick, if it exists. + */ + int GetUPosition() const; + + /** + Returns the maximum V position. + */ + int GetVMax() const; + + /** + Returns the minimum V position. + */ + int GetVMin() const; + + /** + Gets the position of the sixth axis of the joystick, if it exists. + */ + int GetVPosition() const; + + /** + Returns the maximum x position. + */ + int GetXMax() const; + + /** + Returns the minimum x position. + */ + int GetXMin() const; + + /** + Returns the maximum y position. + */ + int GetYMax() const; + + /** + Returns the minimum y position. + */ + int GetYMin() const; + + /** + Returns the maximum z position. + */ + int GetZMax() const; + + /** + Returns the minimum z position. + */ + int GetZMin() const; + + /** + Returns the z position of the joystick. + */ + int GetZPosition() const; + + /** + Returns @true if the joystick has a point of view control. + */ + bool HasPOV() const; + + /** + Returns @true if the joystick point-of-view supports discrete values (centered, + forward, backward, left, and right). + */ + bool HasPOV4Dir() const; + + /** + Returns @true if the joystick point-of-view supports continuous degree bearings. + */ +#define bool HasPOVCTS() const /* implementation is private */ + + /** + Returns @true if there is a rudder attached to the computer. + */ + bool HasRudder() const; + + /** + Returns @true if the joystick has a U axis. + */ + bool HasU() const; + + /** + Returns @true if the joystick has a V axis. + */ + bool HasV() const; + + /** + Returns @true if the joystick has a Z axis. + */ + bool HasZ() const; + + /** + Returns @true if the joystick is functioning. + */ + bool IsOk() const; + + /** + Releases the capture set by @b SetCapture. + + @return @true if the capture release succeeded. + + @see SetCapture(), wxJoystickEvent + */ + bool ReleaseCapture(); + + /** + Sets the capture to direct joystick events to @e win. + + @param win + The window that will receive joystick events. + @param pollingFreq + If zero, movement events are sent when above the + threshold. If greater than zero, events are received every pollingFreq + milliseconds. + + @return @true if the capture succeeded. + + @see ReleaseCapture(), wxJoystickEvent + */ + bool SetCapture(wxWindow* win, int pollingFreq = 0); + + /** + Sets the movement threshold, the number of steps outside which the joystick is + deemed to have + moved. + */ + void SetMovementThreshold(int threshold); +}; + diff --git a/interface/wx/laywin.h b/interface/wx/laywin.h new file mode 100644 index 0000000000..a09ff3d194 --- /dev/null +++ b/interface/wx/laywin.h @@ -0,0 +1,416 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: laywin.h +// Purpose: interface of wxLayoutAlgorithm +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxLayoutAlgorithm + @wxheader{laywin.h} + + wxLayoutAlgorithm implements layout of subwindows in MDI or SDI frames. + It sends a wxCalculateLayoutEvent event + to children of the frame, asking them for information about + their size. For MDI parent frames, the algorithm allocates + the remaining space to the MDI client window (which contains the MDI child + frames). + For SDI (normal) frames, a 'main' window is specified as taking up the + remaining space. + + Because the event system is used, this technique can be applied to any windows, + which are not necessarily 'aware' of the layout classes (no virtual functions + in wxWindow refer to wxLayoutAlgorithm or its events). However, you + may wish to use wxSashLayoutWindow for your subwindows + since this class provides handlers for the required events, and accessors + to specify the desired size of the window. The sash behaviour in the base class + can be used, optionally, to make the windows user-resizable. + + wxLayoutAlgorithm is typically used in IDE (integrated development environment) + applications, + where there are several resizable windows in addition to the MDI client window, + or + other primary editing window. Resizable windows might include toolbars, a + project + window, and a window for displaying error and warning messages. + + When a window receives an OnCalculateLayout event, it should call SetRect in + the given event object, to be the old supplied rectangle minus whatever space + the + window takes up. It should also set its own size accordingly. + wxSashLayoutWindow::OnCalculateLayout generates an OnQueryLayoutInfo event + which it sends to itself to determine the orientation, alignment and size of + the window, + which it gets from internal member variables set by the application. + + The algorithm works by starting off with a rectangle equal to the whole frame + client area. + It iterates through the frame children, generating OnCalculateLayout events + which subtract + the window size and return the remaining rectangle for the next window to + process. It + is assumed (by wxSashLayoutWindow::OnCalculateLayout) that a window stretches + the full dimension + of the frame client, according to the orientation it specifies. For example, a + horizontal window + will stretch the full width of the remaining portion of the frame client area. + In the other orientation, the window will be fixed to whatever size was + specified by + OnQueryLayoutInfo. An alignment setting will make the window 'stick' to the + left, top, right or + bottom of the remaining client area. This scheme implies that order of window + creation is important. + Say you wish to have an extra toolbar at the top of the frame, a project window + to the left of + the MDI client window, and an output window above the status bar. You should + therefore create + the windows in this order: toolbar, output window, project window. This ensures + that the toolbar and + output window take up space at the top and bottom, and then the remaining + height in-between is used for + the project window. + + wxLayoutAlgorithm is quite independent of the way in which + OnCalculateLayout chooses to interpret a window's size and alignment. Therefore + you + could implement a different window class with a new OnCalculateLayout event + handler, + that has a more sophisticated way of laying out the windows. It might allow + specification of whether stretching occurs in the specified orientation, for + example, + rather than always assuming stretching. (This could, and probably should, be + added to the existing + implementation). + + @e Note: wxLayoutAlgorithm has nothing to do with wxLayoutConstraints. It is an + alternative + way of specifying layouts for which the normal constraint system is unsuitable. + + @library{wxadv} + @category{winlayout} + + @see wxSashEvent, wxSashLayoutWindow, @ref overview_eventhandlingoverview +*/ +class wxLayoutAlgorithm : public wxObject +{ +public: + /** + Default constructor. + */ + wxLayoutAlgorithm(); + + /** + Destructor. + */ + ~wxLayoutAlgorithm(); + + /** + Lays out the children of a normal frame. @a mainWindow is set to occupy the + remaining space. + This function simply calls LayoutWindow(). + */ + bool LayoutFrame(wxFrame* frame, wxWindow* mainWindow = NULL) const; + + /** + Lays out the children of an MDI parent frame. If @a rect is non-@NULL, the + given rectangle will be used as a starting point instead of the frame's client + area. + The MDI client window is set to occupy the remaining space. + */ + bool LayoutMDIFrame(wxMDIParentFrame* frame, wxRect* rect = NULL) const; + + /** + Lays out the children of a normal frame or other window. + @a mainWindow is set to occupy the remaining space. If this is not specified, + then + the last window that responds to a calculate layout event in query mode will + get the remaining space + (that is, a non-query OnCalculateLayout event will not be sent to this window + and the window will be set + to the remaining size). + */ + bool LayoutWindow(wxWindow* parent, wxWindow* mainWindow = NULL) const; +}; + + + +/** + @class wxSashLayoutWindow + @wxheader{laywin.h} + + wxSashLayoutWindow responds to OnCalculateLayout events generated + by wxLayoutAlgorithm. It allows the + application to use simple accessors to specify how the window should be + laid out, rather than having to respond to events. The fact that + the class derives from wxSashWindow allows sashes to be used if required, + to allow the windows to be user-resizable. + + The documentation for wxLayoutAlgorithm explains + the purpose of this class in more detail. + + @library{wxadv} + @category{miscwnd} + + @see wxLayoutAlgorithm, wxSashWindow, @ref overview_eventhandlingoverview +*/ +class wxSashLayoutWindow : public wxSashWindow +{ +public: + //@{ + /** + Constructs a sash layout window, which can be a child of a frame, dialog or any + other non-control window. + + @param parent + Pointer to a parent window. + @param id + Window identifier. If -1, will automatically create an identifier. + @param pos + Window position. wxDefaultPosition is (-1, -1) which indicates that + wxSashLayoutWindows + should generate a default position for the window. If using the + wxSashLayoutWindow class directly, supply + an actual position. + @param size + Window size. wxDefaultSize is (-1, -1) which indicates that + wxSashLayoutWindows + should generate a default size for the window. + @param style + Window style. For window styles, please see wxSashLayoutWindow. + @param name + Window name. + */ + wxSashLayoutWindow(); + wxSashLayoutWindow(wxSashLayoutWindow* parent, wxWindowID id, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxCLIP_CHILDREN | wxSW_3D, + const wxString& name = "layoutWindow"); + //@} + + /** + Initializes a sash layout window, which can be a child of a frame, dialog or + any other non-control window. + + @param parent + Pointer to a parent window. + @param id + Window identifier. If -1, will automatically create an identifier. + @param pos + Window position. wxDefaultPosition is (-1, -1) which indicates that + wxSashLayoutWindows + should generate a default position for the window. If using the + wxSashLayoutWindow class directly, supply + an actual position. + @param size + Window size. wxDefaultSize is (-1, -1) which indicates that + wxSashLayoutWindows + should generate a default size for the window. + @param style + Window style. For window styles, please see wxSashLayoutWindow. + @param name + Window name. + */ + bool Create(wxSashLayoutWindow* parent, wxWindowID id, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxCLIP_CHILDREN | wxSW_3D, + const wxString& name = "layoutWindow"); + + /** + Returns the alignment of the window: one of wxLAYOUT_TOP, wxLAYOUT_LEFT, + wxLAYOUT_RIGHT, wxLAYOUT_BOTTOM. + */ + wxLayoutAlignment GetAlignment() const; + + /** + Returns the orientation of the window: one of wxLAYOUT_HORIZONTAL, + wxLAYOUT_VERTICAL. + */ + wxLayoutOrientation GetOrientation() const; + + /** + The default handler for the event that is generated by wxLayoutAlgorithm. The + implementation + of this function calls wxCalculateLayoutEvent::SetRect to shrink the provided + size according to + how much space this window takes up. For further details, + see wxLayoutAlgorithm and wxCalculateLayoutEvent. + */ + void OnCalculateLayout(wxCalculateLayoutEvent& event); + + /** + The default handler for the event that is generated by OnCalculateLayout to get + size, alignment and orientation information for the window. The implementation + of this function uses member variables as set by accessors called by the + application. + For further details, see wxLayoutAlgorithm and wxQueryLayoutInfoEvent. + */ + void OnQueryLayoutInfo(wxQueryLayoutInfoEvent& event); + + /** + Sets the alignment of the window (which edge of the available parent client + area the window + is attached to). @a alignment is one of wxLAYOUT_TOP, wxLAYOUT_LEFT, + wxLAYOUT_RIGHT, wxLAYOUT_BOTTOM. + */ + void SetAlignment(wxLayoutAlignment alignment); + + /** + Sets the default dimensions of the window. The dimension other than the + orientation will be fixed to this + value, and the orientation dimension will be ignored and the window stretched + to fit the available space. + */ + void SetDefaultSize(const wxSize& size); + + /** + Sets the orientation of the window (the direction the window will stretch in, + to fill the available + parent client area). @a orientation is one of wxLAYOUT_HORIZONTAL, + wxLAYOUT_VERTICAL. + */ + void SetOrientation(wxLayoutOrientation orientation); +}; + + + +/** + @class wxQueryLayoutInfoEvent + @wxheader{laywin.h} + + This event is sent when wxLayoutAlgorithm wishes to get + the size, orientation and alignment of a window. More precisely, the event is + sent + by the OnCalculateLayout handler which is itself invoked by wxLayoutAlgorithm. + + @library{wxadv} + @category{events} + + @see wxCalculateLayoutEvent, wxSashLayoutWindow, wxLayoutAlgorithm. +*/ +class wxQueryLayoutInfoEvent : public wxEvent +{ +public: + /** + Constructor. + */ + wxQueryLayoutInfoEvent(wxWindowID id = 0); + + /** + Specifies the alignment of the window (which side of the remaining parent + client area + the window sticks to). One of wxLAYOUT_TOP, wxLAYOUT_LEFT, wxLAYOUT_RIGHT, + wxLAYOUT_BOTTOM. + */ + void GetAlignment() const; + + /** + Returns the flags associated with this event. Not currently used. + */ + int GetFlags() const; + + /** + Returns the orientation that the event handler specified to the event object. + May be one of wxLAYOUT_HORIZONTAL, + wxLAYOUT_VERTICAL. + */ + wxLayoutOrientation GetOrientation() const; + + /** + Returns the requested length of the window in the direction of the window + orientation. This information + is not yet used. + */ + int GetRequestedLength() const; + + /** + Returns the size that the event handler specified to the event object as being + the requested size of the window. + */ + wxSize GetSize() const; + + /** + Call this to specify the alignment of the window (which side of the remaining + parent client area + the window sticks to). May be one of wxLAYOUT_TOP, wxLAYOUT_LEFT, + wxLAYOUT_RIGHT, wxLAYOUT_BOTTOM. + */ + void SetAlignment(wxLayoutAlignment alignment); + + /** + Sets the flags associated with this event. Not currently used. + */ + void SetFlags(int flags); + + /** + Call this to specify the orientation of the window. May be one of + wxLAYOUT_HORIZONTAL, + wxLAYOUT_VERTICAL. + */ + void SetOrientation(wxLayoutOrientation orientation); + + /** + Sets the requested length of the window in the direction of the window + orientation. This information + is not yet used. + */ + void SetRequestedLength(int length); + + /** + Call this to let the calling code know what the size of the window is. + */ + void SetSize(const wxSize& size); +}; + + + +/** + @class wxCalculateLayoutEvent + @wxheader{laywin.h} + + This event is sent by wxLayoutAlgorithm to + calculate the amount of the remaining client area that the window should + occupy. + + @library{wxadv} + @category{events} + + @see wxQueryLayoutInfoEvent, wxSashLayoutWindow, wxLayoutAlgorithm. +*/ +class wxCalculateLayoutEvent : public wxEvent +{ +public: + /** + Constructor. + */ + wxCalculateLayoutEvent(wxWindowID id = 0); + + /** + Returns the flags associated with this event. Not currently used. + */ + int GetFlags() const; + + /** + Before the event handler is entered, returns the remaining parent client area + that the window + could occupy. When the event handler returns, this should contain the remaining + parent client rectangle, + after the event handler has subtracted the area that its window occupies. + */ + wxRect GetRect() const; + + /** + Sets the flags associated with this event. Not currently used. + */ + void SetFlags(int flags); + + /** + Call this to specify the new remaining parent client area, after the space + occupied by the + window has been subtracted. + */ + void SetRect(const wxRect& rect); +}; + diff --git a/interface/wx/link.h b/interface/wx/link.h new file mode 100644 index 0000000000..8bd169380e --- /dev/null +++ b/interface/wx/link.h @@ -0,0 +1,40 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: link.h +// Purpose: interface of global functions +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** @ingroup group_funcmacro_byteorder */ +//@{ + +/** + This macro can be used in conjunction with the wxFORCE_LINK_MODULE() macro + to force the linker to include in its output a specific object file. + + In particular, you should use this macro in the source file which you want + to force for inclusion. The @c moduleName needs to be a name not already in + use in other wxFORCE_LINK_THIS_MODULE() macros, but is not required to be + e.g. the same name of the source file (even if it's a good choice). + + @header{wx/link.h} +*/ +#define wxFORCE_LINK_THIS_MODULE( moduleName ) + +/** + This macro can be used in conjunction with the wxFORCE_LINK_THIS_MODULE() + macro to force the linker to include in its output a specific object file. + + In particular, you should use this macro in a source file which you know + for sure is linked in the output (e.g. the source file containing the + @c main() of your app). The @c moduleName is the name of the module you + want to forcefully link (i.e. the name you used in the relative + wxFORCE_LINK_THIS_MODULE() macro. + + @header{wx/link.h} +*/ +#define wxFORCE_LINK_MODULE( moduleName ) + +//@} + diff --git a/interface/wx/list.h b/interface/wx/list.h new file mode 100644 index 0000000000..e49ae62ed4 --- /dev/null +++ b/interface/wx/list.h @@ -0,0 +1,439 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: list.h +// Purpose: interface of wxList +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @wxheader{list.h} + + The wxList class provides linked list functionality. It has been rewritten + to be type safe and to provide the full API of the STL std::list container and + should be used like it. The exception is that wxList actually stores + pointers and therefore its iterators return pointers and not references + to the actual objets in the list (see example below) and @e value_type + is defined as @e T*. wxList destroys an object after removing it only + if wxList::DeleteContents has been called. + + wxList is not a real template and it requires that you declare and define + each wxListT class in your program. This is done with @e WX_DECLARE_LIST + and @e WX_DEFINE_LIST macros (see example). We hope that we'll be able + to provide a proper template class providing both the STL std::list + and the old wxList API in the future. + + Please refer to the STL std::list documentation for further + information on how to use the class. Below we documented both + the supported STL and the legacy API that originated from the + old wxList class and which can still be used alternatively for + the the same class. + + Note that if you compile wxWidgets in STL mode (wxUSE_STL defined as 1) + then wxList will actually derive from std::list and just add a legacy + compatibility layer for the old wxList class. + + @code + // this part might be in a header or source (.cpp) file + class MyListElement + { + ... // whatever + }; + + // this macro declares and partly implements MyList class + WX_DECLARE_LIST(MyListElement, MyList); + + ... + + // the only requirement for the rest is to be AFTER the full declaration of + // MyListElement (for WX_DECLARE_LIST forward declaration is enough), but + // usually it will be found in the source file and not in the header + + #include + WX_DEFINE_LIST(MyList); + + + MyList list; + MyListElement element; + list.Append(&element); // ok + list.Append(17); // error: incorrect type + + // let's iterate over the list in STL syntax + MyList::iterator iter; + for (iter = list.begin(); iter != list.end(); ++iter) + { + MyListElement *current = *iter; + + ...process the current element... + } + + // the same with the legacy API from the old wxList class + MyList::compatibility_iterator node = list.GetFirst(); + while (node) + { + MyListElement *current = node->GetData(); + + ...process the current element... + + node = node->GetNext(); + } + @endcode + + + @library{wxbase} + @category{FIXME} + + @see wxArray, wxVector +*/ +class wxList +{ +public: + /** + Default constructor. + */ + wxList(); + + /** + Constructor which initialized the list with an array of @count elements. + */ + wxList(size_t count, T* elements[]); + + /** + Destroys the list, but does not delete the objects stored in the list + unless you called DeleteContents(@true ). + */ + ~wxList(); + + /** + Appends the pointer to @a object to the list. + */ + wxList::compatibility_iterator Append(T* object); + + /** + Clears the list. + Deletes the actual objects if DeleteContents( @true ) was called previously. + */ + void Clear(); + + /** + If @a destroy is @true, instructs the list to call @e delete + on objects stored in the list whenever they are removed. + The default is @false. + */ + void DeleteContents(bool destroy); + + /** + Deletes the given element refered to by @a iter from the list + if @a iter is a valid iterator. Returns @true if successful. + + Deletes the actual object if DeleteContents( @true ) was called previously. + */ + bool DeleteNode(const compatibility_iterator& iter); + + /** + Finds the given @a object and removes it from the list, returning + @true if successful. + + Deletes @a object if DeleteContents( @true ) was called previously. + */ + bool DeleteObject(T* object); + + /** + Removes element refered to be @a iter. + + Deletes the actualy object if DeleteContents( @true ) was called previously. + */ + void Erase(const compatibility_iterator& iter); + + /** + Returns the iterator refering to @a object or @NULL if none found. + */ + wxList::compatibility_iterator Find(T* object) const; + + /** + Returns the number of elements in the list. + */ + size_t GetCount() const; + + /** + Returns the first iterator in the list (@NULL if the list is empty). + */ + wxList::compatibility_iterator GetFirst() const; + + /** + Returns the last iterator in the list (@NULL if the list is empty). + */ + wxList::compatibility_iterator GetLast() const; + + /** + Returns the index of @a obj within the list or @c wxNOT_FOUND if + @a obj is not found in the list. + */ + int IndexOf(T* obj) const; + + /** + Inserts @a object at the beginning of the list. + */ + wxList::compatibility_iterator Insert(T* object); + + /** + Inserts @a object at @a position. + */ + wxList::compatibility_iterator Insert(size_t position, + T* object); + + /** + Inserts @a object before the object refered to be @a iter. + */ + wxList::compatibility_iterator Insert(compatibility_iterator iter, + T* object); + + /** + Returns @true if the list is empty, @false otherwise. + */ + bool IsEmpty() const; + + /** + Returns the iterator refering to the object at the given + @a index in the list. + */ + wxList::compatibility_iterator Item(size_t index) const; + + /** + @note This function is deprecated, use Find() instead. + */ + wxList::compatibility_iterator Member(T* object) const; + + /** + @note This function is deprecated, use Item() instead. + */ + wxList::compatibility_iterator Nth(int n) const; + + /** + @note This function is deprecated, use wxList::GetCount instead. + Returns the number of elements in the list. + */ + int Number() const; + + /** + Allows the sorting of arbitrary lists by giving a function to compare + two list elements. We use the system @b qsort function for the actual + sorting process. + */ + void Sort(wxSortCompareFunction compfunc); + + /** + Clears the list and item from @a first to @a last from another list to it. + */ + void assign(const_iterator first, const const_iterator& last); + + /** + Clears the list and adds @a n items with value @a v to it. + */ + void assign(size_type n, const_reference v = value_type()) \ + + /** + Returns the last item of the list. + */ + reference back() const; + + /** + Returns the last item of the list as a const reference. + */ + const_reference back() const; + + /** + Returns an iterator pointing to the beginning of the list. + */ + iterator begin() const; + + /** + Returns a const iterator pointing to the beginning of the list. + */ + const_iterator begin() const; + + /** + Removes all items from the list. + */ + void clear(); + + /** + Returns @e @true if the list is empty. + */ + bool empty() const; + + /** + Returns a const iterator pointing at the end of the list. + */ + const_iterator end() const; + + /** + Returns a iterator pointing at the end of the list. + */ + iterator end() const; + + /** + Erases the given item + */ + iterator erase(const iterator& it); + + /** + Erases the items from @e first to @e last. + */ + iterator erase(const iterator& first, + const iterator& last); + + /** + Returns the first item in the list. + */ + reference front() const; + + /** + Returns the first item in the list as a const reference. + */ + const_reference front() const; + + /** + Inserts an item at the head of the list + */ + iterator insert(const iterator& it); + + /** + Inserts an item at the given position + */ + void insert(const iterator& it, size_type n); + + /** + Inserts several items at the given position. + */ + void insert(const iterator& it, const_iterator first, + const const_iterator& last); + + /** + Returns the largest possible size of the list. + */ + size_type max_size() const; + + /** + Removes the last item from the list. + */ + void pop_back(); + + /** + Removes the first item from the list. + */ + void pop_front(); + + /** + Adds an item to end of the list. + */ + void push_back(); + + /** + Adds an item to the front of the list. + */ + void push_front(); + + /** + Returns a reverse iterator pointing to the beginning of the + reversed list. + */ + reverse_iterator rbegin() const; + + /** + Returns a const reverse iterator pointing to the beginning of the + reversed list. + */ + const_reverse_iterator rbegin() const; + + /** + Removes an item from the list. + */ + void remove(const_reference v); + + /** + Returns a reverse iterator pointing to the end of the + reversed list. + */ + reverse_iterator rend() const; + + /** + Returns a const reverse iterator pointing to the end of the + reversed list. + */ + const_reverse_iterator rend() const; + + /** + Resizes the list. If the the list is enlarges items with + the value @e v are appended to the list. + */ + void resize(size_type n); + + /** + Reverses the list. + */ + void reverse(); + + /** + Returns the size of the list. + */ + size_type size() const; +}; + + + +/** + @class wxNode + @wxheader{list.h} + + wxNodeBase is the node structure used in linked lists (see + wxList) and derived classes. You should never use wxNodeBase + class directly, however, because it works with untyped (@c void *) data and + this is unsafe. Use wxNodeBase-derived classes which are automatically defined + by WX_DECLARE_LIST and WX_DEFINE_LIST macros instead as described in + wxList documentation (see example there). Also note that + although there is a class called wxNode, it is defined for backwards + compatibility only and usage of this class is strongly deprecated. + + In the documentation below, the type @c T should be thought of as a + "template" parameter: this is the type of data stored in the linked list or, + in other words, the first argument of WX_DECLARE_LIST macro. Also, wxNode is + written as wxNodeT even though it isn't really a template class -- but it + helps to think of it as if it were. + + @library{wxbase} + @category{FIXME} + + @see wxList, wxHashTable +*/ +class wxNode +{ +public: + /** + Retrieves the client data pointer associated with the node. + */ + T* GetData() const; + + /** + Retrieves the next node or @NULL if this node is the last one. + */ + wxNode* GetNext() const; + + /** + Retrieves the previous node or @NULL if this node is the first one in the list. + */ + wxNode* GetPrevious(); + + /** + Returns the zero-based index of this node within the list. The return value + will be @c wxNOT_FOUND if the node has not been added to a list yet. + */ + int IndexOf(); + + /** + Sets the data associated with the node (usually the pointer will have been + set when the node was created). + */ + void SetData(T* data); +}; + diff --git a/interface/wx/listbook.h b/interface/wx/listbook.h new file mode 100644 index 0000000000..28855b7ef3 --- /dev/null +++ b/interface/wx/listbook.h @@ -0,0 +1,61 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: listbook.h +// Purpose: interface of wxListbook +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxListbook + @wxheader{listbook.h} + + wxListbook is a class similar to wxNotebook but which + uses a wxListCtrl to show the labels instead of the + tabs. + + The underlying wxListCtrl displays page labels in a one-column report view + by default. Calling wxListbook::SetImageList will implicitly switch the + control to use an icon view. + + There is no documentation for this class yet but its usage is + identical to wxNotebook (except for the features clearly related to tabs + only), so please refer to that class documentation for now. You can also + use the @ref overview_samplenotebook "notebook sample" to see wxListbook in + action. + + @beginStyleTable + @style{wxLB_DEFAULT} + Choose the default location for the labels depending on the current + platform (left everywhere except Mac where it is top). + @style{wxLB_TOP} + Place labels above the page area. + @style{wxLB_LEFT} + Place labels on the left side. + @style{wxLB_RIGHT} + Place labels on the right side. + @style{wxLB_BOTTOM} + Place labels below the page area. + @endStyleTable + + @library{wxcore} + @category{miscwnd} + + @see wxBookCtrl(), wxNotebook, @ref overview_samplenotebook "notebook sample" +*/ +class wxListbook : public wxBookCtrl overview +{ +public: + //@{ + /** + Constructs a listbook control. + */ + wxListbook(); + wxListbook(wxWindow* parent, wxWindowID id, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0, + const wxString& name = wxEmptyStr); + //@} +}; + diff --git a/interface/wx/listbox.h b/interface/wx/listbox.h new file mode 100644 index 0000000000..7d9ad3baaa --- /dev/null +++ b/interface/wx/listbox.h @@ -0,0 +1,250 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: listbox.h +// Purpose: interface of wxListBox +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxListBox + @wxheader{listbox.h} + + A listbox is used to select one or more of a list of strings. The + strings are displayed in a scrolling box, with the selected string(s) + marked in reverse video. A listbox can be single selection (if an item + is selected, the previous selection is removed) or multiple selection + (clicking an item toggles the item on or off independently of other + selections). + + List box elements are numbered from zero. Their number may be limited + under some platforms. + + A listbox callback gets an event wxEVT_COMMAND_LISTBOX_SELECTED for + single clicks, and wxEVT_COMMAND_LISTBOX_DOUBLECLICKED for double clicks. + + @beginStyleTable + @style{wxLB_SINGLE} + Single-selection list. + @style{wxLB_MULTIPLE} + Multiple-selection list: the user can toggle multiple items on and + off. This is the same as wxLB_EXTENDED in wxGTK2 port. + @style{wxLB_EXTENDED} + Extended-selection list: the user can extend the selection by using + @c SHIFT or @c CTRL keys together with the cursor movement keys or + the mouse. + @style{wxLB_HSCROLL} + Create horizontal scrollbar if contents are too wide (Windows only). + @style{wxLB_ALWAYS_SB} + Always show a vertical scrollbar. + @style{wxLB_NEEDED_SB} + Only create a vertical scrollbar if needed. + @style{wxLB_SORT} + The listbox contents are sorted in alphabetical order. + @endStyleTable + + @beginEventTable{wxCommandEvent} + @event{EVT_LISTBOX(id, func)} + Process a wxEVT_COMMAND_LISTBOX_SELECTED event, when an item on the + list is selected or the selection changes. + @event{EVT_LISTBOX_DCLICK(id, func)} + Process a wxEVT_COMMAND_LISTBOXDOUBLECLICKED event, when the + listbox is double-clicked. + @endEventTable + + @library{wxcore} + @category{ctrl} + + + @see wxChoice, wxComboBox, wxListCtrl, wxCommandEvent +*/ +class wxListBox : public wxControlWithItems +{ +public: + /** + Default constructor. + */ + wxListBox(); + + /** + Constructor + + @param n + Number of strings with which to initialise the control. + @param style + Window style. See wxListBox. + */ + + wxListBox(wxWindow* parent, wxWindowID id, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + int n = 0, + const wxString choices[] = NULL, + long style = 0, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "listBox"); + + /** + Constructor + + @param choices + An array of strings with which to initialise the control. + @param style + Window style. See wxListBox. + */ + + wxListBox(wxWindow* parent, wxWindowID id, + const wxPoint& pos, + const wxSize& size, + const wxArrayString& choices, + long style = 0, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "listBox"); + + /** + Destructor, destroying the list box. + */ + ~wxListBox(); + + //@{ + /** + Creates the listbox for two-step construction. See wxListBox() + for further details. + */ + bool Create(wxWindow* parent, wxWindowID id, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + int n, + const wxString choices[] = NULL, + long style = 0, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "listBox"); + bool Create(wxWindow* parent, wxWindowID id, + const wxPoint& pos, + const wxSize& size, + const wxArrayString& choices, + long style = 0, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "listBox"); + //@} + + /** + Deselects an item in the list box. + + @param n + The zero-based item to deselect. + + @remarks This applies to multiple selection listboxes only. + */ + void Deselect(int n); + + /** + Fill an array of ints with the positions of the currently selected items. + + @param selections + A reference to an wxArrayInt instance that is used to store the result of + the query. + + @return The number of selections. + + @remarks Use this with a multiple selection listbox. + + @see wxControlWithItems::GetSelection, wxControlWithItems::GetStringSelection, + wxControlWithItems::SetSelection + */ + int GetSelections(wxArrayInt& selections) const; + + /** + Returns the item located at @e point, or @c wxNOT_FOUND if there + is no item located at @e point. + + It is currently implemented for wxMSW, wxMac and wxGTK2 ports. + + @param point + Point of item (in client coordinates) to obtain + + @return Item located at point, or wxNOT_FOUND if unimplemented or the + item does not exist. + + @since 2.7.0 + */ + int HitTest(const wxPoint point) const; + + /** + Insert the given number of strings before the specified position. + + @param nItems + Number of items in the array items + @param items + Labels of items to be inserted + @param pos + Position before which to insert the items: if pos is 0 the + items will be inserted in the beginning of the listbox + */ + void InsertItems(int nItems, const wxString *items, + unsigned int pos); + + /** + Insert the given number of strings before the specified position. + + @param items + Labels of items to be inserted + @param pos + Position before which to insert the items: if pos is 0 the + items will be inserted in the beginning of the listbox + */ + void InsertItems(const wxArrayString& items, + unsigned int pos); + + /** + Determines whether an item is selected. + + @param n + The zero-based item index. + + @return @true if the given item is selected, @false otherwise. + */ + bool IsSelected(int n) const; + + /** + Clears the list box and adds the given strings to it. + + @param n + The number of strings to set. + @param choices + An array of strings to set. + @param clientData + Options array of client data pointers + */ + void Set(int n, const wxString* choices, void **clientData = NULL); + + /** + Clears the list box and adds the given strings to it. You may + free the array from the calling program after this method + has been called. + + @param choices + An array of strings to set. + @param clientData + Options array of client data pointers + */ + void Set(const wxArrayString& choices, + void **clientData = NULL); + + /** + Set the specified item to be the first visible item. + + @param n + The zero-based item index that should be visible. + */ + void SetFirstItem(int n); + + /** + Set the specified item to be the first visible item. + + @param string + The string that should be visible. + */ + void SetFirstItem(const wxString& string); +}; + diff --git a/interface/wx/listctrl.h b/interface/wx/listctrl.h new file mode 100644 index 0000000000..812a1c2077 --- /dev/null +++ b/interface/wx/listctrl.h @@ -0,0 +1,1441 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: listctrl.h +// Purpose: interface of wxListCtrl +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxListCtrl + @wxheader{listctrl.h} + + A list control presents lists in a number of formats: list view, report view, + icon view and small icon view. In any case, elements are numbered from zero. + For all these modes, the items are stored in the control and must be added to + it using wxListCtrl::InsertItem method. + + A special case of report view quite different from the other modes of the list + control is a virtual control in which the items data (including text, images + and attributes) is managed by the main program and is requested by the control + itself only when needed which allows to have controls with millions of items + without consuming much memory. To use virtual list control you must use + wxListCtrl::SetItemCount first and overload at least + wxListCtrl::OnGetItemText (and optionally + wxListCtrl::OnGetItemImage or wxListCtrl::OnGetItemColumnImage and + wxListCtrl::OnGetItemAttr) to return the information + about the items when the control requests it. Virtual list control can be used + as a normal one except that no operations which can take time proportional to + the number of items in the control happen -- this is required to allow having a + practically infinite number of items. For example, in a multiple selection + virtual list control, the selections won't be sent when many items are selected + at once because this could mean iterating over all the items. + + Using many of wxListCtrl features is shown in the + @ref overview_samplelistctrl "corresponding sample". + + To intercept events from a list control, use the event table macros described + in wxListEvent. + + @b Mac Note: Starting with 2.8, wxListCtrl uses a native implementation for + report mode, and uses a generic implementation for other modes. You can use the + generic implementation for report mode as well by setting the + mac.listctrl.always_use_generic wxSystemOption() to + 1. + + @beginStyleTable + @style{wxLC_LIST} + Multicolumn list view, with optional small icons. Columns are + computed automatically, i.e. you don't set columns as in + wxLC_REPORT. In other words, the list wraps, unlike a wxListBox. + @style{wxLC_REPORT} + Single or multicolumn report view, with optional header. + @style{wxLC_VIRTUAL} + The application provides items text on demand. May only be used + with wxLC_REPORT. + @style{wxLC_ICON} + Large icon view, with optional labels. + @style{wxLC_SMALL_ICON} + Small icon view, with optional labels. + @style{wxLC_ALIGN_TOP} + Icons align to the top. Win32 default, Win32 only. + @style{wxLC_ALIGN_LEFT} + Icons align to the left. + @style{wxLC_AUTOARRANGE} + Icons arrange themselves. Win32 only. + @style{wxLC_EDIT_LABELS} + Labels are editable: the application will be notified when editing + starts. + @style{wxLC_NO_HEADER} + No header in report mode. + @style{wxLC_SINGLE_SEL} + Single selection (default is multiple). + @style{wxLC_SORT_ASCENDING} + Sort in ascending order. (You must still supply a comparison callback + in wxListCtrl::SortItems.) + @style{wxLC_SORT_DESCENDING} + Sort in descending order. (You must still supply a comparison callback + in wxListCtrl::SortItems.) + @style{wxLC_HRULES} + Draws light horizontal rules between rows in report mode. + @style{wxLC_VRULES} + Draws light vertical rules between columns in report mode. + @endStyleTable + + @library{wxcore} + @category{ctrl} + + + @see @ref overview_listctrl "wxListCtrl Overview", wxListView, + wxListBox, wxTreeCtrl, wxImageList, wxListEvent, wxListItem +*/ +class wxListCtrl : public wxControl +{ +public: + //@{ + /** + Constructor, creating and showing a list control. + */ + wxListCtrl(); + + /** + Constructor, creating and showing a list control. + + @param parent + Parent window. Must not be @NULL. + @param id + Window identifier. The value wxID_ANY indicates a default value. + @param pos + Window position. + @param size + Window size. If wxDefaultSize is specified then the window is + sized appropriately. + @param style + Window style. See wxListCtrl. + @param validator + Window validator. + @param name + Window name. + + @see Create(), wxValidator + */ + wxListCtrl(wxWindow* parent, wxWindowID id, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxLC_ICON, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = wxListCtrlNameStr); + //@} + + /** + Destructor, destroying the list control. + */ + ~wxListCtrl(); + + /** + Arranges the items in icon or small icon view. This only has effect on Win32. + @a flag is one of: + + wxLIST_ALIGN_DEFAULT + + Default alignment. + + wxLIST_ALIGN_LEFT + + Align to the left side of the control. + + wxLIST_ALIGN_TOP + + Align to the top side of the control. + + wxLIST_ALIGN_SNAP_TO_GRID + + Snap to grid. + */ + bool Arrange(int flag = wxLIST_ALIGN_DEFAULT); + + /** + Sets the image list associated with the control and + takes ownership of it (i.e. the control will, unlike when using + SetImageList, delete the list when destroyed). @a which is one of + wxIMAGE_LIST_NORMAL, wxIMAGE_LIST_SMALL, wxIMAGE_LIST_STATE (the last is + unimplemented). + + @see SetImageList() + */ + void AssignImageList(wxImageList* imageList, int which); + + /** + Deletes all items and all columns. + */ + void ClearAll(); + + /** + Creates the list control. See wxListCtrl() for further details. + */ + bool Create(wxWindow* parent, wxWindowID id, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxLC_ICON, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = wxListCtrlNameStr); + + /** + Deletes all items in the list control. + @note This function does @e not send the + @c wxEVT_COMMAND_LIST_DELETE_ITEM event because deleting many items + from the control would be too slow then (unlike wxListCtrl::DeleteItem). + */ + bool DeleteAllItems(); + + /** + Deletes a column. + */ + bool DeleteColumn(int col); + + /** + Deletes the specified item. This function sends the + @c wxEVT_COMMAND_LIST_DELETE_ITEM event for the item being deleted. + See also: DeleteAllItems() + */ + bool DeleteItem(long item); + + /** + Starts editing the label of the given item. This function generates a + EVT_LIST_BEGIN_LABEL_EDIT event which can be vetoed so that no + text control will appear for in-place editing. + If the user changed the label (i.e. s/he does not press ESC or leave + the text control without changes, a EVT_LIST_END_LABEL_EDIT event + will be sent which can be vetoed as well. + */ + void EditLabel(long item); + + /** + Ensures this item is visible. + */ + bool EnsureVisible(long item); + + //@{ + /** + Find an item nearest this position in the specified direction, starting from + @a start or the beginning if @a start is -1. + + + @b FindItem( start, str, partial = @false ) + + + @b FindItemData( start, data ) + + + @b FindItemAtPos( start, point, direction ) + */ + long FindItem(long start, const wxString& str, + bool partial = false); + long FindItem(long start, long data); + long FindItem(long start, const wxPoint& pt, int direction); + //@} + + /** + Gets information about this column. See SetItem() for more + information. + */ + bool GetColumn(int col, wxListItem& item) const; + + /** + Returns the number of columns. + */ + int GetColumnCount() const; + + /** + Gets the column number by visual order index (report view only). + */ + int GetColumnIndexFromOrder(int order) const; + + /** + Gets the column visual order index (valid in report view only). + */ + int GetColumnOrder(int col) const; + + /** + Gets the column width (report view only). + */ + int GetColumnWidth(int col) const; + + /** + Returns the array containing the orders of all columns. On error, an empty + array is returned. + */ + wxArrayInt GetColumnsOrder() const; + + /** + Gets the number of items that can fit vertically in the + visible area of the list control (list or report view) + or the total number of items in the list control (icon + or small icon view). + */ + int GetCountPerPage() const; + + /** + Returns the edit control being currently used to edit a label. Returns @NULL + if no label is being edited. + @note It is currently only implemented for wxMSW and the generic version, + not for the native Mac OS X version. + */ + wxTextCtrl* GetEditControl() const; + + /** + Returns the specified image list. @a which may be one of: + + @b wxIMAGE_LIST_NORMAL + + The normal (large icon) image list. + + @b wxIMAGE_LIST_SMALL + + The small icon image list. + + @b wxIMAGE_LIST_STATE + + The user-defined state image list (unimplemented). + */ + wxImageList* GetImageList(int which) const; + + /** + Gets information about the item. See SetItem() for more + information. + You must call @e info.SetId() to the ID of item you're interested in + before calling this method. + */ + bool GetItem(wxListItem& info) const; + + /** + Returns the colour for this item. If the item has no specific colour, returns + an invalid colour (and not the default background control of the control + itself). + + @see GetItemTextColour() + */ + wxColour GetItemBackgroundColour(long item) const; + + /** + Returns the number of items in the list control. + */ + int GetItemCount() const; + + /** + Gets the application-defined data associated with this item. + */ + long GetItemData(long item) const; + + /** + Returns the item's font. + */ + wxFont GetItemFont(long item) const; + + /** + Returns the position of the item, in icon or small icon view. + */ + bool GetItemPosition(long item, wxPoint& pos) const; + + /** + Returns the rectangle representing the item's size and position, in physical + coordinates. + @a code is one of wxLIST_RECT_BOUNDS, wxLIST_RECT_ICON, wxLIST_RECT_LABEL. + */ + bool GetItemRect(long item, wxRect& rect, + int code = wxLIST_RECT_BOUNDS) const; + + /** + Retrieves the spacing between icons in pixels: horizontal spacing is returned + as @c x component of the wxSize object and the vertical + spacing as its @c y component. + */ + wxSize GetItemSpacing() const; + + /** + Gets the item state. For a list of state flags, see SetItem(). + The @b stateMask indicates which state flags are of interest. + */ + int GetItemState(long item, long stateMask) const; + + /** + Gets the item text for this item. + */ + wxString GetItemText(long item) const; + + /** + Returns the colour for this item. If the item has no specific colour, returns + an invalid colour (and not the default foreground control of the control itself + as this wouldn't allow distinguishing between items having the same colour as + the current control foreground and items with default colour which, hence, have + always the same colour as the control). + */ + wxColour GetItemTextColour(long item) const; + + /** + Searches for an item with the given geometry or state, starting from + @a item but excluding the @a item itself. If @a item is -1, + the first item that matches the specified flags will be returned. + Returns the first item with given state following @a item or -1 if + no such item found. + This function may be used to find all selected items in the control like this: + + @a geometry can be one of: + + wxLIST_NEXT_ABOVE + + Searches for an item above the specified item. + + wxLIST_NEXT_ALL + + Searches for subsequent item by index. + + wxLIST_NEXT_BELOW + + Searches for an item below the specified item. + + wxLIST_NEXT_LEFT + + Searches for an item to the left of the specified item. + + wxLIST_NEXT_RIGHT + + Searches for an item to the right of the specified item. + + @note this parameter is only supported by wxMSW currently and ignored on + other platforms. + @a state can be a bitlist of the following: + + wxLIST_STATE_DONTCARE + + Don't care what the state is. + + wxLIST_STATE_DROPHILITED + + The item indicates it is a drop target. + + wxLIST_STATE_FOCUSED + + The item has the focus. + + wxLIST_STATE_SELECTED + + The item is selected. + + wxLIST_STATE_CUT + + The item is selected as part of a cut and paste operation. + */ + long GetNextItem(long item, int geometry = wxLIST_NEXT_ALL, + int state = wxLIST_STATE_DONTCARE) const; + + /** + Returns the number of selected items in the list control. + */ + int GetSelectedItemCount() const; + + /** + Returns the rectangle representing the size and position, in physical + coordinates, of the given subitem, i.e. the part of the row @a item in the + column @e subItem. + This method is only meaningfull when the wxListCtrl is in the report mode. If + @a subItem parameter is equal to the special value + @c wxLIST_GETSUBITEMRECT_WHOLEITEM the return value is the same as + for GetItemRect(). + @a code can be one of @c wxLIST_RECT_BOUNDS, + @c wxLIST_RECT_ICON or @c wxLIST_RECT_LABEL. + + @since 2.7.0 + */ + bool GetSubItemRect(long item, long subItem, wxRect& rect, + int code = wxLIST_RECT_BOUNDS) const; + + /** + Gets the text colour of the list control. + */ + wxColour GetTextColour() const; + + /** + Gets the index of the topmost visible item when in + list or report view. + */ + long GetTopItem() const; + + /** + Returns the rectangle taken by all items in the control. In other words, if the + controls client size were equal to the size of this rectangle, no scrollbars + would be needed and no free space would be left. + Note that this function only works in the icon and small icon views, not in + list or report views (this is a limitation of the native Win32 control). + */ + wxRect GetViewRect() const; + + /** + Determines which item (if any) is at the specified point, + giving details in @e flags. Returns index of the item or @c wxNOT_FOUND + if no item is at the specified point. + @a flags will be a combination of the following flags: + + wxLIST_HITTEST_ABOVE + + Above the client area. + + wxLIST_HITTEST_BELOW + + Below the client area. + + wxLIST_HITTEST_NOWHERE + + In the client area but below the last item. + + wxLIST_HITTEST_ONITEMICON + + On the bitmap associated with an item. + + wxLIST_HITTEST_ONITEMLABEL + + On the label (string) associated with an item. + + wxLIST_HITTEST_ONITEMRIGHT + + In the area to the right of an item. + + wxLIST_HITTEST_ONITEMSTATEICON + + On the state icon for a tree view item that is in a user-defined state. + + wxLIST_HITTEST_TOLEFT + + To the right of the client area. + + wxLIST_HITTEST_TORIGHT + + To the left of the client area. + + wxLIST_HITTEST_ONITEM + + Combination of wxLIST_HITTEST_ONITEMICON, wxLIST_HITTEST_ONITEMLABEL, + wxLIST_HITTEST_ONITEMSTATEICON. + + If @a ptrSubItem is not @NULL and the wxListCtrl is in the report + mode the subitem (or column) number will also be provided. + This feature is only available in version 2.7.0 or higher and is currently only + implemented under wxMSW and requires at least comctl32.dll of verion 4.70 on + the host system or the value stored in @a ptrSubItem will be always -1. To + compile this feature into wxWidgets library you need to have access to + commctrl.h of version 4.70 that is provided by Microsoft. + */ + long HitTest(const wxPoint& point, int& flags, + long* ptrSubItem) const; + + //@{ + /** + For report view mode (only), inserts a column. For more details, see SetItem(). + */ + long InsertColumn(long col, wxListItem& info); + long InsertColumn(long col, const wxString& heading, + int format = wxLIST_FORMAT_LEFT, + int width = -1); + //@} + + //@{ + /** + Insert a wxListItem. + @param info + wxListItem object + */ + long InsertItem(wxListItem& info); + + /** + Insert an string item. + @param index + Index of the new item, supplied by the application + @param label + String label + */ + long InsertItem(long index, const wxString& label); + + /** + Insert an image item. + @param index + Index of the new item, supplied by the application + @param imageIndex + Index into the image list associated with this control and view style + */ + long InsertItem(long index, int imageIndex); + + /** + Insert an image/string item. + @param index + Index of the new item, supplied by the application + @param label + String label + @param imageIndex + Index into the image list associated with this control and view style + */ + long InsertItem(long index, const wxString& label, + int imageIndex); + //@} + + /** + This function may be overloaded in the derived class for a control with + @c wxLC_VIRTUAL style. It should return the attribute for the + for the specified @c item or @NULL to use the default appearance + parameters. + wxListCtrl will not delete the pointer or keep a reference of it. You can + return the same wxListItemAttr pointer for every OnGetItemAttr call. + The base class version always returns @NULL. + + @see OnGetItemImage(), OnGetItemColumnImage(), + OnGetItemText() + */ + virtual wxListItemAttr* OnGetItemAttr(long item) const; + + /** + Overload this function in the derived class for a control with + @c wxLC_VIRTUAL and @c wxLC_REPORT styles in order to specify the image + index for the given line and column. + The base class version always calls OnGetItemImage for the first column, else + it returns -1. + + @see OnGetItemText(), OnGetItemImage(), + OnGetItemAttr() + */ + virtual int OnGetItemColumnImage(long item, long column) const; + + /** + This function must be overloaded in the derived class for a control with + @c wxLC_VIRTUAL style having an @ref SetImageList() "image list" + (if the control doesn't have an image list, it is not necessary to overload + it). It should return the index of the items image in the controls image list + or -1 for no image. + In a control with @c wxLC_REPORT style, OnGetItemImage only gets called for + the first column of each line. + The base class version always returns -1. + + @see OnGetItemText(), OnGetItemColumnImage(), + OnGetItemAttr() + */ + virtual int OnGetItemImage(long item) const; + + /** + This function @b must be overloaded in the derived class for a control with + @c wxLC_VIRTUAL style. It should return the string containing the text of + the given @a column for the specified @c item. + + @see SetItemCount(), OnGetItemImage(), + OnGetItemColumnImage(), OnGetItemAttr() + */ + virtual wxString OnGetItemText(long item, long column) const; + + /** + Redraws the given @e item. This is only useful for the virtual list controls + as without calling this function the displayed value of the item doesn't change + even when the underlying data does change. + + @see RefreshItems() + */ + void RefreshItem(long item); + + /** + Redraws the items between @a itemFrom and @e itemTo. The starting item + must be less than or equal to the ending one. + Just as RefreshItem() this is only useful for + virtual list controls. + */ + void RefreshItems(long itemFrom, long itemTo); + + /** + Scrolls the list control. If in icon, small icon or report view mode, + @a dx specifies the number of pixels to scroll. If in list view mode, + @a dx specifies the number of columns to scroll. @a dy always specifies + the number of pixels to scroll vertically. + @note This method is currently only implemented in the Windows version. + */ + bool ScrollList(int dx, int dy); + + /** + Sets the background colour (GetBackgroundColour already implicit in + wxWindow class). + */ + void SetBackgroundColour(const wxColour& col); + + /** + Sets information about this column. See SetItem() for more + information. + */ + bool SetColumn(int col, wxListItem& item); + + /** + Sets the column width. + @a width can be a width in pixels or wxLIST_AUTOSIZE (-1) or + wxLIST_AUTOSIZE_USEHEADER (-2). + wxLIST_AUTOSIZE will resize the column to the length of its longest item. + wxLIST_AUTOSIZE_USEHEADER + will resize the column to the length of the header (Win32) or 80 pixels (other + platforms). + In small or normal icon view, @a col must be -1, and the column width is set + for all columns. + */ + bool SetColumnWidth(int col, int width); + + /** + Sets the order of all columns at once. The @a orders array must have the + same number elements as the number of columns and contain each position exactly + once. + This function is valid in report view only. + */ + bool SetColumnOrder(const wxArrayInt& orders) const; + + /** + Sets the image list associated with the control. @a which is one of + wxIMAGE_LIST_NORMAL, wxIMAGE_LIST_SMALL, wxIMAGE_LIST_STATE (the last is + unimplemented). + This method does not take ownership of the image list, you have to + delete it yourself. + + @see AssignImageList() + */ + void SetImageList(wxImageList* imageList, int which); + + //@{ + /** + Sets a string field at a particular column. + */ + bool SetItem(wxListItem& info); + long SetItem(long index, int col, const wxString& label, + int imageId = -1); + m_mask m_state field is valid. + + + + + + wxLIST_MASK_TEXT + + + + + The m_text field is valid. + + + + + + wxLIST_MASK_IMAGE + + + + + The m_image field is valid. + + + + + + wxLIST_MASK_DATA + + + + + The m_data field is valid. + + + + + + wxLIST_MASK_WIDTH + + + + + The m_width field is valid. + + + + + + wxLIST_MASK_FORMAT + + + + + The m_format field is valid. + + + + + +The m_stateMask and m_state members take flags from the following: + + + + + + + + wxLIST_STATE_DONTCARE + + + + + Don't care what the state is. Win32 only. + + + + + + wxLIST_STATE_DROPHILITED + + + + + The item is highlighted to receive a drop event. Win32 only. + + + + + + wxLIST_STATE_FOCUSED + + + + + The item has the focus. + + + + + + wxLIST_STATE_SELECTED + + + + + The item is selected. + + + + + + wxLIST_STATE_CUT + + + + + The item is in the cut state. Win32 only. + + + + + + The wxListItem object can also contain item-specific colour and font + information: for this you need to call one of SetTextColour(), + SetBackgroundColour() or SetFont() functions on it passing it the colour/font + to use. If the colour/font is not specified, the default list control + colour/font is used. + long SetItem(long index, int col, const wxString& label, + int imageId = -1); + //@} + + /** + Sets the background colour for this item. This function only works in report + view. + The colour can be retrieved using + GetItemBackgroundColour(). + */ + void SetItemBackgroundColour(long item, const wxColour& col); + + /** + Sets the image associated with the item. In report view, you can specify the + column. + The image is an index into the image list associated with the list control. + */ + bool SetItemColumnImage(long item, long column, int image); + + /** + This method can only be used with virtual list controls. + + It is used to indicate to the control the number of items it contains. + After calling it, the main program should be ready to handle calls to + various item callbacks (such as wxListCtrl::OnGetItemText) for all + items in the range from 0 to @a count. + + Notice that the control is not necessarily redrawn after this call as + it may be undesirable if an item which is not visible on the screen + anyhow was added to or removed from a control displaying many items, if + you do need to refresh the display you can just call Refresh() manually. + */ + void SetItemCount(long count); + + /** + Associates application-defined data with this item. + Notice that this function cannot be used to associate pointers with the control + items, use SetItemPtrData() instead. + */ + bool SetItemData(long item, long data); + + /** + Sets the item's font. + */ + void SetItemFont(long item, const wxFont& font); + + //@{ + /** + Sets the unselected and selected images associated with the item. The images + are indices into the + image list associated with the list control. This form is deprecated: @a + selImage is not + used. + */ + bool SetItemImage(long item, int image); + bool SetItemImage(long item, int image, int selImage); + //@} + + /** + Sets the position of the item, in icon or small icon view. Windows only. + */ + bool SetItemPosition(long item, const wxPoint& pos); + + /** + Associates application-defined data with this item. The @a data parameter may + be either an integer or a pointer cast to the @c wxUIntPtr type which is + guaranteed to be large enough to be able to contain all integer types and + pointers. + + @since 2.8.4 + */ + bool SetItemPtrData(long item, wxUIntPtr data); + + /** + Sets the item state. For a list of state flags, see SetItem(). + The @b stateMask indicates which state flags are valid. + */ + bool SetItemState(long item, long state, long stateMask); + + /** + Sets the item text for this item. + */ + void SetItemText(long item, const wxString& text); + + /** + Sets the colour for this item. This function only works in report view. + The colour can be retrieved using + GetItemTextColour(). + */ + void SetItemTextColour(long item, const wxColour& col); + + /** + Adds or removes a single window style. + */ + void SetSingleStyle(long style, bool add = true); + + /** + Sets the text colour of the list control. + */ + void SetTextColour(const wxColour& col); + + /** + Sets the whole window style, deleting all items. + */ + void SetWindowStyleFlag(long style); + + /** + Call this function to sort the items in the list control. Sorting is done + using the specified @a fnSortCallBack function. This function must have the + following prototype: + + It is called each time when the two items must be compared and should return 0 + if the items are equal, negative value if the first item is less than the + second one and positive value if the first one is greater than the second one + (the same convention as used by @c qsort(3)). + + @param item1 + client data associated with the first item (NOT the index). + @param item2 + client data associated with the second item (NOT the index). + @param data + the value passed to SortItems() itself. + */ + bool SortItems(wxListCtrlCompare fnSortCallBack, long data); +}; + + + +/** + @class wxListEvent + @wxheader{listctrl.h} + + A list event holds information about events associated with wxListCtrl objects. + + @library{wxbase} + @category{events} + + @see wxListCtrl +*/ +class wxListEvent : public wxNotifyEvent +{ +public: + /** + Constructor. + */ + wxListEvent(wxEventType commandType = 0, int id = 0); + + /** + For @c EVT_LIST_CACHE_HINT event only: return the first item which the + list control advises us to cache. + */ + long GetCacheFrom() const; + + /** + For @c EVT_LIST_CACHE_HINT event only: return the last item (inclusive) + which the list control advises us to cache. + */ + long GetCacheTo() const; + + /** + The column position: it is only used with @c COL events. For the column + dragging events, it is the column to the left of the divider being dragged, for + the column click events it may be -1 if the user clicked in the list control + header outside any column. + */ + int GetColumn() const; + + /** + The data. + */ + long GetData() const; + + /** + The image. + */ + int GetImage() const; + + /** + The item index. + */ + long GetIndex() const; + + /** + An item object, used by some events. See also wxListCtrl::SetItem. + */ + const wxListItem GetItem() const; + + /** + Key code if the event is a keypress event. + */ + int GetKeyCode() const; + + /** + The (new) item label for @c EVT_LIST_END_LABEL_EDIT event. + */ + const wxString GetLabel() const; + + /** + The mask. + */ + long GetMask() const; + + /** + The position of the mouse pointer if the event is a drag event. + */ + wxPoint GetPoint() const; + + /** + The text. + */ + const wxString GetText() const; + + /** + This method only makes sense for @c EVT_LIST_END_LABEL_EDIT message + and returns @true if it the label editing has been cancelled by the user + (GetLabel() returns an empty string in this case + but it doesn't allow the application to distinguish between really cancelling + the edit and + the admittedly rare case when the user wants to rename it to an empty string). + */ + bool IsEditCancelled() const; +}; + + + +/** + @class wxListItemAttr + @wxheader{listctrl.h} + + Represents the attributes (color, font, ...) of a + wxListCtrl wxListItem. + + @library{wxbase} + @category{FIXME} + + @see @ref overview_listctrl "wxListCtrl Overview", wxListCtrl, + wxListItem +*/ +class wxListItemAttr +{ +public: + //@{ + /** + Construct a wxListItemAttr with the specified foreground and + background colors and font. + */ + wxListItemAttr(); + wxListItemAttr(const wxColour colText, + const wxColour colBack, + const wxFont font); + //@} + + /** + Returns the currently set background color. + */ + const wxColour GetBackgroundColour() const; + + /** + Returns the currently set font. + */ + const wxFont GetFont() const; + + /** + Returns the currently set text color. + */ + const wxColour GetTextColour() const; + + /** + Returns @true if the currently set background color is valid. + */ + bool HasBackgroundColour() const; + + /** + Returns @true if the currently set font is valid. + */ + bool HasFont() const; + + /** + Returns @true if the currently set text color is valid. + */ + bool HasTextColour() const; + + /** + Sets a new background color. + */ + void SetBackgroundColour(const wxColour& colour); + + /** + Sets a new font. + */ + void SetFont(const wxFont& font); + + /** + Sets a new text color. + */ + void SetTextColour(const wxColour& colour); +}; + + + +/** + @class wxListView + @wxheader{listctrl.h} + + This class currently simply presents a simpler to use interface for the + wxListCtrl -- it can be thought of as a @e faade + for that complicated class. Using it is preferable to using + wxListCtrl directly whenever possible because in the + future some ports might implement wxListView but not the full set of wxListCtrl + features. + + Other than different interface, this class is identical to wxListCtrl. In + particular, it uses the same events, same window styles and so on. + + @library{wxcore} + @category{ctrl} + + + @see wxListView::SetColumnImage +*/ +class wxListView : public wxListCtrl +{ +public: + /** + Resets the column image -- after calling this function, no image will be shown. + + @param col + the column to clear image for + + @see SetColumnImage() + */ + void ClearColumnImage(int col); + + /** + Sets focus to the item with the given @e index. + */ + void Focus(long index); + + /** + Returns the first selected item in a (presumably) multiple selection control. + Together with GetNextSelected() it can be + used to iterate over all selected items in the control. + + @return The first selected item, if any, -1 otherwise. + */ + long GetFirstSelected() const; + + /** + Returns the currently focused item or -1 if none. + + @see IsSelected(), Focus() + */ + long GetFocusedItem() const; + + /** + Used together with GetFirstSelected() to + iterate over all selected items in the control. + + @return Returns the next selected item or -1 if there are no more of + them. + */ + long GetNextSelected(long item) const; + + /** + Returns @true if the item with the given @a index is selected, + @false otherwise. + + @see GetFirstSelected(), GetNextSelected() + */ + bool IsSelected(long index) const; + + /** + Selects or unselects the given item. + + @param n + the item to select or unselect + @param on + if @true (default), selects the item, otherwise unselects it + + @see wxListCtrl::SetItemState + */ + void Select(bool on = true); + + /** + Sets the column image for the specified column. To use the column images, the + control must have a valid image list with at least one image. + + @param col + the column to set image for + @param image + the index of the column image in the controls image list + */ + void SetColumnImage(int col, int image); +}; + + + +/** + @class wxListItem + @wxheader{listctrl.h} + + This class stores information about a wxListCtrl item or column. + + @library{wxbase} + @category{FIXME} +*/ +class wxListItem : public wxObject +{ +public: + /** + Constructor. + */ + wxListItem(); + + /** + Resets the item state to the default. + */ + void Clear(); + + /** + Returns the alignment for this item. Can be one of + wxLIST_FORMAT_LEFT, wxLIST_FORMAT_RIGHT or wxLIST_FORMAT_CENTRE. + */ + wxListColumnFormat GetAlign() const; + + /** + Returns the background colour for this item. + */ + wxColour GetBackgroundColour() const; + + /** + Returns the zero-based column; meaningful only in report mode. + */ + int GetColumn() const; + + /** + Returns client data associated with the control. Please note that + client data is associated with the item and not with subitems. + */ + long GetData() const; + + /** + Returns the font used to display the item. + */ + wxFont GetFont() const; + + /** + Returns the zero-based item position. + */ + long GetId() const; + + /** + Returns the zero-based index of the image + associated with the item into the image list. + */ + int GetImage() const; + + /** + Returns a bit mask indicating which fields of the structure are valid; + can be any combination of the following values: + + wxLIST_MASK_STATE + + @b GetState is valid. + + wxLIST_MASK_TEXT + + @b GetText is valid. + + wxLIST_MASK_IMAGE + + @b GetImage is valid. + + wxLIST_MASK_DATA + + @b GetData is valid. + + wxLIST_MASK_WIDTH + + @b GetWidth is valid. + + wxLIST_MASK_FORMAT + + @b GetFormat is valid. + */ + long GetMask() const; + + /** + Returns a bit field representing the state of the item. Can be any + combination of: + + wxLIST_STATE_DONTCARE + + Don't care what the state is. Win32 only. + + wxLIST_STATE_DROPHILITED + + The item is highlighted to receive a drop event. Win32 only. + + wxLIST_STATE_FOCUSED + + The item has the focus. + + wxLIST_STATE_SELECTED + + The item is selected. + + wxLIST_STATE_CUT + + The item is in the cut state. Win32 only. + */ + long GetState() const; + + /** + Returns the label/header text. + */ + const wxString GetText() const; + + /** + Returns the text colour. + */ + wxColour GetTextColour() const; + + /** + Meaningful only for column headers in report mode. Returns the column width. + */ + int GetWidth() const; + + /** + Sets the alignment for the item. See also + GetAlign() + */ + void SetAlign(wxListColumnFormat align); + + /** + Sets the background colour for the item. + */ + void SetBackgroundColour(const wxColour& colBack); + + /** + Sets the zero-based column. Meaningful only in report mode. + */ + void SetColumn(int col); + + //@{ + /** + Sets client data for the item. Please note that + client data is associated with the item and not with subitems. + */ + void SetData(long data); + void SetData(void* data); + //@} + + /** + Sets the font for the item. + */ + void SetFont(const wxFont& font); + + /** + Sets the zero-based item position. + */ + void SetId(long id); + + /** + Sets the zero-based index of the image associated with the item + into the image list. + */ + void SetImage(int image); + + /** + Sets the mask of valid fields. See GetMask(). + */ + void SetMask(long mask); + + /** + Sets the item state flags (note that the valid state flags are influenced + by the value of the state mask, see + wxListItem::SetStateMask). + See GetState() for valid flag + values. + */ + void SetState(long state); + + /** + Sets the bitmask that is used to determine which of the state flags + are to be set. See also SetState(). + */ + void SetStateMask(long stateMask); + + /** + Sets the text label for the item. + */ + void SetText(const wxString& text); + + /** + Sets the text colour for the item. + */ + void SetTextColour(const wxColour& colText); + + /** + Meaningful only for column headers in report mode. Sets the column width. + */ + void SetWidth(int width); +}; + diff --git a/interface/wx/log.h b/interface/wx/log.h new file mode 100644 index 0000000000..bb96ae2926 --- /dev/null +++ b/interface/wx/log.h @@ -0,0 +1,1023 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: log.h +// Purpose: interface of wxLogWindow +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxLogWindow + @wxheader{log.h} + + This class represents a background log window: to be precise, it collects all + log messages in the log frame which it manages but also passes them on to the + log target which was active at the moment of its creation. This allows you, for + example, to show all the log messages in a frame but still continue to process + them normally by showing the standard log dialog. + + @library{wxbase} + @category{logging} + + @see wxLogTextCtrl +*/ +class wxLogWindow : public wxLogInterposer +{ +public: + /** + Creates the log frame window and starts collecting the messages in it. + + @param parent + The parent window for the log frame, may be @NULL + @param title + The title for the log frame + @param show + @true to show the frame initially (default), otherwise + Show() must be called later. + @param passToOld + @true to process the log messages normally in addition to + logging them in the log frame (default), @false to only log them in the + log frame. + */ + wxLogWindow(wxFrame parent, const wxChar title, bool show = true, + bool passToOld = true); + + /** + Returns the associated log frame window. This may be used to position or resize + it but use Show() to show or hide it. + */ + wxFrame* GetFrame() const; + + /** + Called if the user closes the window interactively, will not be + called if it is destroyed for another reason (such as when program + exits). + Return @true from here to allow the frame to close, @false to + prevent this from happening. + + @see OnFrameDelete() + */ + virtual bool OnFrameClose(wxFrame frame); + + /** + Called immediately after the log frame creation allowing for + any extra initializations. + */ + virtual void OnFrameCreate(wxFrame frame); + + /** + Called right before the log frame is going to be deleted: will + always be called unlike OnFrameClose(). + */ + virtual void OnFrameDelete(wxFrame frame); + + /** + Shows or hides the frame. + */ + void Show(bool show = true); +}; + + + +/** + @class wxLogInterposerTemp + @wxheader{log.h} + + A special version of wxLogChain which uses itself as the + new log target. It forwards log messages to the previously installed one in + addition to + processing them itself. Unlike wxLogInterposer, it doesn't + delete the old target which means it can be used to temporarily redirect log + output. + + As per wxLogInterposer, this class must be derived from to implement + wxLog::DoLog + and/or wxLog::DoLogString methods. + + @library{wxbase} + @category{logging} +*/ +class wxLogInterposerTemp : public wxLogChain +{ +public: + /** + The default constructor installs this object as the current active log target. + */ +}; + + + +/** + @class wxLogChain + @wxheader{log.h} + + This simple class allows you to chain log sinks, that is to install a new sink but + keep passing log messages to the old one instead of replacing it completely as + wxLog::SetActiveTarget does. + + It is especially useful when you want to divert the logs somewhere (for + example to a file or a log window) but also keep showing the error messages + using the standard dialogs as wxLogGui does by default. + + Example of usage: + + @code + wxLogChain *logChain = new wxLogChain(new wxLogStderr); + + // all the log messages are sent to stderr and also processed as usually + ... + + // don't delete logChain directly as this would leave a dangling + // pointer as active log target, use SetActiveTarget() instead + delete wxLog::SetActiveTarget(...something else or @NULL...); + @endcode + + @library{wxbase} + @category{logging} +*/ +class wxLogChain : public wxLog +{ +public: + /** + Sets the specified @c logger (which may be @NULL) as the default log + target but the log messages are also passed to the previous log target if any. + */ + wxLogChain(wxLog* logger); + + /** + Destroys the previous log target. + */ + ~wxLogChain(); + + /** + Detaches the old log target so it won't be destroyed when the wxLogChain object + is destroyed. + */ + void DetachOldLog(); + + /** + Returns the pointer to the previously active log target (which may be @NULL). + */ + wxLog* GetOldLog() const; + + /** + Returns @true if the messages are passed to the previously active log + target (default) or @false if PassMessages() + had been called. + */ + bool IsPassingMessages() const; + + /** + By default, the log messages are passed to the previously active log target. + Calling this function with @false parameter disables this behaviour + (presumably temporarily, as you shouldn't use wxLogChain at all otherwise) and + it can be reenabled by calling it again with @a passMessages set to @true. + */ + void PassMessages(bool passMessages); + + /** + Sets another log target to use (may be @NULL). The log target specified + in the wxLogChain(wxLog*) constructor or in a previous call to + this function is deleted. + This doesn't change the old log target value (the one the messages are + forwarded to) which still remains the same as was active when wxLogChain + object was created. + */ + void SetLog(wxLog* logger); +}; + + + +/** + @class wxLogGui + @wxheader{log.h} + + This is the default log target for the GUI wxWidgets applications. It is passed + to wxLog::SetActiveTarget at the program + startup and is deleted by wxWidgets during the program shut down. + + @library{wxbase} + @category{logging} +*/ +class wxLogGui : public wxLog +{ +public: + /** + Default constructor. + */ + wxLogGui(); +}; + + + +/** + @class wxLogStream + @wxheader{log.h} + + This class can be used to redirect the log messages to a C++ stream. + + Please note that this class is only available if wxWidgets was compiled with + the standard iostream library support (@c wxUSE_STD_IOSTREAM must be on). + + @library{wxbase} + @category{logging} + + @see wxLogStderr, wxStreamToTextRedirector +*/ +class wxLogStream : public wxLog +{ +public: + /** + Constructs a log target which sends all the log messages to the given + output stream. If it is @NULL, the messages are sent to @c cerr. + */ + wxLogStream(std::ostream ostr = NULL); +}; + + + +/** + @class wxLogStderr + @wxheader{log.h} + + This class can be used to redirect the log messages to a C file stream (not to + be confused with C++ streams). It is the default log target for the non-GUI + wxWidgets applications which send all the output to @c stderr. + + @library{wxbase} + @category{logging} + + @see wxLogStream +*/ +class wxLogStderr : public wxLog +{ +public: + /** + Constructs a log target which sends all the log messages to the given + @c FILE. If it is @NULL, the messages are sent to @c stderr. + */ + wxLogStderr(FILE fp = NULL); +}; + + + +/** + @class wxLogBuffer + @wxheader{log.h} + + wxLogBuffer is a very simple implementation of log sink which simply collects + all the logged messages in a string (except the debug messages which are output + in the usual way immediately as we're presumably not interested in collecting + them for later). The messages from different log function calls are separated + by the new lines. + + All the messages collected so far can be shown to the user (and the current + buffer cleared) by calling the overloaded wxLogBuffer::Flush + method. + + @library{wxbase} + @category{logging} +*/ +class wxLogBuffer : public wxLog +{ +public: + /** + Shows all the messages collected so far to the user (using a message box in the + GUI applications or by printing them out to the console in text mode) and + clears the internal buffer. + */ + virtual void Flush(); + + /** + Returns the current buffer contains. Messages from different log function calls + are separated with the new lines in the buffer. + The buffer can be cleared by Flush() which will + also show the current contents to the user. + */ + const wxString GetBuffer(); +}; + + + +/** + @class wxLogInterposer + @wxheader{log.h} + + A special version of wxLogChain which uses itself as the + new log target. It forwards log messages to the previously installed one in + addition to + processing them itself. + + Unlike wxLogChain which is usually used directly as is, + this class must be derived from to implement wxLog::DoLog + and/or wxLog::DoLogString methods. + + wxLogInterposer destroys the previous log target in its destructor. If you + don't want this to happen, use wxLogInterposerTemp instead. + + @library{wxbase} + @category{logging} +*/ +class wxLogInterposer : public wxLogChain +{ +public: + /** + The default constructor installs this object as the current active log target. + */ +}; + + + +/** + @class wxLogTextCtrl + @wxheader{log.h} + + Using these target all the log messages can be redirected to a text control. + The text control must have been created with @c wxTE_MULTILINE style by the + caller previously. + + @library{wxbase} + @category{logging} + + @see wxTextCtrl, wxStreamToTextRedirector +*/ +class wxLogTextCtrl : public wxLog +{ +public: + /** + Constructs a log target which sends all the log messages to the given text + control. The @a textctrl parameter cannot be @NULL. + */ + wxLogTextCtrl(wxTextCtrl textctrl); +}; + + + +/** + @class wxLog + @wxheader{log.h} + + wxLog class defines the interface for the @e log targets used by wxWidgets + logging functions as explained in the @ref overview_log. + The only situations when you need to directly use this class is when you want + to derive your own log target because the existing ones don't satisfy your + needs. Another case is if you wish to customize the behaviour of the standard + logging classes (all of which respect the wxLog settings): for example, set + which trace messages are logged and which are not or change (or even remove + completely) the timestamp on the messages. + + Otherwise, it is completely hidden behind the @e wxLogXXX() functions and + you may not even know about its existence. + + @section overview_wxLog_deriving Deriving your own log target + + There are two functions which must be implemented by any derived class to + actually process the log messages: DoLog() and + DoLogString(). The second function receives a string + which just has to be output in some way and the easiest way to write a new log + target is to override just this function in the derived class. If more control + over the output format is needed, then the first function must be overridden + which allows to construct custom messages depending on the log level or even + do completely different things depending on the message severity (for example, + throw away all messages except warnings and errors, show warnings on the + screen and forward the error messages to the user's (or programmer's) cell + phone - maybe depending on whether the timestamp tells us if it is day or + night in the current time zone). + There also functions to support message buffering. Why are they needed? + Some of wxLog implementations, most notably the standard wxLogGui class, + buffer the messages (for example, to avoid showing the user a zillion of modal + message boxes one after another -- which would be really annoying). + Flush() shows them all and clears the buffer contents. + This function doesn't do anything if the buffer is already empty. + See also: + @li Flush() + @li FlushActive() + + @section overview_wxLog_Trace_Masks Using trace masks + + The functions below allow some limited customization of wxLog behaviour + without writing a new log target class (which, aside from being a matter of + several minutes, allows you to do anything you want). + The verbose messages are the trace messages which are not disabled in the + release mode and are generated by wxLogVerbose(). They + are not normally shown to the user because they present little interest, but + may be activated, for example, in order to help the user find some program + problem. + As for the (real) trace messages, their handling depends on the settings of + the (application global) @e trace mask which can either be specified using + SetTraceMask(), GetTraceMask() and wxLogTrace() which takes an integer mask + or using AddTraceMask() for string trace masks. + The difference between bit-wise and string trace masks is that a message using + integer trace mask will only be logged if all bits of the mask are set in the + current mask while a message using string mask will be logged simply if the + mask had been added before to the list of allowed ones. + For example, + + @code + wxLogTrace( wxTraceRefCount|wxTraceOleCalls, "Active object ref count: %d", nRef ); + @endcode + + will do something only if the current trace mask contains both + @c wxTraceRefCount and @c wxTraceOle, but + + @code + wxLogTrace( wxTRACE_OleCalls, "IFoo::Bar() called" ); + @endcode + + will log the message if it was preceded by + + @code + wxLog::AddTraceMask( wxTRACE_OleCalls); + @endcode + + Using string masks is simpler and allows you to easily add custom ones, so this is + the preferred way of working with trace messages. The integer trace mask is + kept for compatibility and for additional (but very rarely needed) flexibility + only. + The standard trace masks are given in wxLogTrace() documentation. + Finally, the @e wxLog::DoLog() function automatically prepends a time stamp + to all the messages. The format of the time stamp may be changed: it can be + any string with % specifications fully described in the documentation of the + standard @e strftime() function. For example, the default format is + "[%d/%b/%y %H:%M:%S] " which gives something like "[17/Sep/98 22:10:16] " + (without quotes) for the current date. Setting an empty string as the time + format disables timestamping of the messages completely. + See also + @li AddTraceMask() + @li RemoveTraceMask() + @li ClearTraceMasks() + @li GetTraceMasks() + @li IsAllowedTraceMask() + @li SetVerbose() + @li GetVerbose() + @li SetTimestamp() + @li GetTimestamp() + @li SetTraceMask() + @li GetTraceMask() + @li SetRepetitionCounting() + @li GetRepetitionCounting() + + @note Timestamping is disabled for Visual C++ users in debug builds by + default because otherwise it would be impossible to directly go to the line + from which the log message was generated by simply clicking in the debugger + window on the corresponding error message. If you wish to enable it, please + use SetTimestamp() explicitly. + + @section overview_wxLog_Target Manipulating the log target + + The functions in this section work with and manipulate the active log + target. The OnLog() is called by the @e wxLogXXX() functions + and invokes the DoLog() of the active log target if any. + Get/Set methods are used to install/query the current active target and, + finally, DontCreateOnDemand() disables the automatic creation of a standard + log target if none actually exists. It is only useful when the application + is terminating and shouldn't be used in other situations because it may + easily lead to a loss of messages. See also + @li OnLog() + @li GetActiveTarget() + @li SetActiveTarget() + @li DontCreateOnDemand() + @li Suspend() + @li Resume() + + @library{wxcore} + @category{logging} + + @see @ref overview_log +*/ +class wxLog +{ +public: + /** + Add the @a mask to the list of allowed masks for + wxLogTrace(). + + @see RemoveTraceMask(), GetTraceMasks() + */ + static void AddTraceMask(const wxString& mask); + + /** + Removes all trace masks previously set with + AddTraceMask(). + + @see RemoveTraceMask() + */ + static void ClearTraceMasks(); + + */ + + + /** + Disables time stamping of the log messages. + This function is new since wxWidgets version 2.9 + */ + void SetTimestamp(const wxString& format); + + /** + Called to process the message of the specified severity. @a msg is the text + of the message as specified in the call of @e wxLogXXX() function which + generated it and @a timestamp is the moment when the message was generated. + The base class version prepends the timestamp to the message, adds a prefix + corresponding to the log level and then calls + DoLogString() with the resulting string. + */ + virtual void DoLog(wxLogLevel level, const wxString& msg, + time_t timestamp); + + /** + Called to log the specified string. The timestamp is already included in the + string but still passed to this function. + A simple implementation may just send the string to @c stdout or, better, + @c stderr. + */ + virtual void DoLogString(const wxString& msg, time_t timestamp); + + /** + Instructs wxLog to not create new log targets on the fly if there is none + currently. (Almost) for internal use only: it is supposed to be called by the + application shutdown code. + Note that this function also calls + ClearTraceMasks(). + */ + static void DontCreateOnDemand(); + + /** + Shows all the messages currently in buffer and clears it. If the buffer + is already empty, nothing happens. + */ + virtual void Flush(); + + /** + Flushes the current log target if any, does nothing if there is none. + + @see Flush() + */ + static void FlushActive(); + + /** + Returns the pointer to the active log target (may be @NULL). + */ + static wxLog* GetActiveTarget(); + + /** + Returns the current log level limit. + */ + static wxLogLevel GetLogLevel(); + + /** + Returns whether the repetition counting mode is enabled. + */ + static bool GetRepetitionCounting(); + + /** + Returns the current timestamp format string. + */ + static const wxString GetTimestamp(); + + /** + Returns the current trace mask, see Customization() section + for details. + */ + static wxTraceMask GetTraceMask(); + + /** + Returns the currently allowed list of string trace masks. + + @see AddTraceMask(). + */ + static const wxArrayString GetTraceMasks(); + + /** + Returns whether the verbose mode is currently active. + */ + static bool GetVerbose(); + + /** + Returns @true if the @a mask is one of allowed masks for + wxLogTrace(). + + See also: AddTraceMask(), RemoveTraceMask() + */ + static bool IsAllowedTraceMask(const wxString& mask); + + /** + There are two functions which must be implemented by any derived class to + actually process the log messages: DoLog() and + DoLogString(). The second function receives a string + which just has to be output in some way and the easiest way to write a new log + target is to override just this function in the derived class. If more control + over the output format is needed, then the first function must be overridden + which allows you to construct custom messages depending on the log level or even + do completely different things depending on the message severity (for example, + throw away all messages except warnings and errors, show warnings on the + screen and forward the error messages to the user's (or programmer's) cell + phone - maybe depending on whether the timestamp tells us if it is day or + night in the current time zone). + There also functions to support message buffering. Why are they needed? + Some of wxLog implementations, most notably the standard wxLogGui class, + buffer the messages (for example, to avoid showing the user a zillion of modal + message boxes one after another -- which would be really annoying). + Flush() shows them all and clears the buffer contents. + This function doesn't do anything if the buffer is already empty. + Flush() + + FlushActive() + */ + + + /** + Forwards the message at specified level to the @e DoLog() function of the + active log target if there is any, does nothing otherwise. + */ + static void OnLog(wxLogLevel level, const wxString& message); + + /** + Remove the @a mask from the list of allowed masks for + wxLogTrace(). + See also: AddTraceMask() + */ + static void RemoveTraceMask(const wxString& mask); + + /** + Resumes logging previously suspended by a call to + Suspend(). All messages logged in the meanwhile will be + flushed soon. + */ + static void Resume(); + + /** + Sets the specified log target as the active one. Returns the pointer to the + previous active log target (may be @NULL). To suppress logging use a new + instance of wxLogNull not @NULL. If the active log target is set to @NULL a + new default log target will be created when logging occurs. + */ + static wxLog* SetActiveTarget(wxLog* logtarget); + + /** + Specifies that log messages with level logLevel should be ignored + and not sent to the active log target. + */ + static void SetLogLevel(wxLogLevel logLevel); + + /** + Enables logging mode in which a log message is logged once, and in case exactly + the same message successively repeats one or more times, only the number of + repetitions is logged. + */ + static void SetRepetitionCounting(bool repetCounting = true); + + /** + Sets the timestamp format prepended by the default log targets to all + messages. The string may contain any normal characters as well as % + prefixed format specificators, see @e strftime() manual for details. + Passing an empty string to this function disables message time stamping. + */ + static void SetTimestamp(const wxString& format); + + /** + Sets the trace mask, see Customization() + section for details. + */ + static void SetTraceMask(wxTraceMask mask); + + /** + Activates or deactivates verbose mode in which the verbose messages are + logged as the normal ones instead of being silently dropped. + */ + static void SetVerbose(bool verbose = true); + + /** + Suspends the logging until Resume() is called. Note that + the latter must be called the same number of times as the former to undo it, + i.e. if you call Suspend() twice you must call Resume() twice as well. + Note that suspending the logging means that the log sink won't be be flushed + periodically, it doesn't have any effect if the current log target does the + logging immediately without waiting for Flush() to be + called (the standard GUI log target only shows the log dialog when it is + flushed, so Suspend() works as expected with it). + + @see Resume(), wxLogNull + */ + static void Suspend(); +}; + + + +/** + @class wxLogNull + @wxheader{log.h} + + This class allows you to temporarily suspend logging. All calls to the log + functions during the life time of an object of this class are just ignored. + + In particular, it can be used to suppress the log messages given by wxWidgets + itself but it should be noted that it is rarely the best way to cope with this + problem as @b all log messages are suppressed, even if they indicate a + completely different error than the one the programmer wanted to suppress. + + For instance, the example of the overview: + + @code + wxFile file; + + // wxFile.Open() normally complains if file can't be opened, we don't want it + { + wxLogNull logNo; + if ( !file.Open("bar") ) + ... process error ourselves ... + } // ~wxLogNull called, old log sink restored + + wxLogMessage("..."); // ok + @endcode + + would be better written as: + + @code + wxFile file; + + // don't try to open file if it doesn't exist, we are prepared to deal with + // this ourselves - but all other errors are not expected + if ( wxFile::Exists("bar") ) + { + // gives an error message if the file couldn't be opened + file.Open("bar"); + } + else + { + ... + } + @endcode + + + @library{wxbase} + @category{logging} +*/ +class wxLogNull : public wxLog +{ +public: + /** + Suspends logging. + */ + wxLogNull(); + + /** + Resumes logging. + */ +}; + + + +// ============================================================================ +// Global functions/macros +// ============================================================================ + +/** @ingroup group_funcmacro_log */ +//@{ + +/** + This function shows a message to the user in a safe way and should be safe + to call even before the application has been initialized or if it is + currently in some other strange state (for example, about to crash). Under + Windows this function shows a message box using a native dialog instead of + wxMessageBox() (which might be unsafe to call), elsewhere it simply prints + the message to the standard output using the title as prefix. + + @param title + The title of the message box shown to the user or the prefix of the + message string. + @param text + The text to show to the user. + + @see wxLogFatalError() + + @header{wx/log.h} +*/ +void wxSafeShowMessage(const wxString& title, const wxString& text); + +/** + Returns the error code from the last system call. This function uses + @c errno on Unix platforms and @c GetLastError under Win32. + + @see wxSysErrorMsg(), wxLogSysError() + + @header{wx/log.h} +*/ +unsigned long wxSysErrorCode(); + +/** + Returns the error message corresponding to the given system error code. If + @a errCode is 0 (default), the last error code (as returned by + wxSysErrorCode()) is used. + + @see wxSysErrorCode(), wxLogSysError() + + @header{wx/log.h} +*/ +const wxChar* wxSysErrorMsg(unsigned long errCode = 0); + +//@} + +/** @ingroup group_funcmacro_log */ +//@{ +/** + For all normal, informational messages. They also appear in a message box + by default (but it can be changed). + + @header{wx/log.h} +*/ +void wxLogMessage(const char* formatString, ... ); +void wxVLogMessage(const char* formatString, va_list argPtr); +//@} + +/** @ingroup group_funcmacro_log */ +//@{ +/** + For verbose output. Normally, it is suppressed, but might be activated if + the user wishes to know more details about the program progress (another, + but possibly confusing name for the same function could be @c wxLogInfo). + + @header{wx/log.h} +*/ +void wxLogVerbose(const char* formatString, ... ); +void wxVLogVerbose(const char* formatString, va_list argPtr); +//@} + +/** @ingroup group_funcmacro_log */ +//@{ +/** + For warnings - they are also normally shown to the user, but don't + interrupt the program work. + + @header{wx/log.h} +*/ +void wxLogWarning(const char* formatString, ... ); +void wxVLogWarning(const char* formatString, va_list argPtr); +//@} + +/** @ingroup group_funcmacro_log */ +//@{ +/** + Like wxLogError(), but also terminates the program with the exit code 3. + Using @e abort() standard function also terminates the program with this + exit code. + + @header{wx/log.h} +*/ +void wxLogFatalError(const char* formatString, ... ); +void wxVLogFatalError(const char* formatString, va_list argPtr); +//@} + +/** @ingroup group_funcmacro_log */ +//@{ +/** + The functions to use for error messages, i.e. the messages that must be + shown to the user. The default processing is to pop up a message box to + inform the user about it. + + @header{wx/log.h} +*/ +void wxLogError(const char* formatString, ... ); +void wxVLogError(const char* formatString, va_list argPtr); +//@} + +/** @ingroup group_funcmacro_log */ +//@{ +/** + Like wxLogDebug(), trace functions only do something in debug builds and + expand to nothing in the release one. The reason for making it a separate + function is that usually there are a lot of trace messages, so it might + make sense to separate them from other debug messages. + + wxLogDebug(const char*,const char*,...) and + wxLogDebug(wxTraceMask,const char*,...) can be used instead if you would + like to be able to separate trace messages into different categories which + can be enabled or disabled with the static functions provided in wxLog. + + @header{wx/log.h} +*/ +void wxLogTrace(const char* formatString, ... ); +void wxVLogTrace(const char* formatString, va_list argPtr); +//@} + +/** @ingroup group_funcmacro_log */ +//@{ +/** + Like wxLogDebug(), trace functions only do something in debug builds and + expand to nothing in the release one. The reason for making it a separate + function is that usually there are a lot of trace messages, so it might + make sense to separate them from other debug messages. + + In this version of wxLogTrace(), trace messages can be separated into + different categories and calls using this function only log the message if + the given @a mask is currently enabled in wxLog. This lets you selectively + trace only some operations and not others by enabling the desired trace + masks with wxLog::AddTraceMask() or by setting the + @ref overview_envvars "@c WXTRACE environment variable". + + The predefined string trace masks used by wxWidgets are: + + @beginDefList + @itemdef{ wxTRACE_MemAlloc, Trace memory allocation (new/delete) } + @itemdef{ wxTRACE_Messages, Trace window messages/X callbacks } + @itemdef{ wxTRACE_ResAlloc, Trace GDI resource allocation } + @itemdef{ wxTRACE_RefCount, Trace various ref counting operations } + @itemdef{ wxTRACE_OleCalls, Trace OLE method calls (Win32 only) } + @endDefList + + @note Since both the mask and the format string are strings, this might + lead to function signature confusion in some cases: if you intend to + call the format string only version of wxLogTrace(), add a "%s" + format string parameter and then supply a second string parameter for + that "%s", the string mask version of wxLogTrace() will erroneously + get called instead, since you are supplying two string parameters to + the function. In this case you'll unfortunately have to avoid having + two leading string parameters, e.g. by adding a bogus integer (with + its "%d" format string). + + @header{wx/log.h} +*/ +void wxLogTrace(const char* mask, const char* formatString, ... ); +void wxVLogTrace(const char* mask, + const char* formatString, + va_list argPtr); +//@} + +/** @ingroup group_funcmacro_log */ +//@{ +/** + Like wxLogDebug(), trace functions only do something in debug builds and + expand to nothing in the release one. The reason for making it a separate + function is that usually there are a lot of trace messages, so it might + make sense to separate them from other debug messages. + + This version of wxLogTrace() only logs the message if all the bits + corresponding to the @a mask are set in the wxLog trace mask which can be + set by calling wxLog::SetTraceMask(). This version is less flexible than + wxLogDebug(const char*,const char*,...) because it doesn't allow defining + the user trace masks easily. This is why it is deprecated in favour of + using string trace masks. + + The following bitmasks are defined for wxTraceMask: + + @beginDefList + @itemdef{ wxTraceMemAlloc, Trace memory allocation (new/delete) } + @itemdef{ wxTraceMessages, Trace window messages/X callbacks } + @itemdef{ wxTraceResAlloc, Trace GDI resource allocation } + @itemdef{ wxTraceRefCount, Trace various ref counting operations } + @itemdef{ wxTraceOleCalls, Trace OLE method calls (Win32 only) } + @endDefList + + @header{wx/log.h} +*/ +void wxLogTrace(wxTraceMask mask, const char* formatString, ... ); +void wxVLogTrace(wxTraceMask mask, const char* formatString, va_list argPtr); +//@} + +/** @ingroup group_funcmacro_log */ +//@{ +/** + The right functions for debug output. They only do something in debug mode + (when the preprocessor symbol @c __WXDEBUG__ is defined) and expand to + nothing in release mode (otherwise). + + @header{wx/log.h} +*/ +void wxLogDebug(const char* formatString, ... ); +void wxVLogDebug(const char* formatString, va_list argPtr); +//@} + +/** @ingroup group_funcmacro_log */ +//@{ +/** + Messages logged by this function will appear in the statusbar of the + @a frame or of the top level application window by default (i.e. when using + the second version of the functions). + + If the target frame doesn't have a statusbar, the message will be lost. + + @header{wx/log.h} +*/ +void wxLogStatus(wxFrame* frame, const char* formatString, ... ); +void wxVLogStatus(wxFrame* frame, const char* formatString, va_list argPtr); +void wxLogStatus(const char* formatString, ... ); +void wxVLogStatus(const char* formatString, va_list argPtr); +//@} + +/** @ingroup group_funcmacro_log */ +//@{ +/** + Mostly used by wxWidgets itself, but might be handy for logging errors + after system call (API function) failure. It logs the specified message + text as well as the last system error code (@e errno or @e ::GetLastError() + depending on the platform) and the corresponding error message. The second + form of this function takes the error code explicitly as the first + argument. + + @see wxSysErrorCode(), wxSysErrorMsg() + + @header{wx/log.h} +*/ +void wxLogSysError(const char* formatString, ... ); +void wxVLogSysError(const char* formatString, va_list argPtr); +//@} + diff --git a/interface/wx/longlong.h b/interface/wx/longlong.h new file mode 100644 index 0000000000..e3eaef7ec6 --- /dev/null +++ b/interface/wx/longlong.h @@ -0,0 +1,202 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: longlong.h +// Purpose: interface of wxLongLong +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxLongLong + @wxheader{longlong.h} + + This class represents a signed 64 bit long number. It is implemented using the + native 64 bit type where available (machines with 64 bit longs or compilers + which have (an analog of) @e long long type) and uses the emulation code in + the other cases which ensures that it is the most efficient solution for + working with 64 bit integers independently of the architecture. + + wxLongLong defines all usual arithmetic operations such as addition, + subtraction, bitwise shifts and logical operations as well as multiplication + and division (not yet for the machines without native @e long long). It + also has operators for implicit construction from and conversion to the native + @e long long type if it exists and @e long. + + You would usually use this type in exactly the same manner as any other + (built-in) arithmetic type. Note that wxLongLong is a signed type, if you + want unsigned values use wxULongLong which has exactly the same API as + wxLongLong except when explicitly mentioned otherwise. + + If a native (i.e. supported directly by the compiler) 64 bit integer type was + found to exist, @e wxLongLong_t macro will be defined to correspond to it. + Also, in this case only, two additional macros will be defined: + wxLongLongFmtSpec() for printing 64 bit integers + using the standard @c printf() function (but see also + wxLongLong::ToString for a more portable solution) and + wxLL() for defining 64 bit integer compile-time constants. + + @library{wxbase} + @category{data} +*/ +class wxLongLong +{ +public: + /** + Constructor from 2 longs: the high and low part are combined into one + wxLongLong. + */ + wxLongLong(long hi, unsigned long lo); + + //@{ + /** + Returns an absolute value of wxLongLong - either making a copy (const version) + or modifying it in place (the second one). Not in wxULongLong. + */ + wxLongLong Abs(); + const wxLongLong& Abs(); + //@} + + /** + This allows to convert a double value to wxLongLong type. Such conversion is + not always possible in which case the result will be silently truncated in a + platform-dependent way. Not in wxULongLong. + */ + wxLongLong Assign(double d); + + /** + Returns the high 32 bits of 64 bit integer. + */ + long GetHi() const; + + /** + Returns the low 32 bits of 64 bit integer. + */ + unsigned long GetLo() const; + + /** + Convert to native long long (only for compilers supporting it) + */ + wxLongLong_t GetValue() const; + + /** + Returns the value as @c double. + */ + double ToDouble() const; + + /** + Truncate wxLongLong to long. If the conversion loses data (i.e. the wxLongLong + value is outside the range of built-in long type), an assert will be triggered + in debug mode. + */ + long ToLong() const; + + /** + Returns the string representation of a wxLongLong. + */ + wxString ToString() const; + + /** + Adds 2 wxLongLongs together and returns the result. + */ + wxLongLong operator+(const wxLongLong& ll) const; + + //@{ + /** + Pre/post increment operator. + */ + wxLongLong operator++(); + wxLongLong operator++(int ); + //@} + + /** + Add another wxLongLong to this one. + */ + wxLongLong operator+(const wxLongLong& ll); + + /** + Subtracts 2 wxLongLongs and returns the result. + */ + wxLongLong operator-(const wxLongLong& ll) const; + + //@{ + /** + Pre/post decrement operator. + */ + wxLongLong operator--(); + wxLongLong operator--(int ); + //@} + + /** + Subtracts another wxLongLong from this one. + */ + wxLongLong operator-(const wxLongLong& ll); + + /** + Assignment operator from unsigned long long. The sign bit will be copied too. + + @since 2.7.0 + */ + wxLongLong& operator operator=(const wxULongLong& ll); +}; + + + +// ============================================================================ +// Global functions/macros +// ============================================================================ + +/** @ingroup group_funcmacro_misc */ +//@{ + +/** + This macro is defined to contain the @c printf() format specifier using + which 64 bit integer numbers (i.e. those of type @c wxLongLong_t) can be + printed. Example of using it: + + @code + #ifdef wxLongLong_t + wxLongLong_t ll = wxLL(0x1234567890abcdef); + printf("Long long = %" wxLongLongFmtSpec "x\n", ll); + #endif + @endcode + + @see wxLL() + + @header{wx/longlong.h} +*/ +#define wxLongLongFmtSpec + +/** + This macro is defined for the platforms with a native 64 bit integer type + and allow the use of 64 bit compile time constants: + + @code + #ifdef wxLongLong_t + wxLongLong_t ll = wxLL(0x1234567890abcdef); + #endif + @endcode + + @see wxULL(), wxLongLong + + @header{wx/longlong.h} +*/ +wxLongLong_t wxLL(number); + +/** + This macro is defined for the platforms with a native 64 bit integer type + and allow the use of 64 bit compile time constants: + + @code + #ifdef wxLongLong_t + unsigned wxLongLong_t ll = wxULL(0x1234567890abcdef); + #endif + @endcode + + @see wxLL(), wxLongLong + + @header{wx/longlong.h} +*/ +wxLongLong_t wxULL(number); + +//@} + diff --git a/interface/wx/math.h b/interface/wx/math.h new file mode 100644 index 0000000000..e60620eaa5 --- /dev/null +++ b/interface/wx/math.h @@ -0,0 +1,28 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: math.h +// Purpose: interface of global functions +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** @ingroup group_funcmacro_math */ +//@{ + +/** + Returns a non-zero value if @a x is neither infinite nor NaN (not a + number), returns 0 otherwise. + + @header{wx/math.h} +*/ +int wxFinite(double x); + +/** + Returns a non-zero value if x is NaN (not a number), returns 0 otherwise. + + @header{wx/math.h} +*/ +bool wxIsNaN(double x); + +//@} + diff --git a/interface/wx/mdi.h b/interface/wx/mdi.h new file mode 100644 index 0000000000..3d5f3b80bc --- /dev/null +++ b/interface/wx/mdi.h @@ -0,0 +1,405 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: mdi.h +// Purpose: interface of wxMDIClientWindow +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxMDIClientWindow + @wxheader{mdi.h} + + An MDI client window is a child of wxMDIParentFrame, and manages zero or + more wxMDIChildFrame objects. + + @library{wxcore} + @category{FIXME} + + @see wxMDIChildFrame, wxMDIParentFrame, wxFrame +*/ +class wxMDIClientWindow : public wxWindow +{ +public: + //@{ + /** + Constructor, creating the window. + + @param parent + The window parent. + @param style + The window style. Currently unused. + + @remarks The second style of constructor is called within + wxMDIParentFrame::OnCreateClient. + + @see wxMDIParentFrame::wxMDIParentFrame, wxMDIParentFrame::OnCreateClient + */ + wxMDIClientWindow(); + wxMDIClientWindow(wxMDIParentFrame* parent, long style = 0); + //@} + + /** + Destructor. + */ + ~wxMDIClientWindow(); + + /** + Used in two-step frame construction. See wxMDIClientWindow() + for further details. + */ + bool CreateClient(wxMDIParentFrame* parent, long style = 0); +}; + + + +/** + @class wxMDIParentFrame + @wxheader{mdi.h} + + An MDI (Multiple Document Interface) parent frame is a window which can contain + MDI child frames in its own 'desktop'. It is a convenient way to avoid window + clutter, + and is used in many popular Windows applications, such as Microsoft Word(TM). + + @beginStyleTable + @style{wxCAPTION} + Puts a caption on the frame. + @style{wxDEFAULT_FRAME_STYLE} + Defined as wxMINIMIZE_BOX | wxMAXIMIZE_BOX | wxTHICK_FRAME | + wxSYSTEM_MENU | wxCAPTION. + @style{wxHSCROLL} + Displays a horizontal scrollbar in the client window, allowing the + user to view child frames that are off the current view. + @style{wxICONIZE} + Display the frame iconized (minimized) (Windows only). + @style{wxMAXIMIZE} + Displays the frame maximized (Windows only). + @style{wxMAXIMIZE_BOX} + Displays a maximize box on the frame (Windows and Motif only). + @style{wxMINIMIZE} + Identical to wxICONIZE. + @style{wxMINIMIZE_BOX} + Displays a minimize box on the frame (Windows and Motif only). + @style{wxRESIZE_BORDER} + Displays a resizeable border around the window (Motif only; for + Windows, it is implicit in wxTHICK_FRAME). + @style{wxSTAY_ON_TOP} + Stay on top of other windows (Windows only). + @style{wxSYSTEM_MENU} + Displays a system menu (Windows and Motif only). + @style{wxTHICK_FRAME} + Displays a thick frame around the window (Windows and Motif only). + @style{wxVSCROLL} + Displays a vertical scrollbar in the client window, allowing the + user to view child frames that are off the current view. + @style{wxFRAME_NO_WINDOW_MENU} + Under Windows, removes the Window menu that is normally added + automatically. + @endStyleTable + + @library{wxcore} + @category{managedwnd} + + @see wxMDIChildFrame, wxMDIClientWindow, wxFrame, wxDialog +*/ +class wxMDIParentFrame : public wxFrame +{ +public: + //@{ + /** + Constructor, creating the window. + + @param parent + The window parent. This should be @NULL. + @param id + 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. + @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 wxMDIParentFrame. + @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 + individual windows. + + @remarks During the construction of the frame, the client window will be + created. To use a different class from + wxMDIClientWindow, override + OnCreateClient(). + + @see Create(), OnCreateClient() + */ + wxMDIParentFrame(); + wxMDIParentFrame(wxWindow* parent, wxWindowID id, + const wxString& title, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxDEFAULT_FRAME_STYLE | wxVSCROLL | wxHSCROLL, + const wxString& name = "frame"); + //@} + + /** + Destructor. Destroys all child windows and menu bar if present. + */ + ~wxMDIParentFrame(); + + /** + Activates the MDI child following the currently active one. + + @see ActivatePrevious() + */ + void ActivateNext(); + + /** + Activates the MDI child preceding the currently active one. + + @see ActivateNext() + */ + void ActivatePrevious(); + + /** + Arranges any iconized (minimized) MDI child windows. + + @see Cascade(), Tile() + */ + void ArrangeIcons(); + + /** + Arranges the MDI child windows in a cascade. + + @see Tile(), ArrangeIcons() + */ + void Cascade(); + + /** + Used in two-step frame construction. See wxMDIParentFrame() + for further details. + */ + bool Create(wxWindow* parent, wxWindowID id, + const wxString& title, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxDEFAULT_FRAME_STYLE | wxVSCROLL | wxHSCROLL, + const wxString& name = "frame"); + + /** + Returns a pointer to the active MDI child, if there is one. + */ + wxMDIChildFrame* GetActiveChild() const; + + /** + This gets the size of the frame 'client area' in pixels. + + @param width + Receives the client width in pixels. + @param height + Receives the client height in pixels. + + @remarks The client area is the area which may be drawn on by the + programmer, excluding title bar, border, status bar, + and toolbar if present. + + @see GetToolBar(), SetToolBar(), + wxMDIClientWindow + */ + virtual void GetClientSize(int* width, int* height) const; + + /** + Returns a pointer to the client window. + + @see OnCreateClient() + */ + wxMDIClientWindow* GetClientWindow() const; + + /** + Returns the window being used as the toolbar for this frame. + + @see SetToolBar() + */ + virtual wxWindow* GetToolBar() const; + + /** + Returns the current Window menu (added by wxWidgets to the menubar). This + function + is available under Windows only. + */ + wxMenu* GetWindowMenu() const; + + /** + Override this to return a different kind of client window. If you override this + function, + you must create your parent frame in two stages, or your function will never be + called, + due to the way C++ treats virtual functions called from constructors. For + example: + + @remarks You might wish to derive from wxMDIClientWindow in order to + implement different erase behaviour, for example, such + as painting a bitmap on the background. + + @see GetClientWindow(), wxMDIClientWindow + */ + virtual wxMDIClientWindow* OnCreateClient(); + + /** + Sets the window to be used as a toolbar for this + MDI parent window. It saves the application having to manage the positioning + of the toolbar MDI client window. + + @param toolbar + Toolbar to manage. + + @remarks When the frame is resized, the toolbar is resized to be the + width of the frame client area, and the toolbar height + is kept the same. + + @see GetToolBar(), GetClientSize() + */ + virtual void SetToolBar(wxWindow* toolbar); + + /** + Call this to change the current Window menu. Ownership of the menu object + passes to + the frame when you call this function. + This call is available under Windows only. + To remove the window completely, use the wxFRAME_NO_WINDOW_MENU window style. + */ + void SetWindowMenu(wxMenu* menu); + + /** + Tiles the MDI child windows either horizontally or vertically depending on + whether @a orient is wxHORIZONTAL or wxVERTICAL. + Currently only implemented for MSW, does nothing under the other platforms. + */ + void Tile(wxOrientation orient = wxHORIZONTAL); +}; + + + +/** + @class wxMDIChildFrame + @wxheader{mdi.h} + + An MDI child frame is a frame that can only exist on a wxMDIClientWindow, + which is itself a child of wxMDIParentFrame. + + @beginStyleTable + @style{wxCAPTION} + Puts a caption on the frame. + @style{wxDEFAULT_FRAME_STYLE} + Defined as wxMINIMIZE_BOX | wxMAXIMIZE_BOX | wxTHICK_FRAME | + wxSYSTEM_MENU | wxCAPTION. + @style{wxICONIZE} + Display the frame iconized (minimized) (Windows only). + @style{wxMAXIMIZE} + Displays the frame maximized (Windows only). + @style{wxMAXIMIZE_BOX} + Displays a maximize box on the frame (Windows and Motif only). + @style{wxMINIMIZE} + Identical to wxICONIZE. + @style{wxMINIMIZE_BOX} + Displays a minimize box on the frame (Windows and Motif only). + @style{wxRESIZE_BORDER} + Displays a resizeable border around the window (Motif only; for + Windows, it is implicit in wxTHICK_FRAME). + @style{wxSTAY_ON_TOP} + Stay on top of other windows (Windows only). + @style{wxSYSTEM_MENU} + Displays a system menu (Windows and Motif only). + @style{wxTHICK_FRAME} + Displays a thick frame around the window (Windows and Motif only). + @endStyleTable + + @library{wxcore} + @category{managedwnd} + + @see wxMDIClientWindow, wxMDIParentFrame, wxFrame +*/ +class wxMDIChildFrame : public wxFrame +{ +public: + //@{ + /** + Constructor, creating the window. + + @param parent + The window parent. This should not be @NULL. + @param id + 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. + @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 wxMDIChildFrame. + @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 + individual windows. + + @remarks None. + + @see Create() + */ + wxMDIChildFrame(); + wxMDIChildFrame(wxMDIParentFrame* 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. + */ + ~wxMDIChildFrame(); + + /** + Activates this MDI child frame. + + @see Maximize(), Restore() + */ + void Activate(); + + /** + Used in two-step frame construction. See wxMDIChildFrame() + for further details. + */ + bool Create(wxWindow* parent, wxWindowID id, + const wxString& title, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxDEFAULT_FRAME_STYLE, + const wxString& name = "frame"); + + /** + Maximizes this MDI child frame. + + @see Activate(), Restore() + */ + void Maximize(bool maximize); + + /** + Restores this MDI child frame (unmaximizes). + */ + void Restore(); +}; + diff --git a/interface/wx/mediactrl.h b/interface/wx/mediactrl.h new file mode 100644 index 0000000000..6a1fcb3c5f --- /dev/null +++ b/interface/wx/mediactrl.h @@ -0,0 +1,400 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: mediactrl.h +// Purpose: interface of wxMediaEvent +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxMediaEvent + @wxheader{mediactrl.h} + + Event wxMediaCtrl uses. + + @library{wxmedia} + @category{FIXME} +*/ +class wxMediaEvent : public wxNotifyEvent +{ +public: + +}; + + + +/** + @class wxMediaCtrl + @wxheader{mediactrl.h} + + wxMediaCtrl is a class for displaying types of + media, such as videos, audio files, natively through native codecs. + + wxMediaCtrl uses native backends to render media, for example on Windows + there is a ActiveMovie/DirectShow backend, and on Macintosh there is a + QuickTime backend. + + @library{wxmedia} + @category{media} + + @see wxMediaEvent +*/ +class wxMediaCtrl : public wxControl +{ +public: + //@{ + /** + , + wxPoint& + + @param pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0, + const wxString& szBackend = wxT(""), + const wxValidatorvalidator = wxDefaultValidator, + const wxString& name = wxPanelNameStr + ) + + Constructor that calls Create. You may prefer to call Create directly to check + to see if wxMediaCtrl is available on the system. + + parent + parent of this control. Must not be @NULL. + @param id + id to use for events + @param fileName + If not empty, the path of a file to open. + @param pos + Position to put control at. + @param size + Size to put the control at and to stretch movie to. + @param style + Optional styles. + @param szBackend + Name of backend you want to use, leave blank to make + wxMediaCtrl figure it out. + @param validator + validator to use. + @param name + Window name. + */ + wxMediaCtrl() const; + wxMediaCtrl(wxWindow* parent, wxWindowID id) const; + //@} + + /** + Generally, you should almost certainly leave this part up to + wxMediaCtrl - but if you need a certain backend for a particular + reason, such as QuickTime for playing .mov files, all you need + to do to choose a specific backend is to pass the + name of the backend class to + Create(). + The following are valid backend identifiers - + + @b wxMEDIABACKEND_DIRECTSHOW + + + Use ActiveMovie/DirectShow. Uses the native ActiveMovie + (I.E. DirectShow) control. Default backend on Windows and + supported by nearly all Windows versions, even some + Windows CE versions. May display a windows media player + logo while inactive. + + @b wxMEDIABACKEND_QUICKTIME + + Use QuickTime. Mac Only. + WARNING: May not working correctly embedded in a wxNotebook. + + @b wxMEDIABACKEND_GSTREAMER + + Use GStreamer. Unix Only. Requires GStreamer 0.8 along + with at the very least the xvimagesink, xoverlay, and + gst-play modules of gstreamer to function. You need the correct + modules to play the relavant files, for example the mad module + to play mp3s, etc. + + @b wxMEDIABACKEND_WMP10 + + Uses Windows Media Player 10 (Windows only) - works on mobile + machines with Windows Media Player 10 and desktop machines with + either Windows Media Player 9 or 10 + + Note that other backends such as wxMEDIABACKEND_MCI can now be + found at wxCode. + */ + + + /** + , + wxPoint& + + @param pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0, + const wxString& szBackend = wxT(""), + const wxValidatorvalidator = wxDefaultValidator, + const wxString& name = wxPanelNameStr + ) + + Creates this control. Returns @false if it can't load the movie located at + fileName or it cannot load one of its native backends. + + If you specify a file to open via fileName and you don't specify a backend to + use, wxMediaCtrl tries each of its backends until one that can render the path referred to by fileName can be found. + + parent + parent of this control. Must not be @NULL. + @param id + id to use for events + @param fileName + If not empty, the path of a file to open. + @param pos + Position to put control at. + @param size + Size to put the control at and to stretch movie to. + @param style + Optional styles. + @param szBackend + Name of backend you want to use, leave blank to make + wxMediaCtrl figure it out. + @param validator + validator to use. + @param name + Window name. + */ + bool Create(wxWindow* parent, wxWindowID id) const; + + /** + Creating a backend for wxMediaCtrl is a rather simple process. Simply derive + from wxMediaBackendCommonBase and implement the methods you want. The methods + in wxMediaBackend correspond to those in wxMediaCtrl except for CreateControl + which does the actual creation of the control, in cases where a custom control + is not needed you may simply call wxControl::Create. + You need to make sure to use the DECLARE_CLASS and IMPLEMENT_CLASS macros. + The only real tricky part is that you need to make sure the file in compiled + in, which if there are just backends in there will not happen and you may need + to use a force link hack (see http://www.wxwidgets.org/wiki/index.php/RTTI). + This is a rather simple example of how to create a backend in the + wxActiveXContainer documentation. + */ + + + /** + Obtains the best size relative to the original/natural size of the + video, if there is any. See @ref overview_videosizewxmediactrl "Video size" + for more information. + */ + wxSize GetBestSize(); + + /** + Obtains the playback rate, or speed of the media. @c 1.0 represents normal + speed, while @c 2.0 represents twice the normal speed of the media, for + example. Not supported on the GStreamer (Unix) backend. + Returns 0 on failure. + */ + double GetPlaybackrate(); + + /** + Obtains the state the playback of the media is in - + + @b wxMEDIASTATE_STOPPED + + The movie has stopped. + + @b wxMEDIASTATE_PAUSED + + The movie is paused. + + @b wxMEDIASTATE_PLAYING + + The movie is currently playing. + */ + wxMediaCtrlState GetState(); + + /** + Gets the volume of the media from a 0.0 to 1.0 range. Note that due to rounding + and other errors this may not be the exact value sent to SetVolume. + */ + double GetVolume(); + + /** + Obtains the length - the total amount of time the movie has in milliseconds. + */ + wxFileOffset Length(); + + /** + Loads the location that @c uri refers to with the proxy @c proxy. Not + implemented on most backends so it should be called with caution. Returns @false if loading fails. + */ + bool Load(const wxURI& uri, const wxURI& proxy); + + /** + Same as @ref loaduri() Load. Kept for wxPython compatability. + */ + bool LoadURI(const wxURI& uri); + + /** + Same as @ref loaduriwithproxy() Load. Kept for wxPython compatability. + */ + bool LoadURIWithProxy(const wxURI& uri, const wxURI& proxy); + + /** + When wxMediaCtrl plays a file, it plays until the stop position + is reached (currently the end of the file/stream). Right before + it hits the end of the stream, it fires off a EVT_MEDIA_STOP + event to its parent window, at which point the event handler + can choose to veto the event, preventing the stream from actually + stopping. + Example: + + When wxMediaCtrl stops, either by the EVT_MEDIA_STOP not being + vetoed, or by manually calling + Stop(), where it actually + stops is not at the beginning, rather, but at the beginning of + the stream. That is, when it stops and play is called, playback + is gauranteed to start at the beginning of the media. This is + because some streams are not seekable, and when stop is called + on them they return to the beginning, thus wxMediaCtrl tries + to keep consistant for all types of media. + Note that when changing the state of the media through Play() + and other methods, the media may not actually be in the + wxMEDIASTATE_PLAYING, for example. If you are relying on the + media being in certain state catch the event relevant to the state. + See wxMediaEvent for the kinds of events + that you can catch. + */ + + + /** + Pauses playback of the movie. + */ + bool Pause(); + + /** + Resumes playback of the movie. + */ + bool Play(); + + /** + Normally, when you use wxMediaCtrl it is just a window for the video to + play in. However, some toolkits have their own media player interface. + For example, QuickTime generally has a bar below the video with a slider. + A special feature available to wxMediaCtrl, you can use the toolkit's interface + instead of + making your own by using the ShowPlayerControls() + function. There are several options for the flags parameter, with + the two general flags being wxMEDIACTRLPLAYERCONTROLS_NONE which turns off + the native interface, and wxMEDIACTRLPLAYERCONTROLS_DEFAULT which lets + wxMediaCtrl decide what native controls on the interface. Be sure to review + the caveats outlined in @ref overview_videosizewxmediactrl "Video size" before + doing so. + */ + + + /** + Depending upon the backend, wxMediaCtrl can render + and display pretty much any kind of media that the native system can - + such as an image, mpeg video, or mp3 (without license restrictions - + since it relies on native system calls that may not technically + have mp3 decoding available, for example, it falls outside the + realm of licensing restrictions). + For general operation, all you need to do is call + Load() to load the file + you want to render, catch the EVT_MEDIA_LOADED event, + and then call Play() + to show the video/audio of the media in that event. + More complex operations are generally more heavily dependant on the + capabilities of the backend. For example, QuickTime cannot set + the playback rate of certain streaming media - while DirectShow is + slightly more flexible in that regard. + */ + + + /** + Seeks to a position within the movie. + */ + wxFileOffset Seek(wxFileOffset where, wxSeekMode mode); + + /** + Sets the playback rate, or speed of the media, to that referred by @c dRate. + @c 1.0 represents normal speed, while @c 2.0 represents twice the normal + speed of the media, for example. Not supported on the GStreamer (Unix) backend. + Returns @true if successful. + */ + bool SetPlaybackRate(double dRate); + + /** + Sets the volume of the media from a 0.0 to 1.0 range to that referred + by @c dVolume. @c 1.0 represents full volume, while @c 0.5 + represents half (50 percent) volume, for example. Note that this may not be + exact due to conversion and rounding errors, although setting the volume to + full or none is always exact. Returns @true if successful. + */ + bool SetVolume(double dVolume); + + /** + A special feature to wxMediaCtrl. Applications using native toolkits such as + QuickTime usually have a scrollbar, play button, and more provided to + them by the toolkit. By default wxMediaCtrl does not do this. However, on + the directshow and quicktime backends you can show or hide the native controls + provided by the underlying toolkit at will using ShowPlayerControls. Simply + calling the function with default parameters tells wxMediaCtrl to use the + default controls provided by the toolkit. The function takes a + @c wxMediaCtrlPlayerControls enumeration as follows: + + @b wxMEDIACTRLPLAYERCONTROLS_NONE + + No controls. return wxMediaCtrl to it's default state. + + @b wxMEDIACTRLPLAYERCONTROLS_STEP + + Step controls like fastfoward, step one frame etc. + + @b wxMEDIACTRLPLAYERCONTROLS_VOLUME + + Volume controls like the speaker icon, volume slider, etc. + + @b wxMEDIACTRLPLAYERCONTROLS_DEFAULT + + Default controls for the toolkit. Currently a typedef for + wxMEDIACTRLPLAYERCONTROLS_STEP and wxMEDIACTRLPLAYERCONTROLS_VOLUME. + + For more see @ref overview_playercontrolswxmediactrl "Player controls". + Currently + only implemented on the QuickTime and DirectShow backends. The function + returns @true on success. + */ + bool ShowPlayerControls(wxMediaCtrlPlayerControls flags = wxMEDIACTRLPLAYERCONTROLS_DEFAULT); + + /** + Stops the media. + See Operation() for an overview of how + stopping works. + */ + bool Stop(); + + /** + Obtains the current position in time within the movie in milliseconds. + */ + wxFileOffset Tell(); + + /** + By default, wxMediaCtrl will scale the size of the video to the + requested amount passed to either it's constructor or Create(). + After calling Load or performing an equivilant operation, you + can subsequently obtain the "real" size of the video (if there + is any) by calling GetBestSize(). Note that the actual result + on the display will be slightly different when ShowPlayerControls + is activated and the actual video size will be less then + specified due to the extra controls provided by the native toolkit. + In addition, the backend may modify GetBestSize() to include the + size of the extra controls - so if you want the real size of the + video just disable ShowPlayerControls(). + The idea with setting GetBestSize to the size of the video is + that GetBestSize is a wxWindow-derived function that is called + when sizers on a window recalculate. What this means is that + if you use sizers by default the video will show in it's + original size without any extra assistance needed from the user. + */ +}; + diff --git a/interface/wx/memory.h b/interface/wx/memory.h new file mode 100644 index 0000000000..ec1fbed3de --- /dev/null +++ b/interface/wx/memory.h @@ -0,0 +1,295 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: memory.h +// Purpose: interface of wxDebugStreamBuf +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxDebugStreamBuf + @wxheader{memory.h} + + This class allows you to treat debugging output in a similar + (stream-based) fashion on different platforms. Under + Windows, an ostream constructed with this buffer outputs + to the debugger, or other program that intercepts debugging + output. On other platforms, the output goes to standard error (cerr). + + This is soon to be obsolete, replaced by wxLog functionality. + + @library{wxbase} + @category{FIXME} + + @see Overview() +*/ +class wxDebugStreamBuf +{ +public: + +}; + + + +/** + @class wxDebugContext + @wxheader{memory.h} + + A class for performing various debugging and memory tracing + operations. Full functionality (such as printing out objects + currently allocated) is only present in a debugging build of wxWidgets, + i.e. if the __WXDEBUG__ symbol is defined. wxDebugContext + and related functions and macros can be compiled out by setting + wxUSE_DEBUG_CONTEXT to 0 is setup.h + + @library{wxbase} + @category{debugging} + + @see Overview() +*/ +class wxDebugContext +{ +public: + /** + Checks the memory blocks for errors, starting from the currently set + checkpoint. + + @return Returns the number of errors, so a value of zero represents + success. Returns -1 if an error was detected that + prevents further checking. + */ + int Check(); + + /** + Performs a memory dump from the currently set checkpoint, writing to the + current debug stream. Calls the @b Dump member function for each wxObject + derived instance. + + @return @true if the function succeeded, @false otherwise. + */ + bool Dump(); + + /** + Returns @true if the memory allocator checks all previous memory blocks for + errors. + By default, this is @false since it slows down execution considerably. + + @see SetCheckPrevious() + */ + bool GetCheckPrevious(); + + /** + Returns @true if debug mode is on. If debug mode is on, the wxObject new and + delete + operators store or use information about memory allocation. Otherwise, + a straight malloc and free will be performed by these operators. + + @see SetDebugMode() + */ + bool GetDebugMode(); + + /** + Gets the debug level (default 1). The debug level is used by the wxTraceLevel + function and + the WXTRACELEVEL macro to specify how detailed the trace information is; setting + a different level will only have an effect if trace statements in the + application + specify a value other than one. + This is obsolete, replaced by wxLog functionality. + + @see SetLevel() + */ + int GetLevel(); + + /** + Returns the output stream associated with the debug context. + This is obsolete, replaced by wxLog functionality. + + @see SetStream() + */ + ostream GetStream(); + + /** + Returns a pointer to the output stream buffer associated with the debug context. + There may not necessarily be a stream buffer if the stream has been set + by the user. + This is obsolete, replaced by wxLog functionality. + */ + streambuf* GetStreamBuf(); + + /** + Returns @true if there is a stream currently associated + with the debug context. + This is obsolete, replaced by wxLog functionality. + + @see SetStream(), GetStream() + */ + bool HasStream(); + + /** + Prints a list of the classes declared in this application, giving derivation + and whether instances of this class can be dynamically created. + + @see PrintStatistics() + */ + bool PrintClasses(); + + /** + Performs a statistics analysis from the currently set checkpoint, writing + to the current debug stream. The number of object and non-object + allocations is printed, together with the total size. + + @param detailed + If @true, the function will also print how many + objects of each class have been allocated, and the space taken by + these class instances. + + @see PrintStatistics() + */ + bool PrintStatistics(bool detailed = true); + + /** + Tells the memory allocator to check all previous memory blocks for errors. + By default, this is @false since it slows down execution considerably. + + @see GetCheckPrevious() + */ + void SetCheckPrevious(bool check); + + /** + Sets the current checkpoint: Dump and PrintStatistics operations will + be performed from this point on. This allows you to ignore allocations + that have been performed up to this point. + + @param all + If @true, the checkpoint is reset to include all + memory allocations since the program started. + */ + void SetCheckpoint(bool all = false); + + /** + Sets the debug mode on or off. If debug mode is on, the wxObject new and delete + operators store or use information about memory allocation. Otherwise, + a straight malloc and free will be performed by these operators. + By default, debug mode is on if __WXDEBUG__ is defined. If the application + uses this function, it should make sure that all object memory allocated + is deallocated with the same value of debug mode. Otherwise, the + delete operator might try to look for memory information that does not + exist. + + @see GetDebugMode() + */ + void SetDebugMode(bool debug); + + /** + Sets the current debug file and creates a stream. This will delete any existing + stream and stream buffer. By default, the debug context stream + outputs to the debugger (Windows) or standard error (other platforms). + */ + bool SetFile(const wxString& filename); + + /** + Sets the debug level (default 1). The debug level is used by the wxTraceLevel + function and + the WXTRACELEVEL macro to specify how detailed the trace information is; setting + a different level will only have an effect if trace statements in the + application + specify a value other than one. + This is obsolete, replaced by wxLog functionality. + + @see GetLevel() + */ + void SetLevel(int level); + + /** + Installs a function to be called at the end of wxWidgets shutdown. It will be + called after + all files with global instances of wxDebugContextDumpDelayCounter have run + their destructors. + The shutdown function must be take no parameters and return nothing. + */ + void SetShutdownNotifyFunction(wxShutdownNotifyFunction func); + + /** + Sets the debugging stream to be the debugger (Windows) or standard error (other + platforms). + This is the default setting. The existing stream will be flushed and deleted. + This is obsolete, replaced by wxLog functionality. + */ + bool SetStandardError(); + + /** + Sets the stream and optionally, stream buffer associated with the debug context. + This operation flushes and deletes the existing stream (and stream buffer if + any). + This is obsolete, replaced by wxLog functionality. + + @param stream + Stream to associate with the debug context. Do not set this to @NULL. + @param streamBuf + Stream buffer to associate with the debug context. + */ + void SetStream(ostream* stream, streambuf* streamBuf = NULL); +}; + + + +// ============================================================================ +// Global functions/macros +// ============================================================================ + +/** @ingroup group_funcmacro_log */ +//@{ + +/** + @deprecated Use one of the wxLogTrace() functions or one of the + wxVLogTrace() functions instead. + + Calls wxTrace() with printf-style variable argument syntax. Output is + directed to the current output stream (see wxDebugContext). + + @header{wx/memory.h} +*/ +#define WXTRACE(format, ...) + +/** + @deprecated Use one of the wxLogTrace() functions or one of the + wxVLogTrace() functions instead. + + Calls wxTraceLevel with printf-style variable argument syntax. Output is + directed to the current output stream (see wxDebugContext). The first + argument should be the level at which this information is appropriate. It + will only be output if the level returned by wxDebugContext::GetLevel is + equal to or greater than this value. + + @header{wx/memory.h} +*/ +#define WXTRACELEVEL(level, format, ...) + +/** + @deprecated Use one of the wxLogTrace() functions or one of the + wxVLogTrace() functions instead. + + Takes printf-style variable argument syntax. Output is directed to the + current output stream (see wxDebugContext). + + @header{wx/memory.h} +*/ +void wxTrace(const wxString& format, ...); + +/** + @deprecated Use one of the wxLogTrace() functions or one of the + wxVLogTrace() functions instead. + + Takes @e printf() style variable argument syntax. Output is directed to the + current output stream (see wxDebugContext). The first argument should be + the level at which this information is appropriate. It will only be output + if the level returned by wxDebugContext::GetLevel() is equal to or greater + than this value. + + @header{wx/memory.h} +*/ +void wxTraceLevel(int level, const wxString& format, ...); + +//@} + diff --git a/interface/wx/menu.h b/interface/wx/menu.h new file mode 100644 index 0000000000..f19fc4ca04 --- /dev/null +++ b/interface/wx/menu.h @@ -0,0 +1,872 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: menu.h +// Purpose: interface of wxMenuBar +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxMenuBar + @wxheader{menu.h} + + A menu bar is a series of menus accessible from the top of a frame. + + @library{wxcore} + @category{menus} + + @see wxMenu, @ref overview_eventhandling "Event Handling Overview" +*/ +class wxMenuBar : public wxWindow +{ +public: + /** + Construct an empty menu barM + + @param style + If wxMB_DOCKABLE the menu bar can be detached (wxGTK only). + */ + wxMenuBar(long style = 0); + + /** + Construct a menu bar from arrays of menus and titles. + + @param n + The number of menus. + @param menus + An array of menus. Do not use this array again - it now belongs to + the menu bar. + @param titles + An array of title strings. Deallocate this array after creating + the menu bar. + @param style + If wxMB_DOCKABLE the menu bar can be detached (wxGTK only). + */ + wxMenuBar(size_t n, wxMenu* menus[], const wxString titles[], + long style = 0); + + /** + Destructor, destroying the menu bar and removing it from the parent frame (if + any). + */ + ~wxMenuBar(); + + /** + Adds the item to the end of the menu bar. + + @param menu + The menu to add. Do not deallocate this menu after calling Append. + @param title + The title of the menu. + + @return @true on success, @false if an error occurred. + + @see Insert() + */ + bool Append(wxMenu* menu, const wxString& title); + + /** + Checks or unchecks a menu item. + + @param id + The menu item identifier. + @param check + If @true, checks the menu item, otherwise the item is unchecked. + + @remarks Only use this when the menu bar has been associated with a + frame; otherwise, use the wxMenu equivalent call. + */ + void Check(int id, const bool check); + + /** + Enables or disables (greys out) a menu item. + + @param id + The menu item identifier. + @param enable + @true to enable the item, @false to disable it. + + @remarks Only use this when the menu bar has been associated with a + frame; otherwise, use the wxMenu equivalent call. + */ + void Enable(int id, const bool enable); + + /** + Enables or disables a whole menu. + + @param pos + The position of the menu, starting from zero. + @param enable + @true to enable the menu, @false to disable it. + + @remarks Only use this when the menu bar has been associated with a frame. + */ + void EnableTop(int pos, const bool enable); + + /** + Finds the menu item object associated with the given menu item identifier. + + @param id + Menu item identifier. + @param menu + If not @NULL, menu will get set to the associated menu. + + @return The found menu item object, or @NULL if one was not found. + */ + wxMenuItem* FindItem(int id, wxMenu menu = NULL) const; + + /** + Returns the index of the menu with the given @a title or @c wxNOT_FOUND if no + such menu exists in this menubar. The @a title parameter may specify either + the menu title (with accelerator characters, i.e. @c "File") or just the + menu label (@c "File") indifferently. + */ + int FindMenu(const wxString& title) const; + + /** + Finds the menu item id for a menu name/menu item string pair. + + @param menuString + Menu title to find. + @param itemString + Item to find. + + @return The menu item identifier, or wxNOT_FOUND if none was found. + + @remarks Any special menu codes are stripped out of source and target + strings before matching. + */ + int FindMenuItem(const wxString& menuString, + const wxString& itemString) const; + + /** + Gets the help string associated with the menu item identifier. + + @param id + The menu item identifier. + + @return The help string, or the empty string if there was no help string + or the menu item was not found. + + @see SetHelpString() + */ + wxString GetHelpString(int id) const; + + /** + Gets the label associated with a menu item. + + @param id + The menu item identifier. + + @return The menu item label, or the empty string if the item was not + found. + + @remarks Use only after the menubar has been associated with a frame. + */ + wxString GetLabel(int id) const; + + /** + Returns the label of a top-level menu. Note that the returned string does not + include the accelerator characters which could have been specified in the menu + title string during its construction. + + @param pos + Position of the menu on the menu bar, starting from zero. + + @return The menu label, or the empty string if the menu was not found. + + @remarks Use only after the menubar has been associated with a frame. + + @see SetLabelTop() + */ + wxString GetLabelTop(int pos) const; + + /** + Returns the menu at @a menuIndex (zero-based). + */ + wxMenu* GetMenu(int menuIndex) const; + + /** + Returns the number of menus in this menubar. + */ + size_t GetMenuCount() const; + + /** + Returns the label of a top-level menu. Note that the returned string + includes the accelerator characters that have been specified in the menu + title string during its construction. + + @param pos + Position of the menu on the menu bar, starting from zero. + + @return The menu label, or the empty string if the menu was not found. + + @remarks Use only after the menubar has been associated with a frame. + + @see GetMenuLabelText(), SetMenuLabel() + */ + wxString GetMenuLabel(int pos) const; + + /** + Returns the label of a top-level menu. Note that the returned string does not + include any accelerator characters that may have been specified in the menu + title string during its construction. + + @param pos + Position of the menu on the menu bar, starting from zero. + + @return The menu label, or the empty string if the menu was not found. + + @remarks Use only after the menubar has been associated with a frame. + + @see GetMenuLabel(), SetMenuLabel() + */ + wxString GetMenuLabelText(int pos) const; + + /** + Inserts the menu at the given position into the menu bar. Inserting menu at + position 0 will insert it in the very beginning of it, inserting at position + GetMenuCount() is the same as calling + Append(). + + @param pos + The position of the new menu in the menu bar + @param menu + The menu to add. wxMenuBar owns the menu and will free it. + @param title + The title of the menu. + + @return @true on success, @false if an error occurred. + + @see Append() + */ + bool Insert(size_t pos, wxMenu* menu, const wxString& title); + + /** + Determines whether an item is checked. + + @param id + The menu item identifier. + + @return @true if the item was found and is checked, @false otherwise. + */ + bool IsChecked(int id) const; + + /** + Determines whether an item is enabled. + + @param id + The menu item identifier. + + @return @true if the item was found and is enabled, @false otherwise. + */ + bool IsEnabled(int id) const; + + /** + Redraw the menu bar + */ + void Refresh(); + + /** + Removes the menu from the menu bar and returns the menu object - the caller is + responsible for deleting it. This function may be used together with + Insert() to change the menubar + dynamically. + + @see Replace() + */ + wxMenu* Remove(size_t pos); + + /** + Replaces the menu at the given position with another one. + + @param pos + The position of the new menu in the menu bar + @param menu + The menu to add. + @param title + The title of the menu. + + @return The menu which was previously at position pos. The caller is + responsible for deleting it. + + @see Insert(), Remove() + */ + wxMenu* Replace(size_t pos, wxMenu* menu, const wxString& title); + + /** + Sets the help string associated with a menu item. + + @param id + Menu item identifier. + @param helpString + Help string to associate with the menu item. + + @see GetHelpString() + */ + void SetHelpString(int id, const wxString& helpString); + + /** + Sets the label of a menu item. + + @param id + Menu item identifier. + @param label + Menu item label. + + @remarks Use only after the menubar has been associated with a frame. + + @see GetLabel() + */ + void SetLabel(int id, const wxString& label); + + /** + Sets the label of a top-level menu. + + @param pos + The position of a menu on the menu bar, starting from zero. + @param label + The menu label. + + @remarks Use only after the menubar has been associated with a frame. + + @see GetLabelTop() + */ + void SetLabelTop(int pos, const wxString& label); + + /** + Sets the label of a top-level menu. + + @param pos + The position of a menu on the menu bar, starting from zero. + @param label + The menu label. + + @remarks Use only after the menubar has been associated with a frame. + */ + void SetMenuLabel(int pos, const wxString& label); +}; + + + +/** + @class wxMenu + @wxheader{menu.h} + + A menu is a popup (or pull down) list of items, one of which may be + selected before the menu goes away (clicking elsewhere dismisses the + menu). Menus may be used to construct either menu bars or popup menus. + + A menu item has an integer ID associated with it which can be used to + identify the selection, or to change the menu item in some way. A menu item + with a special identifier -1 is a separator item and doesn't have an + associated command but just makes a separator line appear in the menu. + + @note Please note that @e wxID_ABOUT and @e wxID_EXIT are + predefined by wxWidgets and have a special meaning since entries + using these IDs will be taken out of the normal menus under MacOS X + and will be inserted into the system menu (following the appropriate + MacOS X interface guideline). On PalmOS @e wxID_EXIT is disabled according + to Palm OS Companion guidelines. + + Menu items may be either normal items, check items or radio items. Normal items + don't have any special properties while the check items have a boolean flag + associated to them and they show a checkmark in the menu when the flag is set. + wxWidgets automatically toggles the flag value when the item is clicked and its + value may be retrieved using either wxMenu::IsChecked method + of wxMenu or wxMenuBar itself or by using + wxEvent::IsChecked when you get the menu + notification for the item in question. + + The radio items are similar to the check items except that all the other items + in the same radio group are unchecked when a radio item is checked. The radio + group is formed by a contiguous range of radio items, i.e. it starts at the + first item of this kind and ends with the first item of a different kind (or + the end of the menu). Notice that because the radio groups are defined in terms + of the item positions inserting or removing the items in the menu containing + the radio items risks to not work correctly. Finally note that radio items + are not supported under Motif. + + @library{wxcore} + @category{menus} + + @see wxMenuBar, wxWindow::PopupMenu, + @ref overview_eventhandling "Event Handling Overview", + @ref wxFileHistory "wxFileHistory (most recently used files menu)" +*/ +class wxMenu : public wxEvtHandler +{ +public: + /** + Constructs a wxMenu object. + + @param style + If set to wxMENU_TEAROFF, the menu will be detachable (wxGTK only). + */ + wxMenu(long style); + + /** + Constructs a wxMenu object with a title + + @param title + Title at the top of the menu (not always supported). + @param style + If set to wxMENU_TEAROFF, the menu will be detachable (wxGTK only). + */ + wxMenu(const wxString& title = "", long style = 0); + + /** + Destructor, destroying the menu. + Note: under Motif, a popup menu must have a valid parent (the window + it was last popped up on) when being destroyed. Therefore, make sure + you delete or re-use the popup menu @e before destroying the + parent window. Re-use in this context means popping up the menu on + a different window from last time, which causes an implicit destruction + and recreation of internal data structures. + */ + ~wxMenu(); + + /** + Adds a menu item. + + @param id + The menu command identifier. + @param item + The string to appear on the menu item. + @param helpString + An optional help string associated with the item. + By default, the handler for the wxEVT_MENU_HIGHLIGHT event displays + this string in the status line. + @param kind + May be wxITEM_SEPARATOR, wxITEM_NORMAL, + wxITEM_CHECK or wxITEM_RADIO + + @see AppendSeparator(), AppendCheckItem(), AppendRadioItem(), + AppendSubMenu(), Insert(), SetLabel(), + GetHelpString(), SetHelpString(), wxMenuItem + */ + wxMenuItem* Append(int id, const wxString& item = wxEmptyString, + const wxString& helpString = wxEmptyString, + wxItemKind kind = wxITEM_NORMAL); + + /** + Adds a submenu. + + @deprecated This function is deprecated, use AppendSubMenu() instead. + + @param id + The menu command identifier. + @param item + The string to appear on the menu item. + @param subMenu + Pull-right submenu. + @param helpString + An optional help string associated with the item. + By default, the handler for the wxEVT_MENU_HIGHLIGHT event displays + this string in the status line. + + @see AppendSeparator(), AppendCheckItem(), AppendRadioItem(), + AppendSubMenu(), Insert(), SetLabel(), + GetHelpString(), SetHelpString(), wxMenuItem + */ + wxMenuItem* Append(int id, const wxString& item, + wxMenu* subMenu, + const wxString& helpString = wxEmptyString); + + /** + Adds a menu item object. This is the most generic variant of Append() method + because it may be used for both items (including separators) and submenus and + because you can also specify various extra properties of a menu item this way, + such as bitmaps and fonts. + + @param menuItem + A menuitem object. It will be owned by the wxMenu object after this function + is called, so do not delete it yourself. + + @see AppendSeparator(), AppendCheckItem(), AppendRadioItem(), + AppendSubMenu(), Insert(), SetLabel(), + GetHelpString(), SetHelpString(), wxMenuItem + */ + wxMenuItem* Append(wxMenuItem* menuItem); + + /** + Adds a checkable item to the end of the menu. + + @see Append(), InsertCheckItem() + */ + wxMenuItem* AppendCheckItem(int id, const wxString& item, + const wxString& helpString = ""); + + /** + Adds a radio item to the end of the menu. All consequent radio items form a + group and when an item in the group is checked, all the others are + automatically unchecked. + + @see Append(), InsertRadioItem() + */ + wxMenuItem* AppendRadioItem(int id, const wxString& item, + const wxString& helpString = ""); + + /** + Adds a separator to the end of the menu. + + @see Append(), InsertSeparator() + */ + wxMenuItem* AppendSeparator(); + + /** + Adds the given @a submenu to this menu. @a text is the text shown in the + menu for it and @a help is the help string shown in the status bar when the + submenu item is selected. + */ + wxMenuItem* AppendSubMenu(wxMenu* submenu, const wxString& text, + const wxString& help = wxEmptyString); + + /** + Inserts a break in a menu, causing the next appended item to appear in a new + column. + */ + void Break(); + + /** + Checks or unchecks the menu item. + + @param id + The menu item identifier. + @param check + If @true, the item will be checked, otherwise it will be unchecked. + + @see IsChecked() + */ + void Check(int id, const bool check); + + /** + Deletes the menu item from the menu. If the item is a submenu, it will + @b not be deleted. Use Destroy() if you want to delete a submenu. + + @param id + Id of the menu item to be deleted. + + @see FindItem(), Destroy(), Remove() + */ + void Delete(int id); + + /** + Deletes the menu item from the menu. If the item is a submenu, it will + @b not be deleted. Use Destroy() if you want to delete a submenu. + + @param item + Menu item to be deleted. + + @see FindItem(), Destroy(), Remove() + */ + void Delete(wxMenuItem* item); + + /** + Deletes the menu item from the menu. If the item is a submenu, it will + be deleted. Use Remove() if you want to keep the submenu (for example, + to reuse it later). + + @param id + Id of the menu item to be deleted. + + @see FindItem(), Deletes(), Remove() + */ + void Destroy(int id); + + /** + Deletes the menu item from the menu. If the item is a submenu, it will + be deleted. Use Remove() if you want to keep the submenu (for example, + to reuse it later). + + @param item + Menu item to be deleted. + + @see FindItem(), Deletes(), Remove() + */ + void Destroy(wxMenuItem* item); + + /** + Enables or disables (greys out) a menu item. + + @param id + The menu item identifier. + @param enable + @true to enable the menu item, @false to disable it. + + @see IsEnabled() + */ + void Enable(int id, const bool enable); + + /** + Finds the menu id for a menu item string. + + @param itemString + Menu item string to find. + + @return Menu item identifier, or wxNOT_FOUND if none is found. + + @remarks Any special menu codes are stripped out of source and target + strings before matching. + */ + int FindItem(const wxString& itemString) const; + + /** + Finds the menu item object associated with the given menu item identifier and, + optionally, the (sub)menu it belongs to. + + @param id + Menu item identifier. + @param menu + If the pointer is not @NULL, it will be filled with the item's + parent menu (if the item was found) + + @return Menu item object or NULL if none is found. + */ + const wxMenuItem * FindItem(int id, wxMenu** menu = NULL) const; + + /** + Returns the wxMenuItem given a position in the menu. + */ + wxMenuItem* FindItemByPosition(size_t position) const; + + /** + Returns the help string associated with a menu item. + + @param id + The menu item identifier. + + @return The help string, or the empty string if there is no help string + or the item was not found. + + @see SetHelpString(), Append() + */ + wxString GetHelpString(int id) const; + + /** + Returns a menu item label. + + @param id + The menu item identifier. + + @return The item label, or the empty string if the item was not found. + + @see GetLabelText(), SetLabel() + */ + wxString GetLabel(int id) const; + + /** + Returns a menu item label, without any of the original mnemonics and + accelerators. + + @param id + The menu item identifier. + + @return The item label, or the empty string if the item was not found. + + @see GetLabel(), SetLabel() + */ + wxString GetLabelText(int id) const; + + /** + Returns the number of items in the menu. + */ + size_t GetMenuItemCount() const; + + /** + Returns the list of items in the menu. wxMenuItemList is a pseudo-template + list class containing wxMenuItem pointers, see wxList. + */ + wxMenuItemList GetMenuItems() const; + + /** + Returns the title of the menu. + + @remarks This is relevant only to popup menus, use + wxMenuBar::GetMenuLabel for the menus in the menubar. + + @see SetTitle() + */ + wxString GetTitle() const; + + /** + Inserts the given @a item before the position @e pos. Inserting the item + at position GetMenuItemCount() is the same + as appending it. + + @see Append(), Prepend() + */ + wxMenuItem* Insert(size_t pos, wxMenuItem* item); + + /** + Inserts the given @a item before the position @e pos. Inserting the item + at position GetMenuItemCount() is the same + as appending it. + + @see Append(), Prepend() + */ + wxMenuItem* Insert(size_t pos, int id, + const wxString& item = "", + const wxString& helpString = "", + wxItemKind kind = wxITEM_NORMAL); + + /** + Inserts a checkable item at the given position. + + @see Insert(), AppendCheckItem() + */ + wxMenuItem* InsertCheckItem(size_t pos, int id, + const wxString& item, + const wxString& helpString = ""); + + /** + Inserts a radio item at the given position. + + @see Insert(), AppendRadioItem() + */ + wxMenuItem* InsertRadioItem(size_t pos, int id, + const wxString& item, + const wxString& helpString = ""); + + /** + Inserts a separator at the given position. + + @see Insert(), AppendSeparator() + */ + wxMenuItem* InsertSeparator(size_t pos); + + /** + Determines whether a menu item is checked. + + @param id + The menu item identifier. + + @return @true if the menu item is checked, @false otherwise. + + @see Check() + */ + bool IsChecked(int id) const; + + /** + Determines whether a menu item is enabled. + + @param id + The menu item identifier. + + @return @true if the menu item is enabled, @false otherwise. + + @see Enable() + */ + bool IsEnabled(int id) const; + + /** + Inserts the given @a item at position 0, i.e. before all the other + existing items. + + @see Append(), Insert() + */ + wxMenuItem* Prepend(wxMenuItem* item); + + /** + Inserts the given @a item at position 0, i.e. before all the other + existing items. + + @see Append(), Insert() + */ + wxMenuItem* Prepend(int id, const wxString& item = "", + const wxString& helpString = "", + wxItemKind kind = wxITEM_NORMAL); + + /** + Inserts a checkable item at position 0. + + @see Prepend(), AppendCheckItem() + */ + wxMenuItem* PrependCheckItem(int id, const wxString& item, + const wxString& helpString = ""); + + /** + Inserts a radio item at position 0. + + @see Prepend(), AppendRadioItem() + */ + wxMenuItem* PrependRadioItem(int id, const wxString& item, + const wxString& helpString = ""); + + /** + Inserts a separator at position 0. + + @see Prepend(), AppendSeparator() + */ + wxMenuItem* PrependSeparator(); + + /** + Removes the menu item from the menu but doesn't delete the associated C++ + object. This allows you to reuse the same item later by adding it back to the menu + (especially useful with submenus). + + @param id + The identifier of the menu item to remove. + + @return A pointer to the item which was detached from the menu. + */ + wxMenuItem* Remove(int id); + + /** + Removes the menu item from the menu but doesn't delete the associated C++ + object. This allows you to reuse the same item later by adding it back to the menu + (especially useful with submenus). + + @param item + The menu item to remove. + + @return A pointer to the item which was detached from the menu. + */ + wxMenuItem* Remove(wxMenuItem* item); + + /** + Sets an item's help string. + + @param id + The menu item identifier. + @param helpString + The help string to set. + + @see GetHelpString() + */ + void SetHelpString(int id, const wxString& helpString); + + /** + Sets the label of a menu item. + + @param id + The menu item identifier. + @param label + The menu item label to set. + + @see Append(), GetLabel() + */ + void SetLabel(int id, const wxString& label); + + /** + Sets the title of the menu. + + @param title + The title to set. + + @remarks This is relevant only to popup menus, use + wxMenuBar::SetLabelTop for the menus in the menubar. + + @see GetTitle() + */ + void SetTitle(const wxString& title); + + /** + Sends events to @a source (or owning window if @NULL) to update the + menu UI. This is called just before the menu is popped up with + wxWindow::PopupMenu, but + the application may call it at other times if required. + */ + void UpdateUI(wxEvtHandler* source = NULL) const; +}; + diff --git a/interface/wx/menuitem.h b/interface/wx/menuitem.h new file mode 100644 index 0000000000..f9372b5b7c --- /dev/null +++ b/interface/wx/menuitem.h @@ -0,0 +1,281 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: menuitem.h +// Purpose: interface of wxMenuItem +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxMenuItem + @wxheader{menuitem.h} + + A menu item represents an item in a menu. Note that you usually don't have to + deal with it directly as wxMenu methods usually construct an + object of this class for you. + + Also please note that the methods related to fonts and bitmaps are currently + only implemented for Windows and GTK+. + + @library{wxcore} + @category{menus} + + @see wxMenuBar, wxMenu +*/ +class wxMenuItem : public wxObject +{ +public: + /** + Constructs a wxMenuItem object. + Menu items can be standard, or "stock menu items", or custom. For the + standard menu items (such as commands to open a file, exit the program and so + on, see @ref page_stockitems "Stock Items" for the full list) it is enough + to specify just the stock ID and leave @a text and @a helpString empty. In + fact, leaving at least @a text empty for the stock menu items is strongly + recommended as they will have appearance and keyboard interface (including + standard accelerators) familiar to the user. + For the custom (non-stock) menu items, @a text must be specified and while + @a helpString may be left empty, it's recommended to pass the item + description (which is automatically shown by the library in the status bar when + the menu item is selected) in this parameter. + Finally note that you can e.g. use a stock menu label without using its stock + help string; that is, stock properties are set independently one from the other. + + @param parentMenu + Menu that the menu item belongs to. Can be @NULL if the item is + going to be added to the menu later. + @param id + Identifier for this menu item. May be @c wxID_SEPARATOR, in which + case the given kind is ignored and taken to be @c wxITEM_SEPARATOR + instead. + @param text + Text for the menu item, as shown on the menu. An accelerator + key can be specified using the ampersand " character. In order to embed an + ampersand character in the menu item text, the ampersand must be doubled. + @param helpString + Optional help string that will be shown on the status bar. + @param kind + May be @c wxITEM_SEPARATOR, @c wxITEM_NORMAL, @c wxITEM_CHECK or @c + wxITEM_RADIO + @param subMenu + If non-@NULL, indicates that the menu item is a submenu. + */ + wxMenuItem(wxMenu* parentMenu = NULL, int id = wxID_SEPARATOR, + const wxString& text = "", + const wxString& helpString = "", + wxItemKind kind = wxITEM_NORMAL, + wxMenu* subMenu = NULL); + + /** + Destructor. + */ + ~wxMenuItem(); + + /** + Checks or unchecks the menu item. + Note that this only works when the item is already appended to a menu. + */ + void Check(bool check = true); + + /** + Enables or disables the menu item. + */ + void Enable(bool enable = true); + + /** + Returns the background colour associated with the menu item (Windows only). + */ + wxColour GetBackgroundColour() const; + + /** + Returns the checked or unchecked bitmap (Windows only). + */ + wxBitmap GetBitmap(bool checked = true) const; + + /** + Returns the font associated with the menu item (Windows only). + */ + wxFont GetFont() const; + + /** + Returns the help string associated with the menu item. + */ + wxString GetHelp() const; + + /** + Returns the menu item identifier. + */ + int GetId() const; + + /** + Returns the text associated with the menu item including any accelerator + characters that were passed to the constructor or SetItemLabel. + + @see GetItemLabelText(), GetLabelText() + */ + wxString GetItemLabel() const; + + /** + Returns the text associated with the menu item, without any accelerator + characters. + + @see GetItemLabel(), GetLabelText() + */ + wxString GetItemLabelText() const; + + /** + Returns the item kind, one of @c wxITEM_SEPARATOR, @c wxITEM_NORMAL, + @c wxITEM_CHECK or @c wxITEM_RADIO. + */ + wxItemKind GetKind() const; + + /** + Returns the text associated with the menu item without any accelerator + characters it might contain. + @deprecated This function is deprecated in favour of GetItemLabelText(). + @see GetText(), GetLabelFromText() + */ + wxString GetLabel() const; + + /** + @deprecated This function is deprecated; please use GetLabelText() instead. + @see GetText(), GetLabel() + */ + static wxString GetLabelFromText(const wxString& text); + + /** + Strips all accelerator characters and mnemonics from the given @e text. + For example: + + @code + wxMenuItem::GetLabelfromText( "&Hello\tCtrl-h"); + @endcode + + will return just @c "Hello". + + @see GetItemLabelText(), GetItemLabel() + */ + static wxString GetLabelText(const wxString& text); + + /** + Gets the width of the menu item checkmark bitmap (Windows only). + */ + int GetMarginWidth() const; + + /** + Returns the menu this menu item is in, or @NULL if this menu item is not + attached. + */ + wxMenu* GetMenu() const; + + /** + Returns the text associated with the menu item. + @deprecated This function is deprecated. Please use + GetItemLabel() or GetItemLabelText() instead. + */ + wxString GetName() const; + + /** + Returns the submenu associated with the menu item, or @NULL if there isn't one. + */ + wxMenu* GetSubMenu() const; + + /** + Returns the text associated with the menu item, such as it was passed to the + wxMenuItem constructor, i.e. with any accelerator characters it may contain. + @deprecated This function is deprecated in favour of GetItemLabel(). + @see GetLabel(), GetLabelFromText() + */ + wxString GetText() const; + + /** + Returns the text colour associated with the menu item (Windows only). + */ + wxColour GetTextColour() const; + + /** + Returns @true if the item is checkable. + */ + bool IsCheckable() const; + + /** + Returns @true if the item is checked. + */ + bool IsChecked() const; + + /** + Returns @true if the item is enabled. + */ + bool IsEnabled() const; + + /** + Returns @true if the item is a separator. + */ + bool IsSeparator() const; + + /** + Returns @true if the item is a submenu. + */ + bool IsSubMenu() const; + + /** + Sets the background colour associated with the menu item (Windows only). + */ + void SetBackgroundColour(const wxColour& colour) const; + + /** + Sets the bitmap for the menu item (Windows and GTK+ only). It is + equivalent to wxMenuItem::SetBitmaps(bmp, wxNullBitmap). + */ + void SetBitmap(const wxBitmap& bmp); + + /** + Sets the checked/unchecked bitmaps for the menu item (Windows only). The first + bitmap + is also used as the single bitmap for uncheckable menu items. + */ + void SetBitmaps(const wxBitmap& checked, + const wxBitmap& unchecked = wxNullBitmap); + + /** + Sets the font associated with the menu item (Windows only). + */ + void SetFont(const wxFont& font); + + /** + Sets the help string. + */ + void SetHelp(const wxString& helpString); + + /** + Sets the label associated with the menu item. + */ + void SetItemLabel(const wxString& label); + + /** + Sets the width of the menu item checkmark bitmap (Windows only). + */ + void SetMarginWidth(int width) const; + + /** + Sets the parent menu which will contain this menu item. + */ + void SetMenu(const wxMenu* menu); + + /** + Sets the submenu of this menu item. + */ + void SetSubMenu(const wxMenu* menu); + + /** + Sets the text associated with the menu item. + @deprecated This function is deprecated in favour of SetItemLabel(). + */ + void SetText(const wxString& text); + + /** + Sets the text colour associated with the menu item (Windows only). + */ + void SetTextColour(const wxColour& colour); +}; + diff --git a/interface/wx/metafile.h b/interface/wx/metafile.h new file mode 100644 index 0000000000..f994f22cec --- /dev/null +++ b/interface/wx/metafile.h @@ -0,0 +1,156 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: metafile.h +// Purpose: interface of wxMetafileDC +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxMetafileDC + @wxheader{metafile.h} + + This is a type of device context that allows a metafile object to be + created (Windows only), and has most of the characteristics of a normal + @b wxDC. The wxMetafileDC::Close member must be called after drawing into the + device context, to return a metafile. The only purpose for this at + present is to allow the metafile to be copied to the clipboard (see wxMetafile). + + Adding metafile capability to an application should be easy if you + already write to a wxDC; simply pass the wxMetafileDC to your drawing + function instead. You may wish to conditionally compile this code so it + is not compiled under X (although no harm will result if you leave it + in). + + Note that a metafile saved to disk is in standard Windows metafile format, + and cannot be imported into most applications. To make it importable, + call the function ::wxMakeMetafilePlaceable after + closing your disk-based metafile device context. + + @library{wxcore} + @category{dc} + + @see wxMetafile, wxDC +*/ +class wxMetafileDC : public wxDC +{ +public: + /** + Constructor. If no filename is passed, the metafile is created + in memory. + */ + wxMetafileDC(const wxString& filename = ""); + + /** + Destructor. + */ + ~wxMetafileDC(); + + /** + This must be called after the device context is finished with. A + metafile is returned, and ownership of it passes to the calling + application (so it should be destroyed explicitly). + */ + wxMetafile* Close(); +}; + + + +/** + @class wxMetafile + @wxheader{metafile.h} + + A @b wxMetafile represents the MS Windows metafile object, so metafile + operations have no effect in X. In wxWidgets, only sufficient functionality + has been provided for copying a graphic to the clipboard; this may be extended + in a future version. Presently, the only way of creating a metafile + is to use a wxMetafileDC. + + @library{wxcore} + @category{FIXME} + + @see wxMetafileDC +*/ +class wxMetafile : public wxObject +{ +public: + /** + Constructor. If a filename is given, the Windows disk metafile is + read in. Check whether this was performed successfully by + using the @ref isok() wxMetafile:IsOk member. + */ + wxMetafile(const wxString& filename = ""); + + /** + Destructor. + See @ref overview_refcountdestruct "reference-counted object destruction" for + more info. + */ + ~wxMetafile(); + + /** + Returns @true if the metafile is valid. + */ + bool Ok(); + + /** + Plays the metafile into the given device context, returning + @true if successful. + */ + bool Play(wxDC* dc); + + /** + Passes the metafile data to the clipboard. The metafile can no longer be + used for anything, but the wxMetafile object must still be destroyed by + the application. + Below is a example of metafile, metafile device context and clipboard use + from the @c hello.cpp example. Note the way the metafile dimensions + are passed to the clipboard, making use of the device context's ability + to keep track of the maximum extent of drawing commands. + */ + bool SetClipboard(int width = 0, int height = 0); +}; + + + +// ============================================================================ +// Global functions/macros +// ============================================================================ + +/** @ingroup group_funcmacro_gdi */ +//@{ + +/** + Given a filename for an existing, valid metafile (as constructed using + wxMetafileDC) makes it into a placeable metafile by prepending a header + containing the given bounding box. The bounding box may be obtained from a + device context after drawing into it, using the functions wxDC::MinX(), + wxDC::MinY(), wxDC::MaxX() and wxDC::MaxY(). + + In addition to adding the placeable metafile header, this function adds the + equivalent of the following code to the start of the metafile data: + + @code + SetMapMode(dc, MM_ANISOTROPIC); + SetWindowOrg(dc, minX, minY); + SetWindowExt(dc, maxX - minX, maxY - minY); + @endcode + + This simulates the wxMM_TEXT mapping mode, which wxWidgets assumes. + + Placeable metafiles may be imported by many Windows applications, and can + be used in RTF (Rich Text Format) files. + + @a scale allows the specification of scale for the metafile. + + This function is only available under Windows. + + @header{wx/metafile.h} +*/ +bool wxMakeMetafilePlaceable(const wxString& filename, + int minX, int minY, + int maxX, int maxY, + float scale = 1.0); + +//@} + diff --git a/interface/wx/mimetype.h b/interface/wx/mimetype.h new file mode 100644 index 0000000000..3e753b05f0 --- /dev/null +++ b/interface/wx/mimetype.h @@ -0,0 +1,344 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: mimetype.h +// Purpose: interface of wxMimeTypesManager +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxMimeTypesManager + @wxheader{mimetype.h} + + This class allows the application to retrieve the information about all known + MIME types from a system-specific location and the filename extensions to the + MIME types and vice versa. After initialization the functions + wxMimeTypesManager::GetFileTypeFromMimeType + and wxMimeTypesManager::GetFileTypeFromExtension + may be called: they will return a wxFileType object which + may be further queried for file description, icon and other attributes. + + @b Windows: MIME type information is stored in the registry and no additional + initialization is needed. + + @b Unix: MIME type information is stored in the files mailcap and mime.types + (system-wide) and .mailcap and .mime.types in the current user's home directory: + all of these files are searched for and loaded if found by default. However, + additional functions + wxMimeTypesManager::ReadMailcap and + wxMimeTypesManager::ReadMimeTypes are + provided to load additional files. + + If GNOME or KDE desktop environment is installed, then wxMimeTypesManager + gathers MIME information from respective files (e.g. .kdelnk files under KDE). + + @note Currently, wxMimeTypesManager is limited to reading MIME type information + but it will support modifying it as well in future versions. + + @library{wxbase} + @category{misc} + + @see wxFileType +*/ +class wxMimeTypesManager +{ +public: + /** + Constructor puts the object in the "working" state, no additional initialization + are needed - but @ref init() ReadXXX may be used to load + additional mailcap/mime.types files. + */ + wxMimeTypesManager(); + + /** + Destructor is not virtual, so this class should not be derived from. + */ + ~wxMimeTypesManager(); + + /** + This function may be used to provide hard-wired fallbacks for the MIME types + and extensions that might not be present in the system MIME database. + Please see the typetest sample for an example of using it. + */ + void AddFallbacks(const wxFileTypeInfo* fallbacks); + + /** + @note You won't normally need to use more than one wxMimeTypesManager object in a + program. + @ref ctor() wxMimeTypesManager + + @ref dtor() ~wxMimeTypesManager + */ + + + /** + Gather information about the files with given extension and return the + corresponding wxFileType object or @NULL if the extension + is unknown. + The @a extension parameter may have, or not, the leading dot, if it has it, + it is stripped automatically. It must not however be empty. + */ + wxFileType* GetFileTypeFromExtension(const wxString& extension); + + /** + Gather information about the files with given MIME type and return the + corresponding wxFileType object or @NULL if the MIME type + is unknown. + */ + wxFileType* GetFileTypeFromMimeType(const wxString& mimeType); + + /** + All of these functions are static (i.e. don't need a wxMimeTypesManager object + to call them) and provide some useful operations for string representations of + MIME types. Their usage is recommended instead of directly working with MIME + types using wxString functions. + IsOfType() + */ + + + /** + @b Unix: These functions may be used to load additional files (except for the + default ones which are loaded automatically) containing MIME + information in either mailcap(5) or mime.types(5) format. + ReadMailcap() + + ReadMimeTypes() + + AddFallbacks() + */ + + + /** + This function returns @true if either the given @a mimeType is exactly the + same as @a wildcard or if it has the same category and the subtype of + @a wildcard is '*'. Note that the '*' wildcard is not allowed in + @a mimeType itself. + The comparison don by this function is case insensitive so it is not + necessary to convert the strings to the same case before calling it. + */ + bool IsOfType(const wxString& mimeType, const wxString& wildcard); + + /** + These functions are the heart of this class: they allow to find a @ref + overview_wxfiletype "file type" object + from either file extension or MIME type. + If the function is successful, it returns a pointer to the wxFileType object + which @b must be deleted by the caller, otherwise @NULL will be returned. + GetFileTypeFromMimeType() + + GetFileTypeFromExtension() + */ + + + /** + Load additional file containing information about MIME types and associated + information in mailcap format. See metamail(1) and mailcap(5) for more + information. + @a fallback parameter may be used to load additional mailcap files without + overriding the settings found in the standard files: normally, entries from + files loaded with ReadMailcap will override the entries from files loaded + previously (and the standard ones are loaded in the very beginning), but this + will not happen if this parameter is set to @true (default is @false). + The return value is @true if there were no errors in the file or @false + otherwise. + */ + bool ReadMailcap(const wxString& filename, bool fallback = false); + + /** + Load additional file containing information about MIME types and associated + information in mime.types file format. See metamail(1) and mailcap(5) for more + information. + The return value is @true if there were no errors in the file or @false + otherwise. + */ + bool ReadMimeTypes(const wxString& filename); +}; + + + +/** + @class wxFileType + @wxheader{mimetype.h} + + This class holds information about a given @e file type. File type is the same + as + MIME type under Unix, but under Windows it corresponds more to an extension than + to MIME type (in fact, several extensions may correspond to a file type). This + object may be created in several different ways: the program might know the file + extension and wish to find out the corresponding MIME type or, conversely, it + might want to find the right extension for the file to which it writes the + contents of given MIME type. Depending on how it was created some fields may be + unknown so the return value of all the accessors @b must be checked: @false + will be returned if the corresponding information couldn't be found. + + The objects of this class are never created by the application code but are + returned by wxMimeTypesManager::GetFileTypeFromMimeType and + wxMimeTypesManager::GetFileTypeFromExtension methods. + But it is your responsibility to delete the returned pointer when you're done + with it! + + A brief reminder about what the MIME types are (see the RFC 1341 for more + information): basically, it is just a pair category/type (for example, + "text/plain") where the category is a basic indication of what a file is. + Examples of categories are "application", "image", "text", "binary", and + type is a precise definition of the document format: "plain" in the example + above means just ASCII text without any formatting, while "text/html" is the + HTML document source. + + A MIME type may have one or more associated extensions: "text/plain" will + typically correspond to the extension ".txt", but may as well be associated with + ".ini" or ".conf". + + @library{wxbase} + @category{FIXME} + + @see wxMimeTypesManager +*/ +class wxFileType +{ +public: + /** + The default constructor is private because you should never create objects of + this type: they are only returned by wxMimeTypesManager methods. + */ + wxFileType(); + + /** + The destructor of this class is not virtual, so it should not be derived from. + */ + ~wxFileType(); + + /** + This function is primarily intended for GetOpenCommand and GetPrintCommand + usage but may be also used by the application directly if, for example, you want + to use some non-default command to open the file. + The function replaces all occurrences of + + format specification + + with + + %s + + the full file name + + %t + + the MIME type + + %{param} + + the value of the parameter @e param + + using the MessageParameters object you pass to it. + If there is no '%s' in the command string (and the string is not empty), it is + assumed that the command reads the data on stdin and so the effect is the same + as " %s" were appended to the string. + Unlike all other functions of this class, there is no error return for this + function. + */ + static wxString ExpandCommand(const wxString& command, + MessageParameters& params); + + /** + If the function returns @true, the string pointed to by @a desc is filled + with a brief description for this file type: for example, "text document" for + the "text/plain" MIME type. + */ + bool GetDescription(wxString* desc); + + /** + If the function returns @true, the array @a extensions is filled + with all extensions associated with this file type: for example, it may + contain the following two elements for the MIME type "text/html" (notice the + absence of the leading dot): "html" and "htm". + @b Windows: This function is currently not implemented: there is no + (efficient) way to retrieve associated extensions from the given MIME type on + this platform, so it will only return @true if the wxFileType object was + created + by wxMimeTypesManager::GetFileTypeFromExtension + function in the first place. + */ + bool GetExtensions(wxArrayString& extensions); + + /** + If the function returns @true, the @c iconLoc is filled with the + location of the icon for this MIME type. A wxIcon may be + created from @a iconLoc later. + @b Windows: The function returns the icon shown by Explorer for the files of + the specified type. + @b Mac: This function is not implemented and always returns @false. + @b Unix: MIME manager gathers information about icons from GNOME + and KDE settings and thus GetIcon's success depends on availability + of these desktop environments. + */ + bool GetIcon(wxIconLocation* iconLoc); + + /** + If the function returns @true, the string pointed to by @a mimeType is filled + with full MIME type specification for this file type: for example, "text/plain". + */ + bool GetMimeType(wxString* mimeType); + + /** + Same as GetMimeType() but returns array of MIME + types. This array will contain only one item in most cases but sometimes, + notably under Unix with KDE, may contain more MIME types. This happens when + one file extension is mapped to different MIME types by KDE, mailcap and + mime.types. + */ + bool GetMimeType(wxArrayString& mimeTypes); + + //@{ + /** + With the first version of this method, if the @true is returned, the + string pointed to by @a command is filled with the command which must be + executed (see wxExecute()) in order to open the file of the + given type. In this case, the name of the file as well as any other parameters + is retrieved from MessageParameters() + class. + In the second case, only the filename is specified and the command to be used + to open this kind of file is returned directly. An empty string is returned to + indicate that an error occurred (typically meaning that there is no standard way + to open this kind of files). + */ + bool GetOpenCommand(wxString* command, + MessageParameters& params); + wxString GetOpenCommand(const wxString& filename); + //@} + + /** + If the function returns @true, the string pointed to by @a command is filled + with the command which must be executed (see wxExecute()) in + order to print the file of the given type. The name of the file is + retrieved from MessageParameters() class. + */ + bool GetPrintCommand(wxString* command, + MessageParameters& params); + + /** + One of the most common usages of MIME is to encode an e-mail message. The MIME + type of the encoded message is an example of a @e message parameter. These + parameters are found in the message headers ("Content-XXX"). At the very least, + they must specify the MIME type and the version of MIME used, but almost always + they provide additional information about the message such as the original file + name or the charset (for the text documents). + These parameters may be useful to the program used to open, edit, view or print + the message, so, for example, an e-mail client program will have to pass them to + this program. Because wxFileType itself can not know about these parameters, + it uses MessageParameters class to query them. The default implementation only + requires the caller to provide the file name (always used by the program to be + called - it must know which file to open) and the MIME type and supposes that + there are no other parameters. If you wish to supply additional parameters, you + must derive your own class from MessageParameters and override GetParamValue() + function, for example: + + Now you only need to create an object of this class and pass it to, for example, + GetOpenCommand() like this: + + @b Windows: As only the file name is used by the program associated with the + given extension anyhow (but no other message parameters), there is no need to + ever derive from MessageParameters class for a Windows-only program. + */ +}; + diff --git a/interface/wx/minifram.h b/interface/wx/minifram.h new file mode 100644 index 0000000000..c11b24e602 --- /dev/null +++ b/interface/wx/minifram.h @@ -0,0 +1,112 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: minifram.h +// Purpose: interface of wxMiniFrame +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxMiniFrame + @wxheader{minifram.h} + + A miniframe is a frame with a small title bar. It is suitable for floating + toolbars that must not + take up too much screen area. + + An example of mini frame can be seen in the @ref overview_sampledialogs + "dialogs sample" + using the "Mini frame" command of the "Generic dialogs" submenu. + + @beginStyleTable + @style{wxICONIZE} + Display the frame iconized (minimized) (Windows only). + @style{wxCAPTION} + Puts a caption on the frame. + @style{wxMINIMIZE} + Identical to wxICONIZE. + @style{wxMINIMIZE_BOX} + Displays a minimize box on the frame (Windows and Motif only). + @style{wxMAXIMIZE} + Displays the frame maximized (Windows only). + @style{wxMAXIMIZE_BOX} + Displays a maximize box on the frame (Windows and Motif only). + @style{wxCLOSE_BOX} + Displays a close box on the frame. + @style{wxSTAY_ON_TOP} + Stay on top of other windows (Windows only). + @style{wxSYSTEM_MENU} + Displays a system menu (Windows and Motif only). + @style{wxTINY_CAPTION_HORIZ} + This style is obsolete and not used any longer. + @style{wxTINY_CAPTION_VERT} + This style is obsolete and not used any longer. + @style{wxRESIZE_BORDER} + Displays a resizeable border around the window. + @endStyleTable + + @library{wxcore} + @category{managedwnd} + + @see wxMDIParentFrame, wxMDIChildFrame, wxFrame, wxDialog +*/ +class wxMiniFrame : public wxFrame +{ +public: + //@{ + /** + Constructor, creating the window. + + @param parent + 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. + @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. + @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 wxMiniFrame. + @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 + individual windows. + + @remarks The frame behaves like a normal frame on non-Windows platforms. + + @see Create() + */ + wxMiniFrame(); + wxMiniFrame(wxWindow* parent, wxWindowID id, + const wxString& title, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxCAPTION | wxRESIZE_BORDER, + const wxString& name = "frame"); + //@} + + /** + Destructor. Destroys all child windows and menu bar if present. + */ + ~wxMiniFrame(); + + /** + Used in two-step frame construction. See wxMiniFrame() + for further details. + */ + bool Create(wxWindow* parent, wxWindowID id, + const wxString& title, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxCAPTION | wxRESIZE_BORDER, + const wxString& name = "frame"); +}; + diff --git a/interface/wx/module.h b/interface/wx/module.h new file mode 100644 index 0000000000..ec801b608e --- /dev/null +++ b/interface/wx/module.h @@ -0,0 +1,126 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: module.h +// Purpose: interface of wxModule +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxModule + @wxheader{module.h} + + The module system is a very simple mechanism to allow applications (and parts + of wxWidgets itself) to define initialization and cleanup functions that are + automatically called on wxWidgets startup and exit. + + To define a new kind of module, derive a class from wxModule, override the + wxModule::OnInit and wxModule::OnExit + functions, and add the DECLARE_DYNAMIC_CLASS and IMPLEMENT_DYNAMIC_CLASS to + header and implementation files (which can be the same file). On + initialization, wxWidgets will find all classes derived from wxModule, create + an instance of each, and call each OnInit function. On exit, wxWidgets will + call the OnExit function for each module instance. + + Note that your module class does not have to be in a header file. + + For example: + + @code + // A module to allow DDE initialization/cleanup + // without calling these functions from app.cpp or from + // the user's application. + class wxDDEModule: public wxModule + { + public: + wxDDEModule() { } + virtual bool OnInit() { wxDDEInitialize(); return @true; }; + virtual void OnExit() { wxDDECleanUp(); }; + + private: + DECLARE_DYNAMIC_CLASS(wxDDEModule) + }; + + IMPLEMENT_DYNAMIC_CLASS(wxDDEModule, wxModule) + + // Another module which uses DDE in its OnInit() + class MyModule: public wxModule + { + public: + MyModule() { AddDependency(CLASSINFO(wxDDEModule)); } + virtual bool OnInit() { ... code using DDE ... } + virtual void OnExit() { ... } + + private: + DECLARE_DYNAMIC_CLASS(MyModule) + }; + + IMPLEMENT_DYNAMIC_CLASS(MyModule, wxModule) + + // Another module which uses DDE in its OnInit() + // but uses a named dependency + class MyModule2: public wxModule + { + public: + MyModule2() { AddDependency("wxDDEModule"); } + virtual bool OnInit() { ... code using DDE ... } + virtual void OnExit() { ... } + + private: + DECLARE_DYNAMIC_CLASS(MyModule2) + }; + + IMPLEMENT_DYNAMIC_CLASS(MyModule2, wxModule) + @endcode + + @library{wxbase} + @category{FIXME} +*/ +class wxModule : public wxObject +{ +public: + /** + Constructs a wxModule object. + */ + wxModule(); + + /** + Destructor. + */ + ~wxModule(); + + //@{ + /** + Call this function from the constructor of the derived class. @a dep must be + the CLASSINFO() of a wxModule-derived class and the + corresponding module will be loaded before and unloaded after + this module. + The second version of this function allows a dependency to be added by + name without access to the class info. This is useful when a module is + declared entirely in a source file and there is no header for the declaration + of the module needed by CLASSINFO(), however errors are + not detected until run-time, instead of compile-time, then. + Note that circular dependencies are detected and result in a fatal error. + + @param dep + The class information object for the dependent module. + @param classname + The class name of the dependent module. + */ + void AddDependency(wxClassInfo* dep); + void AddDependency(const char* classname); + //@} + + /** + Provide this function with appropriate cleanup for your module. + */ + virtual void OnExit(); + + /** + Provide this function with appropriate initialization for your module. If the + function + returns @false, wxWidgets will exit immediately. + */ + virtual bool OnInit(); +}; + diff --git a/interface/wx/msgdlg.h b/interface/wx/msgdlg.h new file mode 100644 index 0000000000..197224859b --- /dev/null +++ b/interface/wx/msgdlg.h @@ -0,0 +1,204 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: msgdlg.h +// Purpose: interface of wxMessageDialog +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxMessageDialog + @wxheader{msgdlg.h} + + This class represents a dialog that shows a single or multi-line message, + with a choice of OK, Yes, No and Cancel buttons. + + @library{wxcore} + @category{cmndlg} + + @see @ref overview_wxmessagedialogoverview "wxMessageDialog overview" +*/ +class wxMessageDialog : public wxDialog +{ +public: + /** + Constructor specifying the message box properties. + + Use ShowModal() to show the dialog. + + @a style may be a bit list of the following identifiers: + + @beginStyleTable + @style{wxOK} + Puts an Ok button in the message box. May be combined with @c + wxCANCEL. + @style{wxCANCEL} + Puts a Cancel button in the message box. Must be combined with + either @c wxOK or @c wxYES_NO. + @style{wxYES_NO} + Puts Yes and No buttons in the message box. May be combined with + @c wxCANCEL. + @style{wxNO_DEFAULT} + Makes the "No" button default, can only be used with @c wxYES_NO. + @style{wxYES_DEFAULT} + Makes the "Yes" button default, this is the default behaviour and + this flag exists solely for symmetry with @c wxNO_DEFAULT. + @style{wxICON_EXCLAMATION} + Displays an exclamation mark symbol. + @style{wxICON_ERROR} + Displays an error symbol. + @style{wxICON_HAND} + Displays an error symbol, this is a MSW-inspired synonym for @c + wxICON_ERROR. + @style{wxICON_QUESTION} + Displays a question mark symbol. This icon is automatically used + with @c wxYES_NO so it's usually unnecessary to specify it + explicitly. + @style{wxICON_INFORMATION} + Displays an information symbol. This icon is used by default if @c + wxYES_NO is not given so it is usually unnecessary to specify it + explicitly. + @style{wxSTAY_ON_TOP} + Makes the message box stay on top of all other windows (currently + implemented only under MSW). + @endStyleTable + + @param parent + Parent window. + @param message + Message to show in the dialog. + @param caption + The dialog title. + @param style + Combination of style flags described above. + @param pos + Dialog position (ignored under MSW). + */ + wxMessageDialog(wxWindow* parent, const wxString& message, + const wxString& caption = "Message box", + long style = wxOK | wxCANCEL, + const wxPoint& pos = wxDefaultPosition); + + /** + Sets the extended message for the dialog: this message is usually an + extension of the short message specified in the constructor or set with + SetMessage(). + + If it is set, the main message appears highlighted -- if supported -- + and this message appears beneath it in normal font. On the platforms + which don't support extended messages, it is simply appended to the + normal message with a new line separating them. + */ + void SetExtendedMessage(const wxString extendedMessage); + + /** + Sets the message shown by the dialog. + */ + void SetMessage(const wxString msg); + + /** + Overrides the default labels of the OK and Cancel buttons. + + Please see the remarks in SetYesNoLabels() documentation. + */ + bool SetOKCancelLabels(const wxString ok, const wxString cancel); + + /** + Overrides the default label of the OK button. + + Please see the remarks in SetYesNoLabels() documentation. + */ + bool SetOKLabel(const wxString ok); + + /** + Overrides the default labels of the Yes, No and Cancel buttons. + + Please see the remarks in SetYesNoLabels() documentation. + */ + bool SetYesNoCancelLabels(const wxString yes, const wxString no, + const wxString cancel); + + /** + Overrides the default labels of the Yes and No buttons. + + Notice that this function is not currently available on all platforms, + so it may return @false to indicate that the labels couldn't be + changed. If it returns @true (currently only under wxMac), the labels + were set successfully. Typically, if the function was used + successfully, the main dialog message may need to be changed, e.g.: + @code + wxMessageDialog dlg(...); + if ( dlg.SetYesNoLabels(_("&Quit"), _("&Don't quit")) ) + dlg.SetMessage(_("What do you want to do?")); + else // buttons have standard "Yes"/"No" values, so rephrase the question + dlg.SetMessage(_("Do you really want to quit?")); + @endcode + */ + bool SetYesNoLabels(const wxString yes, const wxString no); + + /** + Shows the dialog, returning one of wxID_OK, wxID_CANCEL, wxID_YES, + wxID_NO. + + Notice that this method returns the identifier of the button which was + clicked unlike wxMessageBox() function. + */ + int ShowModal(); +}; + + + +// ============================================================================ +// Global functions/macros +// ============================================================================ + +/** @ingroup group_funcmacro_dialog */ +//@{ + +/** + Show a general purpose message dialog. + + This is a convenient function which is usually used instead of using + wxMessageDialog directly. Notice however that some of the features, such as + extended text and custom labels for the message box buttons, are not + provided by this function but only by wxMessageDialog. + + The return value is one of: @c wxYES, @c wxNO, @c wxCANCEL or @c wxOK + (notice that this return value is @b different from the return value of + wxMessageDialog::ShowModal()). + + For example: + @code + int answer = wxMessageBox("Quit program?", "Confirm", + wxYES_NO | wxCANCEL, main_frame); + if (answer == wxYES) + main_frame->Close(); + @endcode + + @a message may contain newline characters, in which case the message will + be split into separate lines, to cater for large messages. + + @param message + Message to show in the dialog. + @param caption + The dialog title. + @param parent + Parent window. + @param style + Combination of style flags described in wxMessageDialog documentation. + @param x + Horizontal dialog position (ignored under MSW). Use @c wxDefaultCoord + for @a x and @a y to let the system position the window. + @param y + Vertical dialog position (ignored under MSW). + @header{wx/msgdlg.h} +*/ +int wxMessageBox(const wxString& message, + const wxString& caption = "Message", + int style = wxOK, + wxWindow* parent = NULL, + int x = wxDefaultCoord, + int y = wxDefaultCoord); + +//@} + diff --git a/interface/wx/msgqueue.h b/interface/wx/msgqueue.h new file mode 100644 index 0000000000..2b23de8b9a --- /dev/null +++ b/interface/wx/msgqueue.h @@ -0,0 +1,69 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: msgqueue.h +// Purpose: interface of wxMessageQueue +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @wxheader{msgqueue.h} + + wxMessageQueue allows passing messages between threads. + + This class should be typically used to communicate between the main and worker + threads. The main thread calls wxMessageQueue::Post and + the worker thread calls wxMessageQueue::Receive. + + For this class a message is an object of arbitrary type T. Notice that + often there is a some special message indicating that the thread + should terminate as there is no other way to gracefully shutdown a thread + waiting on the message queue. + + @nolibrary + @category{FIXME} + + @see wxThread +*/ +class wxMessageQueue +{ +public: + /** + Returns @true if the object had been initialized successfully, @false + if an error occurred. + */ + bool IsOk() const; + + /** + Add a message to this queue and signal the threads waiting for messages + (i.e. the threads which called wxMessageQueue::Receive or + wxMessageQueue::ReceiveTimeout). + This method is safe to call from multiple threads in parallel. + */ + wxMessageQueueError Post(T const& msg); + + /** + Block until a message becomes available in the queue. Waits indefinitely long + or until an error occurs. + The message is returned in @e msg. + */ + wxMessageQueueError Receive(T& msg); + + /** + Block until a message becomes available in the queue, but no more than + @a timeout milliseconds has elapsed. + If no message is available after @a timeout milliseconds then returns + @b wxMSGQUEUE_TIMEOUT. + If @a timeout is 0 then checks for any messages present in the queue + and returns immediately without waiting. + The message is returned in @e msg. + */ + wxMessageQueueError ReceiveTimeout(long timeout, T& msg); + + /** + Default and only constructor. Use wxMessageQueue::IsOk to check + if the object was successfully initialized. + */ + wxMessageQueue(); +}; + diff --git a/interface/wx/mstream.h b/interface/wx/mstream.h new file mode 100644 index 0000000000..37319f10b2 --- /dev/null +++ b/interface/wx/mstream.h @@ -0,0 +1,87 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: mstream.h +// Purpose: interface of wxMemoryOutputStream +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxMemoryOutputStream + @wxheader{mstream.h} + + + @library{wxbase} + @category{streams} + + @see wxStreamBuffer +*/ +class wxMemoryOutputStream : public wxOutputStream +{ +public: + /** + If @a data is @NULL, then it will initialize a new empty buffer which will + grow if required. + */ + wxMemoryOutputStream(char* data = NULL, size_t length = 0); + + /** + Destructor. + */ + ~wxMemoryOutputStream(); + + /** + CopyTo allowed you to transfer data from the internal buffer of + wxMemoryOutputStream to an external buffer. @a len specifies the size of + the buffer. + */ + size_t CopyTo(char* buffer, size_t len) const; + + /** + Returns the pointer to the stream object used as an internal buffer + for that stream. + */ + wxStreamBuffer* GetOutputStreamBuffer() const; +}; + + + +/** + @class wxMemoryInputStream + @wxheader{mstream.h} + + + @library{wxbase} + @category{streams} + + @see wxStreamBuffer, wxMemoryOutputStream +*/ +class wxMemoryInputStream : public wxInputStream +{ +public: + //@{ + /** + Creates a new read-only memory stream, initializing it with the + data from the given input stream @e stream. + The @a len argument specifies the amount of data to read from + the @e stream. Setting it to @e wxInvalidOffset means that + the @a stream is to be read entirely (i.e. till the EOF is reached). + */ + wxMemoryInputStream(const char* data, size_t len); + wxMemoryInputStream(const wxMemoryOutputStream& stream); + wxMemoryInputStream(wxInputStream& stream, + wxFileOffset len = wxInvalidOffset); + //@} + + /** + Destructor. + */ + ~wxMemoryInputStream(); + + /** + Returns the pointer to the stream object used as an internal buffer + for that stream. + */ + wxStreamBuffer* GetInputStreamBuffer() const; +}; + diff --git a/interface/wx/msw/ole/activex.h b/interface/wx/msw/ole/activex.h new file mode 100644 index 0000000000..84dd86c428 --- /dev/null +++ b/interface/wx/msw/ole/activex.h @@ -0,0 +1,99 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: msw/ole/activex.h +// Purpose: interface of wxActiveXEvent +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxActiveXEvent + @headerfile ole/activex.h wx/msw/ole/activex.h + + An event class for handling activex events passed from wxActiveXContainer. + + ActiveX events are basically a function call with the parameters passed + through an array of wxVariants along with a return value that is a wxVariant + itself. What type the parameters or return value are depends on the context + (i.e. what the .idl specifies). + + Note that unlike the third party wxActiveX function names are not supported. + + @onlyfor{wxmsw} + + @library{wxbase} + @category{FIXME} +*/ +class wxActiveXEvent : public wxCommandEvent +{ +public: + /** + Returns the dispatch id of this activex event. This is the numeric value from + the .idl file specified by the id(). + */ + DISPID GetDispatchId(int idx) const; + + /** + Obtains the number of parameters passed through the activex event. + */ + size_t ParamCount() const; + + /** + Obtains the param name of the param number idx specifies as a string. + */ + wxString ParamName(size_t idx) const; + + /** + Obtains the param type of the param number idx specifies as a string. + */ + wxString ParamType(size_t idx) const; + + /** + Obtains the actual parameter value specified by idx. + */ + wxVariant operator[](size_t idx); +}; + + + +/** + @class wxActiveXContainer + @headerfile ole/activex.h wx/msw/ole/activex.h + + wxActiveXContainer is a host for an activex control on Windows (and + as such is a platform-specific class). Note that the HWND that the class + contains is the actual HWND of the activex control so using dynamic events + and connecting to wxEVT_SIZE, for example, will recieve the actual size + message sent to the control. + + It is somewhat similar to the ATL class CAxWindow in operation. + + The size of the activex control's content is generally gauranteed to be that + of the client size of the parent of this wxActiveXContainer. + + You can also process activex events through wxEVT_ACTIVEX or the + corresponding message map macro EVT_ACTIVEX. + + @onlyfor{wxmsw} + + @library{wxbase} + @category{FIXME} + + @see wxActiveXEvent +*/ +class wxActiveXContainer : public wxControl +{ +public: + /** + Creates this activex container. + + @param parent + parent of this control. Must not be @NULL. + @param iid + COM IID of pUnk to query. Must be a valid interface to an activex control. + @param pUnk + Interface of activex control. + */ + wxActiveXContainer(wxWindow* parent, REFIID iid, IUnknown* pUnk); +}; + diff --git a/interface/wx/msw/ole/automtn.h b/interface/wx/msw/ole/automtn.h new file mode 100644 index 0000000000..e8fe35671b --- /dev/null +++ b/interface/wx/msw/ole/automtn.h @@ -0,0 +1,197 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: msw/ole/automtn.h +// Purpose: interface of wxAutomationObject +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxAutomationObject + @headerfile ole/automtn.h wx/msw/ole/automtn.h + + The @b wxAutomationObject class represents an OLE automation object containing + a single data member, + an IDispatch pointer. It contains a number of functions that make it easy to + perform + automation operations, and set and get properties. The class makes heavy use of + the wxVariant class. + + The usage of these classes is quite close to OLE automation usage in Visual + Basic. The API is + high-level, and the application can specify multiple properties in a single + string. The following example + gets the current Excel instance, and if it exists, makes the active cell bold. + + @code + wxAutomationObject excelObject; + if (excelObject.GetInstance("Excel.Application")) + excelObject.PutProperty("ActiveCell.Font.Bold", @true); + @endcode + + Note that this class obviously works under Windows only. + + @onlyfor{wxmsw} + + @library{wxcore} + @category{misc} + + @see wxVariant +*/ +class wxAutomationObject : public wxObject +{ +public: + /** + Constructor, taking an optional IDispatch pointer which will be released when + the + object is deleted. + */ + wxAutomationObject(WXIDISPATCH* dispatchPtr = NULL); + + /** + Destructor. If the internal IDispatch pointer is non-null, it will be released. + */ + ~wxAutomationObject(); + + //@{ + /** + Calls an automation method for this object. The first form takes a method name, + number of + arguments, and an array of variants. The second form takes a method name and + zero to six + constant references to variants. Since the variant class has constructors for + the basic + data types, and C++ provides temporary objects automatically, both of the + following lines + are syntactically valid: + + Note that @a method can contain dot-separated property names, to save the + application + needing to call GetProperty several times using several temporary objects. For + example: + */ + wxVariant CallMethod(const wxString& method, int noArgs, + wxVariant args[]) const; + const wxVariant CallMethod(const wxString& method, ... ) const; + //@} + + /** + Creates a new object based on the class id, returning @true if the object was + successfully created, + or @false if not. + */ + bool CreateInstance(const wxString& classId) const; + + /** + Gets the IDispatch pointer. + */ + IDispatch* GetDispatchPtr() const; + + /** + Retrieves the current object associated with a class id, and attaches the + IDispatch pointer + to this object. Returns @true if a pointer was successfully retrieved, @false + otherwise. + Note that this cannot cope with two instances of a given OLE object being + active simultaneously, + such as two copies of Excel running. Which object is referenced cannot + currently be specified. + */ + bool GetInstance(const wxString& classId) const; + + /** + Retrieves a property from this object, assumed to be a dispatch pointer, and + initialises @a obj with it. + To avoid having to deal with IDispatch pointers directly, use this function in + preference + to GetProperty() when retrieving objects + from other objects. + Note that an IDispatch pointer is stored as a void* pointer in wxVariant + objects. + + @see GetProperty() + */ + bool GetObject(wxAutomationObject& obj, const wxString& property, + int noArgs = 0, + wxVariant args[] = NULL) const; + + //@{ + /** + Gets a property value from this object. The first form takes a property name, + number of + arguments, and an array of variants. The second form takes a property name and + zero to six + constant references to variants. Since the variant class has constructors for + the basic + data types, and C++ provides temporary objects automatically, both of the + following lines + are syntactically valid: + + Note that @a property can contain dot-separated property names, to save the + application + needing to call GetProperty several times using several temporary objects. + */ + wxVariant GetProperty(const wxString& property, int noArgs, + wxVariant args[]) const; + const wxVariant GetProperty(const wxString& property, ... ) const; + //@} + + /** + This function is a low-level implementation that allows access to the IDispatch + Invoke function. + It is not meant to be called directly by the application, but is used by other + convenience functions. + + @param member + The member function or property name. + @param action + Bitlist: may contain DISPATCH_PROPERTYPUT, DISPATCH_PROPERTYPUTREF, + DISPATCH_METHOD. + @param retValue + Return value (ignored if there is no return value) + @param noArgs + Number of arguments in args or ptrArgs. + @param args + If non-null, contains an array of variants. + @param ptrArgs + If non-null, contains an array of constant pointers to variants. + + @return @true if the operation was successful, @false otherwise. + + @remarks Two types of argument array are provided, so that when possible + pointers are used for efficiency. + */ + bool Invoke(const wxString& member, int action, + wxVariant& retValue, int noArgs, + wxVariant args[], + const wxVariant* ptrArgs[] = 0) const; + + //@{ + /** + Puts a property value into this object. The first form takes a property name, + number of + arguments, and an array of variants. The second form takes a property name and + zero to six + constant references to variants. Since the variant class has constructors for + the basic + data types, and C++ provides temporary objects automatically, both of the + following lines + are syntactically valid: + + Note that @a property can contain dot-separated property names, to save the + application + needing to call GetProperty several times using several temporary objects. + */ + bool PutProperty(const wxString& property, int noArgs, + wxVariant args[]); + const bool PutProperty(const wxString& property, ... ); + //@} + + /** + Sets the IDispatch pointer. This function does not check if there is already an + IDispatch pointer. + You may need to cast from IDispatch* to WXIDISPATCH* when calling this function. + */ + void SetDispatchPtr(WXIDISPATCH* dispatchPtr); +}; + diff --git a/interface/wx/msw/registry.h b/interface/wx/msw/registry.h new file mode 100644 index 0000000000..6937ac4b45 --- /dev/null +++ b/interface/wx/msw/registry.h @@ -0,0 +1,239 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: msw/registry.h +// Purpose: interface of wxRegKey +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxRegKey + @wxheader{msw/registry.h} + + wxRegKey is a class representing the Windows registry (it is only available + under Windows). One can create, query and delete registry keys using this + class. + + The Windows registry is easy to understand. There are five registry keys, + namely: + + @li @c HKEY_CLASSES_ROOT (HKCR) + @li @c HKEY_CURRENT_USER (HKCU) + @li @c HKEY_LOCAL_MACHINE (HKLM) + @li @c HKEY_CURRENT_CONFIG (HKCC) + @li @c HKEY_USERS (HKU) + + After creating a key, it can hold a value. The values can be: + + @li String Value + @li Binary Value + @li DWORD Value + @li Multi String Value + @li Expandable String Value + + @onlyfor{wxmsw} + + @library{wxbase} + @category{misc} + + @b Example: + + @code + wxRegKey *key = new wxRegKey("HKEY_LOCAL_MACHINE\\Software\\MyKey"); + + // Create the key if it does not exist. + if( !key->Exists() ) + key->Create(); + + // Create a new value "MYVALUE" and set it to 12. + key->SetValue("MYVALUE", 12); + + // Read the value back. + long value; + key->QueryValue("MYVALUE", &value); + wxMessageBox(wxString::Format("%d", value), "Registry Value", wxOK); + + // Get the number of subkeys and enumerate them. + size_t subkeys; + key->GetKeyInfo(&subkeys, NULL, NULL, NULL); + + wxString key_name; + key->GetFirstKey(key_name, 1); + for(int i = 0; i < subkeys; i++) + { + wxMessageBox(key_name, "Subkey Name", wxOK); + key->GetNextKey(key_name, 1); + } + @endcode +*/ +class wxRegKey +{ +public: + /** + Default constructor, initializes to @c HKEY_CLASSES_ROOT. + */ + wxRegKey(); + /** + The constructor to set the full name of the key. + */ + wxRegKey(const wxString& strKey); + /** + The constructor to set the full name of the key under a previously created + parent. + */ + wxRegKey(const wxRegKey& keyParent, const wxString& strKey); + + /** + Access modes for wxRegKey. + */ + enum AccessMode + { + Read, ///< Read-only + Write ///< Read and Write + }; + + /** + Closes the key. + */ + void Close(); + + /** + Creates the key. Will fail if the key already exists and @a bOkIfExists is + @false. + */ + bool Create(bool bOkIfExists = true); + + /** + Deletes the subkey with all of its subkeys/values recursively. + */ + void DeleteKey(const wxChar* szKey); + + /** + Deletes this key and all of its subkeys and values recursively. + */ + void DeleteSelf(); + + /** + Deletes the named value. + */ + void DeleteValue(const wxChar* szKey); + + /** + Returns @true if the key exists. + */ + bool Exists() const; + + /** + Gets the first key. + */ + bool GetFirstKey(wxString& strKeyName, long& lIndex); + + /** + Gets the first value of this key. + */ + bool GetFirstValue(wxString& strValueName, long& lIndex); + + /** + Gets information about the key. + + @param pnSubKeys + The number of subkeys. + @param pnMaxKeyLen + The maximum length of the subkey name. + @param pnValues + The number of values. + @param pnMaxValueLen + The maximum length of a value. + */ + bool GetKeyInfo(size_t* pnSubKeys, size_t* pnMaxKeyLen, + size_t* pnValues, size_t* pnMaxValueLen) const; + + /** + Gets the name of the registry key. + */ + wxString GetName(bool bShortPrefix = true) const; + + /** + Gets the next key. + */ + bool GetNextKey(wxString& strKeyName, long& lIndex) const; + + /** + Gets the next key value for this key. + */ + bool GetNextValue(wxString& strValueName, long& lIndex) const; + + /** + Returns @true if given subkey exists. + */ + bool HasSubKey(const wxChar* szKey) const; + + /** + Returns @true if any subkeys exist. + */ + bool HasSubKeys() const; + + /** + Returns @true if the value exists. + */ + bool HasValue(const wxChar* szValue) const; + + /** + Returns @true if any values exist. + */ + bool HasValues() const; + + /** + Returns @true if this key is empty, nothing under this key. + */ + bool IsEmpty() const; + + /** + Returns @true if the key is opened. + */ + bool IsOpened() const; + + /** + Explicitly opens the key. This method also allows the key to be opened in + read-only mode by passing wxRegKey::Read instead of default + wxRegKey::Write parameter. + */ + bool Open(AccessMode mode = Write); + + /** + Retrieves the string value. + */ + bool QueryValue(const wxChar* szValue, wxString& strValue) const; + + /** + Retrieves the numeric value. + */ + const bool QueryValue(const wxChar* szValue, long* plValue) const; + + /** + Renames the key. + */ + bool Rename(const wxChar* szNewName); + + /** + Renames a value. + */ + bool RenameValue(const wxChar* szValueOld, + const wxChar* szValueNew); + + /** + Sets the given @a szValue which must be numeric. + If the value doesn't exist, it is created. + */ + bool SetValue(const wxChar* szValue, long lValue); + /** + Sets the given @a szValue which must be string. + If the value doesn't exist, it is created. + */ + bool SetValue(const wxChar* szValue, const wxString& strValue); + /** + Sets the given @a szValue which must be binary. + If the value doesn't exist, it is created. + */ + bool SetValue(const wxChar* szValue, const wxMemoryBuffer& buf); +}; diff --git a/interface/wx/notebook.h b/interface/wx/notebook.h new file mode 100644 index 0000000000..807e42c1db --- /dev/null +++ b/interface/wx/notebook.h @@ -0,0 +1,425 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: notebook.h +// Purpose: interface of wxNotebookEvent +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxNotebookEvent + @wxheader{notebook.h} + + This class represents the events generated by a notebook control: currently, + there are two of them. The PAGE_CHANGING event is sent before the current + page is changed. It allows the program to examine the current page (which + can be retrieved with + wxNotebookEvent::GetOldSelection) and to veto the page + change by calling wxNotifyEvent::Veto if, for example, the + current values in the controls of the old page are invalid. + + The second event - PAGE_CHANGED - is sent after the page has been changed and + the program cannot veto it any more, it just informs it about the page change. + + To summarize, if the program is interested in validating the page values + before allowing the user to change it, it should process the PAGE_CHANGING + event, otherwise PAGE_CHANGED is probably enough. In any case, it is probably + unnecessary to process both events at once. + + @library{wxcore} + @category{events} + + @see wxNotebook +*/ +class wxNotebookEvent : public wxNotifyEvent +{ +public: + /** + Constructor (used internally by wxWidgets only). + */ + wxNotebookEvent(wxEventType eventType = wxEVT_NULL, int id = 0, + int sel = -1, + int oldSel = -1); + + /** + Returns the page that was selected before the change, -1 if none was selected. + */ + int GetOldSelection() const; + + /** + Returns the currently selected page, or -1 if none was selected. + @note under Windows, GetSelection() will return the same value as + GetOldSelection() when called from + @c EVT_NOTEBOOK_PAGE_CHANGING handler and not the page which is going to + be selected. Also note that the values of selection and old selection returned + for an event generated in response to a call to + wxNotebook::SetSelection shouldn't be trusted + as they are currently inconsistent under different platforms (but in this case + you presumably don't need them anyhow as you already have the corresponding + information). + */ + int GetSelection() const; + + /** + Sets the id of the page selected before the change. + */ + void SetOldSelection(int page); + + /** + Sets the selection member variable. + */ + void SetSelection(int page); +}; + + + +/** + @class wxNotebook + @wxheader{notebook.h} + + This class represents a notebook control, which manages multiple windows with + associated tabs. + + To use the class, create a wxNotebook object and call wxNotebook::AddPage or + wxNotebook::InsertPage, + passing a window to be used as the page. Do not explicitly delete the window + for a page that is currently + managed by wxNotebook. + + @b wxNotebookPage is a typedef for wxWindow. + + @beginStyleTable + @style{wxNB_TOP} + Place tabs on the top side. + @style{wxNB_LEFT} + Place tabs on the left side. + @style{wxNB_RIGHT} + Place tabs on the right side. + @style{wxNB_BOTTOM} + Place tabs under instead of above the notebook pages. + @style{wxNB_FIXEDWIDTH} + (Windows only) All tabs will have same width. + @style{wxNB_MULTILINE} + (Windows only) There can be several rows of tabs. + @style{wxNB_NOPAGETHEME} + (Windows only) Display a solid colour on notebook pages, and not a + gradient, which can reduce performance. + @style{wxNB_FLAT} + (Windows CE only) Show tabs in a flat style. + @endStyleTable + + @library{wxcore} + @category{miscwnd} + + @see wxBookCtrl(), wxNotebookEvent, wxImageList, @ref overview_samplenotebook + "notebook sample" +*/ +class wxNotebook : public wxBookCtrl overview +{ +public: + //@{ + /** + Constructs a notebook control. + Note that sometimes you can reduce flicker by passing the wxCLIP_CHILDREN + window style. + + @param parent + The parent window. Must be non-@NULL. + @param id + The window identifier. + @param pos + The window position. + @param size + The window size. + @param style + The window style. See wxNotebook. + @param name + The name of the control (used only under Motif). + */ + wxNotebook(); + wxNotebook(wxWindow* parent, wxWindowID id, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0, + const wxString& name = wxNotebookNameStr); + //@} + + /** + Destroys the wxNotebook object. + */ + virtual ~wxNotebook(); + + /** + Adds a new page. + The call to this function may generate the page changing events. + + @param page + Specifies the new page. + @param text + Specifies the text for the new page. + @param select + Specifies whether the page should be selected. + @param imageId + Specifies the optional image index for the new page. + + @return @true if successful, @false otherwise. + + @remarks Do not delete the page, it will be deleted by the notebook. + + @see InsertPage() + */ + bool AddPage(wxNotebookPage* page, const wxString& text, + bool select = false, + int imageId = -1); + + /** + Cycles through the tabs. + The call to this function generates the page changing events. + */ + void AdvanceSelection(bool forward = true); + + /** + Sets the image list for the page control and takes ownership of + the list. + + @see wxImageList, SetImageList() + */ + void AssignImageList(wxImageList* imageList); + + /** + Changes the selection for the given page, returning the previous selection. + The call to this function does not generate the page changing events. + This is the only difference with SetSelection(). + See @ref overview_progevent "this topic" for more info. + */ + virtual int ChangeSelection(size_t page); + + /** + Creates a notebook control. See wxNotebook() for a description + of the parameters. + */ + bool Create(wxWindow* parent, wxWindowID id, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0, + const wxString& name = wxNotebookNameStr); + + /** + Deletes all pages. + */ + virtual bool DeleteAllPages(); + + /** + Deletes the specified page, and the associated window. + The call to this function generates the page changing events. + */ + bool DeletePage(size_t page); + + /** + Returns the currently selected notebook page or @NULL. + */ + wxWindow* GetCurrentPage() const; + + /** + Returns the associated image list. + + @see wxImageList, SetImageList() + */ + wxImageList* GetImageList() const; + + /** + Returns the window at the given page position. + */ + wxNotebookPage* GetPage(size_t page); + + /** + Returns the number of pages in the notebook control. + */ + size_t GetPageCount() const; + + /** + Returns the image index for the given page. + */ + virtual int GetPageImage(size_t nPage) const; + + /** + Returns the string for the given page. + */ + virtual wxString GetPageText(size_t nPage) const; + + /** + Returns the number of rows in the notebook control. + */ + virtual int GetRowCount() const; + + /** + Returns the currently selected page, or -1 if none was selected. + Note that this method may return either the previously or newly selected page + when called from the @c EVT_NOTEBOOK_PAGE_CHANGED handler depending on + the platform and so + wxNotebookEvent::GetSelection should be + used instead in this case. + */ + virtual int GetSelection() const; + + /** + If running under Windows and themes are enabled for the application, this + function + returns a suitable colour for painting the background of a notebook page, and + can be passed + to @c SetBackgroundColour. Otherwise, an uninitialised colour will be returned. + */ + virtual wxColour GetThemeBackgroundColour() const; + + /** + Returns the index of the tab at the specified position or @c wxNOT_FOUND + if none. If @a flags parameter is non-@NULL, the position of the point + inside the tab is returned as well. + + @param pt + Specifies the point for the hit test. + @param flags + Return value for detailed information. One of the following values: + + + + + + + + wxBK_HITTEST_NOWHERE + + + + + There was no tab under this point. + + + + + + wxBK_HITTEST_ONICON + + + + + The point was over an icon (currently wxMSW only). + + + + + + wxBK_HITTEST_ONLABEL + + + + + The point was over a label (currently wxMSW only). + + + + + + wxBK_HITTEST_ONITEM + + + + + The point was over an item, but not on the label or icon. + + + + + + wxBK_HITTEST_ONPAGE + + + + + The point was over a currently selected page, not over any tab. Note that + this flag is present only if wxNOT_FOUND is returned. + + @return Returns the zero-based tab index or wxNOT_FOUND if there is no + tab is at the specified position. + */ + virtual int HitTest(const wxPoint& pt, long* = NULL) const; + + /** + Inserts a new page at the specified position. + + @param index + Specifies the position for the new page. + @param page + Specifies the new page. + @param text + Specifies the text for the new page. + @param select + Specifies whether the page should be selected. + @param imageId + Specifies the optional image index for the new page. + + @return @true if successful, @false otherwise. + + @remarks Do not delete the page, it will be deleted by the notebook. + + @see AddPage() + */ + bool InsertPage(size_t index, wxNotebookPage* page, + const wxString& text, + bool select = false, + int imageId = -1); + + /** + An event handler function, called when the page selection is changed. + + @see wxNotebookEvent + */ + void OnSelChange(wxNotebookEvent& event); + + /** + Deletes the specified page, without deleting the associated window. + */ + bool RemovePage(size_t page); + + /** + Sets the image list for the page control. It does not take + ownership of the image list, you must delete it yourself. + + @see wxImageList, AssignImageList() + */ + void SetImageList(wxImageList* imageList); + + /** + Sets the amount of space around each page's icon and label, in pixels. + @note The vertical padding cannot be changed in wxGTK. + */ + void SetPadding(const wxSize& padding); + + /** + Sets the image index for the given page. @a image is an index into + the image list which was set with SetImageList(). + */ + virtual bool SetPageImage(size_t page, int image); + + /** + Sets the width and height of the pages. + @note This method is currently not implemented for wxGTK. + */ + virtual void SetPageSize(const wxSize& size); + + /** + Sets the text for the given page. + */ + virtual bool SetPageText(size_t page, const wxString& text); + + /** + Sets the selection for the given page, returning the previous selection. + The call to this function generates the page changing events. + This function is deprecated and should not be used in new code. Please use the + ChangeSelection() function instead. + + @see GetSelection() + */ + virtual int SetSelection(size_t page); +}; + diff --git a/interface/wx/notifmsg.h b/interface/wx/notifmsg.h new file mode 100644 index 0000000000..ecc14510e9 --- /dev/null +++ b/interface/wx/notifmsg.h @@ -0,0 +1,89 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: notifmsg.h +// Purpose: interface of wxNotificationMessage +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxNotificationMessage + @wxheader{notifmsg.h} + + This class allows to show the user a message non intrusively. Currently it is + implemented natively only for the Maemo platform and uses (non-modal) dialogs + for the display of the notifications under the other platforms but it will be + extended to use the platform-specific notifications in the other ports in the + future. + + Notice that this class is not a window and so doesn't derive from wxWindow. + + @library{wxbase} + @category{FIXME} +*/ +class wxNotificationMessage : public wxEvtHandler +{ +public: + //@{ + /** + , @b wxWindow*@e parent = @NULL, @b int@e flags = @c wxICON_INFORMATION) + Create a notification object with the given attributes. + See SetTitle(), + SetMessage(), + SetParent() and + SetFlags() for the description of the + corresponding parameters. + */ + wxNotificationMessage(); + wxNotificationMessage(const wxString& title); + //@} + + /** + Hides the notification. + Returns @true if it was hidden or @false if it couldn't be done (e.g. on + some + systems automatically hidden notifications can't be hidden manually) + */ + bool Close(); + + /** + This parameter can be currently used to specify the icon to show in the + notification. Valid values are @c wxICON_INFORMATION, + @c wxICON_WARNING and @c wxICON_ERROR (notice that + @c wxICON_QUESTION is not allowed here). + Some implementations of this class may not support the icons. + */ + void SetFlags(int flags); + + /** + Set the main text of the notification. This should be a more detailed + description than the title but still limited to reasonable length (not more + than 256 characters). + */ + void SetMessage(const wxString& message); + + /** + Set the parent for this notification: the notification will be associated with + the top level parent of this window or, if this method is not called, with the + main application window by default + */ + void SetParent(wxWindow* parent); + + /** + Set the title, it must be a concise string (not more than 64 characters), use + SetMessage() to give the user more + details. + */ + void SetTitle(const wxString& title); + + /** + Show the notification to the user and hides it after timeout seconds + pass. Special values @c Timeout_Auto and @c Timeout_Never can be + used here, notice that you shouldn't rely on @a timeout being exactly + respected because the current platform may only support default timeout value + and also because the user may be able to close the notification. + Returns @false if an error occurred. + */ + bool Show(int timeout = Timeout_Auto); +}; + diff --git a/interface/wx/numdlg.h b/interface/wx/numdlg.h new file mode 100644 index 0000000000..904f67e2e8 --- /dev/null +++ b/interface/wx/numdlg.h @@ -0,0 +1,37 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: numdlg.h +// Purpose: interface of global functions +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** @ingroup group_funcmacro_dialog */ +//@{ + +/** + Shows a dialog asking the user for numeric input. The dialogs title is set + to @c caption, it contains a (possibly) multiline @c message above the + single line @c prompt and the zone for entering the number. + + The number entered must be in the range @c min to @c max (both of which + should be positive) and @c value is the initial value of it. If the user + enters an invalid value or cancels the dialog, the function will return + -1. + + Dialog is centered on its @c parent unless an explicit position is given + in @c pos. + + @header{wx/numdlg.h} +*/ +long wxGetNumberFromUser(const wxString& message, + const wxString& prompt, + const wxString& caption, + long value, + long min = 0, + long max = 100, + wxWindow* parent = NULL, + const wxPoint& pos = wxDefaultPosition); + +//@} + diff --git a/interface/wx/object.h b/interface/wx/object.h new file mode 100644 index 0000000000..b6467e9fe6 --- /dev/null +++ b/interface/wx/object.h @@ -0,0 +1,853 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: object.h +// Purpose: interface of wxObjectRefData +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxObjectRefData + @wxheader{object.h} + + This class is used to store reference-counted data. + + Derive classes from this to store your own data. When retrieving information + from a wxObject's reference data, you will need to cast to your own derived class. + + @b Example: + + @code + // include file + + class MyCar: public wxObject + { + public: + MyCar() { } + MyCar( int price ); + + bool IsOk() const { return m_refData != NULL; } + + bool operator == ( const MyCar& car ) const; + bool operator != (const MyCar& car) const { return !(*this == car); } + + void SetPrice( int price ); + int GetPrice() const; + + protected: + virtual wxObjectRefData *CreateRefData() const; + virtual wxObjectRefData *CloneRefData(const wxObjectRefData *data) const; + + DECLARE_DYNAMIC_CLASS(MyCar) + }; + + + // implementation + + class MyCarRefData: public wxObjectRefData + { + public: + MyCarRefData() + { + m_price = 0; + } + + MyCarRefData( const MyCarRefData& data ) + : wxObjectRefData() + { + m_price = data.m_price; + } + + bool operator == (const MyCarRefData& data) const + { + return m_price == data.m_price; + } + + int m_price; + }; + + + #define M_CARDATA ((MyCarRefData *)m_refData) + + IMPLEMENT_DYNAMIC_CLASS(MyCar,wxObject) + + MyCar::MyCar( int price ) + { + m_refData = new MyCarRefData(); + M_CARDATA->m_price = price; + } + + wxObjectRefData *MyCar::CreateRefData() const + { + return new MyCarRefData; + } + + wxObjectRefData *MyCar::CloneRefData(const wxObjectRefData *data) const + { + return new MyCarRefData(*(MyCarRefData *)data); + } + + bool MyCar::operator == ( const MyCar& car ) const + { + if (m_refData == car.m_refData) return true; + + if (!m_refData || !car.m_refData) return false; + + return ( *(MyCarRefData*)m_refData == *(MyCarRefData*)car.m_refData ); + } + + void MyCar::SetPrice( int price ) + { + UnShare(); + + M_CARDATA->m_price = price; + } + + int MyCar::GetPrice() const + { + wxCHECK_MSG( IsOk(), -1, "invalid car" ); + + return (M_CARDATA->m_price); + } + @endcode + + + @library{wxbase} + @category{rtti} + + @see wxObject, wxObjectDataPtr, @ref overview_refcount +*/ +class wxObjectRefData +{ +protected: + /** + Destructor. + + It's declared @c protected so that wxObjectRefData instances + will never be destroyed directly but only as result of a DecRef() call. + */ + ~wxObjectRefData(); + +public: + /** + Default constructor. Initialises the internal reference count to 1. + */ + wxObjectRefData(); + + /** + Decrements the reference count associated with this shared data and, if + it reaches zero, destroys this instance of wxObjectRefData releasing its + memory. + + Please note that after calling this function, the caller should + absolutely avoid to use the pointer to this instance since it may not be + valid anymore. + */ + void DecRef(); + + /** + Returns the reference count associated with this shared data. + + When this goes to zero during a DecRef() call, the object will auto-free itself. + */ + int GetRefCount() const; + + /** + Increments the reference count associated with this shared data. + */ + void IncRef(); +}; + + + +/** + @class wxObject + @wxheader{object.h} + + This is the root class of many of the wxWidgets classes. + + It declares a virtual destructor which ensures that destructors get called + for all derived class objects where necessary. + + wxObject is the hub of a dynamic object creation scheme, enabling a program + to create instances of a class only knowing its string class name, and to + query the class hierarchy. + + The class contains optional debugging versions of @b new and @b delete, which + can help trace memory allocation and deallocation problems. + + wxObject can be used to implement @ref overview_refcount "reference counted" + objects, such as wxPen, wxBitmap and others + (see @ref overview_refcount_list "this list"). + + @library{wxbase} + @category{rtti} + + @see wxClassInfo, @ref overview_debugging, wxObjectRefData +*/ +class wxObject +{ +public: + + wxObject(); + + /** + Copy ctor. + */ + wxObject(const wxObject& other); + + + /** + Destructor. + + Performs dereferencing, for those objects that use reference counting. + */ + wxObject(); + + /** + A virtual function that may be redefined by derived classes to allow dumping of + memory states. + + This function is only defined in debug build and exists only if @c __WXDEBUG__ + is defined. + + @param stream + Stream on which to output dump information. + + @remarks Currently wxWidgets does not define Dump() for derived classes, + but programmers may wish to use it for their own applications. + Be sure to call the Dump member of the class's base class to allow all + information to be dumped. + The implementation of this function in wxObject just writes + the class name of the object. + */ + void Dump(ostream& stream); + + /** + This virtual function is redefined for every class that requires run-time + type information, when using the ::DECLARE_CLASS macro (or similar). + */ + wxClassInfo* GetClassInfo(); + + /** + Returns the wxObject::m_refData pointer, i.e. the data referenced by this object. + + @see Ref(), UnRef(), wxObject::m_refData, SetRefData(), wxObjectRefData + */ + wxObjectRefData* GetRefData() const; + + /** + Determines whether this class is a subclass of (or the same class as) + the given class. + + Example: + + @code + bool tmp = obj->IsKindOf(CLASSINFO(wxFrame)); + @endcode + + @param info + A pointer to a class information object, which may be obtained + by using the ::CLASSINFO macro. + + @return @true if the class represented by info is the same class as this + one or is derived from it. + */ + bool IsKindOf(wxClassInfo* info); + + /** + Returns @true if this object has the same data pointer as @a obj. + + Notice that @true is returned if the data pointers are @NULL in both objects. + + This function only does a @e shallow comparison, i.e. it doesn't compare + the objects pointed to by the data pointers of these objects. + + @see @ref overview_refcount + */ + bool IsSameAs(const wxObject& obj); + + /** + Makes this object refer to the data in @a clone. + + @param clone + The object to 'clone'. + + @remarks First this function calls UnRef() on itself to decrement + (and perhaps free) the data it is currently referring to. + It then sets its own wxObject::m_refData to point to that of @a clone, + and increments the reference count inside the data. + + @see UnRef(), SetRefData(), GetRefData(), wxObjectRefData + */ + void Ref(const wxObject& clone); + + /** + Sets the wxObject::m_refData pointer. + + @see Ref(), UnRef(), GetRefData(), wxObjectRefData + */ + void SetRefData(wxObjectRefData* data); + + /** + Decrements the reference count in the associated data, and if it is zero, + deletes the data. + + The wxObject::m_refData member is set to @NULL. + + @see Ref(), SetRefData(), GetRefData(), wxObjectRefData + */ + void UnRef(); + + /** + Ensure that this object's data is not shared with any other object. + + If we have no data, it is created using CreateRefData() below, + if we have shared data, it is copied using CloneRefData(), + otherwise nothing is done. + */ + void UnShare(); + + /** + The @e delete operator is defined for debugging versions of the library only, + when the identifier @c __WXDEBUG__ is defined. + + It takes over memory deallocation, allowing wxDebugContext operations. + */ + void operator delete(void *buf); + + /** + The @e new operator is defined for debugging versions of the library only, when + the identifier @c __WXDEBUG__ is defined. + + It takes over memory allocation, allowing wxDebugContext operations. + */ + void* operator new(size_t size, const wxString& filename = NULL, int lineNum = 0); + +protected: + + /** + Pointer to an object which is the object's reference-counted data. + + @see Ref(), UnRef(), SetRefData(), GetRefData(), wxObjectRefData + */ + wxObjectRefData* m_refData; +}; + + + +/** + @class wxClassInfo + @wxheader{object.h} + + This class stores meta-information about classes. + + Instances of this class are not generally defined directly by an application, + but indirectly through use of macros such as ::DECLARE_DYNAMIC_CLASS and + ::IMPLEMENT_DYNAMIC_CLASS. + + @library{wxbase} + @category{rtti} + + @see @ref overview_rtti_classinfo, wxObject +*/ +class wxClassInfo +{ +public: + /** + Constructs a wxClassInfo object. + + The supplied macros implicitly construct objects of this class, so there is no + need to create such objects explicitly in an application. + */ + wxClassInfo(const wxChar* className, + const wxClassInfo* baseClass1, + const wxClassInfo* baseClass2, + int size, wxObjectConstructorFn fn); + + /** + Creates an object of the appropriate kind. + + @return @NULL if the class has not been declared dynamically creatable + (typically, this happens for abstract classes). + */ + wxObject* CreateObject() const; + + /** + Finds the wxClassInfo object for a class with the given @a name. + */ + static wxClassInfo* FindClass(wxChar* name); + + /** + Returns the name of the first base class (@NULL if none). + */ + wxChar* GetBaseClassName1() const; + + /** + Returns the name of the second base class (@NULL if none). + */ + wxChar* GetBaseClassName2() const; + + /** + Returns the string form of the class name. + */ + wxChar* GetClassName() const; + + /** + Returns the size of the class. + */ + int GetSize() const; + + /** + Initializes pointers in the wxClassInfo objects for fast execution of IsKindOf(). + Called in base wxWidgets library initialization. + */ + static void InitializeClasses(); + + /** + Returns @true if this class info can create objects of the associated class. + */ + bool IsDynamic() const; + + /** + Returns @true if this class is a kind of (inherits from) the given class. + */ + bool IsKindOf(wxClassInfo* info); +}; + + + +/** + @wxheader{object.h} + + This is helper template class primarily written to avoid memory leaks because of + missing calls to wxObjectRefData::DecRef(). + + Despite the name this template can actually be used as a smart pointer for any + class implementing the reference counting interface which only consists of the two + methods @b T::IncRef() and @b T::DecRef(). + + The difference to wxSharedPtr is that wxObjectDataPtr relies on the reference + counting to be in the class pointed to where instead wxSharedPtr implements the + reference counting itself. + + + @b Example: + + @code + class MyCarRefData: public wxObjectRefData + { + public: + MyCarRefData() { m_price = 0; } + + MyCarRefData( const MyCarRefData& data ) + : wxObjectRefData() + { + m_price = data.m_price; + } + + void SetPrice( int price ) { m_price = price; } + int GetPrice() { return m_price; } + + protected: + int m_price; + }; + + class MyCar + { + public: + MyCar( int price ) : m_data( new MyCarRefData ) + { + m_data->SetPrice( price ); + } + + MyCar& operator =( const MyCar& tocopy ) + { + m_data = tocopy.m_data; + return *this; + } + + bool operator == ( const MyCar& other ) const + { + if (m_data.get() == other.m_data.get()) return true; + return (m_data->GetPrice() == other.m_data->GetPrice()); + } + + void SetPrice( int price ) + { + UnShare(); + m_data->SetPrice( price ); + } + + int GetPrice() const + { + return m_data->GetPrice(); + } + + wxObjectDataPtr m_data; + + protected: + void UnShare() + { + if (m_data->GetRefCount() == 1) + return; + + m_data.reset( new MyCarRefData( *m_data ) ); + } + }; + @endcode + + + @library{wxbase} + @category{rtti,smartpointers} + + @see wxObject, wxObjectRefData, @ref overview_refcount, wxSharedPtr, + wxScopedPtr, wxWeakRef +*/ +class wxObjectDataPtr +{ +public: + /** + Constructor. + + @a ptr is a pointer to the reference counted object to which this class points. + If @a ptr is not NULL @b T::IncRef() will be called on the object. + */ + wxObjectDataPtr(T* ptr = NULL); + + /** + This copy constructor increases the count of the reference counted object to + which @a tocopy points and then this class will point to, as well. + */ + wxObjectDataPtr(const wxObjectDataPtr& tocopy); + + + /** + Decreases the reference count of the object to which this class points. + */ + ~wxObjectDataPtr(); + + /** + Gets a pointer to the reference counted object to which this class points. + */ + T* get() const; + + /** + Reset this class to ptr which points to a reference counted object and + calls T::DecRef() on the previously owned object. + */ + void reset(T *ptr); + + /** + Conversion to a boolean expression (in a variant which is not + convertable to anything but a boolean expression). + + If this class contains a valid pointer it will return @true, if it contains + a @NULL pointer it will return @false. + */ + operator unspecified_bool_type() const; + + /** + Returns a reference to the object. + + If the internal pointer is @NULL this method will cause an assert in debug mode. + */ + T& operator*() const; + + /** + Returns a pointer to the reference counted object to which this class points. + + If this the internal pointer is @NULL, this method will assert in debug mode. + */ + T* operator->() const; + + //@{ + /** + Assignment operator. + */ + wxObjectDataPtr& operator=(const wxObjectDataPtr& tocopy); + wxObjectDataPtr& operator=(T* ptr); + //@} +}; + + + +// ============================================================================ +// Global functions/macros +// ============================================================================ + +/** @ingroup group_funcmacro_rtti */ +//@{ + +/** + Returns a pointer to the wxClassInfo object associated with this class. + + @header{wx/object.h} +*/ +#define CLASSINFO( className ) + +/** + Used inside a class declaration to declare that the class should be made + known to the class hierarchy, but objects of this class cannot be created + dynamically. The same as DECLARE_ABSTRACT_CLASS(). + + @header{wx/object.h} +*/ +#define DECLARE_CLASS( className ) + +/** + Used inside a class declaration to declare that the class should be + made known to the class hierarchy, but objects of this class cannot be created + dynamically. The same as DECLARE_CLASS(). + + @header{wx/object.h} + + Example: + + @code + class wxCommand: public wxObject + { + DECLARE_ABSTRACT_CLASS(wxCommand) + + private: + ... + public: + ... + }; + @endcode +*/ +#define DECLARE_ABSTRACT_CLASS( className ) + +/** + Used inside a class declaration to make the class known to wxWidgets RTTI + system and also declare that the objects of this class should be + dynamically creatable from run-time type information. Notice that this + implies that the class should have a default constructor, if this is not + the case consider using DECLARE_CLASS(). + + @header{wx/object.h} + + Example: + + @code + class wxFrame: public wxWindow + { + DECLARE_DYNAMIC_CLASS(wxFrame) + + private: + const wxString& frameTitle; + public: + ... + }; + @endcode +*/ +#define DECLARE_DYNAMIC_CLASS( className ) + +/** + Used in a C++ implementation file to complete the declaration of a class + that has run-time type information. The same as IMPLEMENT_ABSTRACT_CLASS(). + + @header{wx/object.h} +*/ +#define IMPLEMENT_CLASS( className, baseClassName ) + +/** + Used in a C++ implementation file to complete the declaration of a class + that has run-time type information and two base classes. The same as + IMPLEMENT_ABSTRACT_CLASS2(). + + @header{wx/object.h} +*/ +#define IMPLEMENT_CLASS2( className, baseClassName1, baseClassName2 ) + +/** + Used in a C++ implementation file to complete the declaration of a class + that has run-time type information. The same as IMPLEMENT_CLASS(). + + @header{wx/object.h} + + Example: + + @code + IMPLEMENT_ABSTRACT_CLASS(wxCommand, wxObject) + + wxCommand::wxCommand(void) + { + ... + } + @endcode +*/ +#define IMPLEMENT_ABSTRACT_CLASS( className, baseClassName ) + +/** + Used in a C++ implementation file to complete the declaration of a class + that has run-time type information and two base classes. The same as + IMPLEMENT_CLASS2(). + + @header{wx/object.h} +*/ +#define IMPLEMENT_ABSTRACT_CLASS2( className, baseClassName1, baseClassName2 ) + +/** + Used in a C++ implementation file to complete the declaration of a class + that has run-time type information, and whose instances can be created + dynamically. + + @header{wx/object.h} + + Example: + + @code + IMPLEMENT_DYNAMIC_CLASS(wxFrame, wxWindow) + + wxFrame::wxFrame(void) + { + ... + } + @endcode +*/ +#define IMPLEMENT_DYNAMIC_CLASS( className, baseClassName ) + +/** + Used in a C++ implementation file to complete the declaration of a class + that has run-time type information, and whose instances can be created + dynamically. Use this for classes derived from two base classes. + + @header{wx/object.h} +*/ +#define IMPLEMENT_DYNAMIC_CLASS2( className, baseClassName1, baseClassName2 ) + +/** + Same as @c const_cast(x) if the compiler supports const cast or @c (T)x for + old compilers. Unlike wxConstCast(), the cast it to the type @c T and not to + T * and also the order of arguments is the same as for the standard cast. + + @header{wx/defs.h} + + @see wx_reinterpret_cast(), wx_static_cast() +*/ +#define wx_const_cast(T, x) + +/** + Same as @c reinterpret_cast(x) if the compiler supports reinterpret cast or + @c (T)x for old compilers. + + @header{wx/defs.h} + + @see wx_const_cast(), wx_static_cast() +*/ +#define wx_reinterpret_cast(T, x) + +/** + Same as @c static_cast(x) if the compiler supports static cast or @c (T)x for + old compilers. Unlike wxStaticCast(), there are no checks being done and + the meaning of the macro arguments is exactly the same as for the standard + static cast, i.e. @a T is the full type name and star is not appended to it. + + @header{wx/defs.h} + + @see wx_const_cast(), wx_reinterpret_cast(), wx_truncate_cast() +*/ +#define wx_static_cast(T, x) + +/** + This case doesn’t correspond to any standard cast but exists solely to make + casts which possibly result in a truncation of an integer value more + readable. + + @header{wx/defs.h} +*/ +#define wx_truncate_cast(T, x) + +/** + This macro expands into const_cast(ptr) if the compiler + supports const_cast or into an old, C-style cast, otherwise. + + @header{wx/defs.h} + + @see wx_const_cast(), wxDynamicCast(), wxStaticCast() +*/ +#define wxConstCast( ptr, classname ) + +/** + This macro returns the pointer @e ptr cast to the type @e classname * if + the pointer is of this type (the check is done during the run-time) or + @NULL otherwise. Usage of this macro is preferred over obsoleted + wxObject::IsKindOf() function. + + The @e ptr argument may be @NULL, in which case @NULL will be returned. + + @header{wx/object.h} + + Example: + + @code + wxWindow *win = wxWindow::FindFocus(); + wxTextCtrl *text = wxDynamicCast(win, wxTextCtrl); + if ( text ) + { + // a text control has the focus... + } + else + { + // no window has the focus or it is not a text control + } + @endcode + + @see @ref overview_rtti, wxDynamicCastThis(), wxConstCast(), wxStaticCast() +*/ +#define wxDynamicCast( ptr, classname ) + +/** + This macro is equivalent to wxDynamicCast(this, classname) but the latter provokes + spurious compilation warnings from some compilers (because it tests whether + @c this pointer is non-@NULL which is always true), so this macro should be + used to avoid them. + + @header{wx/object.h} + + @see wxDynamicCast() +*/ +#define wxDynamicCastThis( classname ) + +/** + This macro checks that the cast is valid in debug mode (an assert failure + will result if wxDynamicCast(ptr, classname) == @NULL) and then returns the + result of executing an equivalent of static_cast(ptr). + + @header{wx/object.h} + + @see wx_static_cast(), wxDynamicCast(), wxConstCast() +*/ +#define wxStaticCast( ptr, classname ) + +/** + Creates and returns an object of the given class, if the class has been + registered with the dynamic class system using DECLARE... and IMPLEMENT... + macros. + + @header{wx/object.h} +*/ +wxObject *wxCreateDynamicObject(const wxString& className); + +//@} + +/** @ingroup group_funcmacro_debug */ +//@{ + +/** + This is defined in debug mode to be call the redefined new operator + with filename and line number arguments. The definition is: + + @code + #define WXDEBUG_NEW new(__FILE__,__LINE__) + @endcode + + In non-debug mode, this is defined as the normal new operator. + + @header{wx/object.h} +*/ +#define WXDEBUG_NEW( arg ) + +//@} + diff --git a/interface/wx/odcombo.h b/interface/wx/odcombo.h new file mode 100644 index 0000000000..a47cd424e8 --- /dev/null +++ b/interface/wx/odcombo.h @@ -0,0 +1,209 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: odcombo.h +// Purpose: interface of wxOwnerDrawnComboBox +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + + +enum wxOwnerDrawnComboBoxPaintingFlags +{ + /** + Combo control is being painted, instead of a list item. + Argument item may be @c wxNOT_FOUND in this case. + */ + wxODCB_PAINTING_CONTROL = 0x0001, + + /** + An item with selection background is being painted. + DC text colour should already be correct. + */ + wxODCB_PAINTING_SELECTED = 0x0002 +}; + +/** + @class wxOwnerDrawnComboBox + @wxheader{odcombo.h} + + wxOwnerDrawnComboBox is a combobox with owner-drawn list items. + 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 + OnDrawItem(), OnMeasureItem() and OnMeasureItemWidth(). + + @beginStyleTable + @style{wxODCB_DCLICK_CYCLES} + Double-clicking cycles item if wxCB_READONLY is also used. + Synonymous with wxCC_SPECIAL_DCLICK. + @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. + @endStyleTable + + @see wxComboCtrl window styles and @ref overview_windowstyles. + + @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 + value of selection. + @endEventTable + + @see Events emitted by wxComboCtrl. + + @library{wxadv} + @category{ctrl} + + + @see wxComboCtrl, wxComboBox, wxVListBox, wxCommandEvent +*/ +class wxOwnerDrawnComboBox : public wxComboCtrl +{ +public: + /** + Default constructor. + */ + wxOwnerDrawnComboBox(); + + //@{ + /** + Constructor, creating and showing a owner-drawn combobox. + + @param parent + Parent window. Must not be @NULL. + @param id + 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 sized appropriately. + @param n + Number of strings with which to initialise the control. + @param choices + An array of strings with which to initialise the control. + @param style + Window style. See wxOwnerDrawnComboBox. + @param validator + Window validator. + @param name + Window name. + + @see Create(), wxValidator + */ + wxOwnerDrawnComboBox(wxWindow* parent, wxWindowID id, + const wxString& value = "", + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + int n = 0, + const wxString[] choices = NULL, + long style = 0, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "comboBox"); + wxOwnerDrawnComboBox(wxWindow* parent, wxWindowID id, + const wxString& value, + const wxPoint& pos, + const wxSize& size, + const wxArrayString& choices, + long style = 0, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "comboBox"); + //@} + + /** + Destructor, destroying the owner-drawn combobox. + */ + ~wxOwnerDrawnComboBox(); + + //@{ + /** + 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 = "", + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + int n, const wxString choices[], + long style = 0, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "comboBox"); + bool Create(wxWindow* parent, wxWindowID id, + const wxString& value, + const wxPoint& pos, + const wxSize& size, + const wxArrayString& choices, + long style = 0, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "comboBox"); + //@} + + /** + Returns index to the widest item in the list. + */ + int GetWidestItem() const; + + /** + Returns width of the widest item in the list. + */ + int GetWidestItemWidth() const; + + /** + 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(). + */ + 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. + + @param dc + The device context to use for drawing + @param rect + The bounding rectangle for the item being drawn (DC clipping + region is set to this rectangle before calling this function) + @param item + The index of the item to be drawn + @param flags + A combination of the ::wxOwnerDrawnComboBoxPaintingFlags enumeration values. + */ + void OnDrawItem(wxDC& dc, const wxRect& rect, int item, + int flags) const; + + /** + 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. + */ + wxCoord OnMeasureItem(size_t item) const; + + /** + 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/wx/palette.h b/interface/wx/palette.h new file mode 100644 index 0000000000..f1a9a4bdc0 --- /dev/null +++ b/interface/wx/palette.h @@ -0,0 +1,156 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: palette.h +// Purpose: interface of wxPalette +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxPalette + @wxheader{palette.h} + + A palette is a table that maps pixel values to RGB colours. It allows the + colours of a low-depth bitmap, for example, to be mapped to the available + colours in a display. The notion of palettes is becoming more and more + obsolete nowadays and only the MSW port is still using a native palette. + All other ports use generic code which is basically just an array of + colours. + + It is likely that in the future the only use for palettes within wxWidgets + will be for representing colour indeces from images (such as GIF or PNG). + The image handlers for these formats have been modified to create a palette + if there is such information in the original image file (usually 256 or less + colour images). See wxImage for more information. + + @library{wxcore} + @category{gdi} + + @stdobjects + ::wxNullPalette + + @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 @a n, one for each red, blue or + green component. + + @param palette + A pointer or reference to the palette to copy. + @param n + The number of indices in the palette. + @param red + An array of red values. + @param green + An array of green values. + @param blue + An array of blue values. + + @see Create() + */ + wxPalette(int n, const unsigned char* red, + const unsigned char* green, + const unsigned char* blue); + + /** + Destructor. + + @see @ref overview_refcount_destruct "reference-counted object destruction" + */ + ~wxPalette(); + + /** + Creates a palette from arrays of size @a n, one for each red, blue or + green component. + + @param n + The number of indices in the palette. + @param red + An array of red values. + @param green + An array of green values. + @param blue + An array of blue values. + + @return @true if the creation was successful, @false otherwise. + + @see wxPalette() + */ + bool Create(int n, const unsigned char* red, + const unsigned char* green, + const unsigned char* blue); + + /** + Returns number of entries in palette. + */ + int GetColoursCount() const; + + /** + Returns a pixel value (index into the palette) for the given RGB values. + + @param red + Red value. + @param green + Green value. + @param blue + Blue value. + + @return The nearest palette index or @c wxNOT_FOUND for unexpected errors. + + @see GetRGB() + */ + int GetPixel(unsigned char red, unsigned char green, + unsigned char blue) const; + + /** + Returns RGB values for a given palette index. + + @param pixel + The palette index. + @param red + Receives the red value. + @param green + Receives the green value. + @param blue + Receives the blue value. + + @return @true if the operation was successful. + + @see GetPixel() + */ + bool GetRGB(int pixel, const unsigned char* red, + const unsigned char* green, + const unsigned char* blue) const; + + /** + Returns @true if palette data is present. + */ + bool IsOk() const; + + /** + Assignment operator, using @ref overview_refcount. + */ + wxPalette& operator =(const wxPalette& palette); +}; + + +/** + An empty palette. +*/ +wxPalette wxNullPalette; + + diff --git a/interface/wx/panel.h b/interface/wx/panel.h new file mode 100644 index 0000000000..6e6e8b3d68 --- /dev/null +++ b/interface/wx/panel.h @@ -0,0 +1,136 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: panel.h +// Purpose: interface of wxPanel +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxPanel + @wxheader{panel.h} + + A panel is a window on which controls are placed. It is usually placed within + a frame. Its main feature over its parent class wxWindow is code for handling + child windows and TAB traversal. Since wxWidgets 2.9, there is support both + for TAB traversal implemented by wxWidgets itself as well as native TAB + traversal (such as for GTK 2.0). + + @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 @c wx/containr.h + and @c wx/panel.h to find out how this is achieved. + + @note if not all characters are being intercepted by your OnKeyDown or + OnChar handler, it may be because you are using the @c wxTAB_TRAVERSAL style, + which grabs some keypresses for use by child controls. + + @remarks By default, a panel has the same colouring as a dialog. + + @library{wxbase} + @category{miscwnd} + + @see wxDialog +*/ +class wxPanel : public wxWindow +{ +public: + + /** + Default constructor. + */ + wxPanel(); + + /** + Constructor. + + @param parent + The parent window. + @param id + An identifier for the panel. @c wxID_ANY is taken to mean a default. + @param pos + 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 @c wxDefaultSize indicates a default size, chosen by + either the windowing system or wxWidgets, depending on platform. + @param style + The window style. See wxPanel. + @param name + Window name. + + @see Create() + */ + 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. + */ + ~wxPanel(); + + /** + 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. + */ + bool AcceptsFocus() const; + + /** + Used for two-step panel construction. See wxPanel() for details. + */ + bool Create(wxWindow* parent, wxWindowID id = wxID_ANY, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxTAB_TRAVERSAL, + const wxString& name = "panel"); + + /** + Sends a wxInitDialogEvent, which in turn transfers data to the dialog via + validators. + + @see wxInitDialogEvent + */ + void InitDialog(); + + /** + The default handler for wxEVT_SYS_COLOUR_CHANGED. + + @param event + The colour change event. + + @remarks Changes the panel's colour to conform to the current settings + (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 + the notification to child windows and controls. + + @see wxSysColourChangedEvent + */ + void OnSysColourChanged(wxSysColourChangedEvent& event); + + /** + 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() + */ + virtual void SetFocus(); + + /** + In contrast to SetFocus() (see above) this will set the focus to the panel + even if there are child windows in the panel. This is only rarely needed. + */ + virtual void SetFocusIgnoringChildren(); +}; + diff --git a/interface/wx/pen.h b/interface/wx/pen.h new file mode 100644 index 0000000000..02368092d5 --- /dev/null +++ b/interface/wx/pen.h @@ -0,0 +1,479 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: pen.h +// Purpose: interface of wxPen* classes +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + The possible styles for a wxPen. +*/ +enum wxPenStyle +{ + wxPENSTYLE_INVALID = -1, + + wxPENSTYLE_SOLID, + /**< Solid style. */ + + wxPENSTYLE_DOT, + /**< Dotted style. */ + + wxPENSTYLE_LONG_DASH, + /**< Long dashed style. */ + + wxPENSTYLE_SHORT_DASH, + /**< Short dashed style. */ + + wxPENSTYLE_DOT_DASH, + /**< Dot and dash style. */ + + wxPENSTYLE_USER_DASH, + /**< Use the user dashes: see wxPen::SetDashes. */ + + wxPENSTYLE_TRANSPARENT, + /**< No pen is used. */ + + wxPENSTYLE_STIPPLE_MASK_OPAQUE, + /**< @todo WHAT's this? */ + + wxPENSTYLE_STIPPLE_MASK, + /**< @todo WHAT's this? */ + + wxPENSTYLE_STIPPLE, + /**< Use the stipple bitmap. */ + + wxPENSTYLE_BDIAGONAL_HATCH, + /**< Backward diagonal hatch. */ + + wxPENSTYLE_CROSSDIAG_HATCH, + /**< Cross-diagonal hatch. */ + + wxPENSTYLE_FDIAGONAL_HATCH, + /**< Forward diagonal hatch. */ + + wxPENSTYLE_CROSS_HATCH, + /**< Cross hatch. */ + + wxPENSTYLE_HORIZONTAL_HATCH, + /**< Horizontal hatch. */ + + wxPENSTYLE_VERTICAL_HATCH, + /**< Vertical hatch. */ + + wxPENSTYLE_FIRST_HATCH = wxPENSTYLE_BDIAGONAL_HATCH, + wxPENSTYLE_LAST_HATCH = wxPENSTYLE_VERTICAL_HATCH +}; + +/** + The possible join values of a wxPen. + + @todo use wxPENJOIN_ prefix +*/ +enum wxPenJoin +{ + wxJOIN_INVALID = -1, + + wxJOIN_BEVEL = 120, + wxJOIN_MITER, + wxJOIN_ROUND, +}; + + +/** + The possible cap values of a wxPen. + + @todo use wxPENCAP_ prefix +*/ +enum wxPenCap +{ + wxCAP_INVALID = -1, + + wxCAP_ROUND = 130, + wxCAP_PROJECTING, + wxCAP_BUTT +}; + + + +/** + @class wxPen + @wxheader{pen.h} + + A pen is a drawing tool for drawing outlines. It is used for drawing + lines and painting the outline of rectangles, ellipses, etc. + It has a colour, a width and a style. + + @note 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() + 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 + wxPenList::FindOrCreatePen(). + See wxPenList for more info. + + 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 + counting, are not affected. + + @library{wxcore} + @category{gdi} + + @stdobjects + @li ::wxNullPen + @li ::wxRED_PEN + @li ::wxCYAN_PEN + @li ::wxGREEN_PEN + @li ::wxBLACK_PEN + @li ::wxWHITE_PEN + @li ::wxTRANSPARENT_PEN + @li ::wxBLACK_DASHED_PEN + @li ::wxGREY_PEN + @li ::wxMEDIUM_GREY_PEN + @li ::wxLIGHT_GREY_PEN + + @see wxPenList, wxDC, wxDC::SetPen() +*/ +class wxPen : public wxGDIObject +{ +public: + /** + Default constructor. The pen will be uninitialised, and IsOk() will return @false. + */ + wxPen(); + + /** + Constructs a pen from a colour object, pen width and style. + + @param colour + A colour object. + @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 style + The style may be one of the ::wxPenStyle values. + + @remarks Different versions of Windows and different versions of other + platforms support very different subsets of the styles + above - there is no similarity even between Windows95 + and Windows98 - so handle with care. + + @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_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 + itself. This is because wxWidgets cannot know if a + pointer to the pen object is stored in an application + data structure, and there is a risk of double deletion. + */ + ~wxPen(); + + /** + 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() + */ + virtual wxPenCap GetCap() const; + + /** + Returns a reference to the pen colour. + + @see SetColour() + */ + virtual wxColour GetColour() const; + + /** + 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. + + @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 @c wxJOIN_BEVEL, @c + wxJOIN_ROUND and @c wxJOIN_MITER. + + The default is @c wxJOIN_ROUND. + + @see SetJoin() + */ + virtual wxPenJoin GetJoin() const; + + /** + Gets a pointer to the stipple bitmap. + + @see SetStipple() + */ + virtual wxBitmap* GetStipple() const; + + /** + Returns the pen style. + + @see wxPen(), SetStyle() + */ + virtual wxPenStyle GetStyle() const; + + /** + Returns the pen width. + + @see SetWidth() + */ + virtual int GetWidth() const; + + /** + Returns @true if the pen is initialised. + */ + bool IsOk() const; + + /** + 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() + */ + virtual void SetCap(wxPenCap capStyle); + + //@{ + /** + The pen's colour is changed to the given colour. + + @see GetColour() + */ + virtual void SetColour(wxColour& colour); + virtual void SetColour(unsigned char red, unsigned char green, unsigned char blue); + //@} + + /** + 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. + + @see GetDashes() + */ + virtual void SetDashes(int n, wxDash* dashes); + + /** + 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() + */ + virtual void SetJoin(wxPenJoin join_style); + + /** + Sets the bitmap for stippling. + + @see GetStipple() + */ + virtual void SetStipple(wxBitmap* stipple); + + /** + Set the pen style. + + @see wxPen() + */ + virtual void SetStyle(wxPenStyle style); + + /** + Sets the pen width. + + @see GetWidth() + */ + virtual void SetWidth(int width); + + /** + Inequality operator. + + See @ref overview_refcount_equality "reference-counted object comparison" for + more info. + */ + bool operator !=(const wxPen& pen); + + /** + Assignment operator, using @ref overview_refcount. + */ + wxPen operator =(const wxPen& pen); + + /** + Equality operator. + + See @ref overview_refcount_equality "reference-counted object comparison" for + more info. + */ + bool operator ==(const wxPen& pen); +}; + +/** + An empty pen. +*/ +wxPen wxNullPen; + +/** + Red pen. +*/ +wxPen* wxRED_PEN; + +/** + Cyan pen. +*/ +wxPen* wxCYAN_PEN; + +/** + Green pen. +*/ +wxPen* wxGREEN_PEN; + +/** + Black pen. +*/ +wxPen* wxBLACK_PEN; + +/** + White pen. +*/ +wxPen* wxWHITE_PEN; + +/** + Transparent pen. +*/ +wxPen* wxTRANSPARENT_PEN; + +/** + Black dashed pen. +*/ +wxPen* wxBLACK_DASHED_PEN; + +/** + Grey pen. +*/ +wxPen* wxGREY_PEN; + +/** + Medium-grey pen. +*/ +wxPen* wxMEDIUM_GREY_PEN; + +/** + Light-grey pen. +*/ +wxPen* wxLIGHT_GREY_PEN; + + + +/** + @class wxPenList + @wxheader{gdicmn.h} + + There is only one instance of this class: ::wxThePenList. + Use this object to search for a previously created pen of the desired + type and create it if not already found. In some windowing systems, + the pen may be a scarce resource, so it can pay to reuse old + resources if possible. When an application finishes, all pens will + be deleted and their resources freed, eliminating the possibility of + 'memory leaks'. However, it is best not to rely on this automatic + cleanup because it can lead to double deletion in some circumstances. + + There are two mechanisms in recent versions of wxWidgets which make the + pen list less useful than it once was. Under Windows, scarce resources + are cleaned up internally if they are not being used. Also, a referencing + counting mechanism applied to all GDI objects means that some sharing + of underlying resources is possible. You don't have to keep track of pointers, + working out when it is safe delete a pen, because the referencing counting does + it for you. For example, you can set a pen in a device context, and then + immediately delete the pen you passed, because the pen is 'copied'. + + So you may find it easier to ignore the pen list, and instead create + and copy pens as you see fit. If your Windows resource meter suggests + your application is using too many resources, you can resort to using + GDI lists to share objects explicitly. + + The only compelling use for the pen list is for wxWidgets to keep + track of pens in order to clean them up on exit. It is also kept for + backward compatibility with earlier versions of wxWidgets. + + @library{wxcore} + @category{gdi} + + @stdobjects + ::wxThePenList + + @see wxPen +*/ +class wxPenList +{ +public: + /** + Constructor. The application should not construct its own pen list: + use the object pointer ::wxThePenList. + */ + wxPenList(); + + /** + Finds a pen with the specified attributes and returns it, else creates a + new pen, adds it to the pen list, and returns it. + + @param colour + Colour object. + @param width + Width of pen. + @param style + Pen style. See ::wxPenStyle for a list of styles. + */ + wxPen* FindOrCreatePen(const wxColour& colour, + int width = 1, + wxPenStyle style = wxPENSTYLE_SOLID); +}; + +/** + The global list of wxPen objects ready to be re-used (for better performances). +*/ +wxPenList* wxThePenList; + diff --git a/interface/wx/pickerbase.h b/interface/wx/pickerbase.h new file mode 100644 index 0000000000..8fca81bdd4 --- /dev/null +++ b/interface/wx/pickerbase.h @@ -0,0 +1,123 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: pickerbase.h +// Purpose: interface of wxPickerBase +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxPickerBase + @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. + + @beginStyleTable + @style{wxPB_USE_TEXTCTRL} + Creates a text control to the left of the picker which is + completely managed by this wxPickerBase class. + @endStyleTable + + @library{wxcore} + @category{pickers} + + @see wxColourPickerCtrl +*/ +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; + + /** + Returns the proportion value of the picker. + */ + int GetPickerCtrlProportion() const; + + /** + Returns a pointer to the text control handled by this window or @NULL if the + @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 @c + wxPB_USE_TEXTCTRL style was given when creating this control). + */ + bool HasTextCtrl() const; + + /** + Returns @true if the picker control is growable. + */ + bool IsPickerCtrlGrowable() const; + + /** + 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); + + /** + Sets the picker control as growable when @c grow is @true. + */ + void SetPickerCtrlGrowable(bool grow = true); + + /** + Sets the proportion value of the picker. + + Look at the detailed description of wxPickerBase for more info. + */ + 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 detailed description of wxPickerBase for more info. + + This function can be used only when HasTextCtrl() returns @true. + */ + void SetTextCtrlProportion(int prop); +}; + diff --git a/interface/wx/platform.h b/interface/wx/platform.h new file mode 100644 index 0000000000..73ff643e01 --- /dev/null +++ b/interface/wx/platform.h @@ -0,0 +1,46 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: platform.h +// Purpose: interface of global functions +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** @ingroup group_funcmacro_version */ +//@{ + +/** + Returns @true if the compiler being used is GNU C++ and its version is + at least major.minor or greater. Returns @false otherwise. + + @header{wx/platform.h} +*/ +#define wxCHECK_GCC_VERSION( major, minor ) + +/** + Returns @true if the compiler being used is Sun CC Pro and its version is + at least major.minor or greater. Returns @false otherwise. + + @header{wx/platform.h} +*/ +#define wxCHECK_SUNCC_VERSION( major, minor ) + +/** + Returns @true if the compiler being used is Visual C++ and its version is + at least major or greater. Returns @false otherwise. + + @header{wx/platform.h} +*/ +#define wxCHECK_VISUALC_VERSION( major ) + +/** + Returns @true if the version of w32api headers used is major.minor or + greater. Otherwise, and also if we are not compiling with MinGW32/Cygwin + under Win32 at all, returns @false. + + @header{wx/platform.h} +*/ +#define wxCHECK_W32API_VERSION( major, minor ) + +//@} + diff --git a/interface/wx/platinfo.h b/interface/wx/platinfo.h new file mode 100644 index 0000000000..71439b625d --- /dev/null +++ b/interface/wx/platinfo.h @@ -0,0 +1,394 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: platinfo.h +// Purpose: interface of wxPlatformInfo +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + + +/** + 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. +*/ +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 +}; + +/** + 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. +*/ +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 +}; + + +/** + The architecture of the operating system + (regardless of the build environment of wxWidgets library - see ::wxIsPlatform64bit() + documentation for more info). +*/ +enum wxArchitecture +{ + wxARCH_INVALID = -1, //!< returned on error + + wxARCH_32, //!< 32 bit + wxARCH_64, + + wxARCH_MAX +}; + + +/** + The endian-ness of the machine. +*/ +enum wxEndianness +{ + wxENDIAN_INVALID = -1, //!< returned on error + + wxENDIAN_BIG, //!< 4321 + wxENDIAN_LITTLE, //!< 1234 + wxENDIAN_PDP, //!< 3412 + + wxENDIAN_MAX +}; + + +/** + @class wxPlatformInfo + @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. + + @library{wxbase} + @category{misc} + + @see ::wxGetOsVersion(), wxIsPlatformLittleEndian(), wxIsPlatform64Bit(), + wxAppTraits +*/ +class wxPlatformInfo : public wxObject +{ +public: + + /** + 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, + wxOperatingSystemId id = wxOS_UNKNOWN, + int osMajor = -1, + int osMinor = -1, + wxArchitecture arch = wxARCH_INVALID, + wxEndianness endian = wxENDIAN_INVALID); + + + /** + Returns @true if the OS version is at least @c major.minor. + + @see GetOSMajorVersion(), GetOSMinorVersion(), + CheckToolkitVersion() + */ + bool CheckOSVersion(int major, int minor) const; + + /** + Returns @true if the toolkit version is at least @c major.minor. + + @see GetToolkitMajorVersion(), + GetToolkitMinorVersion(), CheckOSVersion() + */ + bool CheckToolkitVersion(int major, int minor) const; + + /** + 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 + @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 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; + + /** + 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 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(), CheckOSVersion() + */ + int GetOSMajorVersion() const; + + /** + Returns the run-time minor version of the OS associated with this + wxPlatformInfo instance. + + @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. + */ + wxString GetOperatingSystemFamilyName() const; + + /** + 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. + */ + wxString GetOperatingSystemIdName() const; + + + /** + 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. + */ + wxString GetPortIdName() const; + + /** + 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 @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() + */ + int GetToolkitMajorVersion() const; + + /** + Returns the run-time minor version of the toolkit associated with this + wxPlatformInfo instance. + + 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() + */ + int GetToolkitMinorVersion() const; + + /** + Returns @true if this instance is fully initialized with valid values. + */ + bool IsOk() const; + + /** + Returns @true if this wxPlatformInfo describes wxUniversal build. + */ + bool IsUsingUniversalWidgets() const; + + /** + Sets the architecture enum value associated with this wxPlatformInfo instance. + */ + void SetArchitecture(wxArchitecture n); + + /** + Sets the endianness enum value associated with this wxPlatformInfo instance. + */ + void SetEndianness(wxEndianness n); + + /** + Sets the version of the operating system associated with this wxPlatformInfo + instance. + */ + void SetOSVersion(int major, int minor); + + /** + Sets the operating system associated with this wxPlatformInfo instance. + */ + void SetOperatingSystemId(wxOperatingSystemId n); + + /** + Sets the wxWidgets port ID associated with this wxPlatformInfo instance. + */ + void SetPortId(wxPortId n); + + /** + Sets the version of the toolkit associated with this wxPlatformInfo instance. + */ + void SetToolkitVersion(int major, int minor); + + /** + Inequality operator. Tests all class' internal variables. + */ + bool operator!=(const wxPlatformInfo& t) const; + + /** + Equality operator. Tests all class' internal variables. + */ + bool operator==(const wxPlatformInfo& t) const; +}; + diff --git a/interface/wx/popupwin.h b/interface/wx/popupwin.h new file mode 100644 index 0000000000..870ec9feb4 --- /dev/null +++ b/interface/wx/popupwin.h @@ -0,0 +1,50 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: popupwind.h +// Purpose: interface of wxPoppWindow +// Author: wxWidgets team +// RCS-ID: $Id:$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxPopupWindow + @wxheader{popupwin.h} + + A special kind of top level window used for popup menus, + combobox popups and such. + + @library{wxcore} + @category{managedwnd} + + @see wxDialog, wxFrame +*/ + +class wxPopupWindow: public wxNonOwnedWindow +{ +public: + + /** + Constructor + */ + wxPopupWindow(wxWindow *parent, int flags = wxBORDER_NONE); + + /** + Create method for two-step creation + */ + bool Create(wxWindow *parent, int flags = wxBORDER_NONE); + + /** + Move the popup window to the right position, i.e. such that it is + entirely visible. + + The popup is positioned at ptOrigin + size if it opens below and to the + right (default), at ptOrigin - sizePopup if it opens above and to the + left etc. + + @param ptOrigin + Must be given in screen coordinates! + */ + virtual void Position(const wxPoint& ptOrigin, + const wxSize& size); +}; + diff --git a/interface/wx/position.h b/interface/wx/position.h new file mode 100644 index 0000000000..ba5dfbd499 --- /dev/null +++ b/interface/wx/position.h @@ -0,0 +1,87 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: position.h +// Purpose: interface of wxPosition +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxPosition + @wxheader{position.h} + + This class represents the position of an item in any kind of grid of rows and + columns such as wxGridBagSizer, or wxHVScrolledWindow. + + @todo rename this class to wxItemPosition or such, wxPosition is too generic + + @library{wxbase} + @category{data} + + @see wxPoint, wxSize +*/ +class wxPosition +{ +public: + + /** + Construct a new wxPosition, setting the row and column to the + default value of (0, 0). + */ + wxPosition(); + + /** + Construct a new wxPosition, setting the row and column to the + value of (@a row, @a col). + */ + wxPosition(int row, int col); + + /** + A synonym for GetColumn(). + */ + int GetCol() const; + + /** + Get the current row value. + */ + int GetColumn() const; + + /** + Get the current row value. + */ + int GetRow() const; + + /** + A synonym for SetColumn(). + */ + void SetCol(int column); + + /** + Set a new column value. + */ + void SetColumn(int column); + + /** + Set a new row value. + */ + void SetRow(int row); + + + /** + @name Miscellaneous operators + + @{ + */ + bool operator ==(const wxPosition& p) const; + bool operator !=(const wxPosition& p) const; + wxPosition& operator +=(const wxPosition& p) const; + wxPosition& operator -=(const wxPosition& p) const; + wxPosition& operator +=(const wxSize& s) const; + wxPosition& operator -=(const wxSize& s) const; + wxPosition& operator +(const wxPosition& p) const; + wxPosition& operator -(const wxPosition& p) const; + wxPosition& operator +(const wxSize& s) const; + wxPosition& operator -(const wxSize& s) const; + //@} +}; + diff --git a/interface/wx/power.h b/interface/wx/power.h new file mode 100644 index 0000000000..b54808f562 --- /dev/null +++ b/interface/wx/power.h @@ -0,0 +1,54 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: power.h +// Purpose: interface of wxPowerEvent +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxPowerEvent + @wxheader{power.h} + + The power events are generated when the system power state changes, e.g. the + system is suspended, hibernated, plugged into or unplugged from the wall socket + and so on. + + Notice that currently only suspend and resume events are generated and only + under MS Windows platform. To avoid the need to change the code using this + event later when these events are implemented on the other platforms please + use the test ifdef wxHAS_POWER_EVENTS instead of directly testing for + the platform in your code: this symbol will be defined for all platforms + supporting the power events. + + @beginEventTable{wxPowerEvent} + @event{EVT_POWER_SUSPENDING(func)}: + System is about to be suspended, this event can be vetoed to prevent + suspend from taking place. + @event{EVT_POWER_SUSPENDED(func)}: + System is about to suspend: normally the application should quickly + (i.e. without user intervention) close all the open files and network + connections here, possibly remembering them to reopen them later when + the system is resumed. + @event{EVT_POWER_SUSPEND_CANCEL(func)}: + System suspension was cancelled because some application vetoed it. + @event{EVT_POWER_RESUME(func)}: + System resumed from suspend: normally the application should restore + the state in which it had been before the suspension. + @endEventTable + + @library{wxbase} + @category{events} + + @see ::wxGetPowerType(), ::wxGetBatteryState() +*/ +class wxPowerEvent : public wxEvent +{ +public: + /** + Call this to prevent suspend from taking place in @c wxEVT_POWER_SUSPENDING + handler (it is ignored for all the others). + */ + void Veto(); +}; + diff --git a/interface/wx/print.h b/interface/wx/print.h new file mode 100644 index 0000000000..8ad4c4512b --- /dev/null +++ b/interface/wx/print.h @@ -0,0 +1,816 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: print.h +// Purpose: interface of wxPreviewControlBar +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxPreviewControlBar + @wxheader{print.h} + + This is the default implementation of the preview control bar, a panel + with buttons and a zoom control. + + You can derive a new class from this and override some or all member functions + to change the behaviour and appearance; or you can leave it as it is. + + @library{wxbase} + @category{printing} + + @see wxPreviewFrame, wxPreviewCanvas, wxPrintPreview +*/ +class wxPreviewControlBar : public wxPanel +{ +public: + + /** + Constructor. + + The @a buttons parameter may be a combination of the following, using the bitwise + 'or' operator: + + @beginFlagTable + @flag{wxPREVIEW_PRINT} + Create a print button. + @flag{wxPREVIEW_NEXT} + Create a next page button. + @flag{wxPREVIEW_PREVIOUS} + Create a previous page button. + @flag{wxPREVIEW_ZOOM} + Create a zoom control. + @flag{wxPREVIEW_DEFAULT} + Equivalent to a combination of @c wxPREVIEW_PREVIOUS, @c wxPREVIEW_NEXT + and @c wxPREVIEW_ZOOM. + @endFlagTable + */ + wxPreviewControlBar(wxPrintPreview* preview, + long buttons, + wxWindow* parent, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0, + const wxString& name = "panel"); + + /** + Destructor. + */ + ~wxPreviewControlBar(); + + /** + Creates buttons, according to value of the button style flags. + + @todo which flags?? + */ + void CreateButtons(); + + /** + Gets the print preview object associated with the control bar. + */ + wxPrintPreview* GetPrintPreview(); + + /** + Gets the current zoom setting in percent. + */ + int GetZoomControl(); + + /** + Sets the zoom control. + */ + void SetZoomControl(int percent); + +}; + + + +/** + @class wxPreviewCanvas + @wxheader{print.h} + + A preview canvas is the default canvas used by the print preview + system to display the preview. + + @library{wxbase} + @category{printing} + + @see wxPreviewFrame, wxPreviewControlBar, wxPrintPreview +*/ +class wxPreviewCanvas : public wxScrolledWindow +{ +public: + /** + Constructor. + */ + wxPreviewCanvas(wxPrintPreview* preview, wxWindow* parent, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0, + const wxString& name = "canvas"); + + /** + Destructor. + */ + ~wxPreviewCanvas(); + + /** + Calls wxPrintPreview::PaintPage() to refresh the canvas. + */ + void OnPaint(wxPaintEvent& event); +}; + + + +/** + @class wxPreviewFrame + @wxheader{print.h} + + This class provides the default method of managing the print preview interface. + Member functions may be overridden to replace functionality, or the + class may be used without derivation. + + @library{wxbase} + @category{printing} + + @see wxPreviewCanvas, wxPreviewControlBar, wxPrintPreview +*/ +class wxPreviewFrame : public wxFrame +{ +public: + /** + Constructor. + + Pass a print preview object plus other normal frame arguments. + The print preview object will be destroyed by the frame when it closes. + */ + wxPreviewFrame(wxPrintPreview* preview, wxWindow* parent, + const wxString& title, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size size = wxDefaultSize, + long style = wxDEFAULT_FRAME_STYLE, + const wxString& name = "frame"); + + /** + Destructor. + */ + ~wxPreviewFrame(); + + /** + Creates a wxPreviewCanvas. + + Override this function to allow a user-defined preview canvas object + to be created. + */ + void CreateCanvas(); + + /** + Creates a wxPreviewControlBar. + + Override this function to allow a user-defined preview control bar object + to be created. + */ + void CreateControlBar(); + + /** + Creates the preview canvas and control bar, and calls wxWindow::MakeModal(@true) + to disable other top-level windows in the application. + + This function should be called by the application prior to showing the frame. + */ + void Initialize(); + + /** + Enables the other frames in the application, and deletes the print preview + object, implicitly deleting any printout objects associated with the print + preview object. + */ + void OnCloseWindow(wxCloseEvent& event); +}; + + + +/** + @class wxPrintPreview + @wxheader{print.h} + + Objects of this class manage the print preview process. The object is passed + a wxPrintout object, and the wxPrintPreview object itself is passed to + a wxPreviewFrame object. Previewing is started by initializing and showing + the preview frame. Unlike wxPrinter::Print(), flow of control returns to the + application immediately after the frame is shown. + + @note + The preview shown is only exact on Windows. On other platforms, the wxDC + used for preview is different from what is used for printing and the + results may be significantly different, depending on how is the output + created. In particular, printing code relying on wxDC::GetTextExtent() + heavily (for example, wxHtmlEasyPrinting and other wxHTML classes do) is + affected. It is recommended to use native preview functionality on + platforms that offer it (OS X, GTK+). + + @library{wxbase} + @category{printing} + + @see @ref overview_printing, wxPrinterDC, wxPrintDialog, wxPrintout, wxPrinter, + wxPreviewCanvas, wxPreviewControlBar, wxPreviewFrame +*/ +class wxPrintPreview : public wxObject +{ +public: + /** + Constructor. + + Pass a printout object, an optional printout object to be used for actual + printing, and the address of an optional block of printer data, which will + be copied to the print preview object's print data. + + If @a printoutForPrinting is non-@NULL, a @b "Print..." button will be placed on + the preview frame so that the user can print directly from the preview interface. + + @remarks + Do not explicitly delete the printout objects once this destructor has been + called, since they will be deleted in the wxPrintPreview constructor. + The same does not apply to the @a data argument. + + Use IsOk() to check whether the wxPrintPreview object was created correctly. + */ + wxPrintPreview(wxPrintout* printout, + wxPrintout* printoutForPrinting, + wxPrintData* data = NULL); + + /** + Destructor. + + Deletes both print preview objects, so do not destroy these objects + in your application. + */ + ~wxPrinter(); + + /** + Gets the preview window used for displaying the print preview image. + */ + wxPreviewCanvas* GetCanvas(); + + /** + Gets the page currently being previewed. + */ + int GetCurrentPage(); + + /** + Gets the frame used for displaying the print preview canvas + and control bar. + */ + wxFrame* GetFrame(); + + /** + Returns the maximum page number. + */ + int GetMaxPage(); + + /** + Returns the minimum page number. + */ + int GetMinPage(); + + /** + Gets the preview printout object associated with the wxPrintPreview object. + */ + wxPrintout* GetPrintout(); + + /** + Gets the printout object to be used for printing from within the preview + interface, + or @NULL if none exists. + */ + wxPrintout* GetPrintoutForPrinting(); + + /** + Returns @true if the wxPrintPreview is valid, @false otherwise. + + It could return @false if there was a problem initializing the printer + device context (current printer not set, for example). + */ + bool IsOk(); + + /** + This refreshes the preview window with the preview image. + It must be called from the preview window's OnPaint member. + + The implementation simply blits the preview bitmap onto + the canvas, creating a new preview bitmap if none exists. + */ + bool PaintPage(wxPreviewCanvas* canvas, wxDC dc); + + /** + Invokes the print process using the second wxPrintout object + supplied in the wxPrintPreview constructor. + Will normally be called by the @b Print... panel item on the + preview frame's control bar. + + Returns @false in case of error -- call wxPrinter::GetLastError() + to get detailed information about the kind of the error. + */ + bool Print(bool prompt); + + /** + Renders a page into a wxMemoryDC. Used internally by wxPrintPreview. + */ + bool RenderPage(int pageNum); + + /** + Sets the window to be used for displaying the print preview image. + */ + void SetCanvas(wxPreviewCanvas* window); + + /** + Sets the current page to be previewed. + */ + void SetCurrentPage(int pageNum); + + /** + Sets the frame to be used for displaying the print preview canvas + and control bar. + */ + void SetFrame(wxFrame* frame); + + /** + Associates a printout object with the wxPrintPreview object. + */ + void SetPrintout(wxPrintout* printout); + + /** + Sets the percentage preview zoom, and refreshes the preview canvas accordingly. + */ + void SetZoom(int percent); +}; + + + +/** + @class wxPrinter + @wxheader{print.h} + + This class represents the Windows or PostScript printer, and is the vehicle + through which printing may be launched by an application. + + Printing can also be achieved through using of lower functions and classes, + but this and associated classes provide a more convenient and general method + of printing. + + @library{wxbase} + @category{printing} + + @see @ref overview_printing, wxPrinterDC, wxPrintDialog, wxPrintout, wxPrintPreview +*/ +class wxPrinter : public wxObject +{ +public: + /** + Constructor. + + Pass an optional pointer to a block of print dialog data, which will be + copied to the printer object's local data. + + @see wxPrintDialogData, wxPrintData + */ + wxPrinter(wxPrintDialogData* data = NULL); + + /** + Creates the default printing abort window, with a cancel button. + */ + void CreateAbortWindow(wxWindow* parent, wxPrintout* printout); + + /** + Returns @true if the user has aborted the print job. + */ + bool GetAbort(); + + /** + Return last error. Valid after calling Print(), PrintDialog() or + wxPrintPreview::Print(). + + These functions set last error to @c wxPRINTER_NO_ERROR if no error happened. + + Returned value is one of the following: + + @beginTable + @row2col{wxPRINTER_NO_ERROR, No error happened.} + @row2col{wxPRINTER_CANCELLED, The user cancelled printing.} + @row2col{wxPRINTER_ERROR, There was an error during printing.} + @endTable + */ + static wxPrinterError GetLastError(); + + /** + Returns the @ref overview_printing_printdata "print data" associated with + the printer object. + */ + wxPrintDialogData& GetPrintDialogData(); + + /** + Starts the printing process. Provide a parent window, a user-defined wxPrintout + object which controls the printing of a document, and whether the print dialog + should be invoked first. + + Print() could return @false if there was a problem initializing the printer device + context (current printer not set, for example) or the user cancelled printing. + Call GetLastError() to get detailed information about the kind of the error. + */ + bool Print(wxWindow* parent, wxPrintout* printout, + bool prompt = true); + + /** + Invokes the print dialog. + + If successful (the user did not press Cancel and no error occurred), + a suitable device context will be returned; otherwise @NULL is returned; + call GetLastError() to get detailed information about the kind of the error. + + @remarks + The application must delete this device context to avoid a memory leak. + */ + wxDC* PrintDialog(wxWindow* parent); + + /** + Default error-reporting function. + */ + void ReportError(wxWindow* parent, wxPrintout* printout, + const wxString& message); + + /** + Invokes the print setup dialog. + + @remarks + The setup dialog is obsolete from Windows 95, though retained + for backward compatibility. + */ + bool Setup(wxWindow* parent); +}; + + + +/** + @class wxPrintout + @wxheader{print.h} + + This class encapsulates the functionality of printing out an application document. + + A new class must be derived and members overridden to respond to calls such as + OnPrintPage() and HasPage() and to render the print image onto an associated wxDC. + Instances of this class are passed to wxPrinter::Print() or + to a wxPrintPreview object to initiate printing or previewing. + + Your derived wxPrintout is responsible for drawing both the preview image and + the printed page. If your windows' drawing routines accept an arbitrary DC as an + argument, you can re-use those routines within your wxPrintout subclass to draw + the printout image. You may also add additional drawing elements within your + wxPrintout subclass, like headers, footers, and/or page numbers. However, the + image on the printed page will often differ from the image drawn on the screen, + as will the print preview image -- not just in the presence of headers and + footers, but typically in scale. A high-resolution printer presents a much + larger drawing surface (i.e., a higher-resolution DC); a zoomed-out preview + image presents a much smaller drawing surface (lower-resolution DC). By using + the routines FitThisSizeToXXX() and/or MapScreenSizeToXXX() within your + wxPrintout subclass to set the user scale and origin of the associated DC, you + can easily use a single drawing routine to draw on your application's windows, + to create the print preview image, and to create the printed paper image, and + achieve a common appearance to the preview image and the printed page. + + @library{wxbase} + @category{printing} + + @see @ref overview_printing, wxPrinterDC, wxPrintDialog, wxPageSetupDialog, + wxPrinter, wxPrintPreview +*/ +class wxPrintout : public wxObject +{ +public: + /** + Constructor. + + Pass an optional title argument - the current filename would be a + good idea. This will appear in the printing list (at least in MSW) + */ + wxPrintout(const wxString& title = "Printout"); + + /** + Destructor. + */ + ~wxPrintout(); + + /** + Set the user scale and device origin of the wxDC associated with this wxPrintout + so that the given image size fits entirely within the page rectangle and the + origin is at the top left corner of the page rectangle. + + On MSW and Mac, the page rectangle is the printable area of the page. + On other platforms and PostScript printing, the page rectangle is the entire paper. + + Use this if you want your printed image as large as possible, but with the caveat + that on some platforms, portions of the image might be cut off at the edges. + */ + void FitThisSizeToPage(const wxSize& imageSize); + + /** + Set the user scale and device origin of the wxDC associated with this wxPrintout + so that the given image size fits entirely within the page margins set in the + given wxPageSetupDialogData object. + + This function provides the greatest consistency across all platforms because it + does not depend on having access to the printable area of the paper. + + @remarks + On Mac, the native wxPageSetupDialog does not let you set the page margins; + you'll have to provide your own mechanism, or you can use the Mac-only class + wxMacPageMarginsDialog. + */ + void FitThisSizeToPageMargins(const wxSize& imageSize, + const wxPageSetupDialogData& pageSetupData); + + /** + Set the user scale and device origin of the wxDC associated with this wxPrintout + so that the given image size fits entirely within the paper and the origin is at + the top left corner of the paper. + + Use this if you're managing your own page margins. + + @note + With most printers, the region around the edges of the paper are not + printable so that the edges of the image could be cut off. + + */ + void FitThisSizeToPaper(const wxSize& imageSize); + + /** + Returns the device context associated with the printout (given to the printout + at start of printing or previewing). + + The application can use GetDC() to obtain a device context to draw on. + + This will be a wxPrinterDC if printing under Windows or Mac, a wxPostScriptDC + if printing on other platforms, and a wxMemoryDC if previewing. + */ + wxDC* GetDC(); + + /** + Return the rectangle corresponding to the page margins specified by the given + wxPageSetupDialogData object in the associated wxDC's logical coordinates for + the current user scale and device origin. + + The page margins are specified with respect to the edges of the paper on all + platforms. + */ + wxRect GetLogicalPageMarginsRect(const wxPageSetupDialogData& pageSetupData); + + /** + Return the rectangle corresponding to the page in the associated wxDC 's + logical coordinates for the current user scale and device origin. + + On MSW and Mac, this will be the printable area of the paper. + On other platforms and PostScript printing, this will be the full paper + rectangle. + */ + wxRect GetLogicalPageRect(); + + /** + Return the rectangle corresponding to the paper in the associated wxDC 's + logical coordinates for the current user scale and device origin. + */ + wxRect GetLogicalPaperRect(); + + /** + Returns the number of pixels per logical inch of the printer device context. + + Dividing the printer PPI by the screen PPI can give a suitable scaling factor + for drawing text onto the printer. + + Remember to multiply this by a scaling factor to take the preview DC size into + account. + Or you can just use the FitThisSizeToXXX() and MapScreenSizeToXXX routines below, + which do most of the scaling calculations for you. + + @beginWxPythonOnly + This method returns the output-only parameters as a tuple. + @endWxPythonOnly + */ + void GetPPIPrinter(int* w, int* h); + + /** + Returns the number of pixels per logical inch of the screen device context. + + Dividing the printer PPI by the screen PPI can give a suitable scaling factor + for drawing text onto the printer. + + If you are doing your own scaling, remember to multiply this by a scaling + factor to take the preview DC size into account. + + @beginWxPythonOnly + This method returns the output-only parameters as a tuple. + @endWxPythonOnly + */ + void GetPPIScreen(int* w, int* h); + + /** + Called by the framework to obtain information from the application about minimum + and maximum page values that the user can select, and the required page range to + be printed. + + By default this returns (1, 32000) for the page minimum and maximum values, and + (1, 1) for the required page range. + + @a minPage must be greater than zero and @a maxPage must be greater + than @a minPage. + + @beginWxPythonOnly + When this method is implemented in a derived Python class, it should be designed + to take no parameters (other than the self reference) and to return a tuple of + four integers. + @endWxPythonOnly + */ + void GetPageInfo(int* minPage, int* maxPage, int* pageFrom, + int* pageTo); + + /** + Returns the size of the printer page in millimetres. + + @beginWxPythonOnly + This method returns the output-only parameters as a tuple. + @endWxPythonOnly + */ + void GetPageSizeMM(int* w, int* h); + + /** + Returns the size of the printer page in pixels, called the page rectangle. + + The page rectangle has a top left corner at (0,0) and a bottom right corner at + (w,h). These values may not be the same as the values returned from + wxDC::GetSize(); if the printout is being used for + previewing, a memory device context is used, which uses a bitmap size reflecting + the current preview zoom. The application must take this discrepancy into + account if previewing is to be supported. + + @beginWxPythonOnly + This method returns the output-only parameters as a tuple. + @endWxPythonOnly + */ + void GetPageSizePixels(int* w, int* h); + + /** + Returns the rectangle that corresponds to the entire paper in pixels, called the + paper rectangle. + + This distinction between paper rectangle and page rectangle reflects the fact that + most printers cannot print all the way to the edge of the paper. + The page rectangle is a rectangle whose top left corner is at (0,0) and whose width + and height are given by wxDC::GetPageSizePixels(). + + On MSW and Mac, the page rectangle gives the printable area of the paper, while the + paper rectangle represents the entire paper, including non-printable borders. + Thus, the rectangle returned by wxDC::GetPaperRectPixels() will have a top left corner + whose coordinates are small negative numbers and the bottom right corner will have + values somewhat larger than the width and height given by wxDC::GetPageSizePixels(). + + On other platforms and for PostScript printing, the paper is treated as if its entire + area were printable, so this function will return the same rectangle as the page + rectangle. + */ + wxRect GetPaperRectPixels(); + + /** + Returns the title of the printout. + + @todo the python note here was wrong + */ + wxString GetTitle(); + + /** + Should be overridden to return @true if the document has this page, or @false + if not. + + Returning @false signifies the end of the document. By default, + HasPage behaves as if the document has only one page. + */ + bool HasPage(int pageNum); + + /** + Returns @true if the printout is currently being used for previewing. + */ + bool IsPreview(); + + /** + Set the user scale and device origin of the wxDC associated with this wxPrintout + so that one screen pixel maps to one device pixel on the DC. + That is, the user scale is set to (1,1) and the device origin is set to (0,0). + + Use this if you want to do your own scaling prior to calling wxDC drawing calls, + for example, if your underlying model is floating-point and you want to achieve + maximum drawing precision on high-resolution printers. + + You can use the GetLogicalXXXRect() routines below to obtain the paper rectangle, + page rectangle, or page margins rectangle to perform your own scaling. + + @note + While the underlying drawing model of Mac OS X is floating-point, + wxWidgets's drawing model scales from integer coordinates. + */ + void MapScreenSizeToDevice(); + + /** + This sets the user scale of the wxDC assocated with this wxPrintout to the same + scale as MapScreenSizeToPaper() but sets the logical origin to the top left corner + of the page rectangle. + */ + void MapScreenSizeToPage(); + + /** + This sets the user scale of the wxDC assocated with this wxPrintout to the same + scale as MapScreenSizeToPageMargins() but sets the logical origin to the top left + corner of the page margins specified by the given wxPageSetupDialogData object. + */ + void MapScreenSizeToPageMargins(const wxPageSetupDialogData& pageSetupData); + + /** + Set the user scale and device origin of the wxDC associated with this wxPrintout + so that the printed page matches the screen size as closely as possible + and the logical origin is in the top left corner of the paper rectangle. + + That is, a 100-pixel object on screen should appear at the same size on the + printed page. + (It will, of course, be larger or smaller in the preview image, depending on the + zoom factor.) + + Use this if you want WYSIWYG behavior, e.g., in a text editor. + */ + void MapScreenSizeToPaper(); + + /** + Shift the device origin by an amount specified in logical coordinates. + */ + void OffsetLogicalOrigin(wxCoord xoff, wxCoord yoff); + + /** + Called by the framework at the start of document printing. Return @false from + this function cancels the print job. + + OnBeginDocument() is called once for every copy printed. + + @remarks + The base OnBeginDocument() must be called (and the return value + checked) from within the overridden function, since it calls wxDC::StartDoc(). + + @beginWxPythonOnly + If this method is overridden in a Python class then the base class version can + be called by using the method base_OnBeginDocument(startPage, endPage). + @endWxPythonOnly + */ + bool OnBeginDocument(int startPage, int endPage); + + /** + Called by the framework at the start of printing. + + OnBeginPrinting() is called once for every print job + (regardless of how many copies are being printed). + */ + void OnBeginPrinting(); + + /** + Called by the framework at the end of document printing. + + OnEndDocument() is called once for every copy printed. + + @remarks + The base OnEndDocument() must be called from within the overridden function, + since it calls wxDC::EndDoc(). + */ + void OnEndDocument(); + + /** + Called by the framework at the end of printing. + + OnEndPrinting is called once for every print job + (regardless of how many copies are being printed). + */ + void OnEndPrinting(); + + /** + Called once by the framework before any other demands are made of the + wxPrintout object. + + This gives the object an opportunity to calculate the number of pages + in the document, for example. + */ + void OnPreparePrinting(); + + /** + Called by the framework when a page should be printed. Returning @false cancels + the print job. + */ + bool OnPrintPage(int pageNum); + + /** + Set the device origin of the associated wxDC so that the current logical point + becomes the new logical origin. + */ + void SetLogicalOrigin(wxCoord x, wxCoord y); +}; + diff --git a/interface/wx/printdlg.h b/interface/wx/printdlg.h new file mode 100644 index 0000000000..4a174546bb --- /dev/null +++ b/interface/wx/printdlg.h @@ -0,0 +1,128 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: printdlg.h +// Purpose: interface of wxPrintDialog +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxPrintDialog + @wxheader{printdlg.h} + + This class represents the print and print setup common dialogs. + You may obtain a wxPrinterDC device context from a successfully dismissed + print dialog. + + @library{wxcore} + @category{printing} + + @see @ref overview_printing, @ref overview_cmndlg_print +*/ +class wxPrintDialog : public wxDialog +{ +public: + /** + Constructor. + + Pass a parent window, and optionally a pointer to a block of print + data, which will be copied to the print dialog's print data. + + @see wxPrintDialogData + */ + wxPrintDialog(wxWindow* parent, wxPrintDialogData* data = NULL); + + /** + Destructor. + + If GetPrintDC() has not been called, the device context obtained by + the dialog (if any) will be deleted. + */ + ~wxPrintDialog(); + + /** + Returns the device context created by the print dialog, if any. + + When this function has been called, the ownership of the device context + is transferred to the application, so it must then be deleted + explicitly. + */ + wxDC* GetPrintDC(); + + /** + Returns the @ref overview_printing_printdata "print dialog data" associated + with the print dialog. + */ + wxPrintDialogData GetPrintDialogData(); + + /** + Shows the dialog, returning @c wxID_OK if the user pressed OK, and @c + wxID_CANCEL otherwise. + + After this function is called, a device context may be retrievable using + GetPrintDC(). + */ + int ShowModal(); +}; + + + +/** + @class wxPageSetupDialog + @wxheader{printdlg.h} + + This class represents the page setup common dialog. In MSW, the page setup + dialog is standard from Windows 95 on, replacing the print setup dialog (which + is retained in Windows and wxWidgets for backward compatibility). + On Windows 95 and NT 4.0 and above, the page setup dialog is native to the windowing + system, otherwise it is emulated. + + The page setup dialog contains controls for paper size (A4, A5 etc.), + orientation (landscape or portrait), and controls for setting left, top, right + and bottom margin sizes in millimetres. + + On Macintosh, the native page setup dialog is used, which lets you select paper + size and orientation but it does not let you change the page margins. + + On other platforms, a generic dialog is used. + + When the dialog has been closed, you need to query the wxPageSetupDialogData + object associated with the dialog. + + Note that the OK and Cancel buttons do not destroy the dialog; this must be done + by the application. + + @library{wxcore} + @category{printing} + + @see @ref overview_printing "Printing framework overview", + wxPrintDialog, wxPageSetupDialogData +*/ +class wxPageSetupDialog : public wxDialog +{ +public: + /** + Constructor. + + Pass a parent window, and optionally a pointer to a block of page + setup data, which will be copied to the print dialog's internal data. + */ + wxPageSetupDialog(wxWindow* parent, wxPageSetupDialogData* data = NULL); + + /** + Destructor. + */ + ~wxPageSetupDialog(); + + /** + Returns the wxPageSetupDialogData object associated with the dialog. + */ + wxPageSetupDialogData& GetPageSetupData(); + + /** + Shows the dialog, returning @c wxID_OK if the user pressed OK, and + @c wxID_CANCEL otherwise. + */ + int ShowModal(); +}; + diff --git a/interface/wx/process.h b/interface/wx/process.h new file mode 100644 index 0000000000..1401717d76 --- /dev/null +++ b/interface/wx/process.h @@ -0,0 +1,297 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: process.h +// Purpose: interface of wxProcess +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + Signal constants used by wxProcess. +*/ +enum wxSignal +{ + wxSIGNONE = 0, //!< verify if the process exists under Unix + wxSIGHUP, + wxSIGINT, + wxSIGQUIT, + wxSIGILL, + wxSIGTRAP, + wxSIGABRT, + wxSIGEMT, + wxSIGFPE, + wxSIGKILL, //!< forcefully kill, dangerous! + wxSIGBUS, + wxSIGSEGV, + wxSIGSYS, + wxSIGPIPE, + wxSIGALRM, + wxSIGTERM //!< terminate the process gently +}; + +/** + Return values for wxProcess::Kill. +*/ +enum wxKillError +{ + wxKILL_OK, //!< no error + wxKILL_BAD_SIGNAL, //!< no such signal + wxKILL_ACCESS_DENIED, //!< permission denied + wxKILL_NO_PROCESS, //!< no such process + wxKILL_ERROR //!< another, unspecified error +}; + + +/** + @class wxProcess + @wxheader{process.h} + + The objects of this class are used in conjunction with the ::wxExecute() function. + When a wxProcess object is passed to ::wxExecute(), its OnTerminate() virtual method + is called when the process terminates. This allows the program to be (asynchronously) + notified about the process termination and also retrieve its exit status which is + unavailable from ::wxExecute() in the case of asynchronous execution. + + @note If the process termination notification is processed by the + parent, it is responsible for deleting the wxProcess object which sent it. + However, if it is not processed, the object will delete itself and so the + library users should only delete those objects whose notifications have been + processed (and call wxProcess::Detach for others). + + wxProcess also supports IO redirection of the child process. For this, you have + to call its Redirect() method before passing it to ::wxExecute(). + If the child process was launched successfully, GetInputStream(), GetOutputStream() + and GetErrorStream() can then be used to retrieve the streams corresponding to the + child process standard output, input and error output respectively. + + @library{wxbase} + @category{appmanagement} + + @see wxExecute(), @ref page_samples_exec "exec sample" +*/ +class wxProcess : public wxEvtHandler +{ +public: + /** + Constructs a process object. @a id is only used in the case you want to + use wxWidgets events. It identifies this object, or another window that will + receive the event. + + If the @a parent parameter is different from @NULL, it will receive + a @c wxEVT_END_PROCESS notification event (you should insert @c EVT_END_PROCESS + macro in the event table of the parent to handle it) with the given @a id. + + @param parent + The event handler parent. + @param id + id of an event. + */ + wxProcess(wxEvtHandler* parent = NULL, int id = -1); + + /** + Creates an object without any associated parent (and hence no id neither) + but allows to specify the @a flags which can have the value of + @c wxPROCESS_DEFAULT or @c wxPROCESS_REDIRECT. + + Specifying the former value has no particular effect while using the latter + one is equivalent to calling Redirect(). + */ + wxProcess(int flags); + + /** + Destroys the wxProcess object. + */ + ~wxProcess(); + + /** + Closes the output stream (the one connected to the stdin of the child + process). + + This function can be used to indicate to the child process that + there is no more data to be read - usually, a filter program will only + terminate when the input stream is closed. + */ + void CloseOutput(); + + /** + Normally, a wxProcess object is deleted by its parent when it receives the + notification about the process termination. However, it might happen that the + parent object is destroyed before the external process is terminated (e.g. a + window from which this external process was launched is closed by the user) + and in this case it @b should not delete the wxProcess object, but + @b should call Detach() instead. After the wxProcess object is detached + from its parent, no notification events will be sent to the parent and the + object will delete itself upon reception of the process termination + notification. + */ + void Detach(); + + /** + Returns @true if the given process exists in the system. + + @see Kill(), @ref page_samples_exec "Exec sample" + */ + static bool Exists(int pid); + + /** + Returns an input stream which corresponds to the standard error output (stderr) + of the child process. + */ + wxInputStream* GetErrorStream() const; + + /** + It returns an input stream corresponding to the standard output stream of the + subprocess. If it is @NULL, you have not turned on the redirection. + + @see Redirect(). + */ + wxInputStream* GetInputStream() const; + + /** + It returns an output stream correspoding to the input stream of the subprocess. + If it is @NULL, you have not turned on the redirection. + + @see Redirect(). + */ + wxOutputStream* GetOutputStream() const; + + /** + Returns the process ID of the process launched by Open(). + */ + long GetPid() const; + + /** + Returns @true if there is data to be read on the child process standard + error stream. + + @see IsInputAvailable() + */ + bool IsErrorAvailable() const; + + /** + Returns @true if there is data to be read on the child process standard + output stream. + + This allows to write simple (and extremely inefficient) polling-based code + waiting for a better mechanism in future wxWidgets versions. + See the @ref page_samples_exec "exec sample" for an example of using this + function. + + @see IsInputOpened() + */ + bool IsInputAvailable() const; + + /** + Returns @true if the child process standard output stream is opened. + */ + bool IsInputOpened() const; + + /** + Send the specified signal to the given process. Possible signal values + can be one of the ::wxSignal enumeration values. + + @c wxSIGNONE, @c wxSIGKILL and @c wxSIGTERM have the same meaning + under both Unix and Windows but all the other signals are equivalent to + @c wxSIGTERM under Windows. + + The @a flags parameter can be @c wxKILL_NOCHILDREN (the default), + or @c wxKILL_CHILDREN, in which case the child processes of this + process will be killed too. Note that under Unix, for @c wxKILL_CHILDREN + to work you should have created the process passing @c wxEXEC_MAKE_GROUP_LEADER. + + Returns the element of ::wxKillError enum. + + @see Exists(), wxKill(), @ref page_samples_exec "Exec sample" + */ + static wxKillError Kill(int pid, wxSignal signal = wxSIGNONE, + int flags = wxKILL_NOCHILDREN); + + /** + It is called when the process with the pid @a pid finishes. + It raises a wxWidgets event when it isn't overridden. + + @param pid + The pid of the process which has just terminated. + @param status + The exit code of the process. + */ + void OnTerminate(int pid, int status); + + /** + This static method replaces the standard @c popen() function: it launches + the process specified by the @a cmd parameter and returns the wxProcess + object which can be used to retrieve the streams connected to the standard + input, output and error output of the child process. + + If the process couldn't be launched, @NULL is returned. + + @remarks + In any case the returned pointer should @b not be deleted, rather the process + object will be destroyed automatically when the child process terminates. This + does mean that the child process should be told to quit before the main program + exits to avoid memory leaks. + + @param cmd + The command to execute, including optional arguments. + @param flags + The flags to pass to ::wxExecute(). + Note: @c wxEXEC_SYNC should not be used. + + @return A pointer to new wxProcess object or @NULL on error. + + @see ::wxExecute() + */ + static wxProcess* Open(const wxString& cmd, + int flags = wxEXEC_ASYNC); + + /** + Turns on redirection. + + ::wxExecute() will try to open a couple of pipes to catch the subprocess stdio. + The caught input stream is returned by GetOutputStream() as a non-seekable stream. + The caught output stream is returned by GetInputStream() as a non-seekable stream. + */ + void Redirect(); +}; + + + +/** + @class wxProcessEvent + @wxheader{process.h} + + A process event is sent when a process is terminated. + + @beginEventTable{wxProcessEvent} + @event{EVT_END_PROCESS(id, func)} + Process a @c wxEVT_END_PROCESS event. @a id is the identifier of the process + object (the id passed to the wxProcess constructor) or a window to receive + the event. + @endEventTable + + @library{wxbase} + @category{events} + + @see wxProcess, @ref overview_eventhandling +*/ +class wxProcessEvent : public wxEvent +{ +public: + /** + Constructor. + + Takes a wxProcessObject or window id, a process id and an exit status. + */ + wxProcessEvent(int id = 0, int pid = 0, int exitcode = 0); + + /** + Returns the exist status. + */ + int GetExitCode(); + + /** + Returns the process id. + */ + int GetPid() const; +}; + diff --git a/interface/wx/progdlg.h b/interface/wx/progdlg.h new file mode 100644 index 0000000000..45af3f8e81 --- /dev/null +++ b/interface/wx/progdlg.h @@ -0,0 +1,113 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: progdlg.h +// Purpose: interface of wxProgressDialog +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxProgressDialog + @wxheader{progdlg.h} + + This class represents a dialog that shows a short message and a + progress bar. Optionally, it can display ABORT and SKIP buttons, + the elapsed, remaining and estimated time for the end of the progress. + + @beginStyleTable + @style{wxPD_APP_MODAL} + Make the progress dialog modal. If this flag is not given, it is + only "locally" modal - that is the input to the parent window is + disabled, but not to the other ones. + @style{wxPD_AUTO_HIDE} + Causes the progress dialog to disappear from screen as soon as the + maximum value of the progress meter has been reached. + @style{wxPD_SMOOTH} + Causes smooth progress of the gauge control. + @style{wxPD_CAN_ABORT} + This flag tells the dialog that it should have a "Cancel" button + which the user may press. If this happens, the next call to + Update() will return @false. + @style{wxPD_CAN_SKIP} + This flag tells the dialog that it should have a "Skip" button + which the user may press. If this happens, the next call to + Update() will return @true in its skip parameter. + @style{wxPD_ELAPSED_TIME} + This flag tells the dialog that it should show elapsed time (since + creating the dialog). + @style{wxPD_ESTIMATED_TIME} + This flag tells the dialog that it should show estimated time. + @style{wxPD_REMAINING_TIME} + This flag tells the dialog that it should show remaining time. + @endStyleTable + + @library{wxbase} + @category{cmndlg} +*/ +class wxProgressDialog : public wxDialog +{ +public: + /** + Constructor. Creates the dialog, displays it and disables user input + for other windows, or, if @c wxPD_APP_MODAL flag is not given, for its + parent window only. + + @param title + Dialog title to show in titlebar. + @param message + Message displayed above the progress bar. + @param maximum + Maximum value for the progress bar. + @param parent + Parent window. + @param style + The dialog style. See wxProgressDialog. + */ + wxProgressDialog(const wxString& title, const wxString& message, + int maximum = 100, + wxWindow* parent = NULL, + int style = wxPD_AUTO_HIDE | wxPD_APP_MODAL); + + /** + Destructor. Deletes the dialog and enables all top level windows. + */ + ~wxProgressDialog(); + + /** + Works like Update() but makes the gauge control run in indeterminate mode + (see wxGauge documentation); sets the remaining and the estimated time labels + (if present) to "Unknown" or to @a newmsg (if it's non-empty); moves the progress + bar a bit to indicate that some progress was done. + */ + virtual bool Pulse(const wxString& newmsg = "", + bool* skip = NULL); + + /** + Can be used to continue with the dialog, after the user had clicked the "Abort" button. + */ + void Resume(); + + /** + Updates the dialog, setting the progress bar to the new value and, if + given changes the message above it. Returns @true unless the "Cancel" button + has been pressed. + + If @false is returned, the application can either immediately destroy the + dialog or ask the user for the confirmation and if the abort is not confirmed + the dialog may be resumed with Resume() function. + + @param value + The new value of the progress meter. It should be less than or equal to + the maximum value given to the constructor and the dialog is closed if + it is equal to the maximum. + @param newmsg + The new messages for the progress dialog text, if it is + empty (which is the default) the message is not changed. + @param skip + If "Skip" button was pressed since last Update() call, + this is set to @true. + */ + virtual bool Update(int value, const wxString& newmsg = "", + bool* skip = NULL); +}; + diff --git a/interface/wx/propdlg.h b/interface/wx/propdlg.h new file mode 100644 index 0000000000..77cd2f43ed --- /dev/null +++ b/interface/wx/propdlg.h @@ -0,0 +1,200 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: propdlg.h +// Purpose: interface of wxPropertySheetDialog +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + + +/** + Values used by wxPropertySheetDialog::SetSheetStyle +*/ +enum wxPropertySheetDialogFlags +{ + /** + Uses the default look and feel for the controller window, + normally a notebook except on Smartphone where a choice control is used. + */ + wxPROPSHEET_DEFAULT = 0x0001, + + /** + Uses a notebook for the controller window. + */ + wxPROPSHEET_NOTEBOOK = 0x0002, + + /** + Uses a toolbook for the controller window. + */ + wxPROPSHEET_TOOLBOOK = 0x0004, + + /** + Uses a choicebook for the controller window. + */ + wxPROPSHEET_CHOICEBOOK = 0x0008, + + /** + Uses a listbook for the controller window. + */ + wxPROPSHEET_LISTBOOK = 0x0010, + + /** + Uses a button toolbox for the controller window. + */ + wxPROPSHEET_BUTTONTOOLBOOK = 0x0020, + + /** + Uses a treebook for the controller window. + */ + wxPROPSHEET_TREEBOOK = 0x0040, + + /** + Shrinks the dialog window to fit the currently selected page + (common behaviour for property sheets on Mac OS X). + */ + wxPROPSHEET_SHRINKTOFIT = 0x0100, +}; + + +/** + @class wxPropertySheetDialog + @wxheader{propdlg.h} + + This class represents a property sheet dialog: a tabbed dialog + for showing settings. It is optimized to show flat tabs + on PocketPC devices, and can be customized to use different + controllers instead of the default notebook style. + + To use this class, call Create() from your own Create function. + Then call CreateButtons(), and create pages, adding them to the book control. + Finally call LayoutDialog(). + + For example: + + @code + bool MyPropertySheetDialog::Create(...) + { + if (!wxPropertySheetDialog::Create(...)) + return @false; + + CreateButtons(wxOK|wxCANCEL|wxHELP); + + // Add page + wxPanel* panel = new wxPanel(GetBookCtrl(), ...); + GetBookCtrl()->AddPage(panel, wxT("General")); + + LayoutDialog(); + return @true; + } + @endcode + + If necessary, override CreateBookCtrl() and AddBookCtrl() to create and add a + different kind of book control. You will then need to use two-step construction + for the dialog or change the style of the book control by calling SetSheetStyle() + before calling Create(). + + The @ref page_samples_dialogs shows this class being used with notebook and toolbook + controllers (for Windows-style and Mac-style settings dialogs). + + To make pages of the dialog scroll when the display is too small to fit the + whole dialog, you can switch layout adaptation on globally with + wxDialog::EnableLayoutAdaptation() or per dialog with + wxDialog::SetLayoutAdaptationMode(). + + For more about layout adaptation, see @ref overview_dialog_autoscrolling. + + @library{wxadv} + @category{managedwnd} +*/ +class wxPropertySheetDialog : public wxDialog +{ +public: + /** + Constructor. + */ + wxPropertySheetDialog(wxWindow* parent, wxWindowID id, + const wxString& title, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxDEFAULT_DIALOG_STYLE, + const wxString& name = "dialogBox"); + + /** + Override this if you wish to add the book control in a way different from the + standard way (for example, using different spacing). + */ + virtual void AddBookCtrl(wxSizer* sizer); + + /** + Call this from your own Create function, before adding buttons and pages. + */ + bool Create(wxWindow* parent, wxWindowID id, + const wxString& title, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxDEFAULT_DIALOG_STYLE, + const wxString& name = "dialogBox"); + + /** + Override this if you wish to create a different kind of book control; by + default, the value passed to SetSheetStyle() is used to determine the control. + + The default behaviour is to create a notebook except on Smartphone, where a + choicebook is used. + */ + virtual wxBookCtrlBase* CreateBookCtrl(); + + /** + Call this to create the buttons for the dialog. + This calls wxDialog::CreateButtonSizer(), and the flags are the same. + + @note On PocketPC, no buttons are created. + */ + void CreateButtons(int flags = wxOK|wxCANCEL); + + /** + Returns the book control that will contain your settings pages. + */ + wxBookCtrlBase* GetBookCtrl() const; + + /** + Returns the inner sizer that contains the book control and button sizer. + */ + wxSizer* GetInnerSizer() const; + + /** + Returns the sheet style. + + See SetSheetStyle() for allowed values. + */ + long GetSheetStyle() const; + + /** + Call this to lay out the dialog. + + @note On PocketPC, this does nothing, since the dialog will be shown full-screen, + and the layout will be done when the dialog receives a size event. + */ + void LayoutDialog(int centreFlags = wxBOTH); + + /** + Sets the book control used for the dialog. + + You will normally not need to use this. + */ + void SetBookCtrl(wxBookCtrlBase* bookCtrl); + + /** + Sets the inner sizer that contains the book control and button sizer. + + You will normally not need to use this. + */ + void SetInnerSizer(wxSizer* sizer); + + /** + You can customize the look and feel of the dialog by setting the sheet style. + It is a bit list of the ::wxPropertySheetDialogFlags values. + */ + void SetSheetStyle(long style); +}; + diff --git a/interface/wx/protocol/ftp.h b/interface/wx/protocol/ftp.h new file mode 100644 index 0000000000..a99c957787 --- /dev/null +++ b/interface/wx/protocol/ftp.h @@ -0,0 +1,285 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: protocol/ftp.h +// Purpose: interface of wxFTP +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + Transfer modes used by wxFTP. +*/ +enum TransferMode +{ + NONE, //!< not set by user explicitly. + ASCII, + BINARY +}; + +/** + @class wxFTP + @headerfile ftp.h wx/protocol/ftp.h + + wxFTP can be used to establish a connection to an FTP server and perform all the + usual operations. Please consult the RFC 959 for more details about the FTP + protocol. + + To use a command which doesn't involve file transfer (i.e. directory oriented + commands) you just need to call a corresponding member function or use the + generic wxFTP::SendCommand() method. + However to actually transfer files you just get or give a stream to or from this + class and the actual data are read or written using the usual stream methods. + + Example of using wxFTP for file downloading: + + @code + wxFTP ftp; + + // if you don't use these lines anonymous login will be used + ftp.SetUser("user"); + ftp.SetPassword("password"); + + if ( !ftp.Connect("ftp.wxwindows.org") ) + { + wxLogError("Couldn't connect"); + return; + } + + ftp.ChDir("/pub"); + wxInputStream *in = ftp.GetInputStream("wxWidgets-4.2.0.tar.gz"); + if ( !in ) + { + wxLogError("Coudln't get file"); + } + else + { + size_t size = in-GetSize(); + char *data = new char[size]; + if ( !in->Read(data, size) ) + { + wxLogError("Read error"); + } + else + { + // file data is in the buffer + ... + } + + delete [] data; + delete in; + } + @endcode + + To upload a file you would do (assuming the connection to the server was opened + successfully): + + @code + wxOutputStream *out = ftp.GetOutputStream("filename"); + if ( out ) + { + out->Write(...); // your data + delete out; + } + @endcode + + @library{wxnet} + @category{net} + + @see wxSocketBase +*/ +class wxFTP : public wxProtocol +{ +public: + /** + Default constructor. + */ + wxFTP(); + + /** + Destructor will close the connection if connected. + */ + ~wxFTP(); + + /** + Aborts the download currently in process, returns @true if ok, @false + if an error occurred. + */ + bool Abort(); + + /** + Change the current FTP working directory. + Returns @true if successful. + */ + bool ChDir(const wxString& dir); + + /** + Send the specified @a command to the FTP server. @a ret specifies + the expected result. + + @return @true if the command has been sent successfully, else @false. + */ + bool CheckCommand(const wxString& command, char ret); + + /** + Returns @true if the given remote file exists, @false otherwise. + */ + bool FileExists(const wxString& filename); + + /** + The GetList() function is quite low-level. It returns the list of the files in + the current directory. The list can be filtered using the @a wildcard string. + + If @a wildcard is empty (default), it will return all files in directory. + The form of the list can change from one peer system to another. For example, + for a UNIX peer system, it will look like this: + + @verbatim + -r--r--r-- 1 guilhem lavaux 12738 Jan 16 20:17 cmndata.cpp + -r--r--r-- 1 guilhem lavaux 10866 Jan 24 16:41 config.cpp + -rw-rw-rw- 1 guilhem lavaux 29967 Dec 21 19:17 cwlex_yy.c + -rw-rw-rw- 1 guilhem lavaux 14342 Jan 22 19:51 cwy_tab.c + -r--r--r-- 1 guilhem lavaux 13890 Jan 29 19:18 date.cpp + -r--r--r-- 1 guilhem lavaux 3989 Feb 8 19:18 datstrm.cpp + @endverbatim + + But on Windows system, it will look like this: + + @verbatim + winamp~1 exe 520196 02-25-1999 19:28 winamp204.exe + 1 file(s) 520 196 bytes + @endverbatim + + @return @true if the file list was successfully retrieved, @false otherwise. + + @see GetFilesList() + */ + bool GetDirList(wxArrayString& files, + const wxString& wildcard = ""); + + /** + Returns the file size in bytes or -1 if the file doesn't exist or the size + couldn't be determined. + + Notice that this size can be approximative size only and shouldn't be used + for allocating the buffer in which the remote file is copied, for example. + */ + int GetFileSize(const wxString& filename); + + /** + This function returns the computer-parsable list of the files in the current + directory (optionally only of the files matching the @e wildcard, all files + by default). + + This list always has the same format and contains one full (including the + directory path) file name per line. + + @return @true if the file list was successfully retrieved, @false otherwise. + + @see GetDirList() + */ + bool GetFilesList(wxArrayString& files, + const wxString& wildcard = ""); + + /** + Creates a new input stream on the specified path. + + You can use all but the seek functionality of wxStreamBase. + wxStreamBase::Seek() isn't available on all streams. For example, HTTP or FTP + streams do not deal with it. Other functions like wxStreamBase::Tell() are + not available for this sort of stream, at present. + + You will be notified when the EOF is reached by an error. + + @return Returns @NULL if an error occurred (it could be a network failure + or the fact that the file doesn't exist). + */ + wxInputStream* GetInputStream(const wxString& path); + + /** + Returns the last command result, i.e. the full server reply for the last command. + */ + const wxString GetLastResult(); + + /** + Initializes an output stream to the specified @e file. + + The returned stream has all but the seek functionality of wxStreams. + When the user finishes writing data, he has to delete the stream to close it. + + @return An initialized write-only stream. + + @see wxOutputStream + */ + wxOutputStream* GetOutputStream(const wxString& file); + + /** + Create the specified directory in the current FTP working directory. + Returns @true if successful. + */ + bool MkDir(const wxString& dir); + + /** + Returns the current FTP working directory. + */ + wxString Pwd(); + + /** + Rename the specified @a src element to @e dst. Returns @true if successful. + */ + bool Rename(const wxString& src, const wxString& dst); + + /** + Remove the specified directory from the current FTP working directory. + Returns @true if successful. + */ + bool RmDir(const wxString& dir); + + /** + Delete the file specified by @e path. Returns @true if successful. + */ + bool RmFile(const wxString& path); + + /** + Send the specified @a command to the FTP server and return the first + character of the return code. + */ + char SendCommand(const wxString& command); + + /** + Sets the transfer mode to ASCII. It will be used for the next transfer. + */ + bool SetAscii(); + + /** + Sets the transfer mode to binary (IMAGE). It will be used for the next transfer. + */ + bool SetBinary(); + + /** + If @a pasv is @true, passive connection to the FTP server is used. + + This is the default as it works with practically all firewalls. + If the server doesn't support passive move, you may call this function with + @false argument to use active connection. + */ + void SetPassive(bool pasv); + + /** + Sets the password to be sent to the FTP server to be allowed to log in. + */ + void SetPassword(const wxString& passwd); + + /** + Sets the transfer mode to the specified one. It will be used for the next + transfer. + + If this function is never called, binary transfer mode is used by default. + */ + bool SetTransferMode(TransferMode mode); + + /** + Sets the user name to be sent to the FTP server to be allowed to log in. + */ + void SetUser(const wxString& user); +}; + diff --git a/interface/wx/protocol/http.h b/interface/wx/protocol/http.h new file mode 100644 index 0000000000..6cd1332ae8 --- /dev/null +++ b/interface/wx/protocol/http.h @@ -0,0 +1,73 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: protocol/http.h +// Purpose: interface of wxHTTP +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxHTTP + @headerfile http.h wx/protocol/http.h + + wxHTTP can be used to establish a connection to an HTTP server. + + @library{wxnet} + @category{net} + + @see wxSocketBase, wxURL +*/ +class wxHTTP : public wxProtocol +{ +public: + /** + Returns the data attached with a field whose name is specified by @e header. + If the field doesn't exist, it will return an empty string and not a @NULL string. + + @note + The header is not case-sensitive, i.e. "CONTENT-TYPE" and "content-type" + represent the same header. + */ + wxString GetHeader(const wxString& header); + + /** + Creates a new input stream on the specified path. + + Notice that this stream is unseekable, i.e. SeekI() and TellI() methods + shouldn't be used. + + Note that you can still know the size of the file you are getting using + wxStreamBase::GetSize(). However there is a limitation: in HTTP protocol, + the size is not always specified so sometimes @c (size_t)-1 can returned to + indicate that the size is unknown. + In such case, you may want to use wxInputStream::LastRead() method in a loop + to get the total size. + + @return Returns the initialized stream. You must delete it yourself + once you don't use it anymore and this must be done before + the wxHTTP object itself is destroyed. The destructor + closes the network connection. The next time you will + try to get a file the network connection will have to + be reestablished, but you don't have to take care of + this since wxHTTP reestablishes it automatically. + + @see wxInputStream + */ + wxInputStream* GetInputStream(const wxString& path); + + /** + Returns the HTTP response code returned by the server. + + Please refer to RFC 2616 for the list of responses. + */ + int GetResponse() const; + + /** + It sets data of a field to be sent during the next request to the HTTP server. + + The field name is specified by @a header and the content by @e h_data. + This is a low level function and it assumes that you know what you are doing. + */ + void SetHeader(const wxString& header, const wxString& h_data); +}; + diff --git a/interface/wx/protocol/protocol.h b/interface/wx/protocol/protocol.h new file mode 100644 index 0000000000..af8d45e12e --- /dev/null +++ b/interface/wx/protocol/protocol.h @@ -0,0 +1,98 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: protocol/protocol.h +// Purpose: interface of wxProtocol +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + Error values returned by wxProtocol. +*/ +enum wxProtocolError +{ + wxPROTO_NOERR = 0, //!< No error. + wxPROTO_NETERR, //!< A generic network error occurred. + wxPROTO_PROTERR, //!< An error occurred during negotiation. + wxPROTO_CONNERR, //!< The client failed to connect the server. + wxPROTO_INVVAL, //!< Invalid value. + wxPROTO_NOHNDLR, //!< Not currently used. + wxPROTO_NOFILE, //!< The remote file doesn't exist. + wxPROTO_ABRT, //!< Last action aborted. + wxPROTO_RCNCT, //!< An error occurred during reconnection. + wxPROTO_STREAMING //!< Someone tried to send a command during a transfer. +}; + +/** + @class wxProtocol + @headerfile protocol.h wx/protocol/protocol.h + + Represents a protocol for use with wxURL. + + @library{wxnet} + @category{net} + + @see wxSocketBase, wxURL +*/ +class wxProtocol : public wxSocketClient +{ +public: + /** + Abort the current stream. + + @warning + It is advised to destroy the input stream instead of aborting the stream + this way. + + @return Returns @true, if successful, else @false. + */ + bool Abort(); + + /** + Returns the type of the content of the last opened stream. It is a mime-type. + */ + wxString GetContentType(); + + /** + Returns the last occurred error. + + @see wxProtocolError + */ + wxProtocolError GetError(); + + /** + Creates a new input stream on the specified path. + + You can use all but seek() functionality of wxStream. + Seek() isn't available on all streams. For example, HTTP or FTP streams + don't deal with it. Other functions like StreamSize() and Tell() aren't + available for the moment for this sort of stream. + You will be notified when the EOF is reached by an error. + + @return Returns the initialized stream. You will have to delete it + yourself once you don't use it anymore. The destructor + closes the network connection. + + @see wxInputStream + */ + wxInputStream* GetInputStream(const wxString& path); + + /** + Tries to reestablish a previous opened connection (close and renegotiate + connection). + + @return @true, if the connection is established, else @false. + */ + bool Reconnect(); + + /** + Sets the authentication password. It is mainly useful when FTP is used. + */ + void SetPassword(const wxString& user); + + /** + Sets the authentication user. It is mainly useful when FTP is used. + */ + void SetUser(const wxString& user); +}; + diff --git a/interface/wx/ptr_scpd.h b/interface/wx/ptr_scpd.h new file mode 100644 index 0000000000..11180b1a55 --- /dev/null +++ b/interface/wx/ptr_scpd.h @@ -0,0 +1,368 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: ptr_scpd.h +// Purpose: interface of wxScopedPtr +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxScopedPtr + @wxheader{ptr_scpd.h} + + This is a simple scoped smart pointer implementation that is similar to + the Boost smart pointers (see http://www.boost.org) but rewritten + to use macros instead. + + Since wxWidgets 2.9.0 there is also a templated version of this class + with the same name. See wxScopedPtr. + + A smart pointer holds a pointer to an object. The memory used by the object is + deleted when the smart pointer goes out of scope. This class is different from + the @c std::auto_ptr<> in so far as it doesn't provide copy constructor + nor assignment operator. This limits what you can do with it but is much less + surprizing than the "destructive copy" behaviour of the standard class. + + @b Example: + + Below is an example of using a wxWidgets scoped smart pointer and pointer array. + + @code + class MyClass{ ... }; + + // declare a smart pointer to a MyClass called wxMyClassPtr + wxDECLARE_SCOPED_PTR(MyClass, wxMyClassPtr) + // declare a smart pointer to an array of chars + wxDECLARE_SCOPED_ARRAY(char, wxCharArray) + + ... + + // define the first pointer class, must be complete + wxDEFINE_SCOPED_PTR(MyClass, wxMyClassPtr) + // define the second pointer class + wxDEFINE_SCOPED_ARRAY(char, wxCharArray) + + // create an object with a new pointer to MyClass + wxMyClassPtr theObj(new MyClass()); + // reset the pointer (deletes the previous one) + theObj.reset(new MyClass()); + + // access the pointer + theObj->MyFunc(); + + // create an object with a new array of chars + wxCharArray theCharObj(new char[100]); + + // access the array + theCharObj[0] = "!"; + @endcode + + @section wxscopedptr_newpointers Declaring new smart pointer types + + To declare the smart pointer class @c CLASSNAME containing pointes to + a (possibly incomplete) type @c TYPE you should use + @code + wxDECLARE_SCOPED_PTR( TYPE, // type of the values + CLASSNAME ); // name of the class + @endcode + And later, when @c TYPE is fully defined, you must also use + @code + wxDEFINE_SCOPED_PTR( TYPE, CLASSNAME ); + @endcode + to implement the scoped pointer class. + + The first argument of these macro is the pointer type, the second is the name + of the new smart pointer class being created. Below we will use wxScopedPtr + to represent the scoped pointer class, but the user may create the class with + any legal name. + + Alternatively, if you don't have to separate the point of declaration and + definition of this class and if you accept the standard naming convention, + that is that the scoped pointer for the class @c Foo is called @c FooPtr, + you can use a single macro which replaces two macros above: + @code + wxDEFINE_SCOPED_PTR_TYPE( TYPE ); + @endcode + Once again, in this cass @c CLASSNAME will be @c TYPEPtr. + + @library{wxbase} + @category{smartpointers} + + @see wxScopedArray +*/ +class wxScopedPtr +{ +public: + /** + Creates the smart pointer with the given pointer or none if @NULL. + + On compilers that support it, this uses the explicit keyword. + */ + explicit wxScopedPtr(type* T = NULL); + + /** + Destructor frees the pointer help by this object if it is not @NULL. + */ + ~wxScopedPtr(); + + /** + This operator gets the pointer stored in the smart pointer or returns + @NULL if there is none. + */ + const T* get(); + + /** + This operator works like the standard C++ pointer operator to return the object + being pointed to by the pointer. + + @note + If the pointer is @NULL or invalid this will crash. + */ + const T& operator *(); + + /** + This operator works like the standard C++ pointer operator to return the pointer + in the smart pointer or @NULL if it is empty. + */ + const T* operator ->(); + + /** + Returns the currently hold pointer and resets the smart pointer object to + @NULL. + + @remarks + After a call to this function the caller is responsible for deleting the + pointer. + */ + T* release(); + + /** + Deletes the currently held pointer and sets it to @a p or to @NULL if no + arguments are specified. + + @note + This function does check to make sure that the pointer you are assigning + is not the same pointer that is already stored. + */ + reset(T* p = NULL); + + /** + Swap the pointer inside the smart pointer with @a other. The pointer being + swapped must be of the same type (hence the same class name). + */ + swap(wxScopedPtr& other); +}; + + + +/** + @class wxScopedArray + @wxheader{ptr_scpd.h} + + This is a simple scoped smart pointer array implementation that is similar to + the Boost smart pointers (see http://www.boost.org/) but rewritten to + use macros instead. + + @b Example: + + Below is an example of using a wxWidgets scoped smart pointer and pointer array. + + @code + class MyClass { ... }; + + // declare a smart pointer to a MyClass called wxMyClassPtr + wxDECLARE_SCOPED_PTR(MyClass, wxMyClassPtr) + // declare a smart pointer to an array of chars + wxDECLARE_SCOPED_ARRAY(char, wxCharArray) + + ... + + // define the first pointer class, must be complete + wxDEFINE_SCOPED_PTR(MyClass, wxMyClassPtr) + // define the second pointer class + wxDEFINE_SCOPED_ARRAY(char, wxCharArray) + + // create an object with a new pointer to MyClass + wxMyClassPtr theObj(new MyClass()); + // reset the pointer (deletes the previous one) + theObj.reset(new MyClass()); + + // access the pointer + theObj->MyFunc(); + + // create an object with a new array of chars + wxCharArray theCharObj(new char[100]); + + // access the array + theCharObj[0] = "!"; + @endcode + + Declaring new smart pointer types: + @code + wxDECLAR_SCOPED_ARRAY( TYPE, // type of the values + CLASSNAME ); // name of the class + @endcode + + A smart pointer holds a pointer to an object (which must be complete when + wxDEFINE_SCOPED_ARRAY() is called). + + The memory used by the object is deleted when the smart pointer goes out of + scope. The first argument of the macro is the pointer type, the second is the + name of the new smart pointer class being created. Below we will use wxScopedArray + to represent the scoped pointer array class, but the user may create the class with + any legal name. + + @library{wxbase} + @category{smartpointers} + + @see wxScopedPtr +*/ +class wxScopedArray +{ +public: + /** + Creates the smart pointer with the given pointer or none if @NULL. On + compilers that support it, this uses the explicit keyword. + */ + wxScopedArray(type* T = NULL); + + /** + This operator gets the pointer stored in the smart pointer or returns @NULL if + there is none. + */ + const T* get(); + + /** + This operator acts like the standard [] indexing operator for C++ arrays. The + function does not do bounds checking. + */ + const T& operator [](long int i); + + /** + Deletes the currently held pointer and sets it to 'p' or to @NULL if no + arguments are specified. This function does check to make sure that the + pointer you are assigning is not the same pointer that is already stored. + */ + reset(T* p = NULL); + + /** + Swap the pointer inside the smart pointer with @a ot. The pointer being swapped + must be of the same type (hence the same class name). + */ + swap(wxScopedPtr& ot); +}; + + + +/** + @class wxScopedTiedPtr + @wxheader{ptr_scpd.h} + + This is a variation on the topic of wxScopedPtr. This class is also a smart pointer + but in addition it "ties" the pointer value to another variable. In other words, + during the life time of this class the value of that variable is set to be the same + as the value of the pointer itself and it is reset to its old value when the object + is destroyed. This class is especially useful when converting the existing code + (which may already store the pointers value in some variable) to the smart pointers. + + @library{wxbase} + @category{smartpointers} +*/ +class wxScopedTiedPtr : public wxScopedPtr +{ +public: + /** + Constructor creates a smart pointer initialized with @a ptr and stores + @a ptr in the location specified by @a ppTie which must not be @NULL. + */ + wxScopedTiedPtr(T** ppTie, T* ptr); + + /** + Destructor frees the pointer help by this object and restores the value stored + at the tied location (as specified in the @ref ctor() constructor) + to the old value. + + @warning + This location may now contain an uninitialized value if it hadn't been + initialized previously, in particular don't count on it magically being @NULL! + */ + ~wxScopedTiedPtr(); +}; + + + +/** + @wxheader{ptr_scpd.h} + + A scoped pointer template class. It is the template version of + the old-style @ref classwx_scoped_ptr "scoped pointer macros". + + @library{wxbase} + @category{smartpointers} + + @see wxSharedPtr, wxWeakRef +*/ +template +class wxScopedPtr +{ +public: + /** + Constructor. + */ + wxScopedPtr(T* ptr = NULL); + + /** + Destructor. + */ + ~wxScopedPtr(); + + /** + Returns pointer to object or @NULL. + */ + T* get() const; + + /** + Conversion to a boolean expression (in a variant which is not + convertable to anything but a boolean expression). + + If this class contains a valid pointer it will return @true, if it contains + a @NULL pointer it will return @false. + */ + operator unspecified_bool_type() const; + + /** + Returns a reference to the object. + + @note + If the internal pointer is @NULL this method will cause an assert + in debug mode. + */ + T operator*() const; + + /** + Returns pointer to object. If the pointer is @NULL this method will + cause an assert in debug mode. + */ + T* operator->() const; + + /** + Releases the current pointer and returns it. + + @remarks + Afterwards the caller is responsible for deleting + the data contained in the scoped pointer before. + */ + T* release(); + + /** + Reset pointer to the value of @a ptr. + The previous pointer will be deleted. + */ + void reset(T* ptr = NULL); + + /** + Swaps pointers. + */ + void swap(wxScopedPtr& ot); +}; + diff --git a/interface/wx/ptr_shrd.h b/interface/wx/ptr_shrd.h new file mode 100644 index 0000000000..ab24ca063f --- /dev/null +++ b/interface/wx/ptr_shrd.h @@ -0,0 +1,102 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: ptr_shrd.h +// Purpose: interface of wxSharedPtr +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @wxheader{ptr_shrd.h} + + A smart pointer with non-intrusive reference counting. It is modeled after + @c boost::shared_ptr<> and can be used with STL containers and wxVector - + unlike @c std::auto_ptr<> and wxScopedPtr. + + @library{wxbase} + @category{smartpointers} + + @see wxScopedPtr, wxWeakRef, wxObjectDataPtr +*/ + +template +class wxSharedPtr +{ +public: + /** + Constructor. + + Creates shared pointer from the raw pointer @a ptr and takes ownership + of it. + */ + wxEXPLICIT wxSharedPtr(T* ptr = NULL); + + /** + Copy constructor. + */ + wxSharedPtr(const wxSharedPtr& tocopy); + + /** + Destructor. + */ + ~wxSharedPtr(); + + /** + Returns pointer to its object or @NULL. + */ + T* get() const; + + /** + Conversion to a boolean expression (in a variant which is not + convertable to anything but a boolean expression). + + If this class contains a valid pointer it will return @true, if it contains + a @NULL pointer it will return @false. + */ + operator unspecified_bool_type() const; + + /** + Returns a reference to the object. + + If the internal pointer is @NULL this method will cause an assert in debug mode. + */ + T operator*() const; + + /** + Returns pointer to its object or @NULL. + */ + T* operator->() const; + + /** + Assignment operator. + + Releases any previously held pointer and creates a reference to @a ptr. + */ + wxSharedPtr& operator=(T* ptr); + + /** + Assignment operator. + + Releases any previously held pointer and creates a reference to the + same object as @a topcopy. + */ + wxSharedPtr& operator=(const wxSharedPtr& tocopy) + + /** + Reset pointer to @a ptr. + + If the reference count of the previously owned pointer was 1 it will be deleted. + */ + void reset(T* ptr = NULL); + + /** + Returns @true if this is the only pointer pointing to its object. + */ + bool unique() const; + + /** + Returns the number of pointers pointing to its object. + */ + long use_count() const; +}; + diff --git a/interface/wx/quantize.h b/interface/wx/quantize.h new file mode 100644 index 0000000000..eeea5bcad9 --- /dev/null +++ b/interface/wx/quantize.h @@ -0,0 +1,66 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: quantize.h +// Purpose: interface of wxQuantize +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxQuantize + @wxheader{quantize.h} + + Performs quantization, or colour reduction, on a wxImage. + + Functions in this class are static and so a wxQuantize object need not be + created. + + @library{wxcore} + @category{misc} +*/ +class wxQuantize : public wxObject +{ +public: + /** + Constructor. You do not need to construct a wxQuantize object since its + functions are static. + */ + wxQuantize(); + + /** + Converts input bitmap(s) into 8bit representation with custom palette. + @a in_rows and @a out_rows are arrays [0..h-1] of pointer to rows + (@a in_rows contains @a w * 3 bytes per row, @a out_rows @a w bytes per row). + Fills @a out_rows with indexes into palette (which is also stored into @a palette + variable). + */ + void DoQuantize(unsigned w, unsigned h, unsigned char** in_rows, + unsigned char** out_rows, unsigned char* palette, + int desiredNoColours); + + /** + Reduce the colours in the source image and put the result into the destination image. + Both images may be the same, to overwrite the source image. + + Specify an optional palette pointer to receive the resulting palette. + This palette may be passed to ConvertImageToBitmap, for example. + */ + bool Quantize(const wxImage& src, wxImage& dest, + wxPalette** pPalette, int desiredNoColours = 236, + unsigned char** eightBitData = 0, + int flags = wxQUANTIZE_INCLUDE_WINDOWS_COLOURS + |wxQUANTIZE_FILL_DESTINATION_IMAGE + |wxQUANTIZE_RETURN_8BIT_DATA); + + /** + This version sets a palette in the destination image so you don't + have to manage it yourself. + */ + bool Quantize(const wxImage& src, wxImage& dest, + int desiredNoColours = 236, + unsigned char** eightBitData = 0, + int flags = wxQUANTIZE_INCLUDE_WINDOWS_COLOURS + |wxQUANTIZE_FILL_DESTINATION_IMAGE + |wxQUANTIZE_RETURN_8BIT_DATA); +}; + diff --git a/interface/wx/radiobox.h b/interface/wx/radiobox.h new file mode 100644 index 0000000000..2aeb3772fa --- /dev/null +++ b/interface/wx/radiobox.h @@ -0,0 +1,318 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: radiobox.h +// Purpose: interface of wxRadioBox +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxRadioBox + @wxheader{radiobox.h} + + A radio box item is used to select one of number of mutually exclusive + choices. It is displayed as a vertical column or horizontal row of + labelled buttons. + + @beginStyleTable + @style{wxRA_SPECIFY_ROWS} + The major dimension parameter refers to the maximum number of rows. + @style{wxRA_SPECIFY_COLS} + The major dimension parameter refers to the maximum number of + columns. + @style{wxRA_USE_CHECKBOX} + Use of the checkbox controls instead of radio buttons (currently + supported only on PalmOS) + @endStyleTable + + @beginEventTable{wxCommandEvent} + @event{EVT_RADIOBOX(id, func)} + Process a @c wxEVT_COMMAND_RADIOBOX_SELECTED event, when a radiobutton + is clicked. + @endEventTable + + @library{wxcore} + @category{ctrl} + + + @see @ref overview_eventhandling, wxRadioButton, wxCheckBox +*/ +class wxRadioBox : public wxControl, wxItemContainerImmutable +{ +public: + + /** + Default constructor. + + @see Create(), wxValidator + */ + wxRadioBox(); + + /** + Constructor, creating and showing a radiobox. + + @param parent + Parent window. Must not be @NULL. + @param id + Window identifier. The value @c wxID_ANY indicates a default value. + @param label + Label for the static box surrounding the radio buttons. + @param pos + Window position. If @c wxDefaultPosition is specified then a + default position is chosen. + @param size + Window size. If @c wxDefaultSize is specified then a default size + is chosen. + @param n + Number of choices with which to initialize the radiobox. + @param choices + An array of choices with which to initialize the radiobox. + @param majorDimension + Specifies the maximum number of rows (if style contains + @c wxRA_SPECIFY_ROWS) or columns (if style contains + @c wxRA_SPECIFY_COLS) for a two-dimensional radiobox. + @param style + Window style. See wxRadioBox. + @param validator + Window validator. + @param name + Window name. + + @see Create(), wxValidator + */ + wxRadioBox(wxWindow* parent, wxWindowID id, + const wxString& label, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + int n = 0, + const wxString choices[] = NULL, + int majorDimension = 0, + long style = wxRA_SPECIFY_COLS, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "radioBox"); + + /** + Constructor, creating and showing a radiobox. + + @param parent + Parent window. Must not be @NULL. + @param id + Window identifier. The value @c wxID_ANY indicates a default value. + @param label + Label for the static box surrounding the radio buttons. + @param pos + Window position. If @c wxDefaultPosition is specified then a + default position is chosen. + @param size + Window size. If @c wxDefaultSize is specified then a default size + is chosen. + @param choices + An array of choices with which to initialize the radiobox. + @param majorDimension + Specifies the maximum number of rows (if style contains + @c wxRA_SPECIFY_ROWS) or columns (if style contains + @c wxRA_SPECIFY_COLS) for a two-dimensional radiobox. + @param style + Window style. See wxRadioBox. + @param validator + Window validator. + @param name + Window name. + + @see Create(), wxValidator + */ + wxRadioBox(wxWindow* parent, wxWindowID id, + const wxString& label, + const wxPoint& pos, + const wxSize& size, + const wxArrayString& choices, + int majorDimension = 0, + long style = wxRA_SPECIFY_COLS, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "radioBox"); + + /** + Destructor, destroying the radiobox item. + */ + ~wxRadioBox(); + + /** + Creates the radiobox for two-step construction. See wxRadioBox() + for further details. + */ + bool Create(wxWindow* parent, wxWindowID id, + const wxString& label, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + int n = 0, + const wxString choices[] = NULL, + int majorDimension = 0, + long style = wxRA_SPECIFY_COLS, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "radioBox"); + + /** + Creates the radiobox for two-step construction. See wxRadioBox() + for further details. + */ + bool Create(wxWindow* parent, wxWindowID id, + const wxString& label, + const wxPoint& pos, + const wxSize& size, + const wxArrayString& choices, + int majorDimension = 0, + long style = wxRA_SPECIFY_COLS, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "radioBox"); + + /** + Enables or disables an individual button in the radiobox. + + @param enable + @true to enable, @false to disable. + @param n + The zero-based button to enable or disable. + + @see wxWindow::Enable() + + @beginWxPythonOnly + In place of a single overloaded method name, wxPython implements the following methods: + + @beginTable + @row2col{Enable(flag), Enables or disables the entire radiobox.} + @row2col{EnableItem(n\, flag), Enables or disables an individual button in the radiobox.} + @endTable + + @endWxPythonOnly + */ + virtual bool Enable(unsigned int n, bool enable = true); + + + /** + Finds a button matching the given string, returning the position if found, or + -1 if not found. + + @param string + The string to find. + */ + int FindString(const wxString& string) const; + + /** + Returns the number of columns in the radiobox. + */ + unsigned int GetColumnCount() const; + + /** + Returns a radio box item under the point, a zero-based item index, or @c + wxNOT_FOUND if no item is under the point. + + @param pt + Point in client coordinates. + */ + int GetItemFromPoint(const wxPoint pt) const; + + /** + Returns the helptext associated with the specified @a item if any or @c + wxEmptyString. + + @param item + The zero-based item index. + + @see SetItemHelpText() + */ + wxString GetItemHelpText(unsigned int item) const; + + /** + Returns the tooltip associated with the specified @a item if any or @NULL. + + @see SetItemToolTip(), wxWindow::GetToolTip() + */ + wxToolTip* GetItemToolTip(unsigned int item) const; + + /** + Returns the number of rows in the radiobox. + */ + unsigned int GetRowCount() const; + + /** + Returns @true if the item is enabled or @false if it was disabled using + @ref Enable(unsigned int,bool) "Enable(n, false)". + + This function is currently only implemented in wxMSW, wxGTK and + wxUniversal and always returns @true in the other ports. + + @param n + The zero-based button position. + */ + bool IsItemEnabled(unsigned int n) const; + + /** + Returns @true if the item is currently shown or @false if it was hidden + using @ref Show(unsigned int,bool) "Show(n, false)". + + Note that this function returns @true for an item which hadn't been hidden + even if the entire radiobox is not currently shown. + + This function is currently only implemented in wxMSW, wxGTK and + wxUniversal and always returns @true in the other ports. + + @param n + The zero-based button position. + */ + bool IsItemShown(unsigned int n) const; + + /** + Sets the helptext for an item. Empty string erases any existing helptext. + + @param item + The zero-based item index. + @param helptext + The help text to set for the item. + + @see GetItemHelpText() + */ + void SetItemHelpText(unsigned int item, const wxString& helptext); + + /** + Sets the tooltip text for the specified item in the radio group. + + This function is currently only implemented in wxMSW and wxGTK2 and + does nothing in the other ports. + + @param item + Index of the item the tooltip will be shown for. + @param text + Tooltip text for the item, the tooltip is removed if empty. + + @see GetItemToolTip(), wxWindow::SetToolTip() + */ + void SetItemToolTip(unsigned int item, const wxString& text); + + /** + Shows or hides individual buttons. + + @param show + @true to show, @false to hide. + @param item + The zero-based position of the button to show or hide. + + @return + @true if the item has been shown or hidden or @false if nothing + was done because it already was in the requested state. + + @see + wxWindow::Show() + + @beginWxPythonOnly + In place of a single overloaded method name, wxPython implements the following methods: + + @beginTable + @row2col{Show(flag), Shows or hides the entire radiobox.} + @row2col{ShowItem(n\, flag), Shows or hides individual buttons.} + @endTable + + @endWxPythonOnly + + */ + virtual bool Show(unsigned int item, const bool show = true); +}; diff --git a/interface/wx/radiobut.h b/interface/wx/radiobut.h new file mode 100644 index 0000000000..dfce977c50 --- /dev/null +++ b/interface/wx/radiobut.h @@ -0,0 +1,120 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: radiobut.h +// Purpose: interface of wxRadioButton +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxRadioButton + @wxheader{radiobut.h} + + A radio button item is a button which usually denotes one of several + mutually exclusive options. It has a text label next to a (usually) round + button. + + You can create a group of mutually-exclusive radio buttons by specifying + @c wxRB_GROUP for the first in the group. The group ends when another + radio button group is created, or there are no more radio buttons. + + @beginStyleTable + @style{wxRB_GROUP} + Marks the beginning of a new group of radio buttons. + @style{wxRB_SINGLE} + In some circumstances, radio buttons that are not consecutive + siblings trigger a hang bug in Windows (only). If this happens, add + this style to mark the button as not belonging to a group, and + implement the mutually-exclusive group behaviour yourself. + @style{wxRB_USE_CHECKBOX} + Use a checkbox button instead of radio button (currently supported + only on PalmOS). + @endStyleTable + + @beginEventTable{wxCommandEvent} + @event{EVT_RADIOBUTTON(id, func)} + Process a @c wxEVT_COMMAND_RADIOBUTTON_SELECTED event, when the + radiobutton is clicked. + @endEventTable + + @library{wxcore} + @category{ctrl} + + + @see @ref overview_eventhandling, wxRadioBox, wxCheckBox +*/ +class wxRadioButton : public wxControl +{ +public: + + /** + Default constructor. + + @see Create(), wxValidator + */ + wxRadioButton(); + + /** + Constructor, creating and showing a radio button. + + @param parent + Parent window. Must not be @NULL. + @param id + Window identifier. The value @c wxID_ANY indicates a default value. + @param label + Label for the radio button. + @param pos + Window position. If @c wxDefaultPosition is specified then a default + position is chosen. + @param size + Window size. If @c wxDefaultSize is specified then a default size + is chosen. + @param style + Window style. See wxRadioButton. + @param validator + Window validator. + @param name + Window name. + + @see Create(), wxValidator + */ + wxRadioButton(wxWindow* parent, wxWindowID id, + const wxString& label, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "radioButton"); + + /** + Destructor, destroying the radio button item. + */ + ~wxRadioButton(); + + /** + Creates the choice for two-step construction. See wxRadioButton() for + further details. + */ + bool Create(wxWindow* parent, wxWindowID id, + const wxString& label, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "radioButton"); + + /** + Returns @true if the radio button is depressed, @false otherwise. + */ + bool GetValue() const; + + /** + Sets the radio button to selected or deselected status. This does not cause a + @c wxEVT_COMMAND_RADIOBUTTON_SELECTED event to get emitted. + + @param value + @true to select, @false to deselect. + */ + void SetValue(const bool value); +}; + diff --git a/interface/wx/rawbmp.h b/interface/wx/rawbmp.h new file mode 100644 index 0000000000..df9ac84567 --- /dev/null +++ b/interface/wx/rawbmp.h @@ -0,0 +1,215 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: rawbmp.h +// Purpose: interface of wxPixelData +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxPixelData + @wxheader{rawbmp.h} + + A class template with ready to use implementations for getting + direct and efficient access to wxBitmap's internal data and + wxImage's internal data through a standard interface. It is + possible to extend this class (interface) to other types of + image content. + + Implemented on Windows, GTK+ and OS X: + @li wxNativePixelData: Class to access to wxBitmap's internal data + without alpha channel (RGB). + @li wxAlphaPixelData: Class to access to wxBitmap's internal data with + alpha channel (RGBA). + + Implemented everywhere: + @li wxImagePixelData: Class to access to wxImage's internal data with + alpha channel (RGBA). + + Example: + + @code + wxBitmap bmp; + wxNativePixelData data(bmp); + if ( !data ) + { + // ... raw access to bitmap data unavailable, do something else ... + return; + } + + if ( data.GetWidth() < 20 || data.GetHeight() < 20 ) + { + // ... complain: the bitmap it too small ... + return; + } + + wxNativePixelData::Iterator p(data); + + // we draw a (10, 10)-(20, 20) rect manually using the given r, g, b + p.Offset(data, 10, 10); + + for ( int y = 0; y < 10; ++y ) + { + wxNativePixelData::Iterator rowStart = p; + + for ( int x = 0; x < 10; ++x, ++p ) + { + p.Red() = r; + p.Green() = g; + p.Blue() = b; + } + + p = rowStart; + p.OffsetY(data, 1); + } + @endcode + + @library{wxcore} + @category{gdi} + + @see wxBitmap, wxImage +*/ +template > +class wxPixelData : + public wxPixelDataOut::template wxPixelDataIn +{ +public: + /** + The type of the class we're working with. + */ + typedef Image ImageType; + + /** + Create pixel data object representing the entire image. + */ + wxPixelData(Image& image); + + + /** + Create pixel data object representing the area of the image defined by + @a rect. + */ + wxPixelData(Image& i, const wxRect& rect); + + /** + Create pixel data object representing the area of the image defined by + @a pt and @a sz. + */ + wxPixelData(Image& i, const wxPoint& pt, const wxSize& sz) + + /** + Return @true of if we could get access to bitmap data successfully. + */ + operator bool() const: + + /** + Return the iterator pointing to the origin of the image. + */ + Iterator GetPixels() const; + + /** + Returns origin of the rectangular region this wxPixelData represents. + */ + wxPoint GetOrigin() const; + + /** + Return width of the region this wxPixelData represents. + */ + int GetWidth() const; + + /** + Return height of the region this wxPixelData represents. + */ + int GetHeight() const; + + /** + Return the area which this wxPixelData represents in the image. + */ + wxSize GetSize() const; + + /** + Return the distance between two rows. + */ + int GetRowStride() const; + + + /** + The iterator of class wxPixelData. + */ + class Iterator + { + public: + + /** + Reset the iterator to point to (0, 0). + */ + void Reset(const PixelData& data); + + /** + Initializes the iterator to point to the origin of the given pixel + data. + */ + Iterator(PixelData& data); + + /** + Initializes the iterator to point to the origin of the given Bitmap. + */ + Iterator(wxBitmap& bmp, PixelData& data); + + /** + Default constructor. + */ + Iterator(); + + /** + Return @true if this iterator is valid. + */ + bool IsOk() const; + + /** + Advance the iterator to the next pixel, prefix version. + */ + Iterator& operator++(); + + /** + Advance the iterator to the next pixel, postfix (hence less + efficient -- don't use it unless you absolutely must) version. + */ + Iterator operator++(int); + + /** + Move @a x pixels to the right and @a y down. + + @note The rows won't wrap automatically. + */ + void Offset(const PixelData& data, int x, int y); + + /** + Move @a x pixels to the right. + + @note The rows won't wrap automatically. + */ + void OffsetX(const PixelData&data, int x); + + /** + Move @a y rows to the bottom + */ + void OffsetY(const PixelData& data, int y); + + /** + Go to the given position + */ + void MoveTo(const PixelData& data, int x, int y); + + //@{ + /** + Data Access: Access to invidividual colour components. + */ + ChannelType& Red(); + ChannelType& Green(); + ChannelType& Blue(); + ChannelType& Alpha(); + //@} + }; +}; + diff --git a/interface/wx/recguard.h b/interface/wx/recguard.h new file mode 100644 index 0000000000..d646798f41 --- /dev/null +++ b/interface/wx/recguard.h @@ -0,0 +1,100 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: recguard.h +// Purpose: interface of wxRecursionGuardFlag +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxRecursionGuardFlag + @wxheader{recguard.h} + + This is a completely opaque class which exists only to be used with + wxRecursionGuard, please see the example in that class' documentation. + + @remarks + + wxRecursionGuardFlag object must be declared @c static or the recursion + would never be detected. + + @library{wxbase} + @category{misc} +*/ +class wxRecursionGuardFlag +{ +public: + +}; + + + +/** + @class wxRecursionGuard + @wxheader{recguard.h} + + wxRecursionGuard is a very simple class which can be used to prevent reentrancy + problems in a function. It is not thread-safe and so should be used only in + single-threaded programs or in combination with some thread synchronization + mechanisms. + + wxRecursionGuard is always used together with the + wxRecursionGuardFlag like in this example: + + @code + void Foo() + { + static wxRecursionGuardFlag s_flag; + wxRecursionGuard guard(s_flag); + if ( guard.IsInside() ) + { + // don't allow reentrancy + return; + } + + ... + } + @endcode + + As you can see, wxRecursionGuard simply tests the flag value and sets it to + @true if it hadn't been already set. + IsInside() allows testing the old flag + value. The advantage of using this class compared to directly manipulating the + flag is that the flag is always reset in the wxRecursionGuard destructor and so + you don't risk to forget to do it even if the function returns in an unexpected + way (for example because an exception has been thrown). + + @library{wxbase} + @category{misc} +*/ +class wxRecursionGuard +{ +public: + /** + A wxRecursionGuard object must always be initialized with a @c static + wxRecursionGuardFlag. The constructor saves the + value of the flag to be able to return the correct value from + IsInside(). + */ + wxRecursionGuard(wxRecursionGuardFlag& flag); + + /** + The destructor resets the flag value so that the function can be entered again + the next time. + + @note This is not virtual, so this class is not meant to be derived + from (besides, there is absolutely no reason to do it anyhow). + */ + ~wxRecursionGuard(); + + /** + Returns @true if we're already inside the code block "protected" by this + wxRecursionGuard (i.e. between this line and the end of current scope). + Usually the function using wxRecursionGuard takes some specific actions + in such case (may be simply returning) to prevent reentrant calls to itself. + + If this method returns @false, it is safe to continue. + */ + bool IsInside() const; +}; + diff --git a/interface/wx/regex.h b/interface/wx/regex.h new file mode 100644 index 0000000000..a61eaf28a4 --- /dev/null +++ b/interface/wx/regex.h @@ -0,0 +1,246 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: regex.h +// Purpose: interface of wxRegEx +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @anchor wxRE_FLAGS + + Flags for regex compilation to be used with wxRegEx::Compile(). +*/ +enum +{ + /** Use extended regex syntax. */ + wxRE_EXTENDED = 0, + + /** Use advanced RE syntax (built-in regex only). */ + wxRE_ADVANCED = 1, + + /** Use basic RE syntax. */ + wxRE_BASIC = 2, + + /** Ignore case in match. */ + wxRE_ICASE = 4, + + /** Only check match, don't set back references. */ + wxRE_NOSUB = 8, + + /** + If not set, treat '\n' as an ordinary character, otherwise it is + special: it is not matched by '.' and '^' and '$' always match + after/before it regardless of the setting of wxRE_NOT[BE]OL. + */ + wxRE_NEWLINE = 16, + + /** Default flags.*/ + wxRE_DEFAULT = wxRE_EXTENDED +}; + +/** + @anchor wxRE_NOT_FLAGS + + Flags for regex matching to be used with wxRegEx::Matches(). + These flags are mainly useful when doing several matches in a long string + to prevent erroneous matches for '^' and '$': +*/ +enum +{ + /** '^' doesn't match at the start of line. */ + wxRE_NOTBOL = 32, + + /** '$' doesn't match at the end of line. */ + wxRE_NOTEOL = 64 +}; + +/** + @class wxRegEx + @wxheader{regex.h} + + wxRegEx represents a regular expression. This class provides support + for regular expressions matching and also replacement. + + It is built on top of either the system library (if it has support + for POSIX regular expressions - which is the case of the most modern + Unices) or uses the built in Henry Spencer's library. Henry Spencer + would appreciate being given credit in the documentation of software + which uses his library, but that is not a requirement. + + Regular expressions, as defined by POSIX, come in two flavours: @e extended + and @e basic. The builtin library also adds a third flavour + of expression @ref overview_resyntax "advanced", which is not available + when using the system library. + + Unicode is fully supported only when using the builtin library. + When using the system library in Unicode mode, the expressions and data + are translated to the default 8-bit encoding before being passed to + the library. + + On platforms where a system library is available, the default is to use + the builtin library for Unicode builds, and the system library otherwise. + It is possible to use the other if preferred by selecting it when building + the wxWidgets. + + @library{wxbase} + @category{data} + + Examples: + + A bad example of processing some text containing email addresses (the example + is bad because the real email addresses can have more complicated form than + @c user@host.net): + + @code + wxString text; + ... + wxRegEx reEmail = wxT("([^@]+)@([[:alnum:].-_].)+([[:alnum:]]+)"); + if ( reEmail.Matches(text) ) + { + wxString text = reEmail.GetMatch(email); + wxString username = reEmail.GetMatch(email, 1); + if ( reEmail.GetMatch(email, 3) == wxT("com") ) // .com TLD? + { + ... + } + } + + // or we could do this to hide the email address + size_t count = reEmail.ReplaceAll(text, wxT("HIDDEN@\\2\\3")); + printf("text now contains %u hidden addresses", count); + @endcode +*/ +class wxRegEx +{ +public: + + /** + Default constructor: use Compile() later. + */ + wxRegEx(); + + /** + Create and compile the regular expression, use + IsValid() to test for compilation errors. + + As for the flags, please see @ref wxRE_FLAGS. + */ + wxRegEx(const wxString& expr, int flags = wxRE_DEFAULT); + + + /** + Destructor. It's not virtual, don't derive from this class. + */ + ~wxRegEx(); + + /** + Compile the string into regular expression, return @true if ok or @false + if string has a syntax error. + + As for the flags, please see @ref wxRE_FLAGS. + */ + bool Compile(const wxString& pattern, int flags = wxRE_DEFAULT); + + /** + Get the start index and the length of the match of the expression + (if @a index is 0) or a bracketed subexpression (@a index different from 0). + + May only be called after successful call to Matches() and only if @c wxRE_NOSUB + was @b not used in Compile(). + + Returns @false if no match or if an error occurred. + + */ + bool GetMatch(size_t* start, size_t* len, size_t index = 0) const; + + /** + Returns the part of string corresponding to the match where index is interpreted + as above. Empty string is returned if match failed. + + May only be called after successful call to Matches() and only if @c wxRE_NOSUB + was @b not used in Compile(). + */ + wxString GetMatch(const wxString& text, size_t index = 0) const; + + /** + Returns the size of the array of matches, i.e. the number of bracketed + subexpressions plus one for the expression itself, or 0 on error. + + May only be called after successful call to Compile(). + and only if @c wxRE_NOSUB was @b not used. + */ + size_t GetMatchCount() const; + + /** + Return @true if this is a valid compiled regular expression, @false + otherwise. + */ + bool IsValid() const; + + //@{ + /** + Matches the precompiled regular expression against the string @a text, + returns @true if matches and @false otherwise. + + @e Flags may be combination of @c wxRE_NOTBOL and @c wxRE_NOTEOL, see + @ref wxRE_NOT_FLAGS. + + Some regex libraries assume that the text given is null terminated, while + others require the length be given as a separate parameter. Therefore for + maximum portability assume that @a text cannot contain embedded nulls. + + When the Matches(const wxChar *text, int flags = 0) form is used, + a wxStrlen() will be done internally if the regex library requires the + length. When using Matches() in a loop the Matches(text, flags, len) + form can be used instead, making it possible to avoid a wxStrlen() inside + the loop. + + May only be called after successful call to Compile(). + */ + bool Matches(const wxChar* text, int flags = 0) const; + const bool Matches(const wxChar* text, int flags, size_t len) const; + //@} + + /** + Matches the precompiled regular expression against the string @a text, + returns @true if matches and @false otherwise. + + @e Flags may be combination of @c wxRE_NOTBOL and @c wxRE_NOTEOL, see + @ref wxRE_NOT_FLAGS. + + May only be called after successful call to Compile(). + */ + const bool Matches(const wxString& text, int flags = 0) const; + + /** + Replaces the current regular expression in the string pointed to by + @a text, with the text in @a replacement and return number of matches + replaced (maybe 0 if none found) or -1 on error. + + The replacement text may contain back references @c \\number which will be + replaced with the value of the corresponding subexpression in the + pattern match. @c \\0 corresponds to the entire match and @c \& is a + synonym for it. Backslash may be used to quote itself or @c \& character. + + @a maxMatches may be used to limit the number of replacements made, setting + it to 1, for example, will only replace first occurrence (if any) of the + pattern in the text while default value of 0 means replace all. + */ + int Replace(wxString* text, const wxString& replacement, + size_t maxMatches = 0) const; + + /** + Replace all occurrences: this is actually a synonym for + Replace(). + + @see ReplaceFirst() + */ + int ReplaceAll(wxString* text, const wxString& replacement) const; + + /** + Replace the first occurrence. + */ + int ReplaceFirst(wxString* text, const wxString& replacement) const; +}; + diff --git a/interface/wx/region.h b/interface/wx/region.h new file mode 100644 index 0000000000..6d8d212213 --- /dev/null +++ b/interface/wx/region.h @@ -0,0 +1,438 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: region.h +// Purpose: interface of wxRegionIterator +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + Types of results returned from a call to wxRegion::Contains(). +*/ +enum wxRegionContain +{ + /** The specified value is not contained within this region. */ + wxOutRegion = 0, + + /** + The specified value is partially contained within this region. + + On Windows, this result is not supported. ::wxInRegion will be returned + instead. + */ + wxPartRegion = 1, + + /** + The specified value is fully contained within this region. + + On Windows, this result will be returned even if only part of the specified + value is contained in this region. + */ + wxInRegion = 2 +}; + +/** + @class wxRegionIterator + @wxheader{region.h} + + This class is used to iterate through the rectangles in a region, + typically when examining the damaged regions of a window within an OnPaint call. + + To use it, construct an iterator object on the stack and loop through the + regions, testing the object and incrementing the iterator at the end of the + loop. + + See wxPaintEvent for an example of use. + + @library{wxcore} + @category{gdi} + + @stdobjects + ::wxNullRegion + + @see wxPaintEvent +*/ +class wxRegionIterator : public wxObject +{ +public: + /** + Default constructor. + */ + wxRegionIterator(); + /** + Creates an iterator object given a region. + */ + wxRegionIterator(const wxRegion& region); + + /** + An alias for GetHeight(). + */ + wxCoord GetH() const; + + /** + Returns the height value for the current region. + */ + wxCoord GetHeight() const; + + /** + Returns the current rectangle. + */ + wxRect GetRect() const; + + /** + An alias for GetWidth(). + */ + wxCoord GetW() const; + + /** + Returns the width value for the current region. + */ + wxCoord GetWidth() const; + + /** + Returns the x value for the current region. + */ + wxCoord GetX() const; + + /** + Returns the y value for the current region. + */ + wxCoord GetY() const; + + /** + Returns @true if there are still some rectangles; otherwise returns @false. + */ + bool HaveRects() const; + + /** + Resets the iterator to the beginning of the rectangles. + */ + void Reset(); + + /** + Resets the iterator to the given region. + */ + void Reset(const wxRegion& region); + + /** + Increment operator. Increments the iterator to the next region. + + @beginWxPythonOnly + A wxPython alias for this operator is called Next. + @endWxPythonOnly + */ + void operator ++(); + + /** + Returns @true if there are still some rectangles; otherwise returns @false. + + You can use this to test the iterator object as if it were of type @c bool. + */ + operator bool() const; +}; + + + +/** + @class wxRegion + @wxheader{region.h} + + A wxRegion represents a simple or complex region on a device context or window. + + 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 counting, are not affected. + + @stdobjects + - ::wxNullRegion + + @library{wxcore} + @category{data,gdi} + + @see wxRegionIterator +*/ +class wxRegion : public wxGDIObject +{ +public: + /** + Default constructor. + */ + wxRegion(); + /** + Constructs a rectangular region with the given position and size. + */ + wxRegion(wxCoord x, wxCoord y, wxCoord width, wxCoord height); + /** + Constructs a rectangular region from the top left point and the bottom right + point. + */ + wxRegion(const wxPoint& topLeft, const wxPoint& bottomRight); + /** + Constructs a rectangular region a wxRect object. + */ + wxRegion(const wxRect& rect); + /** + Copy constructor, uses @ref overview_refcount. + */ + wxRegion(const wxRegion& region); + /** + Constructs a region corresponding to the polygon made of @a n points + in the provided array. + @a fillStyle parameter may have values @c wxWINDING_RULE or @c wxODDEVEN_RULE. + */ + wxRegion(size_t n, const wxPoint* points, int fillStyle = wxWINDING_RULE); + /** + Constructs a region using a bitmap. See Union() for more details. + */ + wxRegion(const wxBitmap& bmp); + /** + Constructs a region using the non-transparent pixels of a bitmap. See + Union() for more details. + */ + wxRegion(const wxBitmap& bmp, const wxColour& transColour, + int tolerance = 0); + + /** + Destructor. + See @ref overview_refcount_destruct "reference-counted object destruction" for + more info. + */ + ~wxRegion(); + + /** + Clears the current region. + */ + void Clear(); + + /** + Returns a value indicating whether the given point is contained within the region. + + @return The return value is one of @c wxOutRegion and @c wxInRegion. + */ + wxRegionContain Contains(long& x, long& y) const; + /** + Returns a value indicating whether the given point is contained within the region. + + @return The return value is one of @c wxOutRegion and @c wxInRegion. + */ + wxRegionContain Contains(const wxPoint& pt) const; + /** + Returns a value indicating whether the given rectangle is contained within the + region. + + @return One of ::wxOutRegion, ::wxPartRegion or ::wxInRegion. + + @note On Windows, only ::wxOutRegion and ::wxInRegion are returned; a value + ::wxInRegion then indicates that all or some part of the region is + contained in this region. + */ + wxRegionContain Contains(long& x, long& y, long& width, long& height) const; + /** + Returns a value indicating whether the given rectangle is contained within the + region. + + @return One of ::wxOutRegion, ::wxPartRegion or ::wxInRegion. + + @note On Windows, only ::wxOutRegion and ::wxInRegion are returned; a value + ::wxInRegion then indicates that all or some part of the region is + contained in this region. + */ + wxRegionContain Contains(const wxRect& rect) const; + + /** + Convert the region to a black and white bitmap with the white pixels + being inside the region. + */ + wxBitmap ConvertToBitmap() const; + + //@{ + /** + Returns the outer bounds of the region. + */ + void GetBox(wxCoord& x, wxCoord& y, wxCoord& width, + wxCoord& height) const; + const wxRect GetBox() const; + //@} + + /** + Finds the intersection of this region and another, rectangular region, + specified using position and size. + + @return @true if successful, @false otherwise. + + @remarks Creates the intersection of the two regions, that is, the parts + which are in both regions. The result is stored in this + region. + */ + bool Intersect(wxCoord x, wxCoord y, wxCoord width, + wxCoord height); + /** + Finds the intersection of this region and another, rectangular region. + + @return @true if successful, @false otherwise. + + @remarks Creates the intersection of the two regions, that is, the parts + which are in both regions. The result is stored in this + region. + */ + bool Intersect(const wxRect& rect); + /** + Finds the intersection of this region and another region. + + @return @true if successful, @false otherwise. + + @remarks Creates the intersection of the two regions, that is, the parts + which are in both regions. The result is stored in this + region. + */ + bool Intersect(const wxRegion& region); + + /** + Returns @true if the region is empty, @false otherwise. + */ + bool IsEmpty() const; + + /** + Returns @true if the region is equal to, i.e. covers the same area as, + another one. + + @note If both this region and @a region are invalid, they are + considered to be equal. + */ + bool IsEqual(const wxRegion& region) const; + + //@{ + /** + Moves the region by the specified offsets in horizontal and vertical + directions. + + @return @true if successful, @false otherwise (the region is unchanged + then). + */ + bool Offset(wxCoord x, wxCoord y); + bool Offset(const wxPoint& pt); + //@} + + /** + Subtracts a rectangular region from this region. + + @return @true if successful, @false otherwise. + + @remarks This operation combines the parts of 'this' region that are not + part of the second region. The result is stored in this + region. + */ + bool Subtract(const wxRect& rect); + /** + Subtracts a region from this region. + + @return @true if successful, @false otherwise. + + @remarks This operation combines the parts of 'this' region that are not + part of the second region. The result is stored in this + region. + */ + bool Subtract(const wxRegion& region); + + /** + Finds the union of this region and another, rectangular region, specified using + position and size. + + @return @true if successful, @false otherwise. + + @remarks This operation creates a region that combines all of this region + and the second region. The result is stored in this + region. + */ + bool Union(wxCoord x, wxCoord y, wxCoord width, wxCoord height); + /** + Finds the union of this region and another, rectangular region. + + @return @true if successful, @false otherwise. + + @remarks This operation creates a region that combines all of this region + and the second region. The result is stored in this + region. + */ + bool Union(const wxRect& rect); + /** + Finds the union of this region and another region. + + @return @true if successful, @false otherwise. + + @remarks This operation creates a region that combines all of this region + and the second region. The result is stored in this + region. + */ + bool Union(const wxRegion& region); + /** + Finds the union of this region and the non-transparent pixels of a + bitmap. The bitmap's mask is used to determine transparency. If the + bitmap doesn't have a mask, the bitmap's full dimensions are used. + + @return @true if successful, @false otherwise. + + @remarks This operation creates a region that combines all of this region + and the second region. The result is stored in this + region. + */ + bool Union(const wxBitmap& bmp); + /** + Finds the union of this region and the non-transparent pixels of a + bitmap. Colour to be treated as transparent is specified in the + @a transColour argument, along with an optional colour tolerance value. + + @return @true if successful, @false otherwise. + + @remarks This operation creates a region that combines all of this region + and the second region. The result is stored in this + region. + */ + bool Union(const wxBitmap& bmp, const wxColour& transColour, + int tolerance = 0); + + /** + Finds the Xor of this region and another, rectangular region, specified using + position and size. + + @return @true if successful, @false otherwise. + + @remarks This operation creates a region that combines all of this region + and the second region, except for any overlapping + areas. The result is stored in this region. + */ + bool Xor(wxCoord x, wxCoord y, wxCoord width, wxCoord height); + /** + Finds the Xor of this region and another, rectangular region. + + @return @true if successful, @false otherwise. + + @remarks This operation creates a region that combines all of this region + and the second region, except for any overlapping + areas. The result is stored in this region. + */ + bool Xor(const wxRect& rect); + /** + Finds the Xor of this region and another region. + + @return @true if successful, @false otherwise. + + @remarks This operation creates a region that combines all of this region + and the second region, except for any overlapping + areas. The result is stored in this region. + */ + bool Xor(const wxRegion& region); + + /** + Assignment operator, using @ref overview_refcount. + */ + void operator =(const wxRegion& region); +}; + +/** + An empty region. +*/ +wxRegion wxNullRegion; diff --git a/interface/wx/renderer.h b/interface/wx/renderer.h new file mode 100644 index 0000000000..6c33c39d59 --- /dev/null +++ b/interface/wx/renderer.h @@ -0,0 +1,523 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: renderer.h +// Purpose: interface of wxRendererNative +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @anchor wxCONTROL_FLAGS + + The following rendering flags are defined for wxRendererNative: +*/ +enum +{ + /** Control is disabled. */ + wxCONTROL_DISABLED = 0x00000001, + + /** Currently has keyboard focus. */ + wxCONTROL_FOCUSED = 0x00000002, + + /** (Button) is pressed. */ + wxCONTROL_PRESSED = 0x00000004, + + /** Control-specific bit. */ + wxCONTROL_SPECIAL = 0x00000008, + + /** Only for the buttons. */ + wxCONTROL_ISDEFAULT = wxCONTROL_SPECIAL, + + /** Only for the menu items. */ + wxCONTROL_ISSUBMENU = wxCONTROL_SPECIAL, + + /** Only for the tree items. */ + wxCONTROL_EXPANDED = wxCONTROL_SPECIAL, + + /** Only for the status bar panes. */ + wxCONTROL_SIZEGRIP = wxCONTROL_SPECIAL, + + /** Checkboxes only: flat border. */ + wxCONTROL_FLAT = wxCONTROL_SPECIAL, + + /** Mouse is currently over the control. */ + wxCONTROL_CURRENT = 0x00000010, + + /** Selected item in e.g. listbox. */ + wxCONTROL_SELECTED = 0x00000020, + + /** (Check/radio button) is checked. */ + wxCONTROL_CHECKED = 0x00000040, + + /** (Menu) item can be checked. */ + wxCONTROL_CHECKABLE = 0x00000080, + + /** (Check) undetermined state. */ + wxCONTROL_UNDETERMINED = wxCONTROL_CHECKABLE +}; + +/** + @struct wxSplitterRenderParams + @wxheader{renderer.h} + + This is just a simple @c struct used as a return value of + wxRendererNative::GetSplitterParams(). + + It doesn't have any methods and all of its fields are constant, so they can + only be examined but not modified. + + @library{wxbase} + @category{gdi} +*/ +struct wxSplitterRenderParams +{ + /** + The only way to initialize this struct is by using this ctor. + */ + wxSplitterRenderParams(wxCoord widthSash_, wxCoord border_, bool isSens_); + + /** + The width of the border drawn by the splitter inside it, may be 0. + */ + const wxCoord border; + + /** + @true if the sash changes appearance when the mouse passes over it, @false + otherwise. + */ + const bool isHotSensitive; + + /** + The width of the splitter sash. + */ + const wxCoord widthSash; +}; + +/** + @struct wxHeaderButtonParams + @wxheader{renderer.h} + + This @c struct can optionally be used with + wxRendererNative::DrawHeaderButton() to specify custom values used to draw + the text or bitmap label. + + @library{wxbase} + @category{gdi} +*/ +struct wxHeaderButtonParams +{ + wxHeaderButtonParams(); + + wxColour m_arrowColour; + wxColour m_selectionColour; + wxString m_labelText; + wxFont m_labelFont; + wxColour m_labelColour; + wxBitmap m_labelBitmap; + int m_labelAlignment; +}; + +/** + Used to specify the type of sort arrow used with + wxRendererNative::DrawHeaderButton(). +*/ +enum wxHeaderSortIconType +{ + wxHDR_SORT_ICON_NONE, ///< Don't draw a sort arrow. + wxHDR_SORT_ICON_UP, ///< Draw a sort arrow icon pointing up. + wxHDR_SORT_ICON_DOWN ///< Draw a sort arrow icon pointing down. +}; + + + +/** + @class wxDelegateRendererNative + @wxheader{renderer.h} + + wxDelegateRendererNative allows reuse of renderers code by forwarding all the + wxRendererNative methods to the given object and + thus allowing you to only modify some of its methods -- without having to + reimplement all of them. + + Note that the "normal", inheritance-based approach, doesn't work with the + renderers as it is impossible to derive from a class unknown at compile-time + and the renderer is only chosen at run-time. So suppose that you want to only + add something to the drawing of the tree control buttons but leave all the + other methods unchanged -- the only way to do it, considering that the renderer + class which you want to customize might not even be written yet when you write + your code (it could be written later and loaded from a DLL during run-time), is + by using this class. + + Except for the constructor, it has exactly the same methods as + wxRendererNative and their implementation is + trivial: they are simply forwarded to the real renderer. Note that the "real" + renderer may, in turn, be a wxDelegateRendererNative as well and that there may + be arbitrarily many levels like this -- but at the end of the chain there must + be a real renderer which does the drawing. + + @library{wxcore} + @category{gdi} + + @see wxRendererNative +*/ +class wxDelegateRendererNative : public wxRendererNative +{ +public: + /** + The default constructor does the same thing as the other one except that it + uses the @ref wxRendererNative::GetGeneric() "generic renderer" instead of the + user-specified @a rendererNative. + + In any case, this sets up the delegate renderer object to follow all calls to + the specified real renderer. + */ + wxDelegateRendererNative(); + /** + This constructor uses the user-specified @a rendererNative to set up the delegate + renderer object to follow all calls to the specified real renderer. + + @note + This object does not take ownership of (i.e. won't delete) @a rendererNative. + */ + wxDelegateRendererNative(wxRendererNative& rendererNative); + + // The rest of these functions inherit the documentation from wxRendererNative + + virtual int DrawHeaderButton(wxWindow *win, wxDC& dc, + const wxRect& rect, int flags = 0, + wxHeaderSortIconType sortArrow = wxHDR_SORT_ICON_NONE, + wxHeaderButtonParams* params = NULL); + + virtual int DrawHeaderButtonContents(wxWindow *win, wxDC& dc, + const wxRect& rect, int flags = 0, + wxHeaderSortIconType sortArrow = wxHDR_SORT_ICON_NONE, + wxHeaderButtonParams* params = NULL); + + virtual int GetHeaderButtonHeight(wxWindow *win); + + virtual void DrawTreeItemButton(wxWindow *win, wxDC& dc, + const wxRect& rect, int flags = 0); + + virtual void DrawSplitterBorder(wxWindow *win, wxDC& dc, + const wxRect& rect, int flags = 0); + + virtual void DrawSplitterSash(wxWindow *win, wxDC& dc, + const wxSize& size, wxCoord position, + wxOrientation orient, int flags = 0); + + virtual void DrawComboBoxDropButton(wxWindow *win, wxDC& dc, + const wxRect& rect, int flags = 0); + + virtual void DrawDropArrow(wxWindow *win, wxDC& dc, + const wxRect& rect, int flags = 0); + + virtual void DrawCheckBox(wxWindow *win, wxDC& dc, + const wxRect& rect, int flags = 0 ); + + virtual void DrawPushButton(wxWindow *win, wxDC& dc, + const wxRect& rect, int flags = 0 ); + + virtual void DrawItemSelectionRect(wxWindow *win, wxDC& dc, + const wxRect& rect, int flags = 0 ); + + virtual void DrawFocusRect(wxWindow* win, wxDC& dc, + const wxRect& rect, int flags = 0); + + virtual wxSplitterRenderParams GetSplitterParams(const wxWindow *win); + + virtual wxRendererVersion GetVersion() const; +}; + + + +/** + @class wxRendererNative + @wxheader{renderer.h} + + First, a brief introduction to wxRendererNative and why it is needed. + + Usually wxWidgets uses the underlying low level GUI system to draw all the + controls - this is what we mean when we say that it is a "native" framework. + However not all controls exist under all (or even any) platforms and in this + case wxWidgets provides a default, generic, implementation of them written in + wxWidgets itself. + + These controls don't have the native appearance if only the standard + line drawing and other graphics primitives are used, because the native + appearance is different under different platforms while the lines are always + drawn in the same way. + + This is why we have renderers: wxRendererNative is a class which virtualizes the + drawing, i.e. it abstracts the drawing operations and allows you to draw say, a + button, without caring about exactly how this is done. Of course, as we + can draw the button differently in different renderers, this also allows us to + emulate the native look and feel. + + So the renderers work by exposing a large set of high-level drawing functions + which are used by the generic controls. There is always a default global + renderer but it may be changed or extended by the user, see + @ref page_samples_render. + + All drawing functions take some standard parameters: + + @li @a win - The window being drawn. It is normally not used and when + it is it should only be used as a generic wxWindow + (in order to get its low level handle, for example), but you should + not assume that it is of some given type as the same renderer + function may be reused for drawing different kinds of control. + @li @a dc - The wxDC to draw on. Only this device + context should be used for drawing. It is not necessary to restore + pens and brushes for it on function exit but, on the other hand, you + shouldn't assume that it is in any specific state on function entry: + the rendering functions should always prepare it. + @li @a rect - The bounding rectangle for the element to be drawn. + @li @a flags - The optional flags (none by default) which can be a + combination of the @ref wxCONTROL_FLAGS. + + Note that each drawing function restores the wxDC attributes if + it changes them, so it is safe to assume that the same pen, brush and colours + that were active before the call to this function are still in effect after it. + + @library{wxcore} + @category{gdi} +*/ +class wxRendererNative +{ +public: + /** + Virtual destructor as for any base class. + */ + ~wxRendererNative(); + + /** + Draw a check box (used by wxDataViewCtrl). + + @a flags may have the @c wxCONTROL_CHECKED, @c wxCONTROL_CURRENT or + @c wxCONTROL_UNDETERMINED bit set, see @ref wxCONTROL_FLAGS. + */ + virtual void DrawCheckBox(wxWindow* win, wxDC& dc, + const wxRect& rect, int flags); + + /** + Draw a button like the one used by wxComboBox to show a + drop down window. The usual appearance is a downwards pointing arrow. + + @a flags may have the @c wxCONTROL_PRESSED or @c wxCONTROL_CURRENT bit set, + see @ref wxCONTROL_FLAGS. + */ + virtual void DrawComboBoxDropButton(wxWindow* win, wxDC& dc, + const wxRect& rect, + int flags); + + /** + Draw a drop down arrow that is suitable for use outside a combo box. Arrow will + have transparent background. + + @a rect is not entirely filled by the arrow. Instead, you should use bounding + rectangle of a drop down button which arrow matches the size you need. + + @a flags may have the @c wxCONTROL_PRESSED or @c wxCONTROL_CURRENT bit set, + see @ref wxCONTROL_FLAGS. + */ + virtual void DrawDropArrow(wxWindow* win, wxDC& dc, const wxRect& rect, + int flags); + + /** + Draw a focus rectangle using the specified rectangle. + wxListCtrl. + + The only supported flags is @c wxCONTROL_SELECTED for items which are selected. + see @ref wxCONTROL_FLAGS. + */ + virtual void DrawFocusRect(wxWindow* win, wxDC& dc, const wxRect& rect, + int flags = 0); + + /** + Draw the header control button (used, for example, by wxListCtrl). + + Depending on platforms the @a flags parameter may support the @c wxCONTROL_SELECTED + @c wxCONTROL_DISABLED and @c wxCONTROL_CURRENT bits, see @ref wxCONTROL_FLAGS. + + @return + The optimal width to contain the the unabreviated label text or + bitmap, the sort arrow if present, and internal margins. + */ + virtual int DrawHeaderButton(wxWindow* win, wxDC& dc, + const wxRect& rect, int flags = 0, + wxHeaderSortIconType sortArrow = wxHDR_SORT_ICON_NONE, + wxHeaderButtonParams* params = NULL); + + /** + Draw the contents of a header control button (label, sort arrows, + etc.). This function is normally only called by DrawHeaderButton(). + + Depending on platforms the @a flags parameter may support the @c wxCONTROL_SELECTED + @c wxCONTROL_DISABLED and @c wxCONTROL_CURRENT bits, see @ref wxCONTROL_FLAGS. + + @return + The optimal width to contain the the unabreviated label text or + bitmap, the sort arrow if present, and internal margins. + */ + virtual int DrawHeaderButtonContents(wxWindow *win, wxDC& dc, + const wxRect& rect, int flags = 0, + wxHeaderSortIconType sortArrow = wxHDR_SORT_ICON_NONE, + wxHeaderButtonParams* params = NULL); + + /** + Draw a selection rectangle underneath the text as used e.g. in a + wxListCtrl. + + The supported @a flags are @c wxCONTROL_SELECTED for items + which are selected (e.g. often a blue rectangle) and @c wxCONTROL_CURRENT + for the item that has the focus (often a dotted line around the item's text). + @c wxCONTROL_FOCUSED may be used to indicate if the control has the focus + (othewise the the selection rectangle is e.g. often grey and not blue). + This may be ignored by the renderer or deduced by the code directly from + the @a win. + */ + virtual void DrawItemSelectionRect(wxWindow* win, wxDC& dc, + const wxRect& rect, int flags = 0); + + /** + Draw a blank push button that looks very similar to wxButton. + + @a flags may have the @c wxCONTROL_PRESSED, @c wxCONTROL_CURRENT or + @c wxCONTROL_ISDEFAULT bit set, see @ref wxCONTROL_FLAGS. + */ + virtual void DrawPushButton(wxWindow* win, wxDC& dc, + const wxRect& rect, int flags); + + /** + Draw the border for sash window: this border must be such that the sash + drawn by DrawSplitterSash() blends into it well. + */ + virtual void DrawSplitterBorder(wxWindow* win, wxDC& dc, + const wxRect& rect, int flags = 0); + + /** + Draw a sash. The @a orient parameter defines whether the sash should be + vertical or horizontal and how the @a position should be interpreted. + */ + virtual void DrawSplitterSash(wxWindow* win, wxDC& dc, + const wxSize& size, wxCoord position, + wxOrientation orient, int flags = 0); + + /** + Draw the expanded/collapsed icon for a tree control item. + + To draw an expanded button the @a flags parameter must contain @c wxCONTROL_EXPANDED bit, + see @ref wxCONTROL_FLAGS. + */ + virtual void DrawTreeItemButton(wxWindow* win, wxDC& dc, + const wxRect& rect, int flags = 0); + + /** + Return the currently used renderer. + */ + static wxRendererNative Get(); + + /** + Return the default (native) implementation for this platform -- this is also + the one used by default but this may be changed by calling + Set() in which case the return value of this + method may be different from the return value of Get(). + */ + static wxRendererNative GetDefault(); + + /** + Return the generic implementation of the renderer. Under some platforms, this + is the default renderer implementation, others have platform-specific default + renderer which can be retrieved by calling GetDefault(). + */ + static wxRendererNative GetGeneric(); + + /** + Returns the height of a header button, either a fixed platform height if + available, or a + generic height based on the window's font. + */ + virtual int GetHeaderButtonHeight(wxWindow* win); + + /** + Get the splitter parameters, see + wxSplitterRenderParams. + */ + virtual wxSplitterRenderParams GetSplitterParams(const wxWindow* win); + + /** + This function is used for version checking: Load() + refuses to load any shared libraries implementing an older or incompatible + version. + + @remarks + The implementation of this method is always the same in all renderers (simply + construct wxRendererVersion using the @c wxRendererVersion::Current_XXX values), + but it has to be in the derived, not base, class, to detect mismatches between + the renderers versions and so you have to implement it anew in all renderers. + */ + virtual wxRendererVersion GetVersion() const; + + /** + Load the renderer from the specified DLL, the returned pointer must be + deleted by caller if not @NULL when it is not used any more. + + The @a name should be just the base name of the renderer and not the full + name of the DLL file which is constructed differently (using + wxDynamicLibrary::CanonicalizePluginName()) + on different systems. + */ + static wxRendererNative* Load(const wxString& name); + + /** + Set the renderer to use, passing @NULL reverts to using the default + renderer (the global renderer must always exist). + + Return the previous renderer used with Set() or @NULL if none. + */ + static wxRendererNative* Set(wxRendererNative* renderer); +}; + + + +/** + @struct wxRendererVersion + @wxheader{renderer.h} + + This simple struct represents the wxRendererNative + interface version and is only used as the return value of + wxRendererNative::GetVersion(). + + The version has two components: the version itself and the age. If the main + program and the renderer have different versions they are never compatible with + each other because the version is only changed when an existing virtual + function is modified or removed. The age, on the other hand, is incremented + each time a new virtual method is added and so, at least for the compilers + using a common C++ object model, the calling program is compatible with any + renderer which has the age greater or equal to its age. This verification is + done by IsCompatible() method. + + @library{wxbase} + @category{gdi} +*/ +struct wxRendererVersion +{ + /** + Checks if the main program is compatible with the renderer having the version + @e ver, returns @true if it is and @false otherwise. + + This method is used by wxRendererNative::Load() to determine whether a + renderer can be used. + */ + static bool IsCompatible(const wxRendererVersion& ver); + + /** + The age component. + */ + const int age; + + /** + The version component. + */ + const int version; +}; + diff --git a/interface/wx/richtext/richtextbuffer.h b/interface/wx/richtext/richtextbuffer.h new file mode 100644 index 0000000000..31b30625c5 --- /dev/null +++ b/interface/wx/richtext/richtextbuffer.h @@ -0,0 +1,1035 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: richtext/richtextbuffer.h +// Purpose: interface of wxRichTextBuffer +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxRichTextBuffer + @headerfile richtextbuffer.h wx/richtext/richtextbuffer.h + + This class represents the whole buffer associated with a wxRichTextCtrl. + + @library{wxrichtext} + @category{richtext} + + @see wxTextAttr, wxRichTextCtrl +*/ +class wxRichTextBuffer +{ +public: + //@{ + /** + Default constructors. + */ + wxRichTextBuffer(const wxRichTextBuffer& obj); + wxRichTextBuffer(); + //@} + + /** + Destructor. + */ + ~wxRichTextBuffer(); + + /** + Adds an event handler to the buffer's list of handlers. A buffer associated with + a contol has the control as the only event handler, but the application is free + to add more if further notification is required. All handlers are notified + of an event originating from the buffer, such as the replacement of a style + sheet + during loading. The buffer never deletes any of the event handlers, unless + RemoveEventHandler() is + called with @true as the second argument. + */ + bool AddEventHandler(wxEvtHandler* handler); + + /** + Adds a file handler. + */ + void AddHandler(wxRichTextFileHandler* handler); + + /** + Adds a paragraph of text. + */ + wxRichTextRange AddParagraph(const wxString& text); + + /** + Returns @true if the buffer is currently collapsing commands into a single + notional command. + */ + bool BatchingUndo() const; + + /** + Begins using alignment. + */ + bool BeginAlignment(wxTextAttrAlignment alignment); + + /** + Begins collapsing undo/redo commands. Note that this may not work properly + if combining commands that delete or insert content, changing ranges for + subsequent actions. + @a cmdName should be the name of the combined command that will appear + next to Undo and Redo in the edit menu. + */ + bool BeginBatchUndo(const wxString& cmdName); + + /** + Begin applying bold. + */ + bool BeginBold(); + + /** + Begins applying the named character style. + */ + bool BeginCharacterStyle(const wxString& characterStyle); + + /** + Begins using this font. + */ + bool BeginFont(const wxFont& font); + + /** + Begins using the given point size. + */ + bool BeginFontSize(int pointSize); + + /** + Begins using italic. + */ + bool BeginItalic(); + + /** + Begin using @a leftIndent for the left indent, and optionally @a leftSubIndent + for + the sub-indent. Both are expressed in tenths of a millimetre. + The sub-indent is an offset from the left of the paragraph, and is used for all + but the + first line in a paragraph. A positive value will cause the first line to appear + to the left + of the subsequent lines, and a negative value will cause the first line to be + indented + relative to the subsequent lines. + */ + bool BeginLeftIndent(int leftIndent, int leftSubIndent = 0); + + /** + Begins line spacing using the specified value. @e spacing is a multiple, where + 10 means single-spacing, + 15 means 1.5 spacing, and 20 means double spacing. The following constants are + defined for convenience: + */ + bool BeginLineSpacing(int lineSpacing); + + /** + Begins using a specified list style. Optionally, you can also pass a level and + a number. + */ + bool BeginListStyle(const wxString& listStyle, int level = 1, + int number = 1); + + /** + Begins a numbered bullet. This call will be needed for each item in the list, + and the + application should take care of incrementing the numbering. + @a bulletNumber is a number, usually starting with 1. + @a leftIndent and @a leftSubIndent are values in tenths of a millimetre. + @a bulletStyle is a bitlist of the following values: + + wxRichTextBuffer uses indentation to render a bulleted item. The left indent is + the distance between + the margin and the bullet. The content of the paragraph, including the first + line, starts + at leftMargin + leftSubIndent. So the distance between the left edge of the + bullet and the + left of the actual paragraph is leftSubIndent. + */ + bool BeginNumberedBullet(int bulletNumber, int leftIndent, + int leftSubIndent, + int bulletStyle = wxTEXT_ATTR_BULLET_STYLE_ARABIC|wxTEXT_ATTR_BULLET_STYLE_PERIOD); + + /** + Begins paragraph spacing; pass the before-paragraph and after-paragraph spacing + in tenths of + a millimetre. + */ + bool BeginParagraphSpacing(int before, int after); + + /** + Begins applying the named paragraph style. + */ + bool BeginParagraphStyle(const wxString& paragraphStyle); + + /** + Begins a right indent, specified in tenths of a millimetre. + */ + bool BeginRightIndent(int rightIndent); + + /** + Begins applying a standard bullet, using one of the standard bullet names + (currently @c standard/circle or @c standard/square. + See BeginNumberedBullet() for an explanation of how indentation is used to + render the bulleted paragraph. + */ + bool BeginStandardBullet(const wxString& bulletName, + int leftIndent, + int leftSubIndent, + int bulletStyle = wxTEXT_ATTR_BULLET_STYLE_STANDARD); + + /** + Begins using a specified style. + */ + bool BeginStyle(const wxTextAttr& style); + + /** + Begins suppressing undo/redo commands. The way undo is suppressed may be + implemented + differently by each command. If not dealt with by a command implementation, then + it will be implemented automatically by not storing the command in the undo + history + when the action is submitted to the command processor. + */ + bool BeginSuppressUndo(); + + /** + Begins applying a symbol bullet, using a character from the current font. See + BeginNumberedBullet() for + an explanation of how indentation is used to render the bulleted paragraph. + */ + bool BeginSymbolBullet(wxChar symbol, int leftIndent, + int leftSubIndent, + int bulletStyle = wxTEXT_ATTR_BULLET_STYLE_SYMBOL); + + /** + Begins using the specified text foreground colour. + */ + bool BeginTextColour(const wxColour& colour); + + /** + Begins applying wxTEXT_ATTR_URL to the content. Pass a URL and optionally, a + character style to apply, + since it is common to mark a URL with a familiar style such as blue text with + underlining. + */ + bool BeginURL(const wxString& url, + const wxString& characterStyle = wxEmptyString); + + /** + Begins using underline. + */ + bool BeginUnderline(); + + /** + Returns @true if content can be pasted from the clipboard. + */ + bool CanPasteFromClipboard() const; + + /** + Cleans up the file handlers. + */ + void CleanUpHandlers(); + + /** + Clears the buffer. + */ + void Clear(); + + //@{ + /** + Clears the list style from the given range, clearing list-related attributes + and applying any named paragraph style associated with each paragraph. + @a flags is a bit list of the following: + wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable. + See also SetListStyle(), PromoteList(), NumberList(). + */ + bool ClearListStyle(const wxRichTextRange& range, + int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO); + bool ClearListStyle(const wxRichTextRange& range, + int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO); + //@} + + /** + Clears the style stack. + */ + void ClearStyleStack(); + + /** + Clones the object. + */ + wxRichTextObject* Clone() const; + + /** + Copies the given buffer. + */ + void Copy(const wxRichTextBuffer& obj); + + /** + Copy the given range to the clipboard. + */ + bool CopyToClipboard(const wxRichTextRange& range); + + /** + Submits a command to delete the given range. + */ + bool DeleteRangeWithUndo(const wxRichTextRange& range, + wxRichTextCtrl* ctrl); + + //@{ + /** + Dumps the contents of the buffer for debugging purposes. + */ + void Dump(); + void Dump(wxTextOutputStream& stream); + //@} + + /** + Ends alignment. + */ + bool EndAlignment(); + + /** + Ends all styles that have been started with a Begin... command. + */ + bool EndAllStyles(); + + /** + Ends collapsing undo/redo commands, and submits the combined command. + */ + bool EndBatchUndo(); + + /** + Ends using bold. + */ + bool EndBold(); + + /** + Ends using the named character style. + */ + bool EndCharacterStyle(); + + /** + Ends using a font. + */ + bool EndFont(); + + /** + Ends using a point size. + */ + bool EndFontSize(); + + /** + Ends using italic. + */ + bool EndItalic(); + + /** + Ends using a left indent. + */ + bool EndLeftIndent(); + + /** + Ends using a line spacing. + */ + bool EndLineSpacing(); + + /** + Ends using a specified list style. + */ + bool EndListStyle(); + + /** + Ends a numbered bullet. + */ + bool EndNumberedBullet(); + + /** + Ends paragraph spacing. + */ + bool EndParagraphSpacing(); + + /** + Ends applying a named character style. + */ + bool EndParagraphStyle(); + + /** + Ends using a right indent. + */ + bool EndRightIndent(); + + /** + Ends using a standard bullet. + */ + bool EndStandardBullet(); + + /** + Ends the current style. + */ + bool EndStyle(); + + /** + Ends suppressing undo/redo commands. + */ + bool EndSuppressUndo(); + + /** + Ends using a symbol bullet. + */ + bool EndSymbolBullet(); + + /** + Ends using a text foreground colour. + */ + bool EndTextColour(); + + /** + Ends applying a URL. + */ + bool EndURL(); + + /** + Ends using underline. + */ + bool EndUnderline(); + + //@{ + /** + Finds a handler by name. + */ + wxRichTextFileHandler* FindHandler(int imageType); + wxRichTextFileHandler* FindHandler(const wxString& extension, + int imageType); + wxRichTextFileHandler* FindHandler(const wxString& name); + //@} + + /** + Finds a handler by filename or, if supplied, type. + */ + wxRichTextFileHandler* FindHandlerFilenameOrType(const wxString& filename, + int imageType); + + /** + Gets the basic (overall) style. This is the style of the whole + buffer before further styles are applied, unlike the default style, which + only affects the style currently being applied (for example, setting the default + style to bold will cause subsequently inserted text to be bold). + */ + const wxTextAttr GetBasicStyle() const; + + /** + Gets the collapsed command. + */ + wxRichTextCommand* GetBatchedCommand() const; + + /** + Gets the command processor. A text buffer always creates its own command + processor when it is + initialized. + */ + wxCommandProcessor* GetCommandProcessor() const; + + /** + Returns the current default style, affecting the style currently being applied + (for example, setting the default + style to bold will cause subsequently inserted text to be bold). + */ + const wxTextAttr GetDefaultStyle() const; + + /** + Gets a wildcard incorporating all visible handlers. If @a types is present, + it will be filled with the file type corresponding to each filter. This can be + used to determine the type to pass to @ref getextwildcard() LoadFile given a + selected filter. + */ + wxString GetExtWildcard(bool combine = false, bool save = false, + wxArrayInt* types = NULL); + + /** + Returns the list of file handlers. + */ + wxList GetHandlers(); + + /** + Returns the object to be used to render certain aspects of the content, such as + bullets. + */ + static wxRichTextRenderer* GetRenderer(); + + /** + Gets the attributes at the given position. + This function gets the combined style - that is, the style you see on the + screen as a result + of combining base style, paragraph style and character style attributes. To get + the character + or paragraph style alone, use GetUncombinedStyle(). + */ + bool GetStyle(long position, wxTextAttr& style); + + /** + This function gets a style representing the common, combined attributes in the + given range. + Attributes which have different values within the specified range will not be + included the style + flags. + The function is used to get the attributes to display in the formatting dialog: + the user + can edit the attributes common to the selection, and optionally specify the + values of further + attributes to be applied uniformly. + To apply the edited attributes, you can use SetStyle() specifying + the wxRICHTEXT_SETSTYLE_OPTIMIZE flag, which will only apply attributes that + are different + from the @e combined attributes within the range. So, the user edits the + effective, displayed attributes + for the range, but his choice won't be applied unnecessarily to content. As an + example, + say the style for a paragraph specifies bold, but the paragraph text doesn't + specify a weight. The + combined style is bold, and this is what the user will see on-screen and in the + formatting + dialog. The user now specifies red text, in addition to bold. When applying with + SetStyle, the content font weight attributes won't be changed to bold because + this is already specified + by the paragraph. However the text colour attributes @e will be changed to + show red. + */ + bool GetStyleForRange(const wxRichTextRange& range, + wxTextAttr& style); + + /** + Returns the current style sheet associated with the buffer, if any. + */ + wxRichTextStyleSheet* GetStyleSheet() const; + + /** + Get the size of the style stack, for example to check correct nesting. + */ + size_t GetStyleStackSize() const; + + /** + Gets the attributes at the given position. + This function gets the @e uncombined style - that is, the attributes associated + with the + paragraph or character content, and not necessarily the combined attributes you + see on the + screen. To get the combined attributes, use GetStyle(). + If you specify (any) paragraph attribute in @e style's flags, this function + will fetch + the paragraph attributes. Otherwise, it will return the character attributes. + */ + bool GetUncombinedStyle(long position, wxTextAttr& style); + + /** + Finds the text position for the given position, putting the position in @a + textPosition if + one is found. @a pt is in logical units (a zero y position is + at the beginning of the buffer). + The function returns one of the following values: + */ + int HitTest(wxDC& dc, const wxPoint& pt, long& textPosition); + + /** + Initialisation. + */ + void Init(); + + /** + Initialises the standard handlers. Currently, only the plain text + loading/saving handler + is initialised by default. + */ + void InitStandardHandlers(); + + /** + Inserts a handler at the front of the list. + */ + void InsertHandler(wxRichTextFileHandler* handler); + + /** + Submits a command to insert the given image. + */ + bool InsertImageWithUndo(long pos, + const wxRichTextImageBlock& imageBlock, + wxRichTextCtrl* ctrl); + + /** + Submits a command to insert a newline. + */ + bool InsertNewlineWithUndo(long pos, wxRichTextCtrl* ctrl); + + /** + Submits a command to insert the given text. + */ + bool InsertTextWithUndo(long pos, const wxString& text, + wxRichTextCtrl* ctrl); + + /** + Returns @true if the buffer has been modified. + */ + bool IsModified() const; + + //@{ + /** + Loads content from a file. + */ + bool LoadFile(wxInputStream& stream, + int type = wxRICHTEXT_TYPE_ANY); + bool LoadFile(const wxString& filename, + int type = wxRICHTEXT_TYPE_ANY); + //@} + + /** + Marks the buffer as modified or unmodified. + */ + void Modify(bool modify = true); + + //@{ + /** + Numbers the paragraphs in the given range. Pass flags to determine how the + attributes are set. + Either the style definition or the name of the style definition (in the current + sheet) can be passed. + @a flags is a bit list of the following: + wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable. + wxRICHTEXT_SETSTYLE_RENUMBER: specifies that numbering should start from @e + startFrom, otherwise existing attributes are used. + wxRICHTEXT_SETSTYLE_SPECIFY_LEVEL: specifies that @a listLevel should be used + as the level for all paragraphs, otherwise the current indentation will be used. + See also SetListStyle(), PromoteList(), ClearListStyle(). + */ + bool NumberList(const wxRichTextRange& range, + const wxRichTextListStyleDefinition* style, + int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO, + int startFrom = -1, + int listLevel = -1); + bool Number(const wxRichTextRange& range, + const wxString& styleName, + int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO, + int startFrom = -1, + int listLevel = -1); + //@} + + /** + Pastes the clipboard content to the buffer at the given position. + */ + bool PasteFromClipboard(long position); + + //@{ + /** + Promotes or demotes the paragraphs in the given range. A positive @a promoteBy + produces a smaller indent, and a negative number + produces a larger indent. Pass flags to determine how the attributes are set. + Either the style definition or the name of the style definition (in the current + sheet) can be passed. + @a flags is a bit list of the following: + wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable. + wxRICHTEXT_SETSTYLE_RENUMBER: specifies that numbering should start from @e + startFrom, otherwise existing attributes are used. + wxRICHTEXT_SETSTYLE_SPECIFY_LEVEL: specifies that @a listLevel should be used + as the level for all paragraphs, otherwise the current indentation will be used. + See also SetListStyle(), See also SetListStyle(), ClearListStyle(). + */ + bool PromoteList(int promoteBy, const wxRichTextRange& range, + const wxRichTextListStyleDefinition* style, + int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO, + int listLevel = -1); + bool PromoteList(int promoteBy, const wxRichTextRange& range, + const wxString& styleName, + int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO, + int listLevel = -1); + //@} + + /** + Removes an event handler from the buffer's list of handlers, deleting the + object if @a deleteHandler is @true. + */ + bool RemoveEventHandler(wxEvtHandler* handler, + bool deleteHandler = false); + + /** + Removes a handler. + */ + bool RemoveHandler(const wxString& name); + + /** + Clears the buffer, adds a new blank paragraph, and clears the command history. + */ + void ResetAndClearCommands(); + + //@{ + /** + Saves content to a file. + */ + bool SaveFile(wxOutputStream& stream, + int type = wxRICHTEXT_TYPE_ANY); + bool SaveFile(const wxString& filename, + int type = wxRICHTEXT_TYPE_ANY); + //@} + + /** + Sets the basic (overall) style. This is the style of the whole + buffer before further styles are applied, unlike the default style, which + only affects the style currently being applied (for example, setting the default + style to bold will cause subsequently inserted text to be bold). + */ + void SetBasicStyle(const wxTextAttr& style); + + /** + Sets the default style, affecting the style currently being applied (for + example, setting the default + style to bold will cause subsequently inserted text to be bold). + This is not cumulative - setting the default style will replace the previous + default style. + */ + void SetDefaultStyle(const wxTextAttr& style); + + //@{ + /** + Sets the list attributes for the given range, passing flags to determine how + the attributes are set. + Either the style definition or the name of the style definition (in the current + sheet) can be passed. + @a flags is a bit list of the following: + wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable. + wxRICHTEXT_SETSTYLE_RENUMBER: specifies that numbering should start from @e + startFrom, otherwise existing attributes are used. + wxRICHTEXT_SETSTYLE_SPECIFY_LEVEL: specifies that @a listLevel should be used + as the level for all paragraphs, otherwise the current indentation will be used. + See also NumberList(), PromoteList(), ClearListStyle(). + */ + bool SetListStyle(const wxRichTextRange& range, + const wxRichTextListStyleDefinition* style, + int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO, + int startFrom = -1, + int listLevel = -1); + bool SetListStyle(const wxRichTextRange& range, + const wxString& styleName, + int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO, + int startFrom = -1, + int listLevel = -1); + //@} + + /** + Sets @a renderer as the object to be used to render certain aspects of the + content, such as bullets. + You can override default rendering by deriving a new class from + wxRichTextRenderer or wxRichTextStdRenderer, + overriding one or more virtual functions, and setting an instance of the class + using this function. + */ + static void SetRenderer(wxRichTextRenderer* renderer); + + /** + Sets the attributes for the given range. Pass flags to determine how the + attributes are set. + The end point of range is specified as the last character position of the span + of text. + So, for example, to set the style for a character at position 5, use the range + (5,5). + This differs from the wxRichTextCtrl API, where you would specify (5,6). + @a flags may contain a bit list of the following values: + wxRICHTEXT_SETSTYLE_NONE: no style flag. + wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this operation should be + undoable. + wxRICHTEXT_SETSTYLE_OPTIMIZE: specifies that the style should not be applied + if the + combined style at this point is already the style in question. + wxRICHTEXT_SETSTYLE_PARAGRAPHS_ONLY: specifies that the style should only be + applied to paragraphs, + and not the content. This allows content styling to be preserved independently + from that of e.g. a named paragraph style. + wxRICHTEXT_SETSTYLE_CHARACTERS_ONLY: specifies that the style should only be + applied to characters, + and not the paragraph. This allows content styling to be preserved + independently from that of e.g. a named paragraph style. + wxRICHTEXT_SETSTYLE_RESET: resets (clears) the existing style before applying + the new style. + wxRICHTEXT_SETSTYLE_REMOVE: removes the specified style. Only the style flags + are used in this operation. + */ + bool SetStyle(const wxRichTextRange& range, + const wxTextAttr& style, + int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO); + + /** + Sets the current style sheet, if any. This will allow the application to use + named character and paragraph styles found in the style sheet. + */ + void SetStyleSheet(wxRichTextStyleSheet* styleSheet); + + /** + Submit an action immediately, or delay it according to whether collapsing is on. + */ + bool SubmitAction(wxRichTextAction* action); + + /** + Returns @true if undo suppression is currently on. + */ + bool SuppressingUndo() const; +}; + + + +/** + @class wxRichTextFileHandler + @headerfile richtextbuffer.h wx/richtext/richtextbuffer.h + + This is the base class for file handlers, for loading and/or saving content + associated with a wxRichTextBuffer. + + @library{wxrichtext} + @category{richtext} +*/ +class wxRichTextFileHandler : public wxObject +{ +public: + /** + Constructor. + */ + wxRichTextFileHandler(const wxString& name = wxEmptyString, + const wxString& ext = wxEmptyString, + int type = 0); + + /** + Override this function and return @true if this handler can we handle @e + filename. By default, + this function checks the extension. + */ + bool CanHandle(const wxString& filename) const; + + /** + Override and return @true if this handler can load content. + */ + bool CanLoad() const; + + /** + Override and return @true if this handler can save content. + */ + bool CanSave() const; + + /** + Override to load content from @a stream into @e buffer. + */ + bool DoLoadFile(wxRichTextBuffer* buffer, wxInputStream& stream); + + /** + Override to save content to @a stream from @e buffer. + */ + bool DoSaveFile(wxRichTextBuffer* buffer, wxOutputStream& stream); + + /** + Returns the encoding associated with the handler (if any). + */ + const wxString GetEncoding() const; + + /** + Returns the extension associated with the handler. + */ + wxString GetExtension() const; + + /** + Returns flags that change the behaviour of loading or saving. See the + documentation for each + handler class to see what flags are relevant for each handler. + */ + int GetFlags() const; + + /** + Returns the name of the handler. + */ + wxString GetName() const; + + /** + Returns the type of the handler. + */ + int GetType() const; + + /** + Returns @true if this handler should be visible to the user. + */ + bool IsVisible() const; + + //@{ + /** + Loads content from a stream or file. Not all handlers will implement file + loading. + */ + bool LoadFile(wxRichTextBuffer* buffer, wxInputStream& stream); + bool LoadFile(wxRichTextBuffer* buffer, + const wxString& filename); + //@} + + //@{ + /** + Saves content to a stream or file. Not all handlers will implement file saving. + */ + bool SaveFile(wxRichTextBuffer* buffer, wxOutputStream& stream); + bool SaveFile(wxRichTextBuffer* buffer, + const wxString& filename); + //@} + + /** + Sets the encoding to use when saving a file. If empty, a suitable encoding is + chosen. + */ + void SetEncoding(const wxString& encoding); + + /** + Sets the default extension to recognise. + */ + void SetExtension(const wxString& ext); + + /** + Sets flags that change the behaviour of loading or saving. See the + documentation for each + handler class to see what flags are relevant for each handler. + You call this function directly if you are using a file handler explicitly + (without + going through the text control or buffer LoadFile/SaveFile API). Or, you can + call the control or buffer's SetHandlerFlags function to set the flags that will + be used for subsequent load and save operations. + */ + void SetFlags(int flags); + + /** + Sets the name of the handler. + */ + void SetName(const wxString& name); + + /** + Sets the handler type. + */ + void SetType(int type); + + /** + Sets whether the handler should be visible to the user (via the application's + load and save + dialogs). + */ + void SetVisible(bool visible); +}; + + + +/** + @class wxRichTextRange + @headerfile richtextbuffer.h wx/richtext/richtextbuffer.h + + This class stores beginning and end positions for a range of data. + + @library{wxrichtext} + @category{richtext} +*/ +class wxRichTextRange +{ +public: + //@{ + /** + Constructors. + */ + wxRichTextRange(long start, long end); + wxRichTextRange(const wxRichTextRange& range); + wxRichTextRange(); + //@} + + /** + Destructor. + */ + ~wxRichTextRange(); + + /** + Returns @true if the given position is within this range. Does not + match if the range is empty. + */ + bool Contains(long pos) const; + + /** + Converts the internal range, which uses the first and last character positions + of the range, + to the API-standard range, whose end is one past the last character in the + range. + In other words, one is added to the end position. + */ + wxRichTextRange FromInternal() const; + + /** + Returns the end position. + */ + long GetEnd() const; + + /** + Returns the length of the range. + */ + long GetLength() const; + + /** + Returns the start of the range. + */ + long GetStart() const; + + /** + Returns @true if this range is completely outside @e range. + */ + bool IsOutside(const wxRichTextRange& range) const; + + /** + Returns @true if this range is completely within @e range. + */ + bool IsWithin(const wxRichTextRange& range) const; + + /** + Limits this range to be within @e range. + */ + bool LimitTo(const wxRichTextRange& range); + + /** + Sets the end of the range. + */ + void SetEnd(long end); + + /** + Sets the range. + */ + void SetRange(long start, long end); + + /** + Sets the start of the range. + */ + void SetStart(long start); + + /** + Swaps the start and end. + */ + void Swap(); + + /** + Converts the API-standard range, whose end is one past the last character in + the range, + to the internal form, which uses the first and last character positions of the + range. + In other words, one is subtracted from the end position. + */ + wxRichTextRange ToInternal() const; + + /** + Adds @a range to this range. + */ + wxRichTextRange operator+(const wxRichTextRange& range) const; + + /** + Subtracts @a range from this range. + */ + wxRichTextRange operator-(const wxRichTextRange& range) const; + + /** + Assigns @a range to this range. + */ + void operator=(const wxRichTextRange& range); + + /** + Returns @true if @a range is the same as this range. + */ + bool operator==(const wxRichTextRange& range) const; +}; + diff --git a/interface/wx/richtext/richtextctrl.h b/interface/wx/richtext/richtextctrl.h new file mode 100644 index 0000000000..c5c7004ec7 --- /dev/null +++ b/interface/wx/richtext/richtextctrl.h @@ -0,0 +1,1407 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: richtext/richtextctrl.h +// Purpose: interface of wxRichTextEvent +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxRichTextEvent + @headerfile richtextctrl.h wx/richtext/richtextctrl.h + + This is the event class for wxRichTextCtrl notifications. + + @library{wxrichtext} + @category{richtext} +*/ +class wxRichTextEvent : public wxNotifyEvent +{ +public: + //@{ + /** + Constructors. + */ + wxRichTextEvent(const wxRichTextEvent& event); + wxRichTextEvent(wxEventType commandType = wxEVT_NULL, + int winid = 0); + //@} + + /** + Clones the event. + */ + wxEvent* Clone() const; + + /** + Returns the character pressed, within a wxEVT_COMMAND_RICHTEXT_CHARACTER event. + */ + wxChar GetCharacter() const; + + /** + Returns flags indicating modifier keys pressed. Possible values are + wxRICHTEXT_CTRL_DOWN, + wxRICHTEXT_SHIFT_DOWN, and wxRICHTEXT_ALT_DOWN. + */ + int GetFlags() const; + + /** + Returns the new style sheet. Can be used in a + wxEVT_COMMAND_RICHTEXT_STYLESHEET_CHANGING or + wxEVT_COMMAND_RICHTEXT_STYLESHEET_CHANGED event handler. + */ + wxRichTextStyleSheet* GetNewStyleSheet() const; + + /** + Returns the old style sheet. Can be used in a + wxEVT_COMMAND_RICHTEXT_STYLESHEET_CHANGING or + wxEVT_COMMAND_RICHTEXT_STYLESHEET_CHANGED event handler. + */ + wxRichTextStyleSheet* GetOldStyleSheet() const; + + /** + Returns the buffer position at which the event occured. + */ + long GetPosition() const; + + /** + Gets the range for the current operation. + */ + wxRichTextRange GetRange() const; + + /** + Sets the character variable. + */ + void SetCharacter(wxChar ch); + + /** + Sets flags indicating modifier keys pressed. Possible values are + wxRICHTEXT_CTRL_DOWN, + wxRICHTEXT_SHIFT_DOWN, and wxRICHTEXT_ALT_DOWN. + */ + void SetFlags(int flags); + + /** + Sets the new style sheet variable. + */ + void SetNewStyleSheet(wxRichTextStyleSheet* sheet); + + /** + Sets the old style sheet variable. + */ + void SetOldStyleSheet(wxRichTextStyleSheet* sheet); + + /** + Sets the buffer position variable. + */ + void SetPosition(long pos); + + /** + Sets the range variable. + */ + void SetRange(const wxRichTextRange& range); +}; + + + +/** + @class wxRichTextCtrl + @headerfile richtextctrl.h wx/richtext/richtextctrl.h + + wxRichTextCtrl provides a generic, ground-up implementation of a text control + capable of showing multiple styles and images. + + wxRichTextCtrl sends notification events: see wxRichTextEvent. + It also sends the standard wxTextCtrl events wxEVT_COMMAND_TEXT_ENTER and + wxEVT_COMMAND_TEXT_UPDATED, + and wxTextUrlEvent when URL content is clicked. + + For more information, see the @ref overview_wxrichtextctrloverview + "wxRichTextCtrl overview". + + @library{wxrichtext} + @category{richtext} +*/ +class wxRichTextCtrl +{ +public: + //@{ + /** + Constructors. + */ + wxRichTextCtrl(); + wxRichTextCtrl(wxWindow* parent, wxWindowID id = wxID_ANY, + const wxString& value = wxEmptyString, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxRE_MULTILINE, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = wxTextCtrlNameStr); + //@} + + /** + Destructor. + */ + ~wxRichTextCtrl(); + + /** + Adds an image to the control's buffer. + */ + wxRichTextRange AddImage(const wxImage& image); + + /** + Adds a new paragraph of text to the end of the buffer. + */ + wxRichTextRange AddParagraph(const wxString& text); + + /** + Sets the insertion point to the end of the buffer and writes the text. + */ + void AppendText(const wxString& text); + + /** + Applies the given alignment to the selection (undoable). + For alignment values, see wxTextAttr. + */ + bool ApplyAlignmentToSelection(wxTextAttrAlignment alignment); + + /** + Apples bold to the selection (undoable). + */ + bool ApplyBoldToSelection(); + + /** + Applies italic to the selection (undoable). + */ + bool ApplyItalicToSelection(); + + /** + Applies the given style to the selection. + */ + bool ApplyStyle(wxRichTextStyleDefinition* def); + + /** + Applies the style sheet to the buffer, matching paragraph styles in the sheet + against named styles + in the buffer. This might be useful if the styles have changed. If @a sheet is + @NULL, the + sheet set with SetStyleSheet is used. + Currently this applies paragraph styles only. + */ + bool ApplyStyleSheet(wxRichTextStyleSheet* sheet = NULL); + + /** + Applies underline to the selection (undoable). + */ + bool ApplyUnderlineToSelection(); + + /** + Returns @true if undo commands are being batched. + */ + bool BatchingUndo() const; + + /** + Begins using alignment + For alignment values, see wxTextAttr. + */ + bool BeginAlignment(wxTextAttrAlignment alignment); + + /** + Starts batching undo history for commands. + */ + bool BeginBatchUndo(const wxString& cmdName); + + /** + Begins using bold. + */ + bool BeginBold(); + + /** + Begins using the named character style. + */ + bool BeginCharacterStyle(const wxString& characterStyle); + + /** + Begins using this font. + */ + bool BeginFont(const wxFont& font); + + /** + Begins using the given point size. + */ + bool BeginFontSize(int pointSize); + + /** + Begins using italic. + */ + bool BeginItalic(); + + /** + Begins applying a left indent and subindent in tenths of a millimetre. + The sub-indent is an offset from the left of the paragraph, and is used for all + but the + first line in a paragraph. A positive value will cause the first line to appear + to the left + of the subsequent lines, and a negative value will cause the first line to be + indented + relative to the subsequent lines. + wxRichTextBuffer uses indentation to render a bulleted item. The left indent is + the distance between + the margin and the bullet. The content of the paragraph, including the first + line, starts + at leftMargin + leftSubIndent. So the distance between the left edge of the + bullet and the + left of the actual paragraph is leftSubIndent. + */ + bool BeginLeftIndent(int leftIndent, int leftSubIndent = 0); + + /** + Begins appling line spacing. @e spacing is a multiple, where 10 means + single-spacing, + 15 means 1.5 spacing, and 20 means double spacing. The following constants are + defined for convenience: + */ + bool BeginLineSpacing(int lineSpacing); + + /** + Begins using a specified list style. Optionally, you can also pass a level and + a number. + */ + bool BeginListStyle(const wxString& listStyle, int level = 1, + int number = 1); + + /** + Begins a numbered bullet. This call will be needed for each item in the list, + and the + application should take care of incrementing the numbering. + @a bulletNumber is a number, usually starting with 1. + @a leftIndent and @a leftSubIndent are values in tenths of a millimetre. + @a bulletStyle is a bitlist of the following values: + + wxRichTextBuffer uses indentation to render a bulleted item. The left indent is + the distance between + the margin and the bullet. The content of the paragraph, including the first + line, starts + at leftMargin + leftSubIndent. So the distance between the left edge of the + bullet and the + left of the actual paragraph is leftSubIndent. + */ + bool BeginNumberedBullet(int bulletNumber, int leftIndent, + int leftSubIndent, + int bulletStyle = wxTEXT_ATTR_BULLET_STYLE_ARABIC|wxTEXT_ATTR_BULLET_STYLE_PERIOD); + + /** + Begins paragraph spacing; pass the before-paragraph and after-paragraph spacing + in tenths of + a millimetre. + */ + bool BeginParagraphSpacing(int before, int after); + + /** + Begins applying the named paragraph style. + */ + bool BeginParagraphStyle(const wxString& paragraphStyle); + + /** + Begins a right indent, specified in tenths of a millimetre. + */ + bool BeginRightIndent(int rightIndent); + + /** + Begins applying a style. + */ + bool BeginStyle(const wxTextAttr& style); + + /** + Starts suppressing undo history for commands. + */ + bool BeginSuppressUndo(); + + /** + Begins applying a symbol bullet, using a character from the current font. See + BeginNumberedBullet() for + an explanation of how indentation is used to render the bulleted paragraph. + */ + bool BeginSymbolBullet(wxChar symbol, int leftIndent, + int leftSubIndent, + int bulletStyle = wxTEXT_ATTR_BULLET_STYLE_SYMBOL); + + /** + Begins using this colour. + */ + bool BeginTextColour(const wxColour& colour); + + /** + Begins applying wxTEXT_ATTR_URL to the content. Pass a URL and optionally, a + character style to apply, + since it is common to mark a URL with a familiar style such as blue text with + underlining. + */ + bool BeginURL(const wxString& url, + const wxString& characterStyle = wxEmptyString); + + /** + Begins using underlining. + */ + bool BeginUnderline(); + + /** + Returns @true if selected content can be copied to the clipboard. + */ + bool CanCopy() const; + + /** + Returns @true if selected content can be copied to the clipboard and deleted. + */ + bool CanCut() const; + + /** + Returns @true if selected content can be deleted. + */ + bool CanDeleteSelection() const; + + /** + Returns @true if the clipboard content can be pasted to the buffer. + */ + bool CanPaste() const; + + /** + Returns @true if there is a command in the command history that can be redone. + */ + bool CanRedo() const; + + /** + Returns @true if there is a command in the command history that can be undone. + */ + bool CanUndo() const; + + /** + Clears the buffer content, leaving a single empty paragraph. Cannot be undone. + */ + void Clear(); + + //@{ + /** + Clears the list style from the given range, clearing list-related attributes + and applying any named paragraph style associated with each paragraph. + @a flags is a bit list of the following: + wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable. + See also SetListStyle(), PromoteList(), NumberList(). + */ + bool ClearListStyle(const wxRichTextRange& range, + int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO); + bool ClearListStyle(const wxRichTextRange& range, + int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO); + //@} + + /** + Sends the event to the control. + */ + void Command(wxCommandEvent& event); + + /** + Copies the selected content (if any) to the clipboard. + */ + void Copy(); + + /** + Creates the underlying window. + */ + bool Create(wxWindow* parent, wxWindowID id = wxID_ANY, + const wxString& value = wxEmptyString, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxRE_MULTILINE, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = wxTextCtrlNameStr); + + /** + Copies the selected content (if any) to the clipboard and deletes the selection. + This is undoable. + */ + void Cut(); + + /** + Deletes the content within the given range. + */ + bool Delete(const wxRichTextRange& range); + + /** + Deletes content if there is a selection, e.g. when pressing a key. + Returns the new caret position in @e newPos, or leaves it if there + was no action. This is undoable. + */ + bool DeleteSelectedContent(long* newPos = NULL); + + /** + Deletes the content in the selection, if any. This is undoable. + */ + void DeleteSelection(); + + /** + Sets the buffer's modified status to @false, and clears the buffer's command + history. + */ + void DiscardEdits(); + + /** + Currently this simply returns @c wxSize(10, 10). + */ + wxSize DoGetBestSize() const; + + /** + Ends alignment. + */ + bool EndAlignment(); + + /** + Ends application of all styles in the current style stack. + */ + bool EndAllStyles(); + + /** + Ends batching undo command history. + */ + bool EndBatchUndo(); + + /** + Ends using bold. + */ + bool EndBold(); + + /** + Ends application of a named character style. + */ + bool EndCharacterStyle(); + + /** + Ends using a font. + */ + bool EndFont(); + + /** + Ends using a point size. + */ + bool EndFontSize(); + + /** + Ends using italic. + */ + bool EndItalic(); + + /** + Ends left indent. + */ + bool EndLeftIndent(); + + /** + Ends line spacing. + */ + bool EndLineSpacing(); + + /** + Ends using a specified list style. + */ + bool EndListStyle(); + + /** + Ends application of a numbered bullet. + */ + bool EndNumberedBullet(); + + /** + Ends paragraph spacing. + */ + bool EndParagraphSpacing(); + + /** + Ends application of a named character style. + */ + bool EndParagraphStyle(); + + /** + Ends right indent. + */ + bool EndRightIndent(); + + /** + Ends the current style. + */ + bool EndStyle(); + + /** + Ends suppressing undo command history. + */ + bool EndSuppressUndo(); + + /** + Ends applying a symbol bullet. + */ + bool EndSymbolBullet(); + + /** + Ends applying a text colour. + */ + bool EndTextColour(); + + /** + Ends applying a URL. + */ + bool EndURL(); + + /** + End applying underlining. + */ + bool EndUnderline(); + + /** + Helper function for extending the selection, returning @true if the selection + was + changed. Selections are in caret positions. + */ + bool ExtendSelection(long oldPosition, long newPosition, + int flags); + + /** + Helper function for finding the caret position for the next word. Direction + is 1 (forward) or -1 (backwards). + */ + long FindNextWordPosition(int direction = 1) const; + + /** + Call this function to prevent refresh and allow fast updates, and then Thaw() to + refresh the control. + */ + void Freeze(); + + /** + Gets the basic (overall) style. This is the style of the whole + buffer before further styles are applied, unlike the default style, which + only affects the style currently being applied (for example, setting the default + style to bold will cause subsequently inserted text to be bold). + */ + const wxTextAttr GetBasicStyle() const; + + //@{ + /** + Returns the buffer associated with the control. + */ + const wxRichTextBuffer GetBuffer(); + const wxRichTextBuffer& GetBuffer(); + //@} + + /** + Returns the current caret position. + */ + long GetCaretPosition() const; + + /** + Returns the caret height and position for the given character position + */ + bool GetCaretPositionForIndex(long position, wxRect& rect); + + /** + Gets the command processor associated with the control's buffer. + */ + wxCommandProcessor* GetCommandProcessor() const; + + /** + Returns the current default style, which can be used to change how subsequently + inserted + text is displayed. + */ + const wxTextAttr GetDefaultStyle() const; + + /** + Gets the size of the buffer beyond which layout is delayed during resizing. + This optimizes sizing for large buffers. The default is 20000. + */ + long GetDelayedLayoutThreshold() const; + + /** + Gets the current filename associated with the control. + */ + wxString GetFilename() const; + + /** + Returns the first visible position in the current view. + */ + long GetFirstVisiblePosition() const; + + /** + Returns flags that change the behaviour of loading or saving. See the + documentation for each + handler class to see what flags are relevant for each handler. + */ + int GetHandlerFlags() const; + + /** + Returns the current insertion point. + */ + long GetInsertionPoint() const; + + /** + Returns the last position in the buffer. + */ + wxTextPos GetLastPosition() const; + + /** + Returns the length of the specified line in characters. + */ + int GetLineLength(long lineNo) const; + + /** + Returns the text for the given line. + */ + wxString GetLineText(long lineNo) const; + + /** + Transforms physical window position to logical (unscrolled) position. + */ + wxPoint GetLogicalPoint(const wxPoint& ptPhysical) const; + + /** + Returns the number of lines in the buffer. + */ + int GetNumberOfLines() const; + + /** + Transforms logical (unscrolled) position to physical window position. + */ + wxPoint GetPhysicalPoint(const wxPoint& ptLogical) const; + + /** + Gets the text for the given range. + The end point of range is specified as the last character position of the span + of text, plus one. + */ + wxString GetRange(long from, long to) const; + + /** + Returns the range of the current selection. + The end point of range is specified as the last character position of the span + of text, plus one. + If the return values @a from and @a to are the same, there is no selection. + */ + void GetSelection(long* from, long* to) const; + + /** + Returns the selection range in character positions. -1, -1 means no selection. + */ + const wxRichTextRange GetSelectionRange() const; + + /** + Returns the text within the current selection range, if any. + */ + wxString GetStringSelection() const; + + /** + Gets the attributes at the given position. + This function gets the combined style - that is, the style you see on the + screen as a result + of combining base style, paragraph style and character style attributes. To get + the character + or paragraph style alone, use GetUncombinedStyle(). + */ + bool GetStyle(long position, wxTextAttr& style); + + /** + Gets the attributes common to the specified range. Attributes that differ in + value within the range will + not be included in @e style's flags. + */ + bool GetStyleForRange(const wxRichTextRange& range, + wxTextAttr& style); + + /** + Returns the style sheet associated with the control, if any. A style sheet + allows named + character and paragraph styles to be applied. + */ + wxRichTextStyleSheet* GetStyleSheet() const; + + /** + Gets the attributes at the given position. + This function gets the @e uncombined style - that is, the attributes associated + with the + paragraph or character content, and not necessarily the combined attributes you + see on the + screen. To get the combined attributes, use GetStyle(). + If you specify (any) paragraph attribute in @e style's flags, this function + will fetch + the paragraph attributes. Otherwise, it will return the character attributes. + */ + bool GetUncombinedStyle(long position, wxTextAttr& style); + + /** + Returns the content of the entire control as a string. + */ + wxString GetValue() const; + + /** + Internal helper function returning the line for the visible caret position. If + the caret is + shown at the very end of the line, it means the next character is actually + on the following line. So this function gets the line we're expecting to find + if this is the case. + */ + wxRichTextLine* GetVisibleLineForCaretPosition(long caretPosition) const; + + /** + Test if this whole range has character attributes of the specified kind. If any + of the attributes are different within the range, the test fails. You + can use this to implement, for example, bold button updating. @a style must have + flags indicating which attributes are of interest. + */ + bool HasCharacterAttributes(const wxRichTextRange& range, + const wxTextAttr& style) const; + + /** + Test if this whole range has paragraph attributes of the specified kind. If any + of the attributes are different within the range, the test fails. You + can use this to implement, for example, centering button updating. @a style + must have + flags indicating which attributes are of interest. + */ + bool HasParagraphAttributes(const wxRichTextRange& range, + const wxTextAttr& style) const; + + /** + Returns @true if there is a selection. + */ + bool HasSelection() const; + + //@{ + /** + Finds the character at the given position in pixels. + @a pt is in device coords (not adjusted for the client area origin nor for + scrolling). + */ + wxTextCtrlHitTestResult HitTest(const wxPoint& pt, long* pos) const; + const wxTextCtrlHitTestResult HitTest(const wxPoint& pt, + wxTextCoord* col, + wxTextCoord* row) const; + //@} + + /** + Initialises the members of the control. + */ + void Init(); + + /** + Initialises the command event. + */ + void InitCommandEvent(wxCommandEvent& event) const; + + /** + Returns @true if the user has recently set the default style without moving + the caret, + and therefore the UI needs to reflect the default style and not the style at + the caret. + Below is an example of code that uses this function to determine whether the UI + should show that the current style is bold. + + See also SetAndShowDefaultStyle(). + */ + bool IsDefaultStyleShowing() const; + + /** + Returns @true if the control is editable. + */ + bool IsEditable() const; + + /** + Returns @true if Freeze has been called without a Thaw. + */ + bool IsFrozen() const; + + /** + Returns @true if the buffer has been modified. + */ + bool IsModified() const; + + /** + Returns @true if the control is multiline. + */ + bool IsMultiLine() const; + + /** + Returns @true if the given position is visible on the screen. + */ + bool IsPositionVisible(long pos) const; + + /** + Returns @true if all of the selection is aligned according to the specified + flag. + */ + bool IsSelectionAligned(wxTextAttrAlignment alignment) const; + + /** + Returns @true if all of the selection is bold. + */ + bool IsSelectionBold() const; + + /** + Returns @true if all of the selection is italic. + */ + bool IsSelectionItalics() const; + + /** + Returns @true if all of the selection is underlined. + */ + bool IsSelectionUnderlined() const; + + /** + Returns @true if the control is single-line. Currently wxRichTextCtrl does not + support single-line editing. + */ + bool IsSingleLine() const; + + /** + Helper function implementing keyboard navigation. + */ + bool KeyboardNavigate(int keyCode, int flags); + + /** + Lays out the buffer, which must be done before certain operations, such as + setting the caret position. This function should not normally be required by the + application. + */ + bool LayoutContent(bool onlyVisibleRect = false); + + /** + Inserts a line break at the current insertion point. A line break forces + wrapping within a paragraph, and + can be introduced by using this function, by appending the wxChar value @b + wxRichTextLineBreakChar to text content, + or by typing Shift-Return. + */ + bool LineBreak(); + + /** + Loads content into the control's buffer using the given type. If the specified + type + is wxRICHTEXT_TYPE_ANY, the type is deduced from the filename extension. + This function looks for a suitable wxRichTextFileHandler object. + */ + bool LoadFile(const wxString& file, + int type = wxRICHTEXT_TYPE_ANY); + + /** + Marks the buffer as modified. + */ + void MarkDirty(); + + /** + Move the caret to the given character position. + */ + bool MoveCaret(long pos, bool showAtLineStart = false); + + /** + Move the caret one visual step forward: this may mean setting a flag + and keeping the same position if we're going from the end of one line + to the start of the next, which may be the exact same caret position. + */ + void MoveCaretBack(long oldPosition); + + /** + Move the caret one visual step forward: this may mean setting a flag + and keeping the same position if we're going from the end of one line + to the start of the next, which may be the exact same caret position. + */ + void MoveCaretForward(long oldPosition); + + /** + Moves the caret down. + */ + bool MoveDown(int noLines = 1, int flags = 0); + + /** + Moves to the end of the buffer. + */ + bool MoveEnd(int flags = 0); + + /** + Moves to the start of the buffer. + */ + bool MoveHome(int flags = 0); + + /** + Moves left. + */ + bool MoveLeft(int noPositions = 1, int flags = 0); + + /** + Moves right. + */ + bool MoveRight(int noPositions = 1, int flags = 0); + + /** + Moves to the end of the line. + */ + bool MoveToLineEnd(int flags = 0); + + /** + Moves to the start of the line. + */ + bool MoveToLineStart(int flags = 0); + + /** + Moves to the end of the paragraph. + */ + bool MoveToParagraphEnd(int flags = 0); + + /** + Moves to the start of the paragraph. + */ + bool MoveToParagraphStart(int flags = 0); + + /** + Moves up. + */ + bool MoveUp(int noLines = 1, int flags = 0); + + /** + Inserts a new paragraph at the current insertion point. See also LineBreak(). + */ + bool Newline(); + + //@{ + /** + Numbers the paragraphs in the given range. Pass flags to determine how the + attributes are set. + Either the style definition or the name of the style definition (in the current + sheet) can be passed. + @a flags is a bit list of the following: + wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable. + wxRICHTEXT_SETSTYLE_RENUMBER: specifies that numbering should start from @e + startFrom, otherwise existing attributes are used. + wxRICHTEXT_SETSTYLE_SPECIFY_LEVEL: specifies that @a listLevel should be used + as the level for all paragraphs, otherwise the current indentation will be used. + See also SetListStyle(), PromoteList(), ClearListStyle(). + */ + bool NumberList(const wxRichTextRange& range, + const wxRichTextListStyleDefinition* style, + int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO, + int startFrom = -1, + int listLevel = -1); + bool Number(const wxRichTextRange& range, + const wxString& styleName, + int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO, + int startFrom = -1, + int listLevel = -1); + //@} + + /** + Standard handler for the wxID_CLEAR command. + */ + void OnClear(wxCommandEvent& event); + + /** + Shows a standard context menu with undo, redo, cut, copy, paste, clear, and + select all commands. + */ + void OnContextMenu(wxContextMenuEvent& event); + + /** + Standard handler for the wxID_COPY command. + */ + void OnCopy(wxCommandEvent& event); + + /** + Standard handler for the wxID_CUT command. + */ + void OnCut(wxCommandEvent& event); + + /** + Loads the first dropped file. + */ + void OnDropFiles(wxDropFilesEvent& event); + + /** + Standard handler for the wxID_PASTE command. + */ + void OnPaste(wxCommandEvent& event); + + /** + Standard handler for the wxID_REDO command. + */ + void OnRedo(wxCommandEvent& event); + + /** + Standard handler for the wxID_SELECTALL command. + */ + void OnSelectAll(wxCommandEvent& event); + + /** + Standard handler for the wxID_PASTE command. + */ + void OnUndo(wxCommandEvent& event); + + /** + Standard update handler for the wxID_CLEAR command. + */ + void OnUpdateClear(wxUpdateUIEvent& event); + + /** + Standard update handler for the wxID_COPY command. + */ + void OnUpdateCopy(wxUpdateUIEvent& event); + + /** + Standard update handler for the wxID_CUT command. + */ + void OnUpdateCut(wxUpdateUIEvent& event); + + /** + Standard update handler for the wxID_PASTE command. + */ + void OnUpdatePaste(wxUpdateUIEvent& event); + + /** + Standard update handler for the wxID_REDO command. + */ + void OnUpdateRedo(wxUpdateUIEvent& event); + + /** + Standard update handler for the wxID_SELECTALL command. + */ + void OnUpdateSelectAll(wxUpdateUIEvent& event); + + /** + Standard update handler for the wxID_UNDO command. + */ + void OnUpdateUndo(wxUpdateUIEvent& event); + + /** + Moves one or more pages down. + */ + bool PageDown(int noPages = 1, int flags = 0); + + /** + Moves one or more pages up. + */ + bool PageUp(int noPages = 1, int flags = 0); + + /** + Paints the background. + */ + void PaintBackground(wxDC& dc); + + /** + Pastes content from the clipboard to the buffer. + */ + void Paste(); + + /** + Internal function to position the visible caret according to the current caret + position. + */ + void PositionCaret(); + + /** + Converts a text position to zero-based column and line numbers. + */ + bool PositionToXY(long pos, long* x, long* y) const; + + //@{ + /** + Promotes or demotes the paragraphs in the given range. A positive @a promoteBy + produces a smaller indent, and a negative number + produces a larger indent. Pass flags to determine how the attributes are set. + Either the style definition or the name of the style definition (in the current + sheet) can be passed. + @a flags is a bit list of the following: + wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable. + wxRICHTEXT_SETSTYLE_RENUMBER: specifies that numbering should start from @e + startFrom, otherwise existing attributes are used. + wxRICHTEXT_SETSTYLE_SPECIFY_LEVEL: specifies that @a listLevel should be used + as the level for all paragraphs, otherwise the current indentation will be used. + See also SetListStyle(), See also SetListStyle(), ClearListStyle(). + */ + bool PromoteList(int promoteBy, const wxRichTextRange& range, + const wxRichTextListStyleDefinition* style, + int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO, + int listLevel = -1); + bool PromoteList(int promoteBy, const wxRichTextRange& range, + const wxString& styleName, + int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO, + int listLevel = -1); + //@} + + /** + Redoes the current command. + */ + void Redo(); + + /** + Removes the content in the specified range. + */ + void Remove(long from, long to); + + /** + Replaces the content in the specified range with the string specified by @e + value. + */ + void Replace(long from, long to, const wxString& value); + + /** + Saves the buffer content using the given type. If the specified type + is wxRICHTEXT_TYPE_ANY, the type is deduced from the filename extension. + This function looks for a suitable wxRichTextFileHandler object. + */ + bool SaveFile(const wxString& file = wxEmptyString, + int type = wxRICHTEXT_TYPE_ANY); + + /** + Scrolls @a position into view. This function takes a caret position. + */ + bool ScrollIntoView(long position, int keyCode); + + /** + Selects all the text in the buffer. + */ + void SelectAll(); + + /** + Cancels any selection. + */ + void SelectNone(); + + /** + Sets @a attr as the default style and tells the control that the UI should + reflect + this attribute until the user moves the caret. + See also IsDefaultStyleShowing(). + */ + void SetAndShowDefaultStyle(const wxTextAttr& attr); + + /** + Sets the basic (overall) style. This is the style of the whole + buffer before further styles are applied, unlike the default style, which + only affects the style currently being applied (for example, setting the default + style to bold will cause subsequently inserted text to be bold). + */ + void SetBasicStyle(const wxTextAttr& style); + + /** + The caret position is the character position just before the caret. + A value of -1 means the caret is at the start of the buffer. + */ + void SetCaretPosition(long position, + bool showAtLineStart = false); + + /** + Sets the current default style, which can be used to change how subsequently + inserted + text is displayed. + */ + bool SetDefaultStyle(const wxTextAttr& style); + + /** + Sets the default style to the style under the cursor. + */ + bool SetDefaultStyleToCursorStyle(); + + /** + Sets the size of the buffer beyond which layout is delayed during resizing. + This optimizes sizing for large buffers. The default is 20000. + */ + void SetDelayedLayoutThreshold(long threshold); + + /** + Makes the control editable, or not. + */ + void SetEditable(bool editable); + + /** + Sets the current filename. + */ + void SetFilename(const wxString& filename); + + /** + Sets the font, and also the basic and default attributes (see + wxRichTextCtrl::SetDefaultStyle). + */ + bool SetFont(const wxFont& font); + + /** + Sets flags that change the behaviour of loading or saving. See the + documentation for each + handler class to see what flags are relevant for each handler. + */ + void SetHandlerFlags(int flags); + + /** + Sets the insertion point. + */ + void SetInsertionPoint(long pos); + + /** + Sets the insertion point to the end of the text control. + */ + void SetInsertionPointEnd(); + + //@{ + /** + Sets the list attributes for the given range, passing flags to determine how + the attributes are set. + Either the style definition or the name of the style definition (in the current + sheet) can be passed. + @a flags is a bit list of the following: + wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this command will be undoable. + wxRICHTEXT_SETSTYLE_RENUMBER: specifies that numbering should start from @e + startFrom, otherwise existing attributes are used. + wxRICHTEXT_SETSTYLE_SPECIFY_LEVEL: specifies that @a listLevel should be used + as the level for all paragraphs, otherwise the current indentation will be used. + See also NumberList(), PromoteList(), ClearListStyle(). + */ + bool SetListStyle(const wxRichTextRange& range, + const wxRichTextListStyleDefinition* style, + int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO, + int startFrom = -1, + int listLevel = -1); + bool SetListStyle(const wxRichTextRange& range, + const wxString& styleName, + int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO, + int startFrom = -1, + int listLevel = -1); + //@} + + /** + Sets the selection to the given range. + The end point of range is specified as the last character position of the span + of text, plus one. + So, for example, to set the selection for a character at position 5, use the + range (5,6). + */ + void SetSelection(long from, long to); + + /** + Sets the selection to the given range. + The end point of range is specified as the last character position of the span + of text, plus one. + So, for example, to set the selection for a character at position 5, use the + range (5,6). + */ + void SetSelectionRange(const wxRichTextRange& range); + + //@{ + /** + Sets the attributes for the given range. + The end point of range is specified as the last character position of the span + of text, plus one. + So, for example, to set the style for a character at position 5, use the range + (5,6). + */ + bool SetStyle(const wxRichTextRange& range, + const wxTextAttr& style); + bool SetStyle(long start, long end, const wxTextAttr& style); + //@} + + //@{ + /** + Sets the attributes for the given range, passing flags to determine how the + attributes are set. + The end point of range is specified as the last character position of the span + of text, plus one. + So, for example, to set the style for a character at position 5, use the range + (5,6). + @a flags may contain a bit list of the following values: + wxRICHTEXT_SETSTYLE_NONE: no style flag. + wxRICHTEXT_SETSTYLE_WITH_UNDO: specifies that this operation should be + undoable. + wxRICHTEXT_SETSTYLE_OPTIMIZE: specifies that the style should not be applied + if the + combined style at this point is already the style in question. + wxRICHTEXT_SETSTYLE_PARAGRAPHS_ONLY: specifies that the style should only be + applied to paragraphs, + and not the content. This allows content styling to be preserved independently + from that of e.g. a named paragraph style. + wxRICHTEXT_SETSTYLE_CHARACTERS_ONLY: specifies that the style should only be + applied to characters, + and not the paragraph. This allows content styling to be preserved + independently from that of e.g. a named paragraph style. + wxRICHTEXT_SETSTYLE_RESET: resets (clears) the existing style before applying + the new style. + wxRICHTEXT_SETSTYLE_REMOVE: removes the specified style. Only the style flags + are used in this operation. + */ + bool SetStyleEx(const wxRichTextRange& range, + const wxTextAttr& style, + int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO); + bool SetStyleEx(long start, long end, + const wxTextAttr& style, + int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO); + //@} + + /** + Sets the style sheet associated with the control. A style sheet allows named + character and paragraph styles to be applied. + */ + void SetStyleSheet(wxRichTextStyleSheet* styleSheet); + + /** + Replaces existing content with the given text. + */ + void SetValue(const wxString& value); + + /** + A helper function setting up scrollbars, for example after a resize. + */ + void SetupScrollbars(bool atTop = false); + + /** + Scrolls the buffer so that the given position is in view. + */ + void ShowPosition(long pos); + + /** + Returns @true if undo history suppression is on. + */ + bool SuppressingUndo() const; + + /** + Call this function to end a Freeze and refresh the display. + */ + void Thaw(); + + /** + Undoes the command at the top of the command history, if there is one. + */ + void Undo(); + + /** + Moves a number of words to the left. + */ + bool WordLeft(int noWords = 1, int flags = 0); + + /** + Move a nuber of words to the right. + */ + bool WordRight(int noWords = 1, int flags = 0); + + //@{ + /** + Write a bitmap or image at the current insertion point. Supply an optional type + to use + for internal and file storage of the raw data. + */ + bool WriteImage(const wxString& filename, int bitmapType); + bool WriteImage(const wxRichTextImageBlock& imageBlock); + bool WriteImage(const wxBitmap& bitmap, + int bitmapType = wxBITMAP_TYPE_PNG); + bool WriteImage(const wxImage& image, + int bitmapType = wxBITMAP_TYPE_PNG); + //@} + + /** + Writes text at the current position. + */ + void WriteText(const wxString& text); + + /** + Translates from column and line number to position. + */ + long XYToPosition(long x, long y) const; +}; + diff --git a/interface/wx/richtext/richtextformatdlg.h b/interface/wx/richtext/richtextformatdlg.h new file mode 100644 index 0000000000..c5d00abc7a --- /dev/null +++ b/interface/wx/richtext/richtextformatdlg.h @@ -0,0 +1,253 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: richtext/richtextformatdlg.h +// Purpose: interface of wxRichTextFormattingDialogFactory +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxRichTextFormattingDialogFactory + @headerfile richtextformatdlg.h wx/richtext/richtextformatdlg.h + + This class provides pages for wxRichTextFormattingDialog, and allows other + customization of the dialog. + A default instance of this class is provided automatically. If you wish to + change the behaviour of the + formatting dialog (for example add or replace a page), you may derive from this + class, + override one or more functions, and call the static function + wxRichTextFormattingDialog::SetFormattingDialogFactory. + + @library{wxrichtext} + @category{FIXME} +*/ +class wxRichTextFormattingDialogFactory : public wxObject +{ +public: + /** + Constructor. + */ + wxRichTextFormattingDialogFactory(); + + /** + Destructor. + */ + ~wxRichTextFormattingDialogFactory(); + + /** + Creates the main dialog buttons. + */ + virtual bool CreateButtons(wxRichTextFormattingDialog* dialog); + + /** + Creates a page, given a page identifier. + */ + virtual wxPanel* CreatePage(int page, wxString& title, + wxRichTextFormattingDialog* dialog); + + /** + Creates all pages under the dialog's book control, also calling AddPage. + */ + virtual bool CreatePages(long pages, + wxRichTextFormattingDialog* dialog); + + /** + Enumerate all available page identifiers. + */ + virtual int GetPageId(int i) const; + + /** + Gets the number of available page identifiers. + */ + virtual int GetPageIdCount() const; + + /** + Gets the image index for the given page identifier. + */ + virtual int GetPageImage(int id) const; + + /** + Set the property sheet style, called at the start of + wxRichTextFormattingDialog::Create. + */ + virtual bool SetSheetStyle(wxRichTextFormattingDialog* dialog); + + /** + Invokes help for the dialog. + */ + virtual bool ShowHelp(int page, + wxRichTextFormattingDialog* dialog); +}; + + + +/** + @class wxRichTextFormattingDialog + @headerfile richtextformatdlg.h wx/richtext/richtextformatdlg.h + + This dialog allows the user to edit a character and/or paragraph style. + + In the constructor, specify the pages that will be created. Use GetStyle + to retrieve the common style for a given range, and then use ApplyStyle + to apply the user-selected formatting to a control. For example: + + @code + wxRichTextRange range; + if (m_richTextCtrl-HasSelection()) + range = m_richTextCtrl-GetSelectionRange(); + else + range = wxRichTextRange(0, m_richTextCtrl-GetLastPosition()+1); + + int pages = + wxRICHTEXT_FORMAT_FONT|wxRICHTEXT_FORMAT_INDENTS_SPACING|wxRICHTEXT_FORMAT_TABS|wxRICHTEXT_FORMAT_BULLETS; + + wxRichTextFormattingDialog formatDlg(pages, this); + formatDlg.GetStyle(m_richTextCtrl, range); + + if (formatDlg.ShowModal() == wxID_OK) + { + formatDlg.ApplyStyle(m_richTextCtrl, range); + } + @endcode + + @library{wxrichtext} + @category{richtext} +*/ +class wxRichTextFormattingDialog : public wxPropertySheetDialog +{ +public: + //@{ + /** + Constructors. + + @param flags + The pages to show. + @param parent + The dialog's parent. + @param id + The dialog's identifier. + @param title + The dialog's caption. + @param pos + The dialog's position. + @param size + The dialog's size. + @param style + The dialog's window style. + */ + wxRichTextFormattingDialog(long flags, wxWindow* parent); + const wxPoint& pos = wxDefaultPosition, const wxSize& sz = wxDefaultSize, long style = wxDEFAULT_DIALOG_STYLE) + wxRichTextFormattingDialog(); + //@} + + /** + Destructor. + */ + ~wxRichTextFormattingDialog(); + + /** + Apply attributes to the given range, only changing attributes that need to be + changed. + */ + bool ApplyStyle(wxRichTextCtrl* ctrl, + const wxRichTextRange& range, + int flags = wxRICHTEXT_SETSTYLE_WITH_UNDO|wxRICHTEXT_SETSTYLE_OPTIMIZE); + + /** + Creation: see @ref overview_wxrichtextformattingdialog "the constructor" for + details about the parameters. + */ + bool Create(long flags, wxWindow* parent, const wxString& title, + wxWindowID id, + const wxPoint& pos = wxDefaultPosition, + const wxSize& sz = wxDefaultSize, + long style = wxDEFAULT_DIALOG_STYLE); + + //@{ + /** + Gets the attributes being edited. + */ + const wxTextAttr GetAttributes(); + const wxTextAttr& GetAttributes(); + //@} + + /** + Helper for pages to get the top-level dialog. + */ + wxRichTextFormattingDialog* GetDialog(wxWindow* win); + + /** + Helper for pages to get the attributes. + */ + wxTextAttr* GetDialogAttributes(wxWindow* win); + + /** + Helper for pages to get the style. + */ + wxRichTextStyleDefinition* GetDialogStyleDefinition(wxWindow* win); + + /** + Returns the object to be used to customize the dialog and provide pages. + */ + wxRichTextFormattingDialogFactory* GetFormattingDialogFactory(); + + /** + Returns the image list associated with the dialog, used for example if showing + the dialog as a toolbook. + */ + wxImageList* GetImageList() const; + + /** + Gets common attributes from the given range and calls SetAttributes. Attributes + that do not have common values in the given range + will be omitted from the style's flags. + */ + bool GetStyle(wxRichTextCtrl* ctrl, const wxRichTextRange& range); + + /** + Gets the associated style definition, if any. + */ + wxRichTextStyleDefinition* GetStyleDefinition() const; + + /** + Gets the associated style sheet, if any. + */ + wxRichTextStyleSheet* GetStyleSheet() const; + + /** + Sets the attributes to be edited. + */ + void SetAttributes(const wxTextAttr& attr); + + /** + Sets the formatting factory object to be used for customization and page + creation. + It deletes the existing factory object. + */ + void SetFormattingDialogFactory(wxRichTextFormattingDialogFactory* factory); + + /** + Sets the image list associated with the dialog's property sheet. + */ + void SetImageList(wxImageList* imageList); + + /** + Sets the attributes and optionally updates the display, if @a update is @true. + */ + bool SetStyle(const wxTextAttr& style, bool update = true); + + /** + Sets the style definition and optionally update the display, if @a update is @c + @true. + */ + bool SetStyleDefinition(const wxRichTextStyleDefinition& styleDef, + wxRichTextStyleSheet* sheet, + bool update = true); + + /** + Updates the display. + */ + bool UpdateDisplay(); +}; + diff --git a/interface/wx/richtext/richtexthtml.h b/interface/wx/richtext/richtexthtml.h new file mode 100644 index 0000000000..99e51abe0f --- /dev/null +++ b/interface/wx/richtext/richtexthtml.h @@ -0,0 +1,111 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: richtext/richtexthtml.h +// Purpose: interface of wxRichTextHTMLHandler +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxRichTextHTMLHandler + @headerfile richtexthtml.h wx/richtext/richtexthtml.h + + Handles HTML output (only) for wxRichTextCtrl content. + + The most flexible way to use this class is to create a temporary object and call + its functions directly, rather than use wxRichTextBuffer::SaveFile or + wxRichTextCtrl::SaveFile. + + Image handling requires a little extra work from the application, to choose an + appropriate image format for the target HTML viewer and to clean up the + temporary images + later. If you are planning to load the HTML into a standard web browser, you can + specify the handler flag wxRICHTEXT_HANDLER_SAVE_IMAGES_TO_BASE64 (the default) + and no extra work is required: the images will be written with the HTML. + + However, if you want wxHTML compatibility, you will need to use + wxRICHTEXT_HANDLER_SAVE_IMAGES_TO_MEMORY + or wxRICHTEXT_HANDLER_SAVE_IMAGES_TO_FILES. In this case, you must either call + wxRichTextHTMLHandler::DeleteTemporaryImages before + the next load operation, or you must store the image + locations and delete them yourself when appropriate. You can call + wxRichTextHTMLHandler::GetTemporaryImageLocations to + get the array of temporary image names. + + @library{wxrichtext} + @category{richtext} +*/ +class wxRichTextHTMLHandler : public wxRichTextFileHandler +{ +public: + /** + , wxString&@e ext = wxT("html"), @b int@e type = wxRICHTEXT_TYPE_HTML) + Constructor. + */ + wxRichTextHTMLHandler() const; + + /** + Clears the image locations generated by the last operation. + */ + void ClearTemporaryImageLocations(); + + //@{ + /** + Delete the in-memory or temporary files generated by the last operation. This + is a static + function that can be used to delete the saved locations from an earlier + operation, + for example after the user has viewed the HTML file. + */ + bool DeleteTemporaryImages(); + bool DeleteTemporaryImages(int flags, + const wxArrayString& imageLocations); + //@} + + /** + Saves the buffer content to the HTML stream. + */ + bool DoSaveFile(wxRichTextBuffer* buffer, wxOutputStream& stream); + + /** + Returns the mapping for converting point sizes to HTML font sizes. + */ + wxArrayInt GetFontSizeMapping(); + + /** + Returns the directory used to store temporary image files. + */ + const wxString GetTempDir() const; + + /** + Returns the image locations for the last operation. + */ + const wxArrayString GetTemporaryImageLocations() const; + + /** + Reset the file counter, in case, for example, the same names are required each + time + */ + void SetFileCounter(int counter); + + /** + Sets the mapping for converting point sizes to HTML font sizes. + There should be 7 elements, one for each HTML font size, each element + specifying the maximum point size for that + HTML font size. + For example: + */ + void SetFontSizeMapping(const wxArrayInt& fontSizeMapping); + + /** + Sets the directory for storing temporary files. If empty, the system + temporary directory will be used. + */ + void SetTempDir(const wxString& tempDir); + + /** + Sets the list of image locations generated by the last operation. + */ + void SetTemporaryImageLocations(const wxArrayString& locations); +}; + diff --git a/interface/wx/richtext/richtextprint.h b/interface/wx/richtext/richtextprint.h new file mode 100644 index 0000000000..2c70bdbf5d --- /dev/null +++ b/interface/wx/richtext/richtextprint.h @@ -0,0 +1,397 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: richtext/richtextprint.h +// Purpose: interface of wxRichTextHeaderFooterData +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxRichTextHeaderFooterData + @headerfile richtextprint.h wx/richtext/richtextprint.h + + + This class represents header and footer data to be passed to the + wxRichTextPrinting and + wxRichTextPrintout classes. + + Headers and footers can be specified independently for odd, even or both page + sides. Different text can be specified + for left, centre and right locations on the page, and the font and text colour + can also + be specified. You can specify the following keywords in header and footer text, + which will + be substituted for the actual values during printing and preview. + + @DATE@: the current date. + @PAGESCNT@: the total number of pages. + @PAGENUM@: the current page number. + @TIME@: the current time. + @TITLE@: the title of the document, as passed to the wxRichTextPrinting or + wxRichTextLayout constructor. + + @library{wxrichtext} + @category{richtext} +*/ +class wxRichTextHeaderFooterData : public wxObject +{ +public: + //@{ + /** + Constructors. + */ + wxRichTextHeaderFooterData(); + wxRichTextHeaderFooterData(const wxRichTextHeaderFooterData& data); + //@} + + /** + Clears all text. + */ + void Clear(); + + /** + Copies the data. + */ + void Copy(const wxRichTextHeaderFooterData& data); + + /** + Returns the font specified for printing the header and footer. + */ + const wxFont GetFont() const; + + /** + Returns the margin between the text and the footer. + */ + int GetFooterMargin() const; + + /** + Returns the footer text on odd or even pages, and at a given position on the + page (left, centre or right). + */ + wxString GetFooterText(wxRichTextOddEvenPage page = wxRICHTEXT_PAGE_EVEN, + wxRichTextPageLocation location = wxRICHTEXT_PAGE_CENTRE) const; + + /** + Returns the margin between the text and the header. + */ + int GetHeaderMargin() const; + + /** + Returns the header text on odd or even pages, and at a given position on the + page (left, centre or right). + */ + wxString GetHeaderText(wxRichTextOddEvenPage page = wxRICHTEXT_PAGE_EVEN, + wxRichTextPageLocation location = wxRICHTEXT_PAGE_CENTRE) const; + + /** + Returns @true if the header and footer will be shown on the first page. + */ + bool GetShowOnFirstPage() const; + + /** + Helper function for getting the header or footer text, odd or even pages, and + at a given position on the page (left, centre or right). + */ + wxString GetText(int headerFooter, wxRichTextOddEvenPage page, + wxRichTextPageLocation location) const; + + /** + Returns the text colour for drawing the header and footer. + */ + const wxColour GetTextColour() const; + + /** + Initialises the object. + */ + void Init(); + + /** + Sets the font for drawing the header and footer. + */ + void SetFont(const wxFont& font); + + /** + Sets the footer text on odd or even pages, and at a given position on the page + (left, centre or right). + */ + void SetFooterText(const wxString& text, + wxRichTextOddEvenPage page = wxRICHTEXT_PAGE_ALL, + wxRichTextPageLocation location = wxRICHTEXT_PAGE_CENTRE); + + /** + Sets the header text on odd or even pages, and at a given position on the page + (left, centre or right). + */ + void SetHeaderText(const wxString& text, + wxRichTextOddEvenPage page = wxRICHTEXT_PAGE_ALL, + wxRichTextPageLocation location = wxRICHTEXT_PAGE_CENTRE); + + /** + Sets the margins between text and header or footer, in tenths of a millimeter. + */ + void SetMargins(int headerMargin, int footerMargin); + + /** + Pass @true to show the header or footer on first page (the default). + */ + void SetShowOnFirstPage(bool showOnFirstPage); + + /** + Helper function for setting the header or footer text, odd or even pages, and + at a given position on the page (left, centre or right). + */ + void SetText(const wxString& text, int headerFooter, + wxRichTextOddEvenPage page, + wxRichTextPageLocation location); + + /** + Sets the text colour for drawing the header and footer. + */ + void SetTextColour(const wxColour& col); + + /** + Assignment operator. + */ + void operator operator=(const wxRichTextHeaderFooterData& data); +}; + + + +/** + @class wxRichTextPrintout + @headerfile richtextprint.h wx/richtext/richtextprint.h + + This class implements print layout for wxRichTextBuffer. Instead of using it + directly, you + should normally use the wxRichTextPrinting class. + + @library{wxrichtext} + @category{richtext} +*/ +class wxRichTextPrintout : public wxPrintout +{ +public: + /** + ) + Constructor. + */ + wxRichTextPrintout(); + + /** + Calculates scaling and text, header and footer rectangles. + */ + void CalculateScaling(wxDC* dc, wxRect& textRect, + wxRect& headerRect, + wxRect& footerRect); + + /** + Returns the header and footer data associated with the printout. + */ + const wxRichTextHeaderFooterData GetHeaderFooterData() const; + + /** + Gets the page information. + */ + void GetPageInfo(int* minPage, int* maxPage, int* selPageFrom, + int* selPageTo); + + /** + Returns a pointer to the buffer being rendered. + */ + wxRichTextBuffer* GetRichTextBuffer() const; + + /** + Returns @true if the given page exists in the printout. + */ + bool HasPage(int page); + + /** + Prepares for printing, laying out the buffer and calculating pagination. + */ + void OnPreparePrinting(); + + /** + Does the actual printing for this page. + */ + bool OnPrintPage(int page); + + /** + Sets the header and footer data associated with the printout. + */ + void SetHeaderFooterData(const wxRichTextHeaderFooterData& data); + + /** + Sets margins in 10ths of millimetre. Defaults to 1 inch for margins. + */ + void SetMargins(int top = 252, int bottom = 252, int left = 252, + int right = 252); + + /** + Sets the buffer to print. wxRichTextPrintout does not manage this pointer; it + should + be managed by the calling code, such as wxRichTextPrinting. + */ + void SetRichTextBuffer(wxRichTextBuffer* buffer); +}; + + + +/** + @class wxRichTextPrinting + @headerfile richtextprint.h wx/richtext/richtextprint.h + + This class provides a simple interface for performing wxRichTextBuffer printing + and previewing. It uses wxRichTextPrintout for layout and rendering. + + @library{wxrichtext} + @category{richtext} +*/ +class wxRichTextPrinting : public wxObject +{ +public: + /** + , @b wxWindow*@e parentWindow = @NULL) + Constructor. Optionally pass a title to be used in the preview frame and + printing wait dialog, and + also a parent window for these windows. + */ + wxRichTextPrinting(); + + /** + A convenience function to get the footer text. See wxRichTextHeaderFooterData + for details. + */ + wxString GetFooterText(wxRichTextOddEvenPage page = wxRICHTEXT_PAGE_EVEN, + wxRichTextPageLocation location = wxRICHTEXT_PAGE_CENTRE) const; + + /** + Returns the internal wxRichTextHeaderFooterData object. + */ + const wxRichTextHeaderFooterData GetHeaderFooterData() const; + + /** + A convenience function to get the header text. See wxRichTextHeaderFooterData + for details. + */ + wxString GetHeaderText(wxRichTextOddEvenPage page = wxRICHTEXT_PAGE_EVEN, + wxRichTextPageLocation location = wxRICHTEXT_PAGE_CENTRE) const; + + /** + Returns a pointer to the internal page setup data. + */ + wxPageSetupDialogData* GetPageSetupData(); + + /** + Returns the parent window to be used for the preview window and printing wait + dialog. + */ + wxWindow* GetParentWindow() const; + + /** + Returns the dimensions to be used for the preview window. + */ + const wxRect GetPreviewRect() const; + + /** + Returns a pointer to the internal print data. + */ + wxPrintData* GetPrintData(); + + /** + Returns the title of the preview window or printing wait caption. + */ + const wxString GetTitle() const; + + /** + Shows the page setup dialog. + */ + void PageSetup(); + + /** + Shows a preview window for the given buffer. The function takes its own copy of + @e buffer. + */ + bool PreviewBuffer(const wxRichTextBuffer& buffer); + + /** + Shows a preview window for the given file. @a richTextFile can be a text file + or XML file, or other file + depending on the available file handlers. + */ + bool PreviewFile(const wxString& richTextFile); + + /** + Prints the given buffer. The function takes its own copy of @e buffer. + */ + bool PrintBuffer(const wxRichTextBuffer& buffer); + + /** + Prints the given file. @a richTextFile can be a text file or XML file, or other + file + depending on the available file handlers. + */ + bool PrintFile(const wxString& richTextFile); + + /** + A convenience function to set the footer text. See wxRichTextHeaderFooterData + for details. + */ + void SetFooterText(const wxString& text, + wxRichTextOddEvenPage page = wxRICHTEXT_PAGE_ALL, + wxRichTextPageLocation location = wxRICHTEXT_PAGE_CENTRE); + + /** + Sets the internal wxRichTextHeaderFooterData object. + */ + void SetHeaderFooterData(const wxRichTextHeaderFooterData& data); + + /** + Sets the wxRichTextHeaderFooterData font. + */ + void SetHeaderFooterFont(const wxFont& font); + + /** + Sets the wxRichTextHeaderFooterData text colour. + */ + void SetHeaderFooterTextColour(const wxColour& colour); + + /** + A convenience function to set the header text. See wxRichTextHeaderFooterData + for details. + */ + void SetHeaderText(const wxString& text, + wxRichTextOddEvenPage page = wxRICHTEXT_PAGE_ALL, + wxRichTextPageLocation location = wxRICHTEXT_PAGE_CENTRE); + + /** + Sets the page setup data. + */ + void SetPageSetupData(const wxPageSetupData& pageSetupData); + + /** + Sets the parent window to be used for the preview window and printing wait + dialog. + */ + void SetParentWindow(wxWindow* parent); + + /** + Sets the dimensions to be used for the preview window. + */ + void SetPreviewRect(const wxRect& rect); + + /** + Sets the print data. + */ + void SetPrintData(const wxPrintData& printData); + + /** + Pass @true to show the header and footer on the first page. + */ + void SetShowOnFirstPage(bool show); + + /** + Pass the title of the preview window or printing wait caption. + */ + void SetTitle(const wxString& title); +}; + diff --git a/interface/wx/richtext/richtextstyledlg.h b/interface/wx/richtext/richtextstyledlg.h new file mode 100644 index 0000000000..38ad39121d --- /dev/null +++ b/interface/wx/richtext/richtextstyledlg.h @@ -0,0 +1,177 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: richtext/richtextstyledlg.h +// Purpose: interface of wxRichTextStyleOrganiserDialog +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxRichTextStyleOrganiserDialog + @headerfile richtextstyledlg.h wx/richtext/richtextstyledlg.h + + This class shows a style sheet and allows the user to edit, add and remove + styles. + It can also be used as a style browser, for example if the application is not + using a permanent wxRichTextStyleComboCtrl or wxRichTextStyleListCtrl to + present styles. + + @library{wxrichtext} + @category{richtext} +*/ +class wxRichTextStyleOrganiserDialog : public wxDialog +{ +public: + //@{ + /** + Constructors. + To create a dialog, pass a bitlist of @a flags (see below), a style sheet, a + text control to apply a selected style to (or @NULL), followed by the usual window parameters. + To specify the operations available to the user, pass a combination of these + values to @e flags: + + @b wxRICHTEXT_ORGANISER_DELETE_STYLES + + Provides a button for deleting styles. + + @b wxRICHTEXT_ORGANISER_CREATE_STYLES + + Provides buttons for creating styles. + + @b wxRICHTEXT_ORGANISER_APPLY_STYLES + + Provides a button for applying the currently selected style to the selection. + + @b wxRICHTEXT_ORGANISER_EDIT_STYLES + + Provides a button for editing styles. + + @b wxRICHTEXT_ORGANISER_RENAME_STYLES + + Provides a button for renaming styles. + + @b wxRICHTEXT_ORGANISER_OK_CANCEL + + Provides OK and Cancel buttons. + + @b wxRICHTEXT_ORGANISER_RENUMBER + + Provides a checkbox for specifying that the selection should be renumbered. + + The following flags determine what will be displayed in the style list: + + @b wxRICHTEXT_ORGANISER_SHOW_CHARACTER + + Displays character styles only. + + @b wxRICHTEXT_ORGANISER_SHOW_PARAGRAPH + + Displays paragraph styles only. + + @b wxRICHTEXT_ORGANISER_SHOW_LIST + + Displays list styles only. + + @b wxRICHTEXT_ORGANISER_SHOW_ALL + + Displays all styles. + + The following symbols define commonly-used combinations of flags: + + @b wxRICHTEXT_ORGANISER_ORGANISE + + Enable all style editing operations so the dialog behaves as a style organiser. + + @b wxRICHTEXT_ORGANISER_BROWSE + + Show a list of all styles and their previews, but only allow application of a + style or + cancellation of the dialog. This makes the dialog behave as a style browser. + + @b wxRICHTEXT_ORGANISER_BROWSE_NUMBERING + + Enables only list style browsing, plus a control to specify renumbering. This + allows the dialog to be used for applying list styles to the selection. + */ + wxRichTextStyleOrganiserDialog(int flags, + wxRichTextStyleSheet* sheet, + wxRichTextCtrl* ctrl, + wxWindow* parent, + wxWindowID id = wxID_ANY); + const wxSize& size = wxDefaultSize, long style = wxDEFAULT_DIALOG_STYLE|wxRESIZE_BORDER|wxSYSTEM_MENU|wxCLOSE_BOX) + wxRichTextStyleOrganiserDialog(); + //@} + + /** + Applies the selected style to selection in the given control or the control + passed to the constructor. + */ + bool ApplyStyle(wxRichTextCtrl* ctrl = NULL); + + /** + , wxPoint&@e pos = wxDefaultPosition, wxSize&@e size = wxDefaultSize, @b + long@e style = wxDEFAULT_DIALOG_STYLE|wxRESIZE_BORDER|wxSYSTEM_MENU|wxCLOSE_BOX) + Creates the dialog. See + */ + bool Create(int flags, wxRichTextStyleSheet* sheet, + wxRichTextCtrl* ctrl, + wxWindow* parent, + wxWindowID id = wxID_ANY) const; + + /** + Returns @true if the user has opted to restart numbering. + */ + bool GetRestartNumbering() const; + + /** + Returns the associated rich text control (if any). + */ + wxRichTextCtrl* GetRichTextCtrl() const; + + /** + Returns selected style name. + */ + wxString GetSelectedStyle() const; + + /** + Returns selected style definition. + */ + wxRichTextStyleDefinition* GetSelectedStyleDefinition() const; + + /** + Returns the associated style sheet. + */ + wxRichTextStyleSheet* GetStyleSheet() const; + + /** + Sets the flags used to control the interface presented to the user. + */ + void SetFlags(int flags); + + /** + Checks or unchecks the restart numbering checkbox. + */ + void SetRestartNumbering(bool restartNumbering); + + /** + Sets the control to be associated with the dialog, for the purposes of applying + a style to the selection. + */ + void SetRichTextCtrl(wxRichTextCtrl* ctrl); + + /** + Determines whether tooltips will be shown. + */ + void SetShowToolTips(bool show); + + /** + Sets the associated style sheet. + */ + void SetStyleSheet(wxRichTextStyleSheet* sheet); + + /** + Returns the flags used to control the interface presented to the user. + */ + int GetFlags() const; +}; + diff --git a/interface/wx/richtext/richtextstyles.h b/interface/wx/richtext/richtextstyles.h new file mode 100644 index 0000000000..a054d938cc --- /dev/null +++ b/interface/wx/richtext/richtextstyles.h @@ -0,0 +1,677 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: richtext/richtextstyles.h +// Purpose: interface of wxRichTextStyleListCtrl +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxRichTextStyleListCtrl + @headerfile richtextstyles.h wx/richtext/richtextstyles.h + + This class incorporates a wxRichTextStyleListBox and + a choice control that allows the user to select the category of style to view. + It is demonstrated in the wxRichTextCtrl sample in @c samples/richtext. + + To use wxRichTextStyleListCtrl, add the control to your window hierarchy and + call wxRichTextStyleListCtrl::SetStyleType with + one of wxRichTextStyleListBox::wxRICHTEXT_STYLE_ALL, + wxRichTextStyleListBox::wxRICHTEXT_STYLE_PARAGRAPH, + wxRichTextStyleListBox::wxRICHTEXT_STYLE_CHARACTER and + wxRichTextStyleListBox::wxRICHTEXT_STYLE_LIST to set the current view. + Associate the control with a style sheet and rich text control with + SetStyleSheet and SetRichTextCtrl, + so that when a style is double-clicked, it is applied to the selection. + + @beginStyleTable + @style{wxRICHTEXTSTYLELIST_HIDE_TYPE_SELECTOR} + This style hides the category selection control. + @endStyleTable + + @library{wxrichtext} + @category{FIXME} +*/ +class wxRichTextStyleListCtrl : public wxControl +{ +public: + //@{ + /** + Constructors. + */ + wxRichTextStyleListCtrl(wxWindow* parent, + wxWindowID id = wxID_ANY, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0); + wxRichTextStyleListCtrl(); + //@} + + /** + Creates the windows. + */ + bool Create(wxWindow* parent, wxWindowID id = wxID_ANY, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0); + + /** + Returns the associated rich text control, if any. + */ + wxRichTextCtrl* GetRichTextCtrl() const; + + /** + Returns the wxChoice control used for selecting the style category. + */ + wxChoice* GetStyleChoice() const; + + /** + Returns the wxListBox control used to view the style list. + */ + wxRichTextStyleListBox* GetStyleListBox() const; + + /** + Returns the associated style sheet, if any. + */ + wxRichTextStyleSheet* GetStyleSheet() const; + + /** + Returns the type of style to show in the list box. + */ + wxRichTextStyleListBox::wxRichTextStyleType GetStyleType() const; + + /** + Associates the control with a wxRichTextCtrl. + */ + void SetRichTextCtrl(wxRichTextCtrl* ctrl); + + /** + Associates the control with a style sheet. + */ + void SetStyleSheet(wxRichTextStyleSheet* styleSheet); + + /** + Sets the style type to display. One of + wxRichTextStyleListBox::wxRICHTEXT_STYLE_ALL, wxRichTextStyleListBox::wxRICHTEXT_STYLE_PARAGRAPH, + wxRichTextStyleListBox::wxRICHTEXT_STYLE_CHARACTER and + wxRichTextStyleListBox::wxRICHTEXT_STYLE_LIST. + */ + void SetStyleType(wxRichTextStyleListBox::wxRichTextStyleType styleType); + + /** + Updates the style list box. + */ + void UpdateStyles(); +}; + + + +/** + @class wxRichTextStyleDefinition + @headerfile richtextstyles.h wx/richtext/richtextstyles.h + + This is a base class for paragraph and character styles. + + @library{wxrichtext} + @category{FIXME} +*/ +class wxRichTextStyleDefinition : public wxObject +{ +public: + /** + Constructor. + */ + wxRichTextStyleDefinition(const wxString& name = wxEmptyString); + + /** + Destructor. + */ + ~wxRichTextStyleDefinition(); + + /** + Returns the style on which this style is based. + */ + const wxString GetBaseStyle() const; + + /** + Returns the style's description. + */ + const wxString GetDescription() const; + + /** + Returns the style name. + */ + const wxString GetName() const; + + //@{ + /** + Returns the attributes associated with this style. + */ + wxTextAttr GetStyle() const; + const wxTextAttr GetStyle() const; + //@} + + /** + Returns the style attributes combined with the attributes of the specified base + style, if any. This function works recursively. + */ + wxTextAttr GetStyleMergedWithBase(wxRichTextStyleSheet* sheet) const; + + /** + Sets the name of the style that this style is based on. + */ + void SetBaseStyle(const wxString& name); + + /** + Sets the style description. + */ + void SetDescription(const wxString& descr); + + /** + Sets the name of the style. + */ + void SetName(const wxString& name); + + /** + Sets the attributes for this style. + */ + void SetStyle(const wxTextAttr& style); +}; + + + +/** + @class wxRichTextParagraphStyleDefinition + @headerfile richtextstyles.h wx/richtext/richtextstyles.h + + This class represents a paragraph style definition, usually added to a + wxRichTextStyleSheet. + + @library{wxrichtext} + @category{richtext} +*/ +class wxRichTextParagraphStyleDefinition : public wxRichTextStyleDefinition +{ +public: + /** + Constructor. + */ + wxRichTextParagraphStyleDefinition(const wxString& name = wxEmptyString); + + /** + Destructor. + */ + ~wxRichTextParagraphStyleDefinition(); + + /** + Returns the style that should normally follow this style. + */ + const wxString GetNextStyle() const; + + /** + Sets the style that should normally follow this style. + */ + void SetNextStyle(const wxString& name); +}; + + + +/** + @class wxRichTextStyleListBox + @headerfile richtextstyles.h wx/richtext/richtextstyles.h + + This is a listbox that can display the styles in a wxRichTextStyleSheet, + and apply the selection to an associated wxRichTextCtrl. + + See @c samples/richtext for an example of how to use it. + + @library{wxrichtext} + @category{richtext} + + @see wxRichTextStyleComboCtrl, @ref overview_wxrichtextctrloverview + "wxRichTextCtrl overview" +*/ +class wxRichTextStyleListBox : public wxHtmlListBox +{ +public: + /** + Constructor. + */ + wxRichTextStyleListBox(wxWindow* parent, + wxWindowID id = wxID_ANY, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0); + + /** + Destructor. + */ + ~wxRichTextStyleListBox(); + + /** + Applies the @e ith style to the associated rich text control. + */ + void ApplyStyle(int i); + + /** + Converts units in tenths of a millimetre to device units. + */ + int ConvertTenthsMMToPixels(wxDC& dc, int units) const; + + /** + Creates a suitable HTML fragment for a definition. + */ + wxString CreateHTML(wxRichTextStyleDefinition* def) const; + + /** + If the return value is @true, clicking on a style name in the list will + immediately + apply the style to the associated rich text control. + */ + bool GetApplyOnSelection() const; + + /** + Returns the wxRichTextCtrl associated with this listbox. + */ + wxRichTextCtrl* GetRichTextCtrl() const; + + /** + Gets a style for a listbox index. + */ + wxRichTextStyleDefinition* GetStyle(size_t i) const; + + /** + Returns the style sheet associated with this listbox. + */ + wxRichTextStyleSheet* GetStyleSheet() const; + + /** + Returns the type of style to show in the list box. + */ + wxRichTextStyleListBox::wxRichTextStyleType GetStyleType() const; + + /** + Returns the HTML for this item. + */ + wxString OnGetItem(size_t n) const; + + /** + Implements left click behaviour, applying the clicked style to the + wxRichTextCtrl. + */ + void OnLeftDown(wxMouseEvent& event); + + /** + Reacts to selection. + */ + void OnSelect(wxCommandEvent& event); + + /** + If @a applyOnSelection is @true, clicking on a style name in the list will + immediately + apply the style to the associated rich text control. + */ + void SetApplyOnSelection(bool applyOnSelection); + + /** + Associates the listbox with a wxRichTextCtrl. + */ + void SetRichTextCtrl(wxRichTextCtrl* ctrl); + + /** + Associates the control with a style sheet. + */ + void SetStyleSheet(wxRichTextStyleSheet* styleSheet); + + /** + Sets the style type to display. One of + wxRichTextStyleListBox::wxRICHTEXT_STYLE_ALL, wxRichTextStyleListBox::wxRICHTEXT_STYLE_PARAGRAPH, + wxRichTextStyleListBox::wxRICHTEXT_STYLE_CHARACTER and + wxRichTextStyleListBox::wxRICHTEXT_STYLE_LIST. + */ + void SetStyleType(wxRichTextStyleListBox::wxRichTextStyleType styleType); + + /** + Updates the list from the associated style sheet. + */ + void UpdateStyles(); +}; + + + +/** + @class wxRichTextStyleComboCtrl + @headerfile richtextstyles.h wx/richtext/richtextstyles.h + + This is a combo control that can display the styles in a wxRichTextStyleSheet, + and apply the selection to an associated wxRichTextCtrl. + + See @c samples/richtext for an example of how to use it. + + @library{wxrichtext} + @category{richtext} + + @see wxRichTextStyleListBox, @ref overview_wxrichtextctrloverview + "wxRichTextCtrl overview" +*/ +class wxRichTextStyleComboCtrl : public wxComboCtrl +{ +public: + /** + Constructor. + */ + wxRichTextStyleComboCtrl(wxWindow* parent, + wxWindowID id = wxID_ANY, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0); + + /** + Destructor. + */ + ~wxRichTextStyleComboCtrl(); + + /** + Returns the wxRichTextCtrl associated with this control. + */ + wxRichTextCtrl* GetRichTextCtrl() const; + + /** + Returns the style sheet associated with this control. + */ + wxRichTextStyleSheet* GetStyleSheet() const; + + /** + Associates the control with a wxRichTextCtrl. + */ + void SetRichTextCtrl(wxRichTextCtrl* ctrl); + + /** + Associates the control with a style sheet. + */ + void SetStyleSheet(wxRichTextStyleSheet* styleSheet); + + /** + Updates the combo control from the associated style sheet. + */ + void UpdateStyles(); +}; + + + +/** + @class wxRichTextCharacterStyleDefinition + @headerfile richtextstyles.h wx/richtext/richtextstyles.h + + This class represents a character style definition, usually added to a + wxRichTextStyleSheet. + + @library{wxrichtext} + @category{richtext} +*/ +class wxRichTextCharacterStyleDefinition : public wxRichTextStyleDefinition +{ +public: + /** + Constructor. + */ + wxRichTextCharacterStyleDefinition(const wxString& name = wxEmptyString); + + /** + Destructor. + */ + ~wxRichTextCharacterStyleDefinition(); +}; + + + +/** + @class wxRichTextListStyleDefinition + @headerfile richtextstyles.h wx/richtext/richtextstyles.h + + This class represents a list style definition, usually added to a + wxRichTextStyleSheet. + + The class inherits paragraph attributes from + wxRichTextStyleParagraphDefinition, and adds 10 further attribute objects, one for each level of a list. + When applying a list style to a paragraph, the list style's base and + appropriate level attributes are merged with the + paragraph's existing attributes. + + You can apply a list style to one or more paragraphs using + wxRichTextCtrl::SetListStyle. You + can also use the functions wxRichTextCtrl::NumberList, + wxRichTextCtrl::PromoteList and + wxRichTextCtrl::ClearListStyle. As usual, there are wxRichTextBuffer versions + of these functions + so that you can apply them directly to a buffer without requiring a control. + + @library{wxrichtext} + @category{richtext} +*/ +class wxRichTextListStyleDefinition : public wxRichTextParagraphStyleDefinition +{ +public: + /** + Constructor. + */ + wxRichTextListStyleDefinition(const wxString& name = wxEmptyString); + + /** + Destructor. + */ + ~wxRichTextListStyleDefinition(); + + /** + This function combines the given paragraph style with the list style's base + attributes and level style matching the given indent, returning the combined attributes. + If @a styleSheet is specified, the base style for this definition will also be + included in the result. + */ + wxTextAttr CombineWithParagraphStyle(int indent, + const wxTextAttr& paraStyle, + wxRichTextStyleSheet* styleSheet = NULL); + + /** + This function finds the level (from 0 to 9) whose indentation attribute mostly + closely matches @a indent (expressed in tenths of a millimetre). + */ + int FindLevelForIndent(int indent) const; + + /** + This function combines the list style's base attributes and the level style + matching the given indent, returning the combined attributes. + If @a styleSheet is specified, the base style for this definition will also be + included in the result. + */ + wxTextAttr GetCombinedStyle(int indent, + wxRichTextStyleSheet* styleSheet = NULL) const; + + /** + This function combines the list style's base attributes and the style for the + specified level, returning the combined attributes. + If @a styleSheet is specified, the base style for this definition will also be + included in the result. + */ + wxTextAttr GetCombinedStyleLevel(int level, + wxRichTextStyleSheet* styleSheet = NULL) const; + + /** + Returns the style for the given level. @a level is a number between 0 and 9. + */ + const wxTextAttr* GetLevelAttributes(int level) const; + + /** + Returns the number of levels. This is hard-wired to 10. + Returns the style for the given level. @e level is a number between 0 and 9. + */ + int GetLevelCount() const; + + /** + Returns @true if the given level has numbered list attributes. + */ + int IsNumbered(int level) const; + + //@{ + /** + Sets the style for the given level. @a level is a number between 0 and 9. + The first and most flexible form uses a wxTextAttr object, while the second + form is for convenient setting of the most commonly-used attributes. + */ + void SetLevelAttributes(int level, const wxTextAttr& attr); + void SetLevelAttributes(int level, int leftIndent, + int leftSubIndent, + int bulletStyle, + const wxString& bulletSymbol = wxEmptyString); + //@} +}; + + + +/** + @class wxRichTextStyleSheet + @headerfile richtextstyles.h wx/richtext/richtextstyles.h + + A style sheet contains named paragraph and character styles that make it + easy for a user to apply combinations of attributes to a wxRichTextCtrl. + + You can use a wxRichTextStyleListBox in your + user interface to show available styles to the user, and allow application + of styles to the control. + + @library{wxrichtext} + @category{richtext} +*/ +class wxRichTextStyleSheet : public wxObject +{ +public: + /** + Constructor. + */ + wxRichTextStyleSheet(); + + /** + Destructor. + */ + ~wxRichTextStyleSheet(); + + /** + Adds a definition to the character style list. + */ + bool AddCharacterStyle(wxRichTextCharacterStyleDefinition* def); + + /** + Adds a definition to the list style list. + */ + bool AddListStyle(wxRichTextListStyleDefinition* def); + + /** + Adds a definition to the paragraph style list. + */ + bool AddParagraphStyle(wxRichTextParagraphStyleDefinition* def); + + /** + Adds a definition to the appropriate style list. + */ + bool AddStyle(wxRichTextStyleDefinition* def); + + /** + Deletes all styles. + */ + void DeleteStyles(); + + /** + Finds a character definition by name. + */ + wxRichTextCharacterStyleDefinition* FindCharacterStyle(const wxString& name) const; + + /** + Finds a list definition by name. + */ + wxRichTextListStyleDefinition* FindListStyle(const wxString& name) const; + + /** + Finds a paragraph definition by name. + */ + wxRichTextParagraphStyleDefinition* FindParagraphStyle(const wxString& name) const; + + /** + Finds a style definition by name. + */ + wxRichTextStyleDefinition* FindStyle(const wxString& name) const; + + /** + Returns the @e nth character style. + */ + wxRichTextCharacterStyleDefinition* GetCharacterStyle(size_t n) const; + + /** + Returns the number of character styles. + */ + size_t GetCharacterStyleCount() const; + + /** + Returns the style sheet's description. + */ + const wxString GetDescription() const; + + /** + Returns the @e nth list style. + */ + wxRichTextListStyleDefinition* GetListStyle(size_t n) const; + + /** + Returns the number of list styles. + */ + size_t GetListStyleCount() const; + + /** + Returns the style sheet's name. + */ + const wxString GetName() const; + + /** + Returns the @e nth paragraph style. + */ + wxRichTextParagraphStyleDefinition* GetParagraphStyle(size_t n) const; + + /** + Returns the number of paragraph styles. + */ + size_t GetParagraphStyleCount() const; + + /** + Removes a character style. + */ + bool RemoveCharacterStyle(wxRichTextStyleDefinition* def, + bool deleteStyle = false); + + /** + Removes a list style. + */ + bool RemoveListStyle(wxRichTextStyleDefinition* def, + bool deleteStyle = false); + + /** + Removes a paragraph style. + */ + bool RemoveParagraphStyle(wxRichTextStyleDefinition* def, + bool deleteStyle = false); + + /** + Removes a style. + */ + bool RemoveStyle(wxRichTextStyleDefinition* def, + bool deleteStyle = false); + + /** + Sets the style sheet's description. + */ + void SetDescription(const wxString& descr); + + /** + Sets the style sheet's name. + */ + void SetName(const wxString& name); +}; + diff --git a/interface/wx/richtext/richtextsymboldlg.h b/interface/wx/richtext/richtextsymboldlg.h new file mode 100644 index 0000000000..f862372780 --- /dev/null +++ b/interface/wx/richtext/richtextsymboldlg.h @@ -0,0 +1,190 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: richtext/richtextsymboldlg.h +// Purpose: interface of wxSymbolPickerDialog +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxSymbolPickerDialog + @headerfile richtextsymboldlg.h wx/richtext/richtextsymboldlg.h + + wxSymbolPickerDialog presents the user with a choice of fonts and a grid + of available characters. This modal dialog provides the application with + a selected symbol and optional font selection. + + Although this dialog is contained in the rich text library, the dialog + is generic and can be used in other contexts. + + To use the dialog, pass a default symbol specified as a string, an initial font + name, + and a current font name. The difference between the initial font and + current font is that the initial font determines what the font control will be + set to when the dialog shows - an empty string will show the selection @e + normal text. + The current font, on the other hand, is used by the dialog to determine what + font + to display the characters in, even when no initial font is selected. + This allows the user (and application) to distinguish between inserting a + symbol in the current font, and inserting it with a specified font. + + When the dialog is dismissed, the application can get the selected symbol + with GetSymbol and test whether a font was specified with UseNormalFont, + fetching the specified font with GetFontName. + + Here's a realistic example, inserting the supplied symbol into a + rich text control in either the current font or specified font. + + @code + wxRichTextCtrl* ctrl = (wxRichTextCtrl*) FindWindow(ID_RICHTEXT_CTRL); + + wxTextAttr attr; + attr.SetFlags(wxTEXT_ATTR_FONT); + ctrl-GetStyle(ctrl-GetInsertionPoint(), attr); + + wxString currentFontName; + if (attr.HasFont() && attr.GetFont().Ok()) + currentFontName = attr.GetFont().GetFaceName(); + + // Don't set the initial font in the dialog (so the user is choosing + // 'normal text', i.e. the current font) but do tell the dialog + // what 'normal text' is. + + wxSymbolPickerDialog dlg(wxT("*"), wxEmptyString, currentFontName, this); + + if (dlg.ShowModal() == wxID_OK) + { + if (dlg.HasSelection()) + { + long insertionPoint = ctrl-GetInsertionPoint(); + + ctrl-WriteText(dlg.GetSymbol()); + + if (!dlg.UseNormalFont()) + { + wxFont font(attr.GetFont()); + font.SetFaceName(dlg.GetFontName()); + attr.SetFont(font); + ctrl-SetStyle(insertionPoint, insertionPoint+1, attr); + } + } + } + @endcode + + @library{wxrichtext} + @category{cmndlg} +*/ +class wxSymbolPickerDialog : public wxDialog +{ +public: + //@{ + /** + Constructors. + + @param symbol + The initial symbol to show. Specify a single character in a string, or an + empty string. + @param initialFont + The initial font to be displayed in the font list. If empty, the item + normal text will be selected. + @param normalTextFont + The font the dialog will use to display the symbols if the initial font is + empty. + @param parent + The dialog's parent. + @param id + The dialog's identifier. + @param title + The dialog's caption. + @param pos + The dialog's position. + @param size + The dialog's size. + @param style + The dialog's window style. + */ + wxSymbolPickerDialog(const wxString& symbol, + const wxString& initialFont, + const wxString& normalTextFont, + wxWindow* parent, + wxWindowID id = wxID_ANY); + const wxSize& size = wxDefaultSize, long style = wxDEFAULT_DIALOG_STYLE|wxRESIZE_BORDER|wxCLOSE_BOX) + wxSymbolPickerDialog(); + //@} + + /** + , wxPoint&@e pos = wxDefaultPosition, wxSize&@e size = wxDefaultSize, @b + long@e style = wxDEFAULT_DIALOG_STYLE|wxRESIZE_BORDER|wxCLOSE_BOX) + Creation: see @ref wxsymbolpickerdialog() "the constructor" for details about + the parameters. + */ + bool Create(const wxString& symbol, const wxString& initialFont, + const wxString& normalTextFont, + wxWindow* parent, + wxWindowID id = wxID_ANY) const; + + /** + Returns the font name (the font reflected in the font list). + */ + wxString GetFontName() const; + + /** + Returns @true if the dialog is showing the full range of Unicode characters. + */ + bool GetFromUnicode() const; + + /** + Gets the font name used for displaying symbols in the absence of a selected + font. + */ + wxString GetNormalTextFontName() const; + + /** + Gets the current or initial symbol as a string. + */ + wxString GetSymbol() const; + + /** + Gets the selected symbol character as an integer. + */ + int GetSymbolChar() const; + + /** + Returns @true if a symbol is selected. + */ + bool HasSelection() const; + + /** + Sets the initial/selected font name. + */ + void SetFontName(const wxString& value); + + /** + Sets the internal flag indicating that the full Unicode range should be + displayed. + */ + void SetFromUnicode(bool value); + + /** + Sets the name of the font to be used in the absence of a selected font. + */ + void SetNormalTextFontName(const wxString& value); + + /** + Sets the symbol as a one or zero character string. + */ + void SetSymbol(const wxString& value); + + /** + Sets Unicode display mode. + */ + void SetUnicodeMode(bool unicodeMode); + + /** + Returns @true if the has specified normal text - that is, there is no selected + font. + */ + bool UseNormalFont() const; +}; + diff --git a/interface/wx/richtext/richtextxml.h b/interface/wx/richtext/richtextxml.h new file mode 100644 index 0000000000..f469e5401a --- /dev/null +++ b/interface/wx/richtext/richtextxml.h @@ -0,0 +1,102 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: richtext/richtextxml.h +// Purpose: interface of wxRichTextXMLHandler +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxRichTextXMLHandler + @headerfile richtextxml.h wx/richtext/richtextxml.h + + A handler for loading and saving content in an XML format specific + to wxRichTextBuffer. You can either add the handler to the buffer + and load and save through the buffer or control API, or you can + create an instance of the handler on the stack and call its + functions directly. + + @library{wxrichtext} + @category{richtext} +*/ +class wxRichTextXMLHandler : public wxRichTextFileHandler +{ +public: + /** + , wxString&@e ext = wxT("xml"), @b int@e type = wxRICHTEXT_TYPE_XML) + Constructor. + */ + wxRichTextXMLHandler() const; + + /** + Returns @true. + */ + bool CanLoad() const; + + /** + Returns @true. + */ + bool CanSave() const; + + /** + Creates XML code for a given character or paragraph style. + */ + wxString CreateStyle(const wxTextAttr& attr, bool isPara = false); + + /** + Loads buffer context from the given stream. + */ + bool DoLoadFile(wxRichTextBuffer* buffer, wxInputStream& stream); + + /** + Saves buffer context to the given stream. + */ + bool DoSaveFile(wxRichTextBuffer* buffer, wxOutputStream& stream); + + /** + Recursively exports an object to the stream. + */ + bool ExportXML(wxOutputStream& stream, wxMBConv* convMem, + wxMBConv* convFile, + wxRichTextObject& obj, + int level); + + /** + Helper function: gets node context. + */ + wxString GetNodeContent(wxXmlNode* node); + + /** + Helper function: gets a named parameter from the XML node. + */ + wxXmlNode* GetParamNode(wxXmlNode* node, const wxString& param); + + /** + Helper function: gets a named parameter from the XML node. + */ + wxString GetParamValue(wxXmlNode* node, const wxString& param); + + /** + Helper function: gets style parameters from the given XML node. + */ + bool GetStyle(wxTextAttr& attr, wxXmlNode* node, + bool isPara = false); + + /** + Helper function: gets text from the node. + */ + wxString GetText(wxXmlNode* node, + const wxString& param = wxEmptyString, + bool translate = false); + + /** + Helper function: returns @true if the node has the given parameter. + */ + bool HasParam(wxXmlNode* node, const wxString& param); + + /** + Recursively imports an object. + */ + bool ImportXML(wxRichTextBuffer* buffer, wxXmlNode* node); +}; + diff --git a/interface/wx/sashwin.h b/interface/wx/sashwin.h new file mode 100644 index 0000000000..a8fdb75076 --- /dev/null +++ b/interface/wx/sashwin.h @@ -0,0 +1,213 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: sashwin.h +// Purpose: interface of wxSashWindow +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxSashWindow + @wxheader{sashwin.h} + + wxSashWindow allows any of its edges to have a sash which can be dragged + to resize the window. The actual content window will be created by the + application + as a child of wxSashWindow. The window (or an ancestor) will be notified of a + drag + via a wxSashEvent notification. + + @beginStyleTable + @style{wxSW_3D} + Draws a 3D effect sash and border. + @style{wxSW_3DSASH} + Draws a 3D effect sash. + @style{wxSW_3DBORDER} + Draws a 3D effect border. + @style{wxSW_BORDER} + Draws a thin black border. + @endStyleTable + + @beginEventTable{wxSashEvent} + @event{EVT_SASH_DRAGGED(id, func)} + Process a wxEVT_SASH_DRAGGED event, when the user has finished + dragging a sash. + @event{EVT_SASH_DRAGGED_RANGE(id1, id2, func)} + Process a wxEVT_SASH_DRAGGED_RANGE event, when the user has + finished dragging a sash. The event handler is called when windows + with ids in the given range have their sashes dragged. + @endEventTable + + @library{wxadv} + @category{miscwnd} + + @see wxSashEvent, wxSashLayoutWindow, @ref overview_eventhandling +*/ +class wxSashWindow : public wxWindow +{ +public: + //@{ + /** + Constructs a sash window, which can be a child of a frame, dialog or any other + non-control window. + + @param parent + Pointer to a parent window. + @param id + Window identifier. If -1, will automatically create an identifier. + @param pos + Window position. wxDefaultPosition is (-1, -1) which indicates that + wxSashWindows + should generate a default position for the window. If using the + wxSashWindow class directly, supply + an actual position. + @param size + Window size. wxDefaultSize is (-1, -1) which indicates that wxSashWindows + should generate a default size for the window. + @param style + Window style. For window styles, please see wxSashWindow. + @param name + Window name. + */ + wxSashWindow(); + wxSashWindow(wxWindow* parent, wxWindowID id, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxCLIP_CHILDREN | wxSW_3D, + const wxString& name = "sashWindow"); + //@} + + /** + Destructor. + */ + ~wxSashWindow(); + + /** + Gets the maximum window size in the x direction. + */ + int GetMaximumSizeX() const; + + /** + Gets the maximum window size in the y direction. + */ + int GetMaximumSizeY() const; + + /** + Gets the minimum window size in the x direction. + */ + int GetMinimumSizeX(); + + /** + Gets the minimum window size in the y direction. + */ + int GetMinimumSizeY() const; + + /** + Returns @true if a sash is visible on the given edge, @false otherwise. + + @param edge + Edge. One of wxSASH_TOP, wxSASH_RIGHT, wxSASH_BOTTOM, wxSASH_LEFT. + + @see SetSashVisible() + */ + bool GetSashVisible(wxSashEdgePosition edge) const; + + /** + Returns @true if the sash has a border, @false otherwise. + This function is obsolete since the sash border property is unused. + + @param edge + Edge. One of wxSASH_TOP, wxSASH_RIGHT, wxSASH_BOTTOM, wxSASH_LEFT. + + @see SetSashBorder() + */ + bool HasBorder(wxSashEdgePosition edge) const; + + /** + Sets the maximum window size in the x direction. + */ + void SetMaximumSizeX(int min); + + /** + Sets the maximum window size in the y direction. + */ + void SetMaximumSizeY(int min); + + /** + Sets the minimum window size in the x direction. + */ + void SetMinimumSizeX(int min); + + /** + Sets the minimum window size in the y direction. + */ + void SetMinimumSizeY(int min); + + /** + Call this function to give the sash a border, or remove the border. + This function is obsolete since the sash border property is unused. + + @param edge + Edge to change. One of wxSASH_TOP, wxSASH_RIGHT, wxSASH_BOTTOM, wxSASH_LEFT. + @param hasBorder + @true to give the sash a border visible, @false to remove it. + */ + void SetSashBorder(wxSashEdgePosition edge, bool hasBorder); + + /** + Call this function to make a sash visible or invisible on a particular edge. + + @param edge + Edge to change. One of wxSASH_TOP, wxSASH_RIGHT, wxSASH_BOTTOM, wxSASH_LEFT. + @param visible + @true to make the sash visible, @false to make it invisible. + + @see GetSashVisible() + */ + void SetSashVisible(wxSashEdgePosition edge, bool visible); +}; + + + +/** + @class wxSashEvent + @wxheader{sashwin.h} + + A sash event is sent when the sash of a wxSashWindow has been + dragged by the user. + + @library{wxadv} + @category{FIXME} + + @see wxSashWindow, @ref overview_eventhandlingoverview +*/ +class wxSashEvent : public wxCommandEvent +{ +public: + /** + Constructor. + */ + wxSashEvent(int id = 0, wxSashEdgePosition edge = wxSASH_NONE); + + /** + Returns the rectangle representing the new size the window would be if the + resize was applied. It is + up to the application to set the window size if required. + */ + wxRect GetDragRect() const; + + /** + Returns the status of the sash: one of wxSASH_STATUS_OK, + wxSASH_STATUS_OUT_OF_RANGE. + If the drag caused the notional bounding box of the window to flip over, for + example, the drag will be out of rage. + */ + wxSashDragStatus GetDragStatus() const; + + /** + Returns the dragged edge. The return value is one of wxSASH_TOP, wxSASH_RIGHT, + wxSASH_BOTTOM, wxSASH_LEFT. + */ + wxSashEdgePosition GetEdge() const; +}; + diff --git a/interface/wx/sckipc.h b/interface/wx/sckipc.h new file mode 100644 index 0000000000..0ec3ce061e --- /dev/null +++ b/interface/wx/sckipc.h @@ -0,0 +1,306 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: sckipc.h +// Purpose: interface of wxTCPServer +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxTCPServer + @wxheader{sckipc.h} + + A wxTCPServer object represents the server part of a client-server conversation. + It emulates a DDE-style protocol, but uses TCP/IP which is available on most + platforms. + + A DDE-based implementation for Windows is available using wxDDEServer. + + @library{wxnet} + @category{FIXME} + + @see wxTCPClient, wxTCPConnection, @ref overview_ipcoverview "IPC overview" +*/ +class wxTCPServer : public wxObject +{ +public: + /** + Constructs a server object. + */ + wxTCPServer(); + + /** + Registers the server using the given service name. Under Unix, the + string must contain an integer id which is used as an Internet port + number. @false is returned if the call failed (for example, the port + number is already in use). + */ + bool Create(const wxString& service); + + /** + When a client calls @b MakeConnection, the server receives the + message and this member is called. The application should derive a + member to intercept this message and return a connection object of + either the standard wxTCPConnection type, or of a user-derived type. If the + topic is "STDIO", the application may wish to refuse the connection. + Under Unix, when a server is created the OnAcceptConnection message is + always sent for standard input and output. + */ + virtual wxConnectionBase* OnAcceptConnection(const wxString& topic); +}; + + + +/** + @class wxTCPClient + @wxheader{sckipc.h} + + A wxTCPClient object represents the client part of a client-server conversation. + It emulates a DDE-style protocol, but uses TCP/IP which is available on most + platforms. + + A DDE-based implementation for Windows is available using wxDDEClient. + + To create a client which can communicate with a suitable server, + you need to derive a class from wxTCPConnection and another from wxTCPClient. + The custom wxTCPConnection class will intercept communications in + a 'conversation' with a server, and the custom wxTCPServer is required + so that a user-overridden wxTCPClient::OnMakeConnection member can return + a wxTCPConnection of the required class, when a connection is made. + + @library{wxnet} + @category{FIXME} + + @see wxTCPServer, wxTCPConnection, @ref overview_ipcoverview "Interprocess + communications overview" +*/ +class wxTCPClient : public wxObject +{ +public: + /** + Constructs a client object. + */ + wxTCPClient(); + + /** + Tries to make a connection with a server specified by the host + (a machine name under Unix), service name (must + contain an integer port number under Unix), and a topic string. If the + server allows a connection, a wxTCPConnection object will be returned. + The type of wxTCPConnection returned can be altered by overriding + the OnMakeConnection() member to return your own + derived connection object. + */ + wxConnectionBase* MakeConnection(const wxString& host, + const wxString& service, + const wxString& topic); + + /** + The type of wxTCPConnection returned from a MakeConnection() call can + be altered by deriving the @b OnMakeConnection member to return your + own derived connection object. By default, a wxTCPConnection + object is returned. + The advantage of deriving your own connection class is that it will + enable you to intercept messages initiated by the server, such + as wxTCPConnection::OnAdvise. You may also want to + store application-specific data in instances of the new class. + */ + wxConnectionBase* OnMakeConnection(); + + /** + Returns @true if this is a valid host name, @false otherwise. + */ + bool ValidHost(const wxString& host); +}; + + + +/** + @class wxTCPConnection + @wxheader{sckipc.h} + + A wxTCPClient object represents the connection between a client and a server. + It emulates a DDE-style protocol, but uses TCP/IP which is available on most + platforms. + + A DDE-based implementation for Windows is available using wxDDEConnection. + + A wxTCPConnection object can be created by making a connection using a + wxTCPClient object, or by the acceptance of a connection by a + wxTCPServer object. The bulk of a conversation is controlled by + calling members in a @b wxTCPConnection object or by overriding its + members. + + An application should normally derive a new connection class from + wxTCPConnection, in order to override the communication event handlers + to do something interesting. + + @library{wxnet} + @category{FIXME} + + @see wxTCPClient, wxTCPServer, @ref overview_ipcoverview "Interprocess + communications overview" +*/ +class wxTCPConnection : public wxObject +{ +public: + //@{ + /** + Constructs a connection object. If no user-defined connection object is + to be derived from wxTCPConnection, then the constructor should not be + called directly, since the default connection object will be provided on + requesting (or accepting) a connection. However, if the user defines his + or her own derived connection object, the wxTCPServer::OnAcceptConnection + and/or wxTCPClient::OnMakeConnection members should be replaced by + functions which construct the new connection object. If the arguments of + the wxTCPConnection constructor are void, then a default buffer is + associated with the connection. Otherwise, the programmer must provide a + a buffer and size of the buffer for the connection object to use in + transactions. + */ + wxTCPConnection(); + wxTCPConnection(void* buffer, size_t size); + //@} + + //@{ + /** + Called by the server application to advise the client of a change in + the data associated with the given item. Causes the client + connection's OnAdvise() + member to be called. Returns @true if successful. + */ + bool Advise(const wxString& item, const void* data, size_t size, + wxIPCFormat format = wxIPC_PRIVATE); + bool Advise(const wxString& item, const char* data); + bool Advise(const wxString& item, const wchar_t* data); + bool Advise(const wxString& item, const wxString data); + //@} + + /** + Called by the client or server application to disconnect from the other + program; it causes the OnDisconnect() message + to be sent to the corresponding connection object in the other + program. The default behaviour of @b OnDisconnect is to delete the + connection, but the calling application must explicitly delete its + side of the connection having called @b Disconnect. Returns @true if + successful. + */ + bool Disconnect(); + + //@{ + /** + Called by the client application to execute a command on the server. Can + also be used to transfer arbitrary data to the server (similar + to Poke() in that respect). Causes the + server connection's OnExecute() member to be + called. Returns @true if successful. + */ + bool Execute(const void* data, size_t size, + wxIPCFormat format = wxIPC_PRIVATE); + bool Execute(const char* data); + bool Execute(const wchar_t* data); + bool Execute(const wxString data); + //@} + + /** + Message sent to the client application when the server notifies it of a + change in the data associated with the given item. + */ + virtual bool OnAdvise(const wxString& topic, + const wxString& item, + const void* data, + size_t size, + wxIPCFormat format); + + /** + Message sent to the client or server application when the other + application notifies it to delete the connection. Default behaviour is + to delete the connection object. + */ + virtual bool OnDisconnect(); + + /** + Message sent to the server application when the client notifies it to + execute the given data. Note that there is no item associated with + this message. + */ + virtual bool OnExecute(const wxString& topic, const void* data, + size_t size, + wxIPCFormat format); + + /** + Message sent to the server application when the client notifies it to + accept the given data. + */ + virtual bool OnPoke(const wxString& topic, const wxString& item, + const void* data, + size_t size, + wxIPCFormat format); + + /** + Message sent to the server application when the client + calls Request(). The server + should respond by returning a character string from @b OnRequest, + or @NULL to indicate no data. + */ + virtual const void* OnRequest(const wxString& topic, + const wxString& item, + size_t* size, + wxIPCFormat format); + + /** + Message sent to the server application by the client, when the client + wishes to start an 'advise loop' for the given topic and item. The + server can refuse to participate by returning @false. + */ + virtual bool OnStartAdvise(const wxString& topic, + const wxString& item); + + /** + Message sent to the server application by the client, when the client + wishes to stop an 'advise loop' for the given topic and item. The + server can refuse to stop the advise loop by returning @false, although + this doesn't have much meaning in practice. + */ + virtual bool OnStopAdvise(const wxString& topic, + const wxString& item); + + //@{ + /** + Called by the client application to poke data into the server. Can be + used to transfer arbitrary data to the server. Causes the server + connection's OnPoke() member + to be called. Returns @true if successful. + */ + bool Poke(const wxString& item, const void* data, size_t size, + wxIPCFormat format = wxIPC_PRIVATE); + bool Poke(const wxString& item, const char* data); + bool Poke(const wxString& item, const wchar_t* data); + bool Poke(const wxString& item, const wxString data); + //@} + + /** + Called by the client application to request data from the server. Causes + the server connection's OnRequest() member to be called. Returns a + character string (actually a pointer to the connection's buffer) if + successful, @NULL otherwise. + */ + const void* Request(const wxString& item, size_t* size, + wxIPCFormat format = wxIPC_TEXT); + + /** + Called by the client application to ask if an advise loop can be started + with the server. Causes the server connection's OnStartAdvise() + member to be called. Returns @true if the server okays it, @false + otherwise. + */ + bool StartAdvise(const wxString& item); + + /** + Called by the client application to ask if an advise loop can be + stopped. Causes the server connection's OnStopAdvise() member + to be called. Returns @true if the server okays it, @false otherwise. + */ + bool StopAdvise(const wxString& item); +}; + diff --git a/interface/wx/sckstrm.h b/interface/wx/sckstrm.h new file mode 100644 index 0000000000..a29d0ef6f8 --- /dev/null +++ b/interface/wx/sckstrm.h @@ -0,0 +1,56 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: sckstrm.h +// Purpose: interface of wxSocketOutputStream +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxSocketOutputStream + @wxheader{sckstrm.h} + + This class implements an output stream which writes data from + a connected socket. Note that this stream is purely sequential + and it does not support seeking. + + @library{wxnet} + @category{streams} + + @see wxSocketBase +*/ +class wxSocketOutputStream : public wxOutputStream +{ +public: + /** + Creates a new write-only socket stream using the specified initialized + socket connection. + */ + wxSocketOutputStream(wxSocketBase& s); +}; + + + +/** + @class wxSocketInputStream + @wxheader{sckstrm.h} + + This class implements an input stream which reads data from + a connected socket. Note that this stream is purely sequential + and it does not support seeking. + + @library{wxnet} + @category{streams} + + @see wxSocketBase +*/ +class wxSocketInputStream : public wxInputStream +{ +public: + /** + Creates a new read-only socket stream using the specified initialized + socket connection. + */ + wxSocketInputStream(wxSocketBase& s); +}; + diff --git a/interface/wx/scopeguard.h b/interface/wx/scopeguard.h new file mode 100644 index 0000000000..e8c88a7989 --- /dev/null +++ b/interface/wx/scopeguard.h @@ -0,0 +1,95 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: scopeguard.h +// Purpose: interface of global functions +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** @ingroup group_funcmacro_misc */ +//@{ +/** + This macro ensures that the global @a function with 0, 1, 2 or more + parameters (up to some implementation-defined limit) is executed on scope + exit, whether due to a normal function return or because an exception has + been thrown. A typical example of its usage: + + @code + void *buf = malloc(size); + wxON_BLOCK_EXIT1(free, buf); + @endcode + + Please see the original article by Andrei Alexandrescu and Petru Marginean + published in December 2000 issue of C/C++ Users Journal for more details. + + @see wxON_BLOCK_EXIT_OBJ0() + + @header{wx/scopeguard.h} +*/ +#define wxON_BLOCK_EXIT0(function) +#define wxON_BLOCK_EXIT1(function, p1) +#define wxON_BLOCK_EXIT2(function, p1, p2) +//@} + +/** @ingroup group_funcmacro_misc */ +//@{ +/** + This family of macros is similar to wxON_BLOCK_EXIT0(), but calls a method + of the given object instead of a free function. + + @header{wx/scopeguard.h} +*/ +#define wxON_BLOCK_EXIT_OBJ0(object, method) +#define wxON_BLOCK_EXIT_OBJ1(object, method, p1) +#define wxON_BLOCK_EXIT_OBJ2(object, method, p1, p2) +//@} + +/** @ingroup group_funcmacro_misc */ +//@{ +/** + This family of macros is similar to wxON_BLOCK_OBJ0(), but calls a method + of @c this object instead of a method of the specified object. + + @header{wx/scopeguard.h} +*/ +#define wxON_BLOCK_EXIT_THIS0(method) +#define wxON_BLOCK_EXIT_THIS1(method, p1) +#define wxON_BLOCK_EXIT_THIS2(method, p1, p2) +//@} + +/** @ingroup group_funcmacro_misc */ +//@{ +/** + This macro sets a variable to the specified value on scope exit. + + Example of usage: + @code + void foo() + { + bool isDoingSomething = true; + { + wxON_BLOCK_EXIT_SET(isDoingSomething, false); + ... do something ... + } + ... isDoingSomething is false now ... + } + @endcode + + @see wxON_BLOCK_EXIT_OBJ0(), wxON_BLOCK_EXIT_NULL() + + @header{wx/scopeguard.h} +*/ +#define wxON_BLOCK_EXIT_SET(var, value) + +/** + This macro sets the pointer passed to it as argument to NULL on scope exit. + + It must be used instead of wxON_BLOCK_EXIT_SET() when the value being set + is @c NULL. + + @header{wx/scopeguard.h} + */ +#define wxON_BLOCK_EXIT_NULL(ptr) + +//@} + diff --git a/interface/wx/scrolbar.h b/interface/wx/scrolbar.h new file mode 100644 index 0000000000..d6574c6b06 --- /dev/null +++ b/interface/wx/scrolbar.h @@ -0,0 +1,149 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: scrolbar.h +// Purpose: interface of wxScrollBar +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxScrollBar + @wxheader{scrolbar.h} + + A wxScrollBar is a control that represents a horizontal or + vertical scrollbar. It is distinct from the two scrollbars that some windows + provide automatically, but the two types of scrollbar share the way + events are received. + + @beginStyleTable + @style{wxSB_HORIZONTAL} + Specifies a horizontal scrollbar. + @style{wxSB_VERTICAL} + Specifies a vertical scrollbar. + @endStyleTable + + @library{wxcore} + @category{ctrl} + + + @see @ref overview_scrolling, @ref overview_eventhandling, wxScrolled +*/ +class wxScrollBar : public wxControl +{ +public: + /** + Default constructor + */ + wxScrollBar(); + + /** + Constructor, creating and showing a scrollbar. + + @param parent + Parent window. Must be non-@NULL. + @param id + Window identifier. The value wxID_ANY indicates a default value. + @param pos + Window position. If wxDefaultPosition is specified then a default + position is chosen. + @param size + Window size. If wxDefaultSize is specified then a default size + is chosen. + @param style + Window style. See wxScrollBar. + @param validator + Window validator. + @param name + Window name. + + @see Create(), wxValidator + */ + wxScrollBar(wxWindow* parent, wxWindowID id, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxSB_HORIZONTAL, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "scrollBar"); + + /** + Destructor, destroying the scrollbar. + */ + ~wxScrollBar(); + + /** + Scrollbar creation function called by the scrollbar constructor. + See wxScrollBar() for details. + */ + bool Create(wxWindow* parent, wxWindowID id, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxSB_HORIZONTAL, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "scrollBar"); + + /** + Returns the page size of the scrollbar. This is the number of scroll units + that will be scrolled when the user pages up or down. Often it is the + same as the thumb size. + + @see SetScrollbar() + */ + int GetPageSize() const; + + /** + Returns the length of the scrollbar. + + @see SetScrollbar() + */ + int GetRange() const; + + /** + Returns the current position of the scrollbar thumb. + + @see SetThumbPosition() + */ + int GetThumbPosition() const; + + /** + Returns the thumb or 'view' size. + + @see SetScrollbar() + */ + int GetThumbSize() const; + + /** + Sets the scrollbar properties. + + @param position + The position of the scrollbar in scroll units. + @param thumbSize + The size of the thumb, or visible portion of the scrollbar, in scroll units. + @param range + The maximum position of the scrollbar. + @param pageSize + The size of the page size in scroll units. This is the number of units + the scrollbar will scroll when it is paged up or down. Often it is the same + as + the thumb size. + @param refresh + @true to redraw the scrollbar, @false otherwise. + + @remarks Let's say you wish to display 50 lines of text, using the same + font. The window is sized so that you can only see 16 + lines at a time. + */ + virtual void SetScrollbar(int position, int thumbSize, int range, + int pageSize, + bool refresh = true); + + /** + Sets the position of the scrollbar. + + @param viewStart + The position of the scrollbar thumb. + + @see GetThumbPosition() + */ + void SetThumbPosition(int viewStart); +}; + diff --git a/interface/wx/scrolwin.h b/interface/wx/scrolwin.h new file mode 100644 index 0000000000..b05bc233fc --- /dev/null +++ b/interface/wx/scrolwin.h @@ -0,0 +1,423 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: scrolwin.h +// Purpose: interface of wxScrolled template +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @wxheader{scrolwin.h} + + The wxScrolled class manages scrolling for its client area, transforming + the coordinates according to the scrollbar positions, and setting the + scroll positions, thumb sizes and ranges according to the area in view. + + There are two commonly used (but not the only possible!) specializations of + this class: + + - ::wxScrolledWindow, aka wxScrolled, is equivalent to + ::wxScrolledWindow from earlier versions. Derived from wxPanel, it shares + wxPanel's behaviour with regard to TAB traversal and focus handling. Use + this if the scrolled window will have child controls. + + - ::wxScrolledCanvas, aka wxScrolled, derives from wxWindow and + so doesn't handle children specially. This is suitable e.g. for + implementating scrollable controls such as tree or list controls. + + Starting from version 2.4 of wxWidgets, there are several ways to use a + ::wxScrolledWindow (and now wxScrolled). In particular, there are + three ways to set the size of the scrolling area: + + One way is to set the scrollbars directly using a call to SetScrollbars(). + This is the way it used to be in any previous version of wxWidgets and it + will be kept for backwards compatibility. + + An additional method of manual control, which requires a little less + computation of your own, is to set the total size of the scrolling area by + calling either wxWindow::SetVirtualSize(), or wxWindow::FitInside(), and + setting the scrolling increments for it by calling SetScrollRate(). + Scrolling in some orientation is enabled by setting a non-zero increment + for it. + + The most automatic and newest way is to simply let sizers determine the + scrolling area. This is now the default when you set an interior sizer into + a wxScrolled with wxWindow::SetSizer(). The scrolling area will be + set to the size requested by the sizer and the scrollbars will be assigned + for each orientation according to the need for them and the scrolling + increment set by SetScrollRate(). As above, scrolling is only enabled in + orientations with a non-zero increment. You can influence the minimum size + of the scrolled area controlled by a sizer by calling + wxWindow::SetVirtualSizeHints(). (Calling SetScrollbars() has analogous + effects in wxWidgets 2.4 -- in later versions it may not continue to + override the sizer.) + + Note that if maximum size hints are still supported by + wxWindow::SetVirtualSizeHints(), use them at your own dire risk. They may + or may not have been removed for 2.4, but it really only makes sense to set + minimum size hints here. We should probably replace + wxWindow::SetVirtualSizeHints() with wxWindow::SetMinVirtualSize() or + similar and remove it entirely in future. + + As with all windows, an application can draw onto a wxScrolled using a + @ref overview_dc "device context". + + You have the option of handling the OnPaint handler or overriding the + wxScrolled::OnDraw() function, which is passed a pre-scrolled device + context (prepared by wxScrolled::DoPrepareDC()). + + If you don't wish to calculate your own scrolling, you must call + DoPrepareDC() when not drawing from within OnDraw(), to set the device + origin for the device context according to the current scroll position. + + A wxScrolled will normally scroll itself and therefore its child windows + as well. It might however be desired to scroll a different window than + itself: e.g. when designing a spreadsheet, you will normally only have to + scroll the (usually white) cell area, whereas the (usually grey) label area + will scroll very differently. For this special purpose, you can call + SetTargetWindow() which means that pressing the scrollbars will scroll a + different window. + + Note that the underlying system knows nothing about scrolling coordinates, + so that all system functions (mouse events, expose events, refresh calls + etc) as well as the position of subwindows are relative to the "physical" + origin of the scrolled window. If the user insert a child window at + position (10,10) and scrolls the window down 100 pixels (moving the child + window out of the visible area), the child window will report a position + of (10,-90). + + @beginStyleTable + @style{wxRETAINED} + Uses a backing pixmap to speed refreshes. Motif only. + @endStyleTable + + @remarks + Use wxScrolled for applications where the user scrolls by a fixed amount, + and where a 'page' can be interpreted to be the current visible portion of + the window. For more sophisticated applications, use the wxScrolled + implementation as a guide to build your own scroll behaviour or use + wxVScrolledWindow or its variants. + + @since The wxScrolled template exists since version 2.9.0. In older versions, + only ::wxScrolledWindow (equivalent of wxScrolled) was + available. + + @library{wxcore} + @category{miscwnd} + + @see wxScrollBar, wxClientDC, wxPaintDC, + wxVScrolledWindow, wxHScrolledWindow, wxHVScrolledWindow, +*/ +template +class wxScrolled : public T +{ +public: + /// Default constructor. + wxScrolled(); + + /** + Constructor. + + @param parent + Parent window. + @param id + Window identifier. The value @c wxID_ANY indicates a default value. + @param pos + Window position. If a position of @c wxDefaultPosition is specified + then a default position is chosen. + @param size + Window size. If a size of @c wxDefaultSize is specified then the + window is sized appropriately. + @param style + Window style. See wxScrolled. + @param name + Window name. + + @remarks The window is initially created without visible scrollbars. + Call SetScrollbars() to specify how big the virtual window + size should be. + */ + wxScrolled(wxWindow* parent, wxWindowID id = -1, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxHSCROLL | wxVSCROLL, + const wxString& name = "scrolledWindow"); + + + /** + Translates the logical coordinates to the device ones. For example, if + a window is scrolled 10 pixels to the bottom, the device coordinates of + the origin are (0, 0) (as always), but the logical coordinates are (0, + 10) and so the call to CalcScrolledPosition(0, 10, xx, yy) will return + 0 in yy. + + @see CalcUnscrolledPosition() + */ + void CalcScrolledPosition(int x, int y, int* xx, int* yy) const; + + /** + Translates the device coordinates to the logical ones. For example, if + a window is scrolled 10 pixels to the bottom, the device coordinates of + the origin are (0, 0) (as always), but the logical coordinates are (0, + 10) and so the call to CalcUnscrolledPosition(0, 0, xx, yy) will return + 10 in yy. + + @see CalcScrolledPosition() + */ + void CalcUnscrolledPosition(int x, int y, int* xx, int* yy) const; + + /** + Creates the window for two-step construction. Derived classes + should call or replace this function. See wxScrolled::wxScrolled() + for details. + */ + bool Create(wxWindow* parent, wxWindowID id = -1, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxHSCROLL | wxVSCROLL, + const wxString& name = "scrolledWindow"); + + /** + Call this function to prepare the device context for drawing a scrolled + image. + + It sets the device origin according to the current scroll position. + DoPrepareDC() is called automatically within the default OnPaint() + event handler, so your OnDraw() override will be passed a + 'pre-scrolled' device context. However, if you wish to draw from + outside of OnDraw() (via OnPaint()), or you wish to implement OnPaint() + yourself, you must call this function yourself. + + For example: + @code + void MyWindow::OnEvent(wxMouseEvent& event) + { + wxClientDC dc(this); + DoPrepareDC(dc); + + dc.SetPen(*wxBLACK_PEN); + float x, y; + event.Position(&x, &y); + if (xpos > -1 && ypos > -1 && event.Dragging()) + { + dc.DrawLine(xpos, ypos, x, y); + } + xpos = x; + ypos = y; + } + @endcode + + */ + void DoPrepareDC(wxDC& dc); + + /** + Enable or disable physical scrolling in the given direction. Physical + scrolling is the physical transfer of bits up or down the + screen when a scroll event occurs. If the application scrolls by a + variable amount (e.g. if there are different font sizes) then physical + scrolling will not work, and you should switch it off. Note that you + will have to reposition child windows yourself, if physical scrolling + is disabled. + + @param xScrolling + If @true, enables physical scrolling in the x direction. + @param yScrolling + If @true, enables physical scrolling in the y direction. + + @remarks Physical scrolling may not be available on all platforms. Where + it is available, it is enabled by default. + */ + void EnableScrolling(bool xScrolling, bool yScrolling); + + /** + Get the number of pixels per scroll unit (line), in each direction, as + set by SetScrollbars(). A value of zero indicates no scrolling in that + direction. + + @param xUnit + Receives the number of pixels per horizontal unit. + @param yUnit + Receives the number of pixels per vertical unit. + + @see SetScrollbars(), GetVirtualSize() + */ + void GetScrollPixelsPerUnit(int* xUnit, int* yUnit) const; + + /** + Get the position at which the visible portion of the window starts. + + @param x + Receives the first visible x position in scroll units. + @param y + Receives the first visible y position in scroll units. + + @remarks If either of the scrollbars is not at the home position, x + and/or y will be greater than zero. Combined with + wxWindow::GetClientSize(), the application can use this + function to efficiently redraw only the visible portion + of the window. The positions are in logical scroll + units, not pixels, so to convert to pixels you will + have to multiply by the number of pixels per scroll + increment. + + @see SetScrollbars() + */ + void GetViewStart(int* x, int* y) const; + + /** + Gets the size in device units of the scrollable window area (as + opposed to the client size, which is the area of the window currently + visible). + + @param x + Receives the length of the scrollable window, in pixels. + @param y + Receives the height of the scrollable window, in pixels. + + @remarks Use wxDC::DeviceToLogicalX() and wxDC::DeviceToLogicalY() to + translate these units to logical units. + + @see SetScrollbars(), GetScrollPixelsPerUnit() + */ + void GetVirtualSize(int* x, int* y) const; + + /** + Motif only: @true if the window has a backing bitmap. + */ + bool IsRetained() const; + + /** + Called by the default paint event handler to allow the application to + define painting behaviour without having to worry about calling + DoPrepareDC(). + + Instead of overriding this function you may also just process the paint + event in the derived class as usual, but then you will have to call + DoPrepareDC() yourself. + */ + virtual void OnDraw(wxDC& dc); + + /** + This function is for backwards compatibility only and simply calls + DoPrepareDC() now. Notice that it is not called by the default paint + event handle (DoPrepareDC() is), so overriding this method in your + derived class is useless. + */ + void PrepareDC(wxDC& dc); + + /** + Scrolls a window so the view start is at the given point. + + @param x + The x position to scroll to, in scroll units. + @param y + The y position to scroll to, in scroll units. + + @remarks The positions are in scroll units, not pixels, so to convert to + pixels you will have to multiply by the number of + pixels per scroll increment. If either parameter is -1, + that position will be ignored (no change in that + direction). + + @see SetScrollbars(), GetScrollPixelsPerUnit() + */ + void Scroll(int x, int y); + + /** + Set the horizontal and vertical scrolling increment only. See the + pixelsPerUnit parameter in SetScrollbars(). + */ + void SetScrollRate(int xstep, int ystep); + + /** + Sets up vertical and/or horizontal scrollbars. + + The first pair of parameters give the number of pixels per 'scroll + step', i.e. amount moved when the up or down scroll arrows are pressed. + The second pair gives the length of scrollbar in scroll steps, which + sets the size of the virtual window. + + @a xPos and @a yPos optionally specify a position to scroll to + immediately. + + For example, the following gives a window horizontal and vertical + scrollbars with 20 pixels per scroll step, and a size of 50 steps (1000 + pixels) in each direction: + @code + window->SetScrollbars(20, 20, 50, 50); + @endcode + + wxScrolled manages the page size itself, using the current client + window size as the page size. + + Note that for more sophisticated scrolling applications, for example + where scroll steps may be variable according to the position in the + document, it will be necessary to derive a new class from wxWindow, + overriding OnSize() and adjusting the scrollbars appropriately. + + @param pixelsPerUnitX + Pixels per scroll unit in the horizontal direction. + @param pixelsPerUnitY + Pixels per scroll unit in the vertical direction. + @param noUnitsX + Number of units in the horizontal direction. + @param noUnitsY + Number of units in the vertical direction. + @param xPos + Position to initialize the scrollbars in the horizontal direction, + in scroll units. + @param yPos + Position to initialize the scrollbars in the vertical direction, in + scroll units. + @param noRefresh + Will not refresh window if @true. + + @see wxWindow::SetVirtualSize() + */ + void SetScrollbars(int pixelsPerUnitX, int pixelsPerUnitY, + int noUnitsX, + int noUnitsY, + int xPos = 0, + int yPos = 0, + bool noRefresh = false); + + /** + Call this function to tell wxScrolled to perform the actual + scrolling on a different window (and not on itself). + */ + void SetTargetWindow(wxWindow* window); +}; + + +/** + Scrolled window derived from wxPanel. + + See wxScrolled for detailed description. + + @note Note that because this class derives from wxPanel, it shares its + behavior with regard to TAB traversal and focus handling (in + particular, it forwards focus to its children). If you don't want + this behaviour, use ::wxScrolledCanvas instead. + + @note ::wxScrolledWindow is an alias for wxScrolled since version + 2.9.0. In older versions, it was a standalone class. + + @library{wxcore} + @category{miscwnd} + + @see wxScrolled, ::wxScrolledCanvas +*/ +typedef wxScrolled wxScrolledWindow; + +/** + Alias for wxScrolled. Scrolled window that doesn't have children + and so doesn't need or want special handling of TAB traversal. + + @since 2.9.0 + + @library{wxcore} + @category{miscwnd} + + @see wxScrolled, ::wxScrolledWindow +*/ +typedef wxScrolled wxScrolledCanvas; diff --git a/interface/wx/settings.h b/interface/wx/settings.h new file mode 100644 index 0000000000..83fff83f18 --- /dev/null +++ b/interface/wx/settings.h @@ -0,0 +1,406 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: settings.h +// Purpose: interface of wxSystemSettings +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxSystemSettings + @wxheader{settings.h} + + wxSystemSettings allows the application to ask for details about + the system. This can include settings such as standard colours, fonts, + and user interface element sizes. + + @library{wxcore} + @category{misc} + + @see wxFont, wxColour +*/ +class wxSystemSettings : public wxObject +{ +public: + /** + Default constructor. You don't need to create an instance of wxSystemSettings + since all of its functions are static. + */ + wxSystemSettings(); + + /** + Returns a system colour. + @a index can be one of: + + @b wxSYS_COLOUR_SCROLLBAR + + The scrollbar grey area. + + @b wxSYS_COLOUR_BACKGROUND + + The desktop colour. + + @b wxSYS_COLOUR_ACTIVECAPTION + + Active window caption. + + @b wxSYS_COLOUR_INACTIVECAPTION + + Inactive window caption. + + @b wxSYS_COLOUR_MENU + + Menu background. + + @b wxSYS_COLOUR_WINDOW + + Window background. + + @b wxSYS_COLOUR_WINDOWFRAME + + Window frame. + + @b wxSYS_COLOUR_MENUTEXT + + Menu text. + + @b wxSYS_COLOUR_WINDOWTEXT + + Text in windows. + + @b wxSYS_COLOUR_CAPTIONTEXT + + Text in caption, size box and scrollbar arrow box. + + @b wxSYS_COLOUR_ACTIVEBORDER + + Active window border. + + @b wxSYS_COLOUR_INACTIVEBORDER + + Inactive window border. + + @b wxSYS_COLOUR_APPWORKSPACE + + Background colour MDI applications. + + @b wxSYS_COLOUR_HIGHLIGHT + + Item(s) selected in a control. + + @b wxSYS_COLOUR_HIGHLIGHTTEXT + + Text of item(s) selected in a control. + + @b wxSYS_COLOUR_BTNFACE + + Face shading on push buttons. + + @b wxSYS_COLOUR_BTNSHADOW + + Edge shading on push buttons. + + @b wxSYS_COLOUR_GRAYTEXT + + Greyed (disabled) text. + + @b wxSYS_COLOUR_BTNTEXT + + Text on push buttons. + + @b wxSYS_COLOUR_INACTIVECAPTIONTEXT + + Colour of text in active captions. + + @b wxSYS_COLOUR_BTNHIGHLIGHT + + Highlight colour for buttons (same as wxSYS_COLOUR_3DHILIGHT). + + @b wxSYS_COLOUR_3DDKSHADOW + + Dark shadow for three-dimensional display elements. + + @b wxSYS_COLOUR_3DLIGHT + + Light colour for three-dimensional display elements. + + @b wxSYS_COLOUR_INFOTEXT + + Text colour for tooltip controls. + + @b wxSYS_COLOUR_INFOBK + + Background colour for tooltip controls. + + @b wxSYS_COLOUR_DESKTOP + + Same as wxSYS_COLOUR_BACKGROUND. + + @b wxSYS_COLOUR_3DFACE + + Same as wxSYS_COLOUR_BTNFACE. + + @b wxSYS_COLOUR_3DSHADOW + + Same as wxSYS_COLOUR_BTNSHADOW. + + @b wxSYS_COLOUR_3DHIGHLIGHT + + Same as wxSYS_COLOUR_BTNHIGHLIGHT. + + @b wxSYS_COLOUR_3DHILIGHT + + Same as wxSYS_COLOUR_BTNHIGHLIGHT. + + @b wxSYS_COLOUR_BTNHILIGHT + + Same as wxSYS_COLOUR_BTNHIGHLIGHT. + */ + static wxColour GetColour(wxSystemColour index); + + /** + Returns a system font. + @a index can be one of: + + @b wxSYS_OEM_FIXED_FONT + + Original equipment manufacturer dependent fixed-pitch font. + + @b wxSYS_ANSI_FIXED_FONT + + Windows fixed-pitch font. + + @b wxSYS_ANSI_VAR_FONT + + Windows variable-pitch (proportional) font. + + @b wxSYS_SYSTEM_FONT + + System font. + + @b wxSYS_DEVICE_DEFAULT_FONT + + Device-dependent font (Windows NT only). + + @b wxSYS_DEFAULT_GUI_FONT + + Default font for user interface + objects such as menus and dialog boxes. Note that with modern GUIs nothing + guarantees that the same font is used for all GUI elements, so some controls + might use a different font by default. + */ + static wxFont GetFont(wxSystemFont index); + + /** + Returns the value of a system metric, or -1 if the metric is not supported on + the current system. + The value of @a win determines if the metric returned is a global value or + a wxWindow based value, in which case it might determine the widget, the + display the window is on, or something similar. The window given should be as + close to the + metric as possible (e.g a wxTopLevelWindow in case of the wxSYS_CAPTION_Y + metric). + @a index can be one of: + + @b wxSYS_MOUSE_BUTTONS + + Number of buttons on mouse, or zero if no mouse was installed. + + @b wxSYS_BORDER_X + + Width of single border. + + @b wxSYS_BORDER_Y + + Height of single border. + + @b wxSYS_CURSOR_X + + Width of cursor. + + @b wxSYS_CURSOR_Y + + Height of cursor. + + @b wxSYS_DCLICK_X + + Width in pixels of rectangle within which two successive mouse + clicks must fall to generate a double-click. + + @b wxSYS_DCLICK_Y + + Height in pixels of rectangle within which two successive mouse + clicks must fall to generate a double-click. + + @b wxSYS_DCLICK_MSEC + + Maximal time, in milliseconds, which may + pass between subsequent clicks for a double click to be generated. + + @b wxSYS_DRAG_X + + Width in pixels of a rectangle centered on a drag point + to allow for limited movement of the mouse pointer before a drag operation + begins. + + @b wxSYS_DRAG_Y + + Height in pixels of a rectangle centered on a drag point + to allow for limited movement of the mouse pointer before a drag operation + begins. + + @b wxSYS_EDGE_X + + Width of a 3D border, in pixels. + + @b wxSYS_EDGE_Y + + Height of a 3D border, in pixels. + + @b wxSYS_HSCROLL_ARROW_X + + Width of arrow bitmap on horizontal scrollbar. + + @b wxSYS_HSCROLL_ARROW_Y + + Height of arrow bitmap on horizontal scrollbar. + + @b wxSYS_HTHUMB_X + + Width of horizontal scrollbar thumb. + + @b wxSYS_ICON_X + + The default width of an icon. + + @b wxSYS_ICON_Y + + The default height of an icon. + + @b wxSYS_ICONSPACING_X + + Width of a grid cell for items in large icon view, + in pixels. Each item fits into a rectangle of this size when arranged. + + @b wxSYS_ICONSPACING_Y + + Height of a grid cell for items in large icon view, + in pixels. Each item fits into a rectangle of this size when arranged. + + @b wxSYS_WINDOWMIN_X + + Minimum width of a window. + + @b wxSYS_WINDOWMIN_Y + + Minimum height of a window. + + @b wxSYS_SCREEN_X + + Width of the screen in pixels. + + @b wxSYS_SCREEN_Y + + Height of the screen in pixels. + + @b wxSYS_FRAMESIZE_X + + Width of the window frame for a wxTHICK_FRAME window. + + @b wxSYS_FRAMESIZE_Y + + Height of the window frame for a wxTHICK_FRAME window. + + @b wxSYS_SMALLICON_X + + Recommended width of a small icon (in window captions, and small icon view). + + @b wxSYS_SMALLICON_Y + + Recommended height of a small icon (in window captions, and small icon view). + + @b wxSYS_HSCROLL_Y + + Height of horizontal scrollbar in pixels. + + @b wxSYS_VSCROLL_X + + Width of vertical scrollbar in pixels. + + @b wxSYS_VSCROLL_ARROW_X + + Width of arrow bitmap on a vertical scrollbar. + + @b wxSYS_VSCROLL_ARROW_Y + + Height of arrow bitmap on a vertical scrollbar. + + @b wxSYS_VTHUMB_Y + + Height of vertical scrollbar thumb. + + @b wxSYS_CAPTION_Y + + Height of normal caption area. + + @b wxSYS_MENU_Y + + Height of single-line menu bar. + + @b wxSYS_NETWORK_PRESENT + + 1 if there is a network present, 0 otherwise. + + @b wxSYS_PENWINDOWS_PRESENT + + 1 if PenWindows is installed, 0 otherwise. + + @b wxSYS_SHOW_SOUNDS + + Non-zero if the user requires an application to present information visually in + situations + where it would otherwise present the information only in audible form; zero + otherwise. + + @b wxSYS_SWAP_BUTTONS + + Non-zero if the meanings of the left and right mouse buttons are swapped; zero + otherwise. + + @a win is a pointer to the window for which the metric is requested. + Specifying the @a win parameter is encouraged, because some metrics on some + ports are not supported without one, + or they might be capable of reporting better values if given one. If a window + does not make sense for a metric, + one should still be given, as for example it might determine which displays + cursor width is requested with + wxSYS_CURSOR_X. + */ + static int GetMetric(wxSystemMetric index, wxWindow* win = NULL); + + /** + Returns the screen type. The return value is one of: + + @b wxSYS_SCREEN_NONE + + Undefined screen type + + @b wxSYS_SCREEN_TINY + + Tiny screen, less than 320x240 + + @b wxSYS_SCREEN_PDA + + PDA screen, 320x240 or more but less than 640x480 + + @b wxSYS_SCREEN_SMALL + + Small screen, 640x480 or more but less than 800x600 + + @b wxSYS_SCREEN_DESKTOP + + Desktop screen, 800x600 or more + */ + static wxSystemScreenType GetScreenType(); +}; + diff --git a/interface/wx/sizer.h b/interface/wx/sizer.h new file mode 100644 index 0000000000..bba558dd4d --- /dev/null +++ b/interface/wx/sizer.h @@ -0,0 +1,1683 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: sizer.h +// Purpose: interface of wxStdDialogButtonSizer +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxStdDialogButtonSizer + @wxheader{sizer.h} + + This class creates button layouts which conform to the standard button spacing + and ordering defined by the platform + or toolkit's user interface guidelines (if such things exist). By using this + class, you can ensure that all your + standard dialogs look correct on all major platforms. Currently it conforms to + the Windows, GTK+ and Mac OS X + human interface guidelines. + + When there aren't interface guidelines defined for a particular platform or + toolkit, wxStdDialogButtonSizer reverts + to the Windows implementation. + + To use this class, first add buttons to the sizer by calling AddButton (or + SetAffirmativeButton, SetNegativeButton, + or SetCancelButton) and then call Realize in order to create the actual button + layout used. Other than these special + operations, this sizer works like any other sizer. + + If you add a button with wxID_SAVE, on Mac OS X the button will be renamed to + "Save" and + the wxID_NO button will be renamed to "Don't Save" in accordance with the Mac + OS X Human Interface Guidelines. + + @library{wxcore} + @category{winlayout} + + @see wxSizer, @ref overview_sizer "Sizer Overview", + wxDialog::CreateButtonSizer +*/ +class wxStdDialogButtonSizer : public wxBoxSizer +{ +public: + /** + Constructor for a wxStdDialogButtonSizer. + */ + wxStdDialogButtonSizer(); + + /** + Adds a button to the wxStdDialogButtonSizer. The @a button must have + one of the following identifiers: + wxID_OK + wxID_YES + wxID_SAVE + wxID_APPLY + wxID_CLOSE + wxID_NO + wxID_CANCEL + wxID_HELP + wxID_CONTEXT_HELP + */ + void AddButton(wxButton* button); + + /** + Rearranges the buttons and applies proper spacing between buttons to make them + match the platform or toolkit's interface guidelines. + */ + void Realize(); + + /** + Sets the affirmative button for the sizer. This allows you to use identifiers + other than the standard identifiers outlined above. + */ + void SetAffirmativeButton(wxButton* button); + + /** + Sets the cancel button for the sizer. This allows you to use identifiers other + than the standard identifiers outlined above. + */ + void SetCancelButton(wxButton* button); + + /** + Sets the negative button for the sizer. This allows you to use identifiers + other than the standard identifiers outlined above. + */ + void SetNegativeButton(wxButton* button); +}; + + + +/** + @class wxSizerItem + @wxheader{sizer.h} + + The wxSizerItem class is used to track the position, size and other + attributes of each item managed by a wxSizer. It is not usually necessary + to use this class because the sizer elements can also be identified by + their positions or window or sizer pointers but sometimes it may be more + convenient to use it directly. + + @library{wxcore} + @category{winlayout} +*/ +class wxSizerItem : public wxObject +{ +public: + //@{ + /** + Construct a sizer item for tracking a subsizer. + */ + wxSizerItem(int width, int height, int proportion, int flag, + int border, wxObject* userData); + wxSizerItem(wxWindow* window, const wxSizerFlags& flags); + wxSizerItem(wxWindow* window, int proportion, int flag, + int border, + wxObject* userData); + wxSizerItem(wxSizer* window, const wxSizerFlags& flags); + wxSizerItem(wxSizer* sizer, int proportion, int flag, + int border, + wxObject* userData); + //@} + + /** + Deletes the user data and subsizer, if any. + */ + ~wxSizerItem(); + + /** + Calculates the minimum desired size for the item, including any space + needed by borders. + */ + wxSize CalcMin(); + + /** + Destroy the window or the windows in a subsizer, depending on the type + of item. + */ + void DeleteWindows(); + + /** + Enable deleting the SizerItem without destroying the contained sizer. + */ + void DetachSizer(); + + /** + Return the border attribute. + */ + int GetBorder() const; + + /** + Return the flags attribute. + + See @ref wxsizer_flags "wxSizer flags list" for details. + */ + int GetFlag() const; + + /** + Return the numeric id of wxSizerItem, or @c wxID_NONE if the id has + not been set. + */ + int GetId() const; + + /** + Get the minimum size needed for the item. + */ + wxSize GetMinSize() const; + + /** + Sets the minimum size to be allocated for this item. + + If this item is a window, the @a size is also passed to + wxWindow::SetMinSize(). + */ + void SetMinSize(const wxSize& size); + + /** + @overload + */ + void SetMinSize(int x, int y); + + /** + What is the current position of the item, as set in the last Layout. + */ + wxPoint GetPosition() const; + + /** + Get the proportion item attribute. + */ + int GetProportion() const; + + /** + Get the ration item attribute. + */ + float GetRatio() const; + + /** + Get the rectangle of the item on the parent window, excluding borders. + */ + wxRect GetRect(); + + /** + Get the current size of the item, as set in the last Layout. + */ + wxSize GetSize() const; + + /** + If this item is tracking a sizer, return it. @NULL otherwise. + */ + wxSizer* GetSizer() const; + + /** + If this item is tracking a spacer, return its size. + */ + const wxSize GetSpacer() const; + + /** + Get the userData item attribute. + */ + wxObject* GetUserData() const; + + /** + If this item is tracking a window then return it. @NULL otherwise. + */ + wxWindow* GetWindow() const; + + /** + Returns @true if this item is a window or a spacer and it is shown or + if this item is a sizer and not all of its elements are hidden. + + In other words, for sizer items, all of the child elements must be + hidden for the sizer itself to be considered hidden. + + As an exception, if the @c wxRESERVE_SPACE_EVEN_IF_HIDDEN flag was + used for this sizer item, then IsShown() always returns @true for it + (see wxSizerFlags::ReserveSpaceEvenIfHidden()). + */ + bool IsShown() const; + + /** + Is this item a sizer? + */ + bool IsSizer() const; + + /** + Is this item a spacer? + */ + bool IsSpacer() const; + + /** + Is this item a window? + */ + bool IsWindow() const; + + /** + Set the border item attribute. + */ + void SetBorder(int border); + + /** + Set the position and size of the space allocated to the sizer, and + adjust the position and size of the item to be within that space + taking alignment and borders into account. + */ + void SetDimension(const wxPoint& pos, const wxSize& size); + + /** + Set the flag item attribute. + */ + void SetFlag(int flag); + + /** + Sets the numeric id of the wxSizerItem to @e id. + */ + void SetId(int id); + + /** + + */ + void SetInitSize(int x, int y); + + /** + Set the proportion item attribute. + */ + void SetProportion(int proportion); + + //@{ + /** + Set the ratio item attribute. + */ + void SetRatio(int width, int height); + void SetRatio(wxSize size); + void SetRatio(float ratio); + //@} + + /** + Set the sizer tracked by this item. + */ + void SetSizer(wxSizer* sizer); + + /** + Set the size of the spacer tracked by this item. + */ + void SetSpacer(const wxSize& size); + + /** + Set the window to be tracked by thsi item. + */ + void SetWindow(wxWindow* window); + + /** + Set the show item attribute, which sizers use to determine if the item + is to be made part of the layout or not. If the item is tracking a + window then it is shown or hidden as needed. + */ + void Show(bool show); +}; + + + +/** + @class wxSizerFlags + @wxheader{sizer.h} + + Container for sizer items flags providing readable names for them. + + Normally, when you add an item to a sizer via wxSizer::Add, you have to + specify a lot of flags and parameters which can be unwieldy. This is where + wxSizerFlags comes in: it allows you to specify all parameters using the + named methods instead. For example, instead of + + @code + sizer->Add(ctrl, 0, wxEXPAND | wxALL, 10); + @endcode + + you can now write + + @code + sizer->Add(ctrl, wxSizerFlags().Expand().Border(10)); + @endcode + + This is more readable and also allows you to create wxSizerFlags objects which + can be reused for several sizer items. + + @code + wxSizerFlags flagsExpand(1); + flagsExpand.Expand().Border(10); + + sizer->Add(ctrl1, flagsExpand); + sizer->Add(ctrl2, flagsExpand); + @endcode + + Note that by specification, all methods of wxSizerFlags return the wxSizerFlags + object itself to allowing chaining multiple methods calls like in the examples + above. + + @library{wxcore} + @category{winlayout} + + @see wxSizer +*/ +class wxSizerFlags +{ +public: + /** + Creates the wxSizer with the proportion specified by @e proportion. + */ + wxSizerFlags(int proportion = 0); + + /** + Sets the alignment of this wxSizerFlags to @e align. + + This method replaces the previously set alignment with the specified + one. + + @see Top(), Left(), Right(), Bottom(), Centre() + + @param align Combination of @c wxALIGN_XXX bit masks. + */ + wxSizerFlags& Align(int align = 0); + + /** + Sets the wxSizerFlags to have a border of a number of pixels specified + by @a borderinpixels with the directions specified by @e direction. + */ + wxSizerFlags& Border(int direction, int borderinpixels); + + /** + Sets the wxSizerFlags to have a border with size as returned by + GetDefaultBorder(). + + @param direction Direction(s) to apply the border in. + */ + wxSizerFlags& Border(int direction = wxALL); + + /** + Aligns the object to the bottom, similar for @c Align(wxALIGN_BOTTOM). + + Unlike Align(), this method doesn't change the horizontal alignment of + the item. + */ + wxSizerFlags& Bottom(); + + /** + Sets the object of the wxSizerFlags to center itself in the area it is + given. + */ + wxSizerFlags& Center(); + + /** + Center() for people with the other dialect of English. + */ + wxSizerFlags& Centre(); + + /** + Sets the border in the given @a direction having twice the default + border size. + */ + wxSizerFlags& DoubleBorder(int direction = wxALL); + + /** + Sets the border in left and right directions having twice the default + border size. + */ + wxSizerFlags& DoubleHorzBorder(); + + /** + Sets the object of the wxSizerFlags to expand to fill as much area as + it can. + */ + wxSizerFlags& Expand(); + + /** + Set the @c wxFIXED_MINSIZE flag which indicates that the initial size + of the window should be also set as its minimal size. + */ + wxSizerFlags& FixedMinSize(); + + /** + Set the @c wxRESERVE_SPACE_EVEN_IF_HIDDEN flag. Normally wxSizers + don't allocate space for hidden windows or other items. This flag + overrides this behavior so that sufficient space is allocated for the + window even if it isn't visible. This makes it possible to dynamically + show and hide controls without resizing parent dialog, for example. + + @since 2.8.8 + */ + wxSizerFlags& ReserveSpaceEvenIfHidden(); + + /** + Returns the border used by default in Border() method. + */ + static int GetDefaultBorder(); + + /** + Aligns the object to the left, similar for @c Align(wxALIGN_LEFT). + + Unlike Align(), this method doesn't change the vertical alignment of + the item. + */ + wxSizerFlags& Left(); + + /** + Sets the proportion of this wxSizerFlags to @e proportion + */ + wxSizerFlags& Proportion(int proportion = 0); + + /** + Aligns the object to the right, similar for @c Align(wxALIGN_RIGHT). + + Unlike Align(), this method doesn't change the vertical alignment of + the item. + */ + wxSizerFlags& Right(); + + /** + Set the @c wx_SHAPED flag which indicates that the elements should + always keep the fixed width to height ratio equal to its original value. + */ + wxSizerFlags& Shaped(); + + /** + Aligns the object to the top, similar for @c Align(wxALIGN_TOP). + + Unlike Align(), this method doesn't change the horizontal alignment of + the item. + */ + wxSizerFlags& Top(); + + /** + Sets the border in the given @a direction having thrice the default + border size. + */ + wxSizerFlags& TripleBorder(int direction = wxALL); +}; + + + +/** + @class wxNotebookSizer + @wxheader{sizer.h} + + @deprecated + This class is deprecated and should not be used in new code! It is no + longer needed, wxNotebook control can be inserted + into any sizer class and its minimal size will be determined correctly. + + wxNotebookSizer is a specialized sizer to make sizers work in connection + with using notebooks. This sizer is different from any other sizer as you + must not add any children to it - instead, it queries the notebook class + itself. The only thing this sizer does is to determine the size of the + biggest page of the notebook and report an adjusted minimal size to a more + toplevel sizer. + + @library{wxbase} + @category{winlayout} + + @see wxSizer, wxNotebook, + @ref overview_sizer "Sizers overview" +*/ +class wxNotebookSizer : public wxSizer +{ +public: + /** + Constructor. It takes an associated notebook as its only parameter. + */ + wxNotebookSizer(wxNotebook* notebook); + + /** + Returns the notebook associated with the sizer. + */ + wxNotebook* GetNotebook(); +}; + + + +/** + @class wxFlexGridSizer + @wxheader{sizer.h} + + A flex grid sizer is a sizer which lays out its children in a two-dimensional + table with all table fields in one row having the same + height and all fields in one column having the same width, but all + rows or all columns are not necessarily the same height or width as in + the wxGridSizer. + + Since wxWidgets 2.5.0, wxFlexGridSizer can also size items equally in one + direction but unequally ("flexibly") in the other. If the sizer is only + flexible in one direction (this can be changed using + wxFlexGridSizer::SetFlexibleDirection), + it needs to be decided how the sizer should grow in the other ("non-flexible") + direction in order to fill the available space. The + wxFlexGridSizer::SetNonFlexibleGrowMode method + serves this purpose. + + @library{wxcore} + @category{winlayout} + + @see wxSizer, @ref overview_sizer "Sizer Overview" +*/ +class wxFlexGridSizer : public wxGridSizer +{ +public: + //@{ + /** + Constructor for a wxGridSizer. @a rows and @a cols determine the number of + columns and rows in the sizer - if either of the parameters is zero, it will be + calculated to form the total number of children in the sizer, thus making the + sizer grow dynamically. @a vgap and @a hgap define extra space between + all children. + */ + wxFlexGridSizer(int rows, int cols, int vgap, int hgap); + wxFlexGridSizer(int cols, int vgap = 0, int hgap = 0); + //@} + + /** + Specifies that column @a idx (starting from zero) should be grown if + there is extra space available to the sizer. + The @a proportion parameter has the same meaning as the stretch factor for + the sizers() except that if all proportions are 0, + then all columns are resized equally (instead of not being resized at all). + */ + void AddGrowableCol(size_t idx, int proportion = 0); + + /** + Specifies that row idx (starting from zero) should be grown if there + is extra space available to the sizer. + See AddGrowableCol() for the description + of @a proportion parameter. + */ + void AddGrowableRow(size_t idx, int proportion = 0); + + /** + Returns a wxOrientation value that specifies whether the sizer flexibly + resizes its columns, rows, or both (default). + + @return One of the following values: + + @see SetFlexibleDirection() + */ + int GetFlexibleDirection() const; + + /** + Returns the value that specifies how the sizer grows in the "non-flexible" + direction if there is one. + + @return One of the following values: + + @see SetFlexibleDirection(), + SetNonFlexibleGrowMode() + */ + int GetNonFlexibleGrowMode() const; + + /** + Specifies that column idx is no longer growable. + */ + void RemoveGrowableCol(size_t idx); + + /** + Specifies that row idx is no longer growable. + */ + void RemoveGrowableRow(size_t idx); + + /** + Specifies whether the sizer should flexibly resize its columns, rows, or + both. Argument @c direction can be @c wxVERTICAL, @c wxHORIZONTAL + or @c wxBOTH (which is the default value). Any other value is ignored. See + @ref GetFlexibleDirection() GetFlexibleDirection for the + explanation of these values. + Note that this method does not trigger relayout. + */ + void SetFlexibleDirection(int direction); + + /** + Specifies how the sizer should grow in the non-flexible direction if + there is one (so + SetFlexibleDirection() must have + been called previously). Argument @a mode can be one of those documented in + GetNonFlexibleGrowMode(), please + see there for their explanation. + Note that this method does not trigger relayout. + */ + void SetNonFlexibleGrowMode(wxFlexSizerGrowMode mode); +}; + + + +/** + @class wxSizer + @wxheader{sizer.h} + + wxSizer is the abstract base class used for laying out subwindows in a window. + You + cannot use wxSizer directly; instead, you will have to use one of the sizer + classes derived from it. Currently there are wxBoxSizer, + wxStaticBoxSizer, + wxGridSizer, + wxFlexGridSizer, + wxWrapSizer + and wxGridBagSizer. + + The layout algorithm used by sizers in wxWidgets is closely related to layout + in other GUI toolkits, such as Java's AWT, the GTK toolkit or the Qt toolkit. + It is + based upon the idea of the individual subwindows reporting their minimal + required + size and their ability to get stretched if the size of the parent window has + changed. + This will most often mean that the programmer does not set the original size of + a dialog in the beginning, rather the dialog will be assigned a sizer and this + sizer + will be queried about the recommended size. The sizer in turn will query its + children, which can be normal windows, empty space or other sizers, so that + a hierarchy of sizers can be constructed. Note that wxSizer does not derive + from wxWindow + and thus does not interfere with tab ordering and requires very little + resources compared + to a real window on screen. + + What makes sizers so well fitted for use in wxWidgets is the fact that every + control + reports its own minimal size and the algorithm can handle differences in font + sizes + or different window (dialog item) sizes on different platforms without + problems. If e.g. + the standard font as well as the overall design of Motif widgets requires more + space than + on Windows, the initial dialog size will automatically be bigger on Motif than + on Windows. + + Sizers may also be used to control the layout of custom drawn items on the + window. The Add(), Insert(), and Prepend() functions return a pointer to + the newly added wxSizerItem. Just add empty space of the desired size and + attributes, and then use the wxSizerItem::GetRect() method to determine + where the drawing operations should take place. + + Please notice that sizers, like child windows, are owned by the library and + will be deleted by it which implies that they must be allocated on the + heap. However if you create a sizer and do not add it to another sizer or + window, the library wouldn't be able to delete such an orphan sizer and in + this, and only this, case it should be deleted explicitly. + + @b wxPython note: If you wish to create a sizer class in wxPython you should + derive the class from @c wxPySizer in order to get Python-aware + capabilities for the various virtual methods. + + @anchor wxsizer_flags + @par wxSizer flags + The "flag" argument accepted by wxSizeItem constructors and other + functions, e.g. wxSizer::Add(), is OR-combination of the following flags. + Two main behaviours are defined using these flags. One is the border around + a window: the border parameter determines the border width whereas the + flags given here determine which side(s) of the item that the border will + be added. The other flags determine how the sizer item behaves when the + space allotted to the sizer changes, and is somewhat dependent on the + specific kind of sizer used. + @beginDefList + @itemdef{wxTOP
+ wxBOTTOM
+ wxLEFT
+ wxRIGHT
+ wxALL, + These flags are used to specify which side(s) of the sizer item + the border width will apply to.} + @itemdef{wxEXPAND, + The item will be expanded to fill the space assigned to the item.} + @itemdef{wxSHAPED, + The item will be expanded as much as possible while also + maintaining its aspect ratio.} + @itemdef{wxFIXED_MINSIZE, + Normally wxSizers will use GetAdjustedBestSize() to determine what + the minimal size of window items should be, and will use that size + to calculate the layout. This allows layouts to adjust when an + item changes and its best size becomes different. If you would + rather have a window item stay the size it started with then use + wxFIXED_MINSIZE.} + @itemdef{wxRESERVE_SPACE_EVEN_IF_HIDDEN, + Normally wxSizers don't allocate space for hidden windows or other + items. This flag overrides this behavior so that sufficient space + is allocated for the window even if it isn't visible. This makes + it possible to dynamically show and hide controls without resizing + parent dialog, for example. (Available since 2.8.8.) + } + @itemdef{wxALIGN_CENTER
+ wxALIGN_CENTRE
+ wxALIGN_LEFT
+ wxALIGN_RIGHT
+ wxALIGN_TOP
+ wxALIGN_BOTTOM
+ wxALIGN_CENTER_VERTICAL
+ wxALIGN_CENTRE_VERTICAL
+ wxALIGN_CENTER_HORIZONTAL
+ wxALIGN_CENTRE_HORIZONTAL, + The wxALIGN flags allow you to specify the alignment of the item + within the space allotted to it by the sizer, adjusted for the + border if any.} + @endDefList + + + @library{wxcore} + @category{winlayout} + + @see @ref overview_sizer "Sizer Overview" +*/ +class wxSizer : public wxObject +{ +public: + /** + The constructor. Note that wxSizer is an abstract base class and may not + be instantiated. + */ + wxSizer(); + + /** + The destructor. + */ + ~wxSizer(); + + /** + Appends a child to the sizer. + + wxSizer itself is an abstract class, but the parameters are equivalent + in the derived classes that you will instantiate to use it so they are + described here: + + @param window + The window to be added to the sizer. Its initial size (either set + explicitly by the user or calculated internally when using + wxDefaultSize) is interpreted as the minimal and in many cases also + the initial size. + @param flags + A wxSizerFlags object that enables you to specify most of the above + parameters more conveniently. + */ + wxSizerItem* Add(wxWindow* window, const wxSizerFlags& flags); + + /** + Appends a child to the sizer. + + wxSizer itself is an abstract class, but the parameters are equivalent + in the derived classes that you will instantiate to use it so they are + described here: + + @param window + The window to be added to the sizer. Its initial size (either set + explicitly by the user or calculated internally when using + wxDefaultSize) is interpreted as the minimal and in many cases also + the initial size. + @param proportion + Although the meaning of this parameter is undefined in wxSizer, it + is used in wxBoxSizer to indicate if a child of a sizer can change + its size in the main orientation of the wxBoxSizer - where 0 stands + for not changeable and a value of more than zero is interpreted + relative to the value of other children of the same wxBoxSizer. For + example, you might have a horizontal wxBoxSizer with three + children, two of which are supposed to change their size with the + sizer. Then the two stretchable windows would get a value of 1 each + to make them grow and shrink equally with the sizer's horizontal + dimension. + @param flag + OR-combination of flags affecting sizer's behavior. See + @ref wxsizer_flags "wxSizer flags list" for details. + @param border + Determines the border width, if the flag parameter is set to + include any border flag. + @param userData + Allows an extra object to be attached to the sizer item, for use in + derived classes when sizing information is more complex than the + proportion and flag will allow for. + */ + wxSizerItem* Add(wxWindow* window, int proportion = 0, + int flag = 0, + int border = 0, + wxObject* userData = NULL); + + /** + Appends a child to the sizer. + + wxSizer itself is an abstract class, but the parameters are equivalent + in the derived classes that you will instantiate to use it so they are + described here: + + @param sizer + The (child-)sizer to be added to the sizer. This allows placing a + child sizer in a sizer and thus to create hierarchies of sizers + (typically a vertical box as the top sizer and several horizontal + boxes on the level beneath). + @param flags + A wxSizerFlags object that enables you to specify most of the above + parameters more conveniently. + */ + wxSizerItem* Add(wxSizer* sizer, const wxSizerFlags& flags); + + /** + Appends a child to the sizer. + + wxSizer itself is an abstract class, but the parameters are equivalent + in the derived classes that you will instantiate to use it so they are + described here: + + @param sizer + The (child-)sizer to be added to the sizer. This allows placing a + child sizer in a sizer and thus to create hierarchies of sizers + (typically a vertical box as the top sizer and several horizontal + boxes on the level beneath). + @param proportion + Although the meaning of this parameter is undefined in wxSizer, it + is used in wxBoxSizer to indicate if a child of a sizer can change + its size in the main orientation of the wxBoxSizer - where 0 stands + for not changeable and a value of more than zero is interpreted + relative to the value of other children of the same wxBoxSizer. For + example, you might have a horizontal wxBoxSizer with three + children, two of which are supposed to change their size with the + sizer. Then the two stretchable windows would get a value of 1 each + to make them grow and shrink equally with the sizer's horizontal + dimension. + @param flag + OR-combination of flags affecting sizer's behavior. See + @ref wxsizer_flags "wxSizer flags list" for details. + @param border + Determines the border width, if the flag parameter is set to + include any border flag. + @param userData + Allows an extra object to be attached to the sizer item, for use in + derived classes when sizing information is more complex than the + proportion and flag will allow for. + */ + wxSizerItem* Add(wxSizer* sizer, int proportion = 0, + int flag = 0, + int border = 0, + wxObject* userData = NULL); + + /** + Appends a spacer child to the sizer. + + wxSizer itself is an abstract class, but the parameters are equivalent + in the derived classes that you will instantiate to use it so they are + described here. + + @a width and @a height specify the dimension of a spacer to be added to + the sizer. Adding spacers to sizers gives more flexibility in the + design of dialogs; imagine for example a horizontal box with two + buttons at the bottom of a dialog: you might want to insert a space + between the two buttons and make that space stretchable using the + proportion flag and the result will be that the left button will be + aligned with the left side of the dialog and the right button with the + right side - the space in between will shrink and grow with the dialog. + + @param width + Width of the spacer. + @param height + Height of the spacer. + @param proportion + Although the meaning of this parameter is undefined in wxSizer, it + is used in wxBoxSizer to indicate if a child of a sizer can change + its size in the main orientation of the wxBoxSizer - where 0 stands + for not changeable and a value of more than zero is interpreted + relative to the value of other children of the same wxBoxSizer. For + example, you might have a horizontal wxBoxSizer with three + children, two of which are supposed to change their size with the + sizer. Then the two stretchable windows would get a value of 1 each + to make them grow and shrink equally with the sizer's horizontal + dimension. + @param flag + OR-combination of flags affecting sizer's behavior. See + @ref wxsizer_flags "wxSizer flags list" for details. + @param border + Determines the border width, if the flag parameter is set to + include any border flag. + @param userData + Allows an extra object to be attached to the sizer item, for use in + derived classes when sizing information is more complex than the + proportion and flag will allow for. + */ + wxSizerItem* Add(int width, int height, int proportion = 0, + int flag = 0, + int border = 0, + wxObject* userData = NULL); + + /** + Adds non-stretchable space to the sizer. More readable way of calling + wxSizer::Add(size, size, 0). + */ + wxSizerItem* AddSpacer(int size); + + /** + Adds stretchable space to the sizer. More readable way of calling + wxSizer::Add(0, 0, prop). + */ + wxSizerItem* AddStretchSpacer(int prop = 1); + + /** + This method is abstract and has to be overwritten by any derived class. + Here, the sizer will do the actual calculation of its children's minimal sizes. + */ + wxSize CalcMin(); + + /** + Detaches all children from the sizer. If @a delete_windows is @true then + child windows will also be deleted. + */ + void Clear(bool delete_windows = false); + + /** + Computes client area size for @a window so that it matches the sizer's + minimal size. Unlike GetMinSize(), this method accounts for other + constraints imposed on @e window, namely display's size (returned size + will never be too large for the display) and maximum window size if + previously set by wxWindow::SetMaxSize(). The returned value is + suitable for passing to wxWindow::SetClientSize() or + wxWindow::SetMinClientSize(). + + @since 2.8.8 + + @see ComputeFittingWindowSize(), Fit() + */ + wxSize ComputeFittingClientSize(wxWindow* window); + + /** + Like ComputeFittingClientSize(), but converts the result into window + size. The returned value is suitable for passing to wxWindow::SetSize() + or wxWindow::SetMinSize(). + + @since 2.8.8 + + @see ComputeFittingClientSize(), Fit() + */ + wxSize ComputeFittingWindowSize(wxWindow* window); + + /** + Detach the child @a window from the sizer without destroying it. + + This method does not cause any layout or resizing to take place, call Layout() + to update the layout "on screen" after detaching a child from the sizer. + + Returns @true if the child item was found and detached, @false otherwise. + + @see Remove() + */ + bool Detach(wxWindow* window); + + /** + Detach the child @a sizer from the sizer without destroying it. + + This method does not cause any layout or resizing to take place, call Layout() + to update the layout "on screen" after detaching a child from the sizer. + + Returns @true if the child item was found and detached, @false otherwise. + + @see Remove() + */ + bool Detach(wxSizer* sizer); + + /** + Detach a item at position @a index from the sizer without destroying it. + + This method does not cause any layout or resizing to take place, call Layout() + to update the layout "on screen" after detaching a child from the sizer. + Returns @true if the child item was found and detached, @false otherwise. + + @see Remove() + */ + bool Detach(size_t index); + + /** + Tell the sizer to resize the @a window so that its client area matches the + sizer's minimal size + (ComputeFittingClientSize() is called + to determine it). + This is commonly done in the constructor of the window + itself, see sample in the description + of wxBoxSizer. Returns the new window size. + + @see ComputeFittingClientSize(), ComputeFittingWindowSize() + */ + wxSize Fit(wxWindow* window); + + /** + Tell the sizer to resize the virtual size of the @a window to match the sizer's + minimal size. This will not alter the on screen size of the window, but may + cause the addition/removal/alteration of scrollbars required to view the virtual + area in windows which manage it. + + @see wxScrolled::SetScrollbars(), SetVirtualSizeHints() + */ + void FitInside(wxWindow* window); + + /** + Returns the list of the items in this sizer. The elements of type-safe + wxList @a wxSizerItemList are pointers to objects of type + @ref wxSizerItem "wxSizerItem". + */ + wxSizerItemList& GetChildren(); + + /** + Returns the list of the items in this sizer. The elements of type-safe + wxList @a wxSizerItemList are pointers to objects of type + @ref wxSizerItem "wxSizerItem". + */ + const wxSizerItemList& GetChildren() const; + + /** + Returns the window this sizer is used in or @NULL if none. + */ + wxWindow* GetContainingWindow() const; + + /** + Finds wxSizerItem which holds the given @a window + Use parameter @a recursive to search in subsizers too. + Returns pointer to item or @NULL. + */ + wxSizerItem* GetItem(wxWindow* window, bool recursive = false); + + /** + Finds wxSizerItem which holds the given @a sizer + Use parameter @a recursive to search in subsizers too. + Returns pointer to item or @NULL. + */ + + wxSizerItem* GetItem(wxSizer* sizer, bool recursive = false); + /** + Finds wxSizerItem which is located in the sizer at position + @a index. + Use parameter @a recursive to search in subsizers too. + Returns pointer to item or @NULL. + */ + wxSizerItem* GetItem(size_t index); + + /** + Finds item of the sizer which has the given @e id. This @a id is not the + window id but the id of the wxSizerItem itself. This is mainly useful for + retrieving the sizers created from XRC resources. + Use parameter @a recursive to search in subsizers too. + Returns pointer to item or @NULL. + */ + wxSizerItem* GetItemById(int id, bool recursive = false); + + /** + Returns the minimal size of the sizer. This is either the combined minimal + size of all the children and their borders or the minimal size set by + SetMinSize(), depending on which is bigger. + Note that the returned value is client size, not window size. + In particular, if you use the value to set toplevel window's minimal or + actual size, use wxWindow::SetMinClientSize + or wxWindow::SetClientSize, not + wxWindow::SetMinSize + or wxWindow::SetSize. + */ + wxSize GetMinSize(); + + /** + Returns the current position of the sizer. + */ + wxPoint GetPosition(); + + /** + Returns the current size of the sizer. + */ + wxSize GetSize(); + + /** + Hides the child @a window. + + To make a sizer item disappear, use Hide() followed by Layout(). + + Use parameter @a recursive to hide elements found in subsizers. + Returns @true if the child item was found, @false otherwise. + + @see IsShown(), Show() + */ + bool Hide(wxWindow* window, bool recursive = false); + + /** + Hides the child @a sizer. + + To make a sizer item disappear, use Hide() followed by Layout(). + + Use parameter @a recursive to hide elements found in subsizers. + Returns @true if the child item was found, @false otherwise. + + @see IsShown(), Show() + */ + bool Hide(wxSizer* sizer, bool recursive = false); + + /** + Hides the item at position @a index. + + To make a sizer item disappear, use Hide() followed by Layout(). + + Use parameter @a recursive to hide elements found in subsizers. + Returns @true if the child item was found, @false otherwise. + + @see IsShown(), Show() + */ + bool Hide(size_t index); + + /** + Insert a child into the sizer before any existing item at + + See Add() for the meaning of the other parameters. + */ + wxSizerItem* Insert(size_t index, wxWindow* window, + const wxSizerFlags& flags); + + /** + Insert a child into the sizer before any existing item at + + See Add() for the meaning of the other parameters. + */ + wxSizerItem* Insert(size_t index, wxWindow* window, + int proportion = 0, + int flag = 0, + int border = 0, + wxObject* userData = NULL); + + /** + Insert a child into the sizer before any existing item at + + See Add() for the meaning of the other parameters. + */ + wxSizerItem* Insert(size_t index, wxSizer* sizer, + const wxSizerFlags& flags); + + /** + Insert a child into the sizer before any existing item at + + See Add() for the meaning of the other parameters. + */ + wxSizerItem* Insert(size_t index, wxSizer* sizer, + int proportion = 0, + int flag = 0, + int border = 0, + wxObject* userData = NULL); + + /** + Insert a child into the sizer before any existing item at + + See Add() for the meaning of the other parameters. + */ + wxSizerItem* Insert(size_t index, int width, int height, + int proportion = 0, + int flag = 0, + int border = 0, + wxObject* userData = NULL); + + /** + Inserts non-stretchable space to the sizer. More readable way of calling + wxSizer::Insert(size, size, 0). + */ + wxSizerItem* InsertSpacer(size_t index, int size); + + /** + Inserts stretchable space to the sizer. More readable way of calling + wxSizer::Insert(0, 0, prop). + */ + wxSizerItem* InsertStretchSpacer(size_t index, int prop = 1); + + /** + Returns @true if the @e window is shown. + + @see Hide(), Show(), wxSizerItem::IsShown() + */ + bool IsShown(wxWindow* window) const; + + /** + Returns @true if the @e sizer is shown. + + @see Hide(), Show(), wxSizerItem::IsShown() + */ + bool IsShown(wxSizer* sizer) const; + + /** + Returns @true if the item at @a index is shown. + + @see Hide(), Show(), wxSizerItem::IsShown() + */ + bool IsShown(size_t index) const; + + /** + Call this to force layout of the children anew, e.g. after having added a child + to or removed a child (window, other sizer or space) from the sizer while + keeping + the current dimension. + */ + void Layout(); + + /** + Same as Add(), but prepends the items to the beginning of the + list of items (windows, subsizers or spaces) owned by this sizer. + */ + wxSizerItem* Prepend(wxWindow* window, const wxSizerFlags& flags); + + /** + Same as Add(), but prepends the items to the beginning of the + list of items (windows, subsizers or spaces) owned by this sizer. + */ + wxSizerItem* Prepend(wxWindow* window, int proportion = 0, + int flag = 0, + int border = 0, + wxObject* userData = NULL); + + /** + Same as Add(), but prepends the items to the beginning of the + list of items (windows, subsizers or spaces) owned by this sizer. + */ + wxSizerItem* Prepend(wxSizer* sizer, + const wxSizerFlags& flags); + + /** + Same as Add(), but prepends the items to the beginning of the + list of items (windows, subsizers or spaces) owned by this sizer. + */ + wxSizerItem* Prepend(wxSizer* sizer, int proportion = 0, + int flag = 0, + int border = 0, + wxObject* userData = NULL); + + /** + Same as Add(), but prepends the items to the beginning of the + list of items (windows, subsizers or spaces) owned by this sizer. + */ + wxSizerItem* Prepend(int width, int height, + int proportion = 0, + int flag = 0, + int border = 0, + wxObject* userData = NULL); + + /** + Prepends non-stretchable space to the sizer. More readable way of + calling wxSizer::Prepend(size, size, 0). + */ + wxSizerItem* PrependSpacer(int size); + + /** + Prepends stretchable space to the sizer. More readable way of calling + wxSizer::Prepend(0, 0, prop). + */ + wxSizerItem* PrependStretchSpacer(int prop = 1); + + /** + This method is abstract and has to be overwritten by any derived class. + Here, the sizer will do the actual calculation of its children's + positions and sizes. + */ + void RecalcSizes(); + + /** + Removes a child window from the sizer, but does @b not destroy it + (because windows are owned by their parent window, not the sizer). + + @deprecated + The overload of this method taking a wxWindow* parameter + is deprecated as it does not destroy the window as would usually be + expected from Remove(). You should use Detach() in new code instead. + There is currently no wxSizer method that will both detach and destroy + a wxWindow item. + + @note This method does not cause any layout or resizing to take + place, call Layout() to update the layout "on screen" after + removing a child from the sizer. + + @return @true if the child item was found and removed, @false otherwise. + */ + bool Remove(wxWindow* window); + + /** + Removes a sizer child from the sizer and destroys it. + + @note This method does not cause any layout or resizing to take + place, call Layout() to update the layout "on screen" after + removing a child from the sizer. + + @param sizer The wxSizer to be removed. + + @return @true if the child item was found and removed, @false otherwise. + */ + bool Remove(wxSizer* sizer); + + /** + Removes a child from the sizer and destroys it if it is a sizer or a + spacer, but not if it is a window (because windows are owned by their + parent window, not the sizer). + + @note This method does not cause any layout or resizing to take + place, call Layout() to update the layout "on screen" after + removing a child from the sizer. + + @param index The position of the child in the sizer, e.g. 0 for the + first item. + + @return @true if the child item was found and removed, @false otherwise. + */ + bool Remove(size_t index); + + /** + Detaches the given @a oldwin from the sizer and + replaces it with the given @a newwin. The detached + child window is @b not deleted (because windows are + owned by their parent window, not the sizer). + + Use parameter @a recursive to search the given element recursively in subsizers. + + This method does not cause any layout or resizing to take place, + call Layout() to update the layout "on screen" after replacing a + child from the sizer. + + Returns @true if the child item was found and removed, @false otherwise. + */ + bool Replace(wxWindow* oldwin, wxWindow* newwin, + bool recursive = false); + + /** + Detaches the given @a oldsz from the sizer and + replaces it with the given @a newsz. The detached + child sizer is deleted. + + Use parameter @a recursive to search the given element recursively in subsizers. + + This method does not cause any layout or resizing to take place, + call Layout() to update the layout "on screen" after replacing a + child from the sizer. + + Returns @true if the child item was found and removed, @false otherwise. + */ + bool Replace(wxSizer* oldsz, wxSizer* newsz, + bool recursive = false); + + /** + Detaches the given item at position @a index from the sizer and + replaces it with the given wxSizerItem @a newitem. + + The detached child is deleted @b only if it is a sizer or a spacer + (but not if it is a wxWindow because windows are owned by their + parent window, not the sizer). + + This method does not cause any layout or resizing to take place, + call Layout() to update the layout "on screen" after replacing a + child from the sizer. + + Returns @true if the child item was found and removed, @false otherwise. + */ + bool Replace(size_t index, wxSizerItem* newitem); + + /** + Call this to force the sizer to take the given dimension and thus force + the items owned by the sizer to resize themselves according to the + rules defined by the parameter in the Add() and Prepend() methods. + */ + void SetDimension(int x, int y, int width, int height); + + /** + @overload + */ + void SetDimension(const wxPoint& pos, const wxSize& size); + + /** + Set an item's minimum size by window, sizer, or position. + + The item will be found recursively in the sizer's descendants. This + function enables an application to set the size of an item after + initial creation. + + @see wxSizerItem::SetMinSize() + */ + void SetItemMinSize(wxWindow* window, int width, int height); + + /** + Set an item's minimum size by window, sizer, or position. + + The item will be found recursively in the sizer's descendants. This + function enables an application to set the size of an item after + initial creation. + + @see wxSizerItem::SetMinSize() + */ + void SetItemMinSize(wxSizer* sizer, int width, int height); + + /** + Set an item's minimum size by window, sizer, or position. + + The item will be found recursively in the sizer's descendants. This + function enables an application to set the size of an item after + initial creation. + + @see wxSizerItem::SetMinSize() + */ + void SetItemMinSize(size_t index, int width, int height); + + /** + Call this to give the sizer a minimal size. Normally, the sizer will + calculate its minimal size based purely on how much space its children + need. After calling this method GetMinSize() will return either the + minimal size as requested by its children or the minimal size set here, + depending on which is bigger. + */ + void SetMinSize(const wxSize& size); + + /** + @overload + */ + void SetMinSize(int width, int height); + + /** + This method first calls Fit() and then + wxTopLevelWindow::SetSizeHints on the @e window + passed to it. This only makes sense when @a window is actually a + wxTopLevelWindow such as a wxFrame or a + wxDialog, since SetSizeHints only has any effect in these classes. + It does nothing in normal windows or controls. + This method is implicitly used by wxWindow::SetSizerAndFit + which is commonly invoked in the constructor of a toplevel window itself (see + the sample in the description of wxBoxSizer) if the + toplevel window is resizable. + */ + void SetSizeHints(wxWindow* window); + + /** + Tell the sizer to set the minimal size of the @a window virtual area to match + the sizer's + minimal size. For windows with managed scrollbars this will set them + appropriately. + + @see wxScrolled::SetScrollbars() + */ + void SetVirtualSizeHints(wxWindow* window); + + /** + Shows or hides the @a window. + To make a sizer item disappear or reappear, use Show() followed by Layout(). + + Use parameter @a recursive to show or hide elements found in subsizers. + + Returns @true if the child item was found, @false otherwise. + + @see Hide(), IsShown() + */ + bool Show(wxWindow* window, bool show = true, + bool recursive = false); + + /** + Shows or hides @a sizer. + To make a sizer item disappear or reappear, use Show() followed by Layout(). + + Use parameter @a recursive to show or hide elements found in subsizers. + + Returns @true if the child item was found, @false otherwise. + + @see Hide(), IsShown() + */ + bool Show(wxSizer* sizer, bool show = true, + bool recursive = false); + + /** + Shows the item at @a index. + To make a sizer item disappear or reappear, use Show() followed by Layout(). + + Returns @true if the child item was found, @false otherwise. + + @see Hide(), IsShown() + */ + bool Show(size_t index, bool show = true); +}; + + + +/** + @class wxGridSizer + @wxheader{sizer.h} + + A grid sizer is a sizer which lays out its children in a two-dimensional + table with all table fields having the same size, + i.e. the width of each field is the width of the widest child, + the height of each field is the height of the tallest child. + + @library{wxcore} + @category{winlayout} + + @see wxSizer, @ref overview_sizer "Sizer Overview" +*/ +class wxGridSizer : public wxSizer +{ +public: + //@{ + /** + Constructor for a wxGridSizer. @a rows and @a cols determine the number of + columns and rows in the sizer - if either of the parameters is zero, it will be + calculated to form the total number of children in the sizer, thus making the + sizer grow dynamically. @a vgap and @a hgap define extra space between + all children. + */ + wxGridSizer(int rows, int cols, int vgap, int hgap); + wxGridSizer(int cols, int vgap = 0, int hgap = 0); + //@} + + /** + Returns the number of columns in the sizer. + */ + int GetCols(); + + /** + Returns the horizontal gap (in pixels) between cells in the sizer. + */ + int GetHGap(); + + /** + Returns the number of rows in the sizer. + */ + int GetRows(); + + /** + Returns the vertical gap (in pixels) between the cells in the sizer. + */ + int GetVGap(); + + /** + Sets the number of columns in the sizer. + */ + void SetCols(int cols); + + /** + Sets the horizontal gap (in pixels) between cells in the sizer. + */ + void SetHGap(int gap); + + /** + Sets the number of rows in the sizer. + */ + void SetRows(int rows); + + /** + Sets the vertical gap (in pixels) between the cells in the sizer. + */ + void SetVGap(int gap); +}; + + + +/** + @class wxStaticBoxSizer + @wxheader{sizer.h} + + wxStaticBoxSizer is a sizer derived from wxBoxSizer but adds a static + box around the sizer. This static box may be either created independently or + the sizer may create it itself as a convenience. In any case, the sizer owns + the wxStaticBox control and will delete it if it is + deleted. + + @library{wxcore} + @category{winlayout} + + @see wxSizer, wxStaticBox, wxBoxSizer, @ref overview_sizer + "Sizer Overview" +*/ +class wxStaticBoxSizer : public wxBoxSizer +{ +public: + //@{ + /** + The first constructor uses an already existing static box. It takes the + associated static box and the orientation @e orient, which can be either + @c wxVERTICAL or @c wxHORIZONTAL as parameters. + The second one creates a new static box with the given label and parent window. + */ + wxStaticBoxSizer(wxStaticBox* box, int orient); + wxStaticBoxSizer(int orient, wxWindow parent, + const wxString& label = wxEmptyString); + //@} + + /** + Returns the static box associated with the sizer. + */ + wxStaticBox* GetStaticBox(); +}; + + + +/** + @class wxBoxSizer + @wxheader{sizer.h} + + The basic idea behind a box sizer is that windows will most often be laid out + in rather + simple basic geometry, typically in a row or a column or several hierarchies of + either. + + For more information, please see @ref overview_sizer_box + "Programming with wxBoxSizer". + + @library{wxcore} + @category{winlayout} + + @see wxSizer, @ref overview_sizer "Sizers Overview" +*/ +class wxBoxSizer : public wxSizer +{ +public: + /** + Constructor for a wxBoxSizer. @a orient may be either of wxVERTICAL + or wxHORIZONTAL for creating either a column sizer or a row sizer. + */ + wxBoxSizer(int orient); + + /** + Implements the calculation of a box sizer's minimal. It is used internally + only and must not be called by the user. Documented for information. + */ + wxSize CalcMin(); + + /** + Returns the orientation of the box sizer, either wxVERTICAL + or wxHORIZONTAL. + */ + int GetOrientation(); + + /** + Implements the calculation of a box sizer's dimensions and then sets + the size of its children (calling wxWindow::SetSize + if the child is a window). It is used internally only and must not be called + by the user (call Layout() if you want to resize). Documented for information. + */ + void RecalcSizes(); +}; + diff --git a/interface/wx/slider.h b/interface/wx/slider.h new file mode 100644 index 0000000000..5d20acb9fc --- /dev/null +++ b/interface/wx/slider.h @@ -0,0 +1,283 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: slider.h +// Purpose: interface of wxSlider +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxSlider + @wxheader{slider.h} + + A slider is a control with a handle which can be pulled + back and forth to change the value. + + On Windows, the track bar control is used. + + Slider events are handled in the same way as a scrollbar. + + @beginStyleTable + @style{wxSL_HORIZONTAL} + Displays the slider horizontally (this is the default). + @style{wxSL_VERTICAL} + Displays the slider vertically. + @style{wxSL_AUTOTICKS} + Displays tick marks. + @style{wxSL_LABELS} + Displays minimum, maximum and value labels. + @style{wxSL_LEFT} + Displays ticks on the left and forces the slider to be vertical. + @style{wxSL_RIGHT} + Displays ticks on the right and forces the slider to be vertical. + @style{wxSL_TOP} + Displays ticks on the top. + @style{wxSL_BOTTOM} + Displays ticks on the bottom (this is the default). + @style{wxSL_SELRANGE} + Allows the user to select a range on the slider. Windows only. + @style{wxSL_INVERSE} + Inverses the mininum and maximum endpoints on the slider. Not + compatible with wxSL_SELRANGE. + @endStyleTable + + @library{wxcore} + @category{ctrl} + + + @see @ref overview_eventhandlingoverview, wxScrollBar +*/ +class wxSlider : public wxControl +{ +public: + /** + Default constructor + */ + wxSlider(); + + /** + Constructor, creating and showing a slider. + + @param parent + Parent window. Must not be @NULL. + @param id + Window identifier. The value wxID_ANY indicates a default value. + @param value + Initial position for the slider. + @param minValue + Minimum slider position. + @param maxValue + Maximum slider position. + @param size + Window size. If wxDefaultSize is specified then a default size + is chosen. + @param style + Window style. See wxSlider. + @param validator + Window validator. + @param name + Window name. + + @see Create(), wxValidator + */ + wxSlider(wxWindow* parent, wxWindowID id, int value, + int minValue, int maxValue, + const wxPoint& point = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxSL_HORIZONTAL, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "slider"); + + /** + Destructor, destroying the slider. + */ + ~wxSlider(); + + /** + Clears the selection, for a slider with the @b wxSL_SELRANGE style. + + @remarks Windows 95 only. + */ + void ClearSel(); + + /** + Clears the ticks. + + @remarks Windows 95 only. + */ + void ClearTicks(); + + /** + Used for two-step slider construction. See wxSlider() + for further details. + */ + bool Create(wxWindow* parent, wxWindowID id, int value, + int minValue, int maxValue, + const wxPoint& point = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxSL_HORIZONTAL, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "slider"); + + /** + Returns the line size. + + @see SetLineSize() + */ + int GetLineSize() const; + + /** + Gets the maximum slider value. + + @see GetMin(), SetRange() + */ + int GetMax() const; + + /** + Gets the minimum slider value. + + @see GetMin(), SetRange() + */ + int GetMin() const; + + /** + Returns the page size. + + @see SetPageSize() + */ + int GetPageSize() const; + + /** + Returns the selection end point. + + @remarks Windows 95 only. + + @see GetSelStart(), SetSelection() + */ + int GetSelEnd() const; + + /** + Returns the selection start point. + + @remarks Windows 95 only. + + @see GetSelEnd(), SetSelection() + */ + int GetSelStart() const; + + /** + Returns the thumb length. + + @remarks Windows 95 only. + + @see SetThumbLength() + */ + int GetThumbLength() const; + + /** + Returns the tick frequency. + + @remarks Windows 95 only. + + @see SetTickFreq() + */ + int GetTickFreq() const; + + /** + Gets the current slider value. + + @see GetMin(), GetMax(), SetValue() + */ + int GetValue() const; + + /** + Sets the line size for the slider. + + @param lineSize + The number of steps the slider moves when the user moves it up or down a + line. + + @see GetLineSize() + */ + void SetLineSize(int lineSize); + + /** + Sets the page size for the slider. + + @param pageSize + The number of steps the slider moves when the user pages up or down. + + @see GetPageSize() + */ + void SetPageSize(int pageSize); + + /** + Sets the minimum and maximum slider values. + + @see GetMin(), GetMax() + */ + void SetRange(int minValue, int maxValue); + + /** + Sets the selection. + + @param startPos + The selection start position. + @param endPos + The selection end position. + + @remarks Windows 95 only. + + @see GetSelStart(), GetSelEnd() + */ + void SetSelection(int startPos, int endPos); + + /** + Sets the slider thumb length. + + @param len + The thumb length. + + @remarks Windows 95 only. + + @see GetThumbLength() + */ + void SetThumbLength(int len); + + /** + Sets a tick position. + + @param tickPos + The tick position. + + @remarks Windows 95 only. + + @see SetTickFreq() + */ + void SetTick(int tickPos); + + /** + Sets the tick mark frequency and position. + + @param n + Frequency. For example, if the frequency is set to two, a tick mark is + displayed for + every other increment in the slider's range. + @param pos + Position. Must be greater than zero. TODO: what is this for? + + @remarks Windows 95 only. + + @see GetTickFreq() + */ + void SetTickFreq(int n, int pos); + + /** + Sets the slider position. + + @param value + The slider position. + */ + void SetValue(int value); +}; + diff --git a/interface/wx/snglinst.h b/interface/wx/snglinst.h new file mode 100644 index 0000000000..b24130c399 --- /dev/null +++ b/interface/wx/snglinst.h @@ -0,0 +1,107 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: snglinst.h +// Purpose: interface of wxSingleInstanceChecker +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxSingleInstanceChecker + @wxheader{snglinst.h} + + wxSingleInstanceChecker class allows to check that only a single instance of a + program is running. To do it, you should create an object of this class. As + long as this object is alive, calls to + wxSingleInstanceChecker::IsAnotherRunning from + other processes will return @true. + + As the object should have the life span as big as possible, it makes sense to + create it either as a global or in wxApp::OnInit. For + example: + + @code + bool MyApp::OnInit() + { + const wxString name = wxString::Format("MyApp-%s", wxGetUserId().c_str()); + m_checker = new wxSingleInstanceChecker(name); + if ( m_checker-IsAnotherRunning() ) + { + wxLogError(_("Another program instance is already running, aborting.")); + + delete m_checker; // OnExit() won't be called if we return @false + m_checker = @NULL; + + return @false; + } + + ... more initializations ... + + return @true; + } + + int MyApp::OnExit() + { + delete m_checker; + + return 0; + } + @endcode + + Note using wxGetUserId() to construct the name: this + allows different user to run the application concurrently which is usually the + intended goal. If you don't use the user name in the wxSingleInstanceChecker + name, only one user would be able to run the application at a time. + + This class is implemented for Win32 and Unix platforms (supporting @c fcntl() + system call, but almost all of modern Unix systems do) only. + + @library{wxbase} + @category{misc} +*/ +class wxSingleInstanceChecker +{ +public: + /** + Like Create() but without + error checking. + */ + wxSingleInstanceChecker(const wxString& name, + const wxString& path = wxEmptyString); + + /** + Destructor frees the associated resources. + Note that it is not virtual, this class is not meant to be used polymorphically + */ + ~wxSingleInstanceChecker(); + + /** + Initialize the object if it had been created using the default constructor. + Note that you can't call Create() more than once, so calling it if the + @ref wxsingleinstancechecker() "non default ctor" + had been used is an error. + + @param name + must be given and be as unique as possible. It is used as the + mutex name under Win32 and the lock file name under Unix. + GetAppName() and wxGetUserId() + are commonly used to construct this parameter. + @param path + is optional and is ignored under Win32 and used as the directory to + create the lock file in under Unix (default is + wxGetHomeDir()) + + @return Returns @false if initialization failed, it doesn't mean that + another instance is running - use IsAnotherRunning() + to check for it. + */ + bool Create(const wxString& name, + const wxString& path = wxEmptyString); + + /** + Returns @true if another copy of this program is already running, @false + otherwise. + */ + bool IsAnotherRunning() const; +}; + diff --git a/interface/wx/socket.h b/interface/wx/socket.h new file mode 100644 index 0000000000..2312cf26e0 --- /dev/null +++ b/interface/wx/socket.h @@ -0,0 +1,1096 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: socket.h +// Purpose: interface of wxIPV4address +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxIPV4address + @wxheader{socket.h} + + + @library{wxbase} + @category{net} +*/ +class wxIPV4address : public wxIPaddress +{ +public: + /** + Set address to any of the addresses of the current machine. Whenever + possible, use this function instead of LocalHost(), + as this correctly handles multi-homed hosts and avoids other small + problems. Internally, this is the same as setting the IP address + to @b INADDR_ANY. + + @return Returns @true on success, @false if something went wrong. + */ + bool AnyAddress(); + + //@{ + /** + Returns the hostname which matches the IP address. + */ + bool Hostname(const wxString& hostname); + Return value wxString Hostname(); + //@} + + /** + Returns a wxString containing the IP address in dot quad (127.0.0.1) format. + */ + wxString IPAddress(); + + /** + Set address to localhost (127.0.0.1). Whenever possible, use the + AnyAddress(), + function instead of this one, as this will correctly handle multi-homed + hosts and avoid other small problems. + */ + bool LocalHost(); + + //@{ + /** + Returns the current service. + */ + bool Service(const wxString& service); + Return value bool Service(unsigned short service); + Return value unsigned short Service(); + //@} +}; + + + +/** + @class wxSocketServer + @wxheader{socket.h} + + + @library{wxnet} + @category{net} + + @see wxSocketServer::WaitForAccept, wxSocketBase::SetNotify, + wxSocketBase::Notify, wxSocketServer::AcceptWith +*/ +class wxSocketServer : public wxSocketBase +{ +public: + /** + Constructs a new server and tries to bind to the specified @e address. + Before trying to accept new connections, test whether it succeeded with + @ref wxSocketBase::isok wxSocketBase:IsOk. + + @param address + Specifies the local address for the server (e.g. port number). + @param flags + Socket flags (See wxSocketBase::SetFlags) + */ + wxSocketServer(const wxSockAddress& address, + wxSocketFlags flags = wxSOCKET_NONE); + + /** + Destructor (it doesn't close the accepted connections). + */ + ~wxSocketServer(); + + /** + Accepts an incoming connection request, and creates a new + wxSocketBase object which represents + the server-side of the connection. + If @a wait is @true and there are no pending connections to be + accepted, it will wait for the next incoming connection to + arrive. @b Warning: This will block the GUI. + If @a wait is @false, it will try to accept a pending connection + if there is one, but it will always return immediately without blocking + the GUI. If you want to use Accept in this way, you can either check for + incoming connections with WaitForAccept() + or catch @b wxSOCKET_CONNECTION events, then call Accept once you know + that there is an incoming connection waiting to be accepted. + + @return Returns an opened socket connection, or @NULL if an error + occurred or if the wait parameter was @false and there + were no pending connections. + + @see WaitForAccept(), wxSocketBase::SetNotify, + wxSocketBase::Notify, AcceptWith() + */ + wxSocketBase* Accept(bool wait = true); + + /** + Accept an incoming connection using the specified socket object. + + @param socket + Socket to be initialized + + @return Returns @true on success, or @false if an error occurred or if the + wait parameter was @false and there were no pending + connections. + */ + bool AcceptWith(wxSocketBase& socket, bool wait = true); + + /** + This function waits for an incoming connection. Use it if you want to call + Accept() or AcceptWith() + with @e wait set to @false, to detect when an incoming connection is waiting + to be accepted. + + @param seconds + Number of seconds to wait. + If -1, it will wait for the default timeout, + as set with SetTimeout. + @param millisecond + Number of milliseconds to wait. + + @return Returns @true if an incoming connection arrived, @false if the + timeout elapsed. + */ + bool WaitForAccept(long seconds = -1, long millisecond = 0); +}; + + + +/** + @class wxIPaddress + @wxheader{socket.h} + + wxIPaddress is an abstract base class for all internet protocol address + objects. Currently, only wxIPV4address + is implemented. An experimental implementation for IPV6, wxIPV6address, + is being developed. + + @library{wxbase} + @category{net} +*/ +class wxIPaddress : public wxSockAddress +{ +public: + /** + Internally, this is the same as setting the IP address + to @b INADDR_ANY. + On IPV4 implementations, 0.0.0.0 + On IPV6 implementations, :: + + @return Returns @true on success, @false if something went wrong. + */ + virtual bool AnyAddress(); + + /** + Internally, this is the same as setting the IP address + to @b INADDR_BROADCAST. + On IPV4 implementations, 255.255.255.255 + + @return Returns @true on success, @false if something went wrong. + */ + virtual bool BroadcastAddress(); + + //@{ + /** + Returns the hostname which matches the IP address. + */ + virtual bool Hostname(const wxString& hostname); + Return value virtual wxString Hostname(); + //@} + + /** + Returns a wxString containing the IP address. + */ + virtual wxString IPAddress(); + + /** + Determines if current address is set to localhost. + */ + virtual bool IsLocalHost(); + + /** + Set address to localhost. + On IPV4 implementations, 127.0.0.1 + On IPV6 implementations, ::1 + + @return Returns @true on success, @false if something went wrong. + */ + virtual bool LocalHost(); + + //@{ + /** + Returns the current service. + */ + virtual bool Service(const wxString& service); + Return value virtual bool Service(unsigned short service); + Return value virtual unsigned short Service(); + //@} +}; + + + +/** + @class wxSocketClient + @wxheader{socket.h} + + + @library{wxnet} + @category{net} + + @see wxSocketClient::WaitOnConnect, wxSocketBase::SetNotify, + wxSocketBase::Notify +*/ +class wxSocketClient : public wxSocketBase +{ +public: + /** + Constructor. + + @param flags + Socket flags (See wxSocketBase::SetFlags) + */ + wxSocketClient(wxSocketFlags flags = wxSOCKET_NONE); + + /** + Destructor. Please see wxSocketBase::Destroy. + */ + ~wxSocketClient(); + + //@{ + /** + Connects to a server using the specified address. + If @a wait is @true, Connect will wait until the connection + completes. @b Warning: This will block the GUI. + If @a wait is @false, Connect will try to establish the connection and + return immediately, without blocking the GUI. When used this way, even if + Connect returns @false, the connection request can be completed later. + To detect this, use WaitOnConnect(), + or catch @b wxSOCKET_CONNECTION events (for successful establishment) + and @b wxSOCKET_LOST events (for connection failure). + + @param address + Address of the server. + @param local + Bind to the specified local address and port before connecting. + The local address and port can also be set using SetLocal, + and then using the 2-parameter Connect method. + @param wait + If @true, waits for the connection to complete. + + @return Returns @true if the connection is established and no error + occurs. + + @see WaitOnConnect(), wxSocketBase::SetNotify, + wxSocketBase::Notify + */ + bool Connect(wxSockAddress& address, bool wait = true); + bool Connect(wxSockAddress& address, wxSockAddress& local, + bool wait = true); + //@} + + /** + Wait until a connection request completes, or until the specified timeout + elapses. Use this function after issuing a call + to Connect() with @e wait set to @false. + + @param seconds + Number of seconds to wait. + If -1, it will wait for the default timeout, + as set with SetTimeout. + @param millisecond + Number of milliseconds to wait. + + @return WaitOnConnect returns @true if the connection request completes. + This does not necessarily mean that the connection was + successfully established; it might also happen that the + connection was refused by the peer. Use IsConnected to + distinguish between these two situations. + */ + bool WaitOnConnect(long seconds = -1, long milliseconds = 0); +}; + + + +/** + @class wxSockAddress + @wxheader{socket.h} + + You are unlikely to need to use this class: only wxSocketBase uses it. + + @library{wxbase} + @category{FIXME} + + @see wxSocketBase, wxIPaddress, wxIPV4address +*/ +class wxSockAddress : public wxObject +{ +public: + /** + Default constructor. + */ + wxSockAddress(); + + /** + Default destructor. + */ + ~wxSockAddress(); + + /** + Delete all informations about the address. + */ + void Clear(); + + /** + Returns the length of the socket address. + */ + int SockAddrLen(); +}; + + + +/** + @class wxSocketEvent + @wxheader{socket.h} + + This event class contains information about socket events. + + @library{wxnet} + @category{net} + + @see wxSocketBase, wxSocketClient, wxSocketServer +*/ +class wxSocketEvent : public wxEvent +{ +public: + /** + Constructor. + */ + wxSocketEvent(int id = 0); + + /** + Gets the client data of the socket which generated this event, as + set with wxSocketBase::SetClientData. + */ + void* GetClientData(); + + /** + Returns the socket object to which this event refers to. This makes + it possible to use the same event handler for different sockets. + */ + wxSocketBase* GetSocket() const; + + /** + Returns the socket event type. + */ + wxSocketNotify GetSocketEvent() const; +}; + + + +/** + @class wxSocketBase + @wxheader{socket.h} + + wxSocketBase is the base class for all socket-related objects, and it + defines all basic IO functionality. + + Note: (Workaround for implementation limitation for wxWidgets up to 2.5.x) + If you want to use sockets or derived classes such as wxFTP in a secondary + thread, + call wxSocketBase::Initialize() (undocumented) from the main thread before + creating + any sockets - in wxApp::OnInit for example. + See http://wiki.wxwidgets.org/wiki.pl?WxSocket or + http://www.litwindow.com/knowhow/knowhow.html for more details. + + @library{wxnet} + @category{net} + + @see wxSocketEvent, wxSocketClient, wxSocketServer, @ref overview_samplesockets + "Sockets sample" +*/ +class wxSocketBase : public wxObject +{ +public: + /** + Default constructor. Don't use it directly; instead, use + wxSocketClient to construct a socket client, or + wxSocketServer to construct a socket server. + */ + wxSocketBase(); + + /** + Destructor. Do not destroy a socket using the delete operator directly; + use Destroy() instead. Also, do not create + socket objects in the stack. + */ + ~wxSocketBase(); + + /** + Functions that perform basic IO functionality. + Close() + + Discard() + + Peek() + + Read() + + ReadMsg() + + Unread() + + Write() + + WriteMsg() + Functions that perform a timed wait on a certain IO condition. + InterruptWait() + + Wait() + + WaitForLost() + + WaitForRead() + + WaitForWrite() + + and also: + wxSocketServer::WaitForAccept + + wxSocketClient::WaitOnConnect + Functions that allow applications to customize socket IO as needed. + GetFlags() + + SetFlags() + + SetTimeout() + + SetLocal() + */ + + + /** + This function shuts down the socket, disabling further transmission and + reception of data; it also disables events for the socket and frees the + associated system resources. Upon socket destruction, Close is automatically + called, so in most cases you won't need to do it yourself, unless you + explicitly want to shut down the socket, typically to notify the peer + that you are closing the connection. + */ + void Close(); + + /** + @ref construct() wxSocketBase + + @ref destruct() ~wxSocketBase + + Destroy() + */ + + + /** + Destroys the socket safely. Use this function instead of the delete operator, + since otherwise socket events could reach the application even after the + socket has been destroyed. To prevent this problem, this function appends + the wxSocket to a list of object to be deleted on idle time, after all + events have been processed. For the same reason, you should avoid creating + socket objects in the stack. + Destroy calls Close() automatically. + + @return Always @true. + */ + bool Destroy(); + + /** + This function simply deletes all bytes in the incoming queue. This function + always returns immediately and its operation is not affected by IO flags. + Use LastCount() to verify the number of bytes actually discarded. + If you use Error(), it will always return @false. + */ + wxSocketBase Discard(); + + /** + Returns @true if an error occurred in the last IO operation. + Use this function to check for an error condition after one of the + following calls: Discard, Peek, Read, ReadMsg, Unread, Write, WriteMsg. + */ + bool Error() const; + + /** + Returns a pointer of the client data for this socket, as set with + SetClientData() + */ + void* GetClientData() const; + + /** + Returns current IO flags, as set with SetFlags() + */ + wxSocketFlags GetFlags() const; + + /** + This function returns the local address field of the socket. The local + address field contains the complete local address of the socket (local + address, local port, ...). + + @return @true if no error happened, @false otherwise. + */ + bool GetLocal(wxSockAddress& addr) const; + + /** + This function returns the peer address field of the socket. The peer + address field contains the complete peer host address of the socket + (address, port, ...). + + @return @true if no error happened, @false otherwise. + */ + bool GetPeer(wxSockAddress& addr) const; + + /** + Functions that allow applications to receive socket events. + Notify() + + SetNotify() + + GetClientData() + + SetClientData() + + SetEventHandler() + */ + + + /** + Use this function to interrupt any wait operation currently in progress. + Note that this is not intended as a regular way to interrupt a Wait call, + but only as an escape mechanism for exceptional situations where it is + absolutely necessary to use it, for example to abort an operation due to + some exception or abnormal problem. InterruptWait is automatically called + when you Close() a socket (and thus also upon + socket destruction), so you don't need to use it in these cases. + Wait(), + wxSocketServer::WaitForAccept, + WaitForLost(), + WaitForRead(), + WaitForWrite(), + wxSocketClient::WaitOnConnect + */ + void InterruptWait(); + + /** + Returns @true if the socket is connected. + */ + bool IsConnected() const; + + /** + This function waits until the socket is readable. This might mean that + queued data is available for reading or, for streamed sockets, that + the connection has been closed, so that a read operation will complete + immediately without blocking (unless the @b wxSOCKET_WAITALL flag + is set, in which case the operation might still block). + */ + bool IsData() const; + + /** + Returns @true if the socket is not connected. + */ + bool IsDisconnected() const; + + /** + Returns @true if the socket is initialized and ready and @false in other + cases. + */ + bool IsOk() const; + + /** + Returns the number of bytes read or written by the last IO call. + Use this function to get the number of bytes actually transferred + after using one of the following IO calls: Discard, Peek, Read, + ReadMsg, Unread, Write, WriteMsg. + */ + wxUint32 LastCount() const; + + /** + Returns the last wxSocket error. See @ref overview_wxsocketbase "wxSocket + errors". + Please note that this function merely returns the last error code, + but it should not be used to determine if an error has occurred (this + is because successful operations do not change the LastError value). + Use Error() first, in order to determine + if the last IO call failed. If this returns @true, use LastError + to discover the cause of the error. + */ + wxSocketError LastError() const; + + /** + According to the @a notify value, this function enables + or disables socket events. If @a notify is @true, the events + configured with SetNotify() will + be sent to the application. If @a notify is @false; no events + will be sent. + */ + void Notify(bool notify); + + /** + This function peeks a buffer of @a nbytes bytes from the socket. + Peeking a buffer doesn't delete it from the socket input queue. + Use LastCount() to verify the number of bytes actually peeked. + Use Error() to determine if the operation succeeded. + + @param buffer + Buffer where to put peeked data. + @param nbytes + Number of bytes. + + @return Returns a reference to the current object. + + @see Error(), LastError(), LastCount(), + SetFlags() + */ + wxSocketBase Peek(void* buffer, wxUint32 nbytes); + + /** + This function reads a buffer of @a nbytes bytes from the socket. + Use LastCount() to verify the number of bytes actually read. + Use Error() to determine if the operation succeeded. + + @param buffer + Buffer where to put read data. + @param nbytes + Number of bytes. + + @return Returns a reference to the current object. + + @see Error(), LastError(), LastCount(), + SetFlags() + */ + wxSocketBase Read(void* buffer, wxUint32 nbytes); + + /** + This function reads a buffer sent by WriteMsg() + on a socket. If the buffer passed to the function isn't big enough, the + remaining bytes will be discarded. This function always waits for the + buffer to be entirely filled, unless an error occurs. + Use LastCount() to verify the number of bytes actually read. + Use Error() to determine if the operation succeeded. + + @param buffer + Buffer where to put read data. + @param nbytes + Size of the buffer. + + @return Returns a reference to the current object. + + @see Error(), LastError(), LastCount(), + SetFlags(), WriteMsg() + */ + wxSocketBase ReadMsg(void* buffer, wxUint32 nbytes); + + /** + This function restores the previous state of the socket, as saved + with SaveState() + Calls to SaveState and RestoreState can be nested. + + @see SaveState() + */ + void RestoreState(); + + /** + This function saves the current state of the socket in a stack. Socket + state includes flags, as set with SetFlags(), + event mask, as set with SetNotify() and + Notify(), user data, as set with + SetClientData(). + Calls to SaveState and RestoreState can be nested. + + @see RestoreState() + */ + void SaveState(); + + /** + Sets user-supplied client data for this socket. All socket events will + contain a pointer to this data, which can be retrieved with + the wxSocketEvent::GetClientData function. + */ + void SetClientData(void* data); + + /** + Sets an event handler to be called when a socket event occurs. The + handler will be called for those events for which notification is + enabled with SetNotify() and + Notify(). + + @param handler + Specifies the event handler you want to use. + @param id + The id of socket event. + + @see SetNotify(), Notify(), wxSocketEvent, wxEvtHandler + */ + void SetEventHandler(wxEvtHandler& handler, int id = -1); + + /** + Use SetFlags to customize IO operation for this socket. + The @a flags parameter may be a combination of flags ORed together. + The following flags can be used: + + @b wxSOCKET_NONE + + Normal functionality. + + @b wxSOCKET_NOWAIT + + Read/write as much data as possible and return immediately. + + @b wxSOCKET_WAITALL + + Wait for all required data to be read/written unless an error occurs. + + @b wxSOCKET_BLOCK + + Block the GUI (do not yield) while reading/writing data. + + @b wxSOCKET_REUSEADDR + + Allows the use of an in-use port (wxServerSocket only) + + @b wxSOCKET_BROADCAST + + Switches the socket to broadcast mode + + @b wxSOCKET_NOBIND + + Stops the socket from being bound to a specific adapter (normally used in + conjunction with @b wxSOCKET_BROADCAST) + + A brief overview on how to use these flags follows. + If no flag is specified (this is the same as @b wxSOCKET_NONE), + IO calls will return after some data has been read or written, even + when the transfer might not be complete. This is the same as issuing + exactly one blocking low-level call to recv() or send(). Note + that @e blocking here refers to when the function returns, not + to whether the GUI blocks during this time. + If @b wxSOCKET_NOWAIT is specified, IO calls will return immediately. + Read operations will retrieve only available data. Write operations will + write as much data as possible, depending on how much space is available + in the output buffer. This is the same as issuing exactly one nonblocking + low-level call to recv() or send(). Note that @e nonblocking here + refers to when the function returns, not to whether the GUI blocks during + this time. + If @b wxSOCKET_WAITALL is specified, IO calls won't return until ALL + the data has been read or written (or until an error occurs), blocking if + necessary, and issuing several low level calls if necessary. This is the + same as having a loop which makes as many blocking low-level calls to + recv() or send() as needed so as to transfer all the data. Note + that @e blocking here refers to when the function returns, not + to whether the GUI blocks during this time. + The @b wxSOCKET_BLOCK flag controls whether the GUI blocks during + IO operations. If this flag is specified, the socket will not yield + during IO calls, so the GUI will remain blocked until the operation + completes. If it is not used, then the application must take extra + care to avoid unwanted reentrance. + The @b wxSOCKET_REUSEADDR flag controls the use of the SO_REUSEADDR standard + setsockopt() flag. This flag allows the socket to bind to a port that is + already in use. + This is mostly used on UNIX-based systems to allow rapid starting and stopping + of a server - + otherwise you may have to wait several minutes for the port to become available. + wxSOCKET_REUSEADDR can also be used with socket clients to (re)bind to a + particular local port + for an outgoing connection. + This option can have surprising platform dependent behavior, so check the + documentation for + your platform's implementation of setsockopt(). Note that on BSD-based systems + (e.g. Mac OS X), + use of wxSOCKET_REUSEADDR implies SO_REUSEPORT in addition to SO_REUSEADDR to + be consistent + with Windows. + The @b wxSOCKET_BROADCAST flag controls the use of the SO_BROADCAST standard + setsockopt() flag. This flag allows the socket to use the broadcast address, + and is generally + used in conjunction with @b wxSOCKET_NOBIND and wxIPaddress::BroadcastAddress. + So: + @b wxSOCKET_NONE will try to read at least SOME data, no matter how much. + @b wxSOCKET_NOWAIT will always return immediately, even if it cannot + read or write ANY data. + @b wxSOCKET_WAITALL will only return when it has read or written ALL + the data. + @b wxSOCKET_BLOCK has nothing to do with the previous flags and + it controls whether the GUI blocks. + @b wxSOCKET_REUSEADDR controls special platform-specific behavior for + reusing local addresses/ports. + */ + void SetFlags(wxSocketFlags flags); + + /** + This function allows you to set the local address and port, + useful when an application needs to reuse a particular port. When + a local port is set for a wxSocketClient, + @b bind will be called before @b connect. + */ + bool SetLocal(wxIPV4address& local); + + /** + SetNotify specifies which socket events are to be sent to the event handler. + The @a flags parameter may be combination of flags ORed together. The + following flags can be used: + + @b wxSOCKET_INPUT_FLAG + + to receive wxSOCKET_INPUT + + @b wxSOCKET_OUTPUT_FLAG + + to receive wxSOCKET_OUTPUT + + @b wxSOCKET_CONNECTION_FLAG + + to receive wxSOCKET_CONNECTION + + @b wxSOCKET_LOST_FLAG + + to receive wxSOCKET_LOST + + For example: + + In this example, the user will be notified about incoming socket data and + whenever the connection is closed. + For more information on socket events see @ref overview_wxsocketbase "wxSocket + events". + */ + void SetNotify(wxSocketEventFlags flags); + + /** + This function sets the default socket timeout in seconds. This timeout + applies to all IO calls, and also to the Wait() family + of functions if you don't specify a wait interval. Initially, the default + timeout is 10 minutes. + */ + void SetTimeout(int seconds); + + /** + Functions to retrieve current state and miscellaneous info. + Error() + + GetLocal() + + GetPeer() + IsConnected() + + IsData() + + IsDisconnected() + + LastCount() + + LastError() + + IsOk() + + SaveState() + + RestoreState() + */ + + + /** + This function unreads a buffer. That is, the data in the buffer is put back + in the incoming queue. This function is not affected by wxSocket flags. + If you use LastCount(), it will always return @e nbytes. + If you use Error(), it will always return @false. + + @param buffer + Buffer to be unread. + @param nbytes + Number of bytes. + + @return Returns a reference to the current object. + + @see Error(), LastCount(), LastError() + */ + wxSocketBase Unread(const void* buffer, wxUint32 nbytes); + + /** + This function waits until any of the following conditions is @true: + + The socket becomes readable. + The socket becomes writable. + An ongoing connection request has completed (wxSocketClient only) + An incoming connection request has arrived (wxSocketServer only) + The connection has been closed. + Note that it is recommended to use the individual Wait functions + to wait for the required condition, instead of this one. + + @param seconds + Number of seconds to wait. + If -1, it will wait for the default timeout, + as set with SetTimeout. + @param millisecond + Number of milliseconds to wait. + + @return Returns @true when any of the above conditions is satisfied, + @false if the timeout was reached. + + @see InterruptWait(), wxSocketServer::WaitForAccept, + WaitForLost(), WaitForRead(), + WaitForWrite(), wxSocketClient::WaitOnConnect + */ + bool Wait(long seconds = -1, long millisecond = 0); + + /** + This function waits until the connection is lost. This may happen if + the peer gracefully closes the connection or if the connection breaks. + + @param seconds + Number of seconds to wait. + If -1, it will wait for the default timeout, + as set with SetTimeout. + @param millisecond + Number of milliseconds to wait. + + @return Returns @true if the connection was lost, @false if the timeout + was reached. + + @see InterruptWait(), Wait() + */ + bool WaitForLost(long seconds = -1, long millisecond = 0); + + /** + This function waits until the socket is readable. This might mean that + queued data is available for reading or, for streamed sockets, that + the connection has been closed, so that a read operation will complete + immediately without blocking (unless the @b wxSOCKET_WAITALL flag + is set, in which case the operation might still block). + + @param seconds + Number of seconds to wait. + If -1, it will wait for the default timeout, + as set with SetTimeout. + @param millisecond + Number of milliseconds to wait. + + @return Returns @true if the socket becomes readable, @false on timeout. + + @see InterruptWait(), Wait() + */ + bool WaitForRead(long seconds = -1, long millisecond = 0); + + /** + This function waits until the socket becomes writable. This might mean that + the socket is ready to send new data, or for streamed sockets, that the + connection has been closed, so that a write operation is guaranteed to + complete immediately (unless the @b wxSOCKET_WAITALL flag is set, + in which case the operation might still block). + + @param seconds + Number of seconds to wait. + If -1, it will wait for the default timeout, + as set with SetTimeout. + @param millisecond + Number of milliseconds to wait. + + @return Returns @true if the socket becomes writable, @false on timeout. + + @see InterruptWait(), Wait() + */ + bool WaitForWrite(long seconds = -1, long millisecond = 0); + + /** + This function writes a buffer of @a nbytes bytes to the socket. + Use LastCount() to verify the number of bytes actually written. + Use Error() to determine if the operation succeeded. + + @param buffer + Buffer with the data to be sent. + @param nbytes + Number of bytes. + + @return Returns a reference to the current object. + + @see Error(), LastError(), LastCount(), + SetFlags() + */ + wxSocketBase Write(const void* buffer, wxUint32 nbytes); + + /** + This function writes a buffer of @a nbytes bytes from the socket, but it + writes a short header before so that ReadMsg() + knows how much data should it actually read. So, a buffer sent with WriteMsg + @b must be read with ReadMsg. This function always waits for the entire + buffer to be sent, unless an error occurs. + Use LastCount() to verify the number of bytes actually written. + Use Error() to determine if the operation succeeded. + + @param buffer + Buffer with the data to be sent. + @param nbytes + Number of bytes to send. + + @return Returns a reference to the current object. + */ + wxSocketBase WriteMsg(const void* buffer, wxUint32 nbytes); +}; + + + +/** + @class wxDatagramSocket + @wxheader{socket.h} + + + @library{wxnet} + @category{FIXME} + + @see wxSocketBase::Error, wxSocketBase::LastError, wxSocketBase::LastCount, + wxSocketBase::SetFlags, +*/ +class wxDatagramSocket : public wxSocketBase +{ +public: + /** + Constructor. + + @param flags + Socket flags (See wxSocketBase::SetFlags) + */ + wxDatagramSocket(wxSocketFlags flags = wxSOCKET_NONE); + + /** + Destructor. Please see wxSocketBase::Destroy. + */ + ~wxDatagramSocket(); + + /** + This function reads a buffer of @a nbytes bytes from the socket. + Use wxSocketBase::LastCount to verify the number of bytes actually read. + Use wxSocketBase::Error to determine if the operation succeeded. + + @param address + Any address - will be overwritten with the address of the peer that sent + that data. + @param buffer + Buffer where to put read data. + @param nbytes + Number of bytes. + + @return Returns a reference to the current object, and the address of + the peer that sent the data on address param. + + @see wxSocketBase::Error, wxSocketBase::LastError, wxSocketBase::LastCount, + wxSocketBase::SetFlags, + */ + wxDatagramSocket ReceiveFrom(wxSockAddress& address, + void* buffer, + wxUint32 nbytes); + + /** + This function writes a buffer of @a nbytes bytes to the socket. + Use wxSocketBase::LastCount to verify the number of bytes actually wrote. + Use wxSocketBase::Error to determine if the operation succeeded. + + @param address + The address of the destination peer for this data. + @param buffer + Buffer where read data is. + @param nbytes + Number of bytes. + + @return Returns a reference to the current object. + */ + wxDatagramSocket SendTo(const wxSockAddress& address, + const void* buffer, + wxUint32 nbytes); +}; + diff --git a/interface/wx/sound.h b/interface/wx/sound.h new file mode 100644 index 0000000000..2d22a5b76c --- /dev/null +++ b/interface/wx/sound.h @@ -0,0 +1,107 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: sound.h +// Purpose: interface of wxSound +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxSound + @wxheader{sound.h} + + This class represents a short sound (loaded from Windows WAV file), that + can be stored in memory and played. Currently this class is implemented + on Windows and Unix (and uses either + Open Sound System or + Simple DirectMedia Layer). + + @library{wxadv} + @category{FIXME} +*/ +class wxSound : public wxObject +{ +public: + //@{ + /** + Constructs a wave object from a file or, under Windows, from a Windows + resource. Call IsOk() to determine whether this + succeeded. + + @param fileName + The filename or Windows resource. + @param isResource + @true if fileName is a resource, @false if it is a filename. + */ + wxSound(); + wxSound(const wxString& fileName, bool isResource = false); + //@} + + /** + Destroys the wxSound object. + */ + ~wxSound(); + + /** + Constructs a wave object from a file or resource. + + @param fileName + The filename or Windows resource. + @param isResource + @true if fileName is a resource, @false if it is a filename. + + @return @true if the call was successful, @false otherwise. + */ + bool Create(const wxString& fileName, bool isResource = false); + + /** + Returns @true if the object contains a successfully loaded file or resource, + @false otherwise. + */ + bool IsOk() const; + + /** + Returns @true if a sound is played at the moment. + This method is currently not implemented under Windows. + */ + static bool IsPlaying() const; + + //@{ + /** + Plays the sound file. If another sound is playing, it will be interrupted. + Returns @true on success, @false otherwise. Note that in general it is + possible + to delete the object which is being asynchronously played any time after + calling this function and the sound would continue playing, however this + currently doesn't work under Windows for sound objects loaded from memory data. + The possible values for @a flags are: + + wxSOUND_SYNC + + @c Play will block and wait until the sound is + replayed. + + wxSOUND_ASYNC + + Sound is played asynchronously, + @c Play returns immediately + + wxSOUND_ASYNC | wxSOUND_LOOP + + Sound is played asynchronously + and loops until another sound is played, + Stop() is called or the program terminates. + + The static form is shorthand for this code: + */ + bool Play(unsigned flags = wxSOUND_ASYNC); + const static bool Play(const wxString& filename, + unsigned flags = wxSOUND_ASYNC); + //@} + + /** + If a sound is played, this function stops it. + */ + static void Stop(); +}; + diff --git a/interface/wx/spinbutt.h b/interface/wx/spinbutt.h new file mode 100644 index 0000000000..054bce9150 --- /dev/null +++ b/interface/wx/spinbutt.h @@ -0,0 +1,165 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: spinbutt.h +// Purpose: interface of wxSpinEvent +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxSpinEvent + @wxheader{spinbutt.h} + + This event class is used for the events generated by + wxSpinButton and wxSpinCtrl. + + @library{wxcore} + @category{events} + + @see wxSpinButton and wxSpinCtrl +*/ +class wxSpinEvent : public wxNotifyEvent +{ +public: + /** + The constructor is not normally used by the user code. + */ + wxSpinEvent(wxEventType commandType = wxEVT_NULL, int id = 0); + + /** + Retrieve the current spin button or control value. + */ + int GetPosition() const; + + /** + Set the value associated with the event. + */ + void SetPosition(int pos); +}; + + + +/** + @class wxSpinButton + @wxheader{spinbutt.h} + + A wxSpinButton has two small up and down (or left and right) arrow buttons. It + is often used next to a text control for increment and decrementing a value. + Portable programs should try to use wxSpinCtrl instead + as wxSpinButton is not implemented for all platforms but wxSpinCtrl is as it + degenerates to a simple wxTextCtrl on such platforms. + + @note the range supported by this control (and wxSpinCtrl) depends on the + platform but is at least @c -0x8000 to @c 0x7fff. Under GTK and + Win32 with sufficiently new version of @c comctrl32.dll (at least 4.71 is + required, 5.80 is recommended) the full 32 bit range is supported. + + @beginStyleTable + @style{wxSP_HORIZONTAL} + Specifies a horizontal spin button (note that this style is not + supported in wxGTK). + @style{wxSP_VERTICAL} + Specifies a vertical spin button. + @style{wxSP_ARROW_KEYS} + The user can use arrow keys to change the value. + @style{wxSP_WRAP} + The value wraps at the minimum and maximum. + @endStyleTable + + @library{wxcore} + @category{ctrl} + + + @see wxSpinCtrl +*/ +class wxSpinButton : public wxControl +{ +public: + /** + Default constructor. + */ + wxSpinButton(); + + /** + Constructor, creating and showing a spin button. + + @param parent + Parent window. Must not be @NULL. + @param id + Window identifier. The value wxID_ANY indicates a default value. + @param pos + Window position. If wxDefaultPosition is specified then a default + position is chosen. + @param size + Window size. If wxDefaultSize is specified then a default size + is chosen. + @param style + Window style. See wxSpinButton. + @param name + Window name. + + @see Create() + */ + wxSpinButton(wxWindow* parent, wxWindowID id, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxSP_HORIZONTAL, + const wxString& name = "spinButton"); + + /** + Destructor, destroys the spin button control. + */ + ~wxSpinButton(); + + /** + Scrollbar creation function called by the spin button constructor. + See wxSpinButton() for details. + */ + bool Create(wxWindow* parent, wxWindowID id, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxSP_HORIZONTAL, + const wxString& name = "spinButton"); + + /** + Returns the maximum permissible value. + + @see SetRange() + */ + int GetMax() const; + + /** + Returns the minimum permissible value. + + @see SetRange() + */ + int GetMin() const; + + /** + Returns the current spin button value. + + @see SetValue() + */ + int GetValue() const; + + /** + Sets the range of the spin button. + + @param min + The minimum value for the spin button. + @param max + The maximum value for the spin button. + + @see GetMin(), GetMax() + */ + void SetRange(int min, int max); + + /** + Sets the value of the spin button. + + @param value + The value for the spin button. + */ + void SetValue(int value); +}; + diff --git a/interface/wx/spinctrl.h b/interface/wx/spinctrl.h new file mode 100644 index 0000000000..06d29a3647 --- /dev/null +++ b/interface/wx/spinctrl.h @@ -0,0 +1,124 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: spinctrl.h +// Purpose: interface of wxSpinCtrl +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxSpinCtrl + @wxheader{spinctrl.h} + + wxSpinCtrl combines wxTextCtrl and + wxSpinButton in one control. + + @beginStyleTable + @style{wxSP_ARROW_KEYS} + The user can use arrow keys to change the value. + @style{wxSP_WRAP} + The value wraps at the minimum and maximum. + @endStyleTable + + @library{wxcore} + @category{ctrl} + + + @see wxSpinButton, wxControl +*/ +class wxSpinCtrl : public wxControl +{ +public: + /** + Default constructor. + */ + wxSpinCtrl(); + + /** + Constructor, creating and showing a spin control. + + @param parent + Parent window. Must not be @NULL. + @param value + Default value (as text). + @param id + Window identifier. The value wxID_ANY indicates a default value. + @param pos + Window position. If wxDefaultPosition is specified then a default + position is chosen. + @param size + Window size. If wxDefaultSize is specified then a default size + is chosen. + @param style + Window style. See wxSpinButton. + @param min + Minimal value. + @param max + Maximal value. + @param initial + Initial value. + @param name + Window name. + + @see Create() + */ + wxSpinCtrl(wxWindow* parent, wxWindowID id = -1, + const wxString& value = wxEmptyString, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxSP_ARROW_KEYS, + int min = 0, int max = 100, + int initial = 0); + + /** + Creation function called by the spin control constructor. + See wxSpinCtrl() for details. + */ + bool Create(wxWindow* parent, wxWindowID id = -1, + const wxString& value = wxEmptyString, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxSP_ARROW_KEYS, + int min = 0, int max = 100, + int initial = 0); + + /** + Gets maximal allowable value. + */ + int GetMax() const; + + /** + Gets minimal allowable value. + */ + int GetMin() const; + + /** + Gets the value of the spin control. + */ + int GetValue() const; + + /** + Sets range of allowable values. + */ + void SetRange(int minVal, int maxVal); + + /** + Select the text in the text part of the control between positions + @a from (inclusive) and @a to (exclusive). This is similar to + wxTextCtrl::SetSelection. + @note this is currently only implemented for Windows and generic versions + of the control. + */ + void SetSelection(long from, long to); + + /** + Sets the value of the spin control. Use the variant using int instead. + */ + void SetValue(const wxString& text); + + /** + Sets the value of the spin control. + */ + void SetValue(int value); +}; + diff --git a/interface/wx/splash.h b/interface/wx/splash.h new file mode 100644 index 0000000000..ae408f6bb0 --- /dev/null +++ b/interface/wx/splash.h @@ -0,0 +1,86 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: splash.h +// Purpose: interface of wxSplashScreen +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxSplashScreen + @wxheader{splash.h} + + wxSplashScreen shows a window with a thin border, displaying a bitmap + describing your + application. Show it in application initialisation, and then either explicitly + destroy + it or let it time-out. + + Example usage: + + @code + wxBitmap bitmap; + if (bitmap.LoadFile("splash16.png", wxBITMAP_TYPE_PNG)) + { + wxSplashScreen* splash = new wxSplashScreen(bitmap, + wxSPLASH_CENTRE_ON_SCREEN|wxSPLASH_TIMEOUT, + 6000, @NULL, -1, wxDefaultPosition, wxDefaultSize, + wxBORDER_SIMPLE|wxSTAY_ON_TOP); + } + wxYield(); + @endcode + + @library{wxadv} + @category{managedwnd} +*/ +class wxSplashScreen : public wxFrame +{ +public: + /** + Construct the splash screen passing a bitmap, a style, a timeout, a window id, + optional position + and size, and a window style. + @a splashStyle is a bitlist of some of the following: + wxSPLASH_CENTRE_ON_PARENT + wxSPLASH_CENTRE_ON_SCREEN + wxSPLASH_NO_CENTRE + wxSPLASH_TIMEOUT + wxSPLASH_NO_TIMEOUT + @a milliseconds is the timeout in milliseconds. + */ + wxSplashScreen(const wxBitmap& bitmap, long splashStyle, + int milliseconds, + wxWindow* parent, + wxWindowID id, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxBORDER_SIMPLE|wxFRAME_NO_TASKBAR|wxSTAY_ON_TOP); + + /** + Destroys the splash screen. + */ + ~wxSplashScreen(); + + /** + Returns the splash style (see wxSplashScreen() for + details). + */ + long GetSplashStyle() const; + + /** + Returns the window used to display the bitmap. + */ + wxSplashScreenWindow* GetSplashWindow() const; + + /** + Returns the timeout in milliseconds. + */ + int GetTimeout() const; + + /** + Reimplement this event handler if you want to set an application variable on + window destruction, for example. + */ + void OnCloseWindow(wxCloseEvent& event); +}; + diff --git a/interface/wx/splitter.h b/interface/wx/splitter.h new file mode 100644 index 0000000000..71478582a3 --- /dev/null +++ b/interface/wx/splitter.h @@ -0,0 +1,441 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: splitter.h +// Purpose: interface of wxSplitterWindow +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxSplitterWindow + @wxheader{splitter.h} + + @ref overview_wxsplitterwindowoverview "wxSplitterWindow overview" + + This class manages up to two subwindows. The current view can be + split into two programmatically (perhaps from a menu command), and unsplit + either programmatically or via the wxSplitterWindow user interface. + + @beginStyleTable + @style{wxSP_3D} + Draws a 3D effect border and sash. + @style{wxSP_3DSASH} + Draws a 3D effect sash. + @style{wxSP_3DBORDER} + Synonym for wxSP_BORDER. + @style{wxSP_BORDER} + Draws a standard border. + @style{wxSP_NOBORDER} + No border (default). + @style{wxSP_NO_XP_THEME} + Under Windows XP, switches off the attempt to draw the splitter + using Windows XP theming, so the borders and sash will take on the + pre-XP look. + @style{wxSP_PERMIT_UNSPLIT} + Always allow to unsplit, even with the minimum pane size other than + zero. + @style{wxSP_LIVE_UPDATE} + Don't draw XOR line but resize the child windows immediately. + @endStyleTable + + @library{wxcore} + @category{miscwnd} + + @see wxSplitterEvent +*/ +class wxSplitterWindow : public wxWindow +{ +public: + /** + Default constructor + */ + wxSplitterWindow(); + + /** + Constructor for creating the window. + + @param parent + The parent of the splitter window. + @param id + The window identifier. + @param pos + The window position. + @param size + The window size. + @param style + The window style. See wxSplitterWindow. + @param name + The window name. + + @remarks After using this constructor, you must create either one or two + subwindows with the splitter window as parent, and then + call one of Initialize(), + SplitVertically() and + SplitHorizontally() in order to set the + pane(s). + + @see Initialize(), SplitVertically(), + SplitHorizontally(), Create() + */ + wxSplitterWindow(wxWindow* parent, wxWindowID id, + const wxPoint& point = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxSP_3D, + const wxString& name = "splitterWindow"); + + /** + Destroys the wxSplitterWindow and its children. + */ + ~wxSplitterWindow(); + + /** + Creation function, for two-step construction. See wxSplitterWindow() for + details. + */ + bool Create(wxWindow* parent, wxWindowID id, + const wxPoint& point = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxSP_3D, + const wxString& name = "splitterWindow"); + + /** + Returns the current minimum pane size (defaults to zero). + + @see SetMinimumPaneSize() + */ + int GetMinimumPaneSize() const; + + /** + Returns the current sash gravity. + + @see SetSashGravity() + */ + double GetSashGravity(); + + /** + Returns the current sash position. + + @see SetSashPosition() + */ + int GetSashPosition(); + + /** + Gets the split mode. + + @see SetSplitMode(), SplitVertically(), + SplitHorizontally(). + */ + int GetSplitMode() const; + + /** + Returns the left/top or only pane. + */ + wxWindow* GetWindow1() const; + + /** + Returns the right/bottom pane. + */ + wxWindow* GetWindow2() const; + + /** + Initializes the splitter window to have one pane. The child window is + shown if it is currently hidden. + + @param window + The pane for the unsplit window. + + @remarks This should be called if you wish to initially view only a + single pane in the splitter window. + + @see SplitVertically(), SplitHorizontally() + */ + void Initialize(wxWindow* window); + + /** + Returns @true if the window is split, @false otherwise. + */ + bool IsSplit() const; + + /** + Application-overridable function called when the sash is double-clicked with + the left mouse button. + + @param x + The x position of the mouse cursor. + @param y + The y position of the mouse cursor. + + @remarks The default implementation of this function calls Unsplit if the + minimum pane size is zero. + + @see Unsplit() + */ + virtual void OnDoubleClickSash(int x, int y); + + /** + Application-overridable function called when the sash position is changed by + user. It may return @false to prevent the change or @true to allow it. + + @param newSashPosition + The new sash position (always positive or zero) + + @remarks The default implementation of this function verifies that the + sizes of both panes of the splitter are greater than + minimum pane size. + */ + virtual bool OnSashPositionChange(int newSashPosition); + + /** + Application-overridable function called when the window is unsplit, either + programmatically or using the wxSplitterWindow user interface. + + @param removed + The window being removed. + + @remarks The default implementation of this function simply hides + removed. You may wish to delete the window. + */ + virtual void OnUnsplit(wxWindow* removed); + + /** + This function replaces one of the windows managed by the wxSplitterWindow with + another one. It is in general better to use it instead of calling Unsplit() + and then resplitting the window back because it will provoke much less flicker + (if any). It is valid to call this function whether the splitter has two + windows or only one. + Both parameters should be non-@NULL and @a winOld must specify one of the + windows managed by the splitter. If the parameters are incorrect or the window + couldn't be replaced, @false is returned. Otherwise the function will return + @true, but please notice that it will not delete the replaced window and you + may wish to do it yourself. + + @see GetMinimumPaneSize() + */ + bool ReplaceWindow(wxWindow* winOld, wxWindow* winNew); + + /** + Sets the minimum pane size. + + @param paneSize + Minimum pane size in pixels. + + @remarks The default minimum pane size is zero, which means that either + pane can be reduced to zero by dragging the sash, thus + removing one of the panes. To prevent this behaviour + (and veto out-of-range sash dragging), set a minimum + size, for example 20 pixels. If the wxSP_PERMIT_UNSPLIT + style is used when a splitter window is created, the + window may be unsplit even if minimum size is non-zero. + + @see GetMinimumPaneSize() + */ + void SetMinimumPaneSize(int paneSize); + + /** + Sets the sash gravity. + + @param gravity + The sash gravity. Value between 0.0 and 1.0. + + @see GetSashGravity() + */ + void SetSashGravity(double gravity); + + /** + Sets the sash position. + + @param position + The sash position in pixels. + @param redraw + If @true, resizes the panes and redraws the sash and border. + + @remarks Does not currently check for an out-of-range value. + + @see GetSashPosition() + */ + void SetSashPosition(int position, const bool redraw = true); + + /** + Sets the sash size. Normally, the sash size is determined according to the + metrics + of each platform, but the application can override this, for example to show + a thin sash that the user is not expected to drag. If @a size is more -1, + the custom sash size will be used. + */ + void SetSashSize(int size); + + /** + Sets the split mode. + + @param mode + Can be wxSPLIT_VERTICAL or wxSPLIT_HORIZONTAL. + + @remarks Only sets the internal variable; does not update the display. + + @see GetSplitMode(), SplitVertically(), + SplitHorizontally(). + */ + void SetSplitMode(int mode); + + /** + Initializes the top and bottom panes of the splitter window. The + child windows are shown if they are currently hidden. + + @param window1 + The top pane. + @param window2 + The bottom pane. + @param sashPosition + The initial position of the sash. If this value is + positive, it specifies the size of the upper pane. If it is negative, its + absolute value gives the size of the lower pane. Finally, specify 0 + (default) + to choose the default position (half of the total window height). + + @return @true if successful, @false otherwise (the window was already + split). + + @remarks This should be called if you wish to initially view two panes. + It can also be called at any subsequent time, but the + application should check that the window is not + currently split using IsSplit. + + @see SplitVertically(), IsSplit(), + Unsplit() + */ + bool SplitHorizontally(wxWindow* window1, wxWindow* window2, + int sashPosition = 0); + + /** + Initializes the left and right panes of the splitter window. The + child windows are shown if they are currently hidden. + + @param window1 + The left pane. + @param window2 + The right pane. + @param sashPosition + The initial position of the sash. If this value is + positive, it specifies the size of the left pane. If it is negative, it is + absolute value gives the size of the right pane. Finally, specify 0 + (default) + to choose the default position (half of the total window width). + + @return @true if successful, @false otherwise (the window was already + split). + + @remarks This should be called if you wish to initially view two panes. + It can also be called at any subsequent time, but the + application should check that the window is not + currently split using IsSplit. + + @see SplitHorizontally(), IsSplit(), + Unsplit(). + */ + bool SplitVertically(wxWindow* window1, wxWindow* window2, + int sashPosition = 0); + + /** + Unsplits the window. + + @param toRemove + The pane to remove, or @NULL to remove the right or bottom pane. + + @return @true if successful, @false otherwise (the window was not split). + + @remarks This call will not actually delete the pane being removed; it + calls OnUnsplit which can be overridden for the desired + behaviour. By default, the pane being removed is hidden. + + @see SplitHorizontally(), SplitVertically(), + IsSplit(), OnUnsplit() + */ + bool Unsplit(wxWindow* toRemove = NULL); + + /** + Causes any pending sizing of the sash and child panes to take place + immediately. + Such resizing normally takes place in idle time, in order + to wait for layout to be completed. However, this can cause + unacceptable flicker as the panes are resized after the window has been + shown. To work around this, you can perform window layout (for + example by sending a size event to the parent window), and then + call this function, before showing the top-level window. + */ + void UpdateSize(); +}; + + + +/** + @class wxSplitterEvent + @wxheader{splitter.h} + + This class represents the events generated by a splitter control. Also there is + only one event class, the data associated to the different events is not the + same and so not all accessor functions may be called for each event. The + documentation mentions the kind of event(s) for which the given accessor + function makes sense: calling it for other types of events will result + in assert failure (in debug mode) and will return meaningless results. + + @library{wxcore} + @category{events} + + @see wxSplitterWindow, @ref overview_eventhandlingoverview +*/ +class wxSplitterEvent : public wxNotifyEvent +{ +public: + /** + Constructor. Used internally by wxWidgets only. + */ + wxSplitterEvent(wxEventType eventType = wxEVT_NULL, + wxSplitterWindow* splitter = NULL); + + /** + Returns the new sash position. + May only be called while processing + wxEVT_COMMAND_SPLITTER_SASH_POS_CHANGING and + wxEVT_COMMAND_SPLITTER_SASH_POS_CHANGED events. + */ + int GetSashPosition() const; + + /** + Returns a pointer to the window being removed when a splitter window + is unsplit. + May only be called while processing + wxEVT_COMMAND_SPLITTER_UNSPLIT events. + */ + wxWindow* GetWindowBeingRemoved() const; + + /** + Returns the x coordinate of the double-click point. + May only be called while processing + wxEVT_COMMAND_SPLITTER_DOUBLECLICKED events. + */ + int GetX() const; + + /** + Returns the y coordinate of the double-click point. + May only be called while processing + wxEVT_COMMAND_SPLITTER_DOUBLECLICKED events. + */ + int GetY() const; + + /** + In the case of wxEVT_COMMAND_SPLITTER_SASH_POS_CHANGED events, + sets the new sash position. In the case of + wxEVT_COMMAND_SPLITTER_SASH_POS_CHANGING events, sets the new + tracking bar position so visual feedback during dragging will + represent that change that will actually take place. Set to -1 from + the event handler code to prevent repositioning. + May only be called while processing + wxEVT_COMMAND_SPLITTER_SASH_POS_CHANGING and + wxEVT_COMMAND_SPLITTER_SASH_POS_CHANGED events. + + @param pos + New sash position. + */ + void SetSashPosition(int pos); +}; + diff --git a/interface/wx/srchctrl.h b/interface/wx/srchctrl.h new file mode 100644 index 0000000000..348632ae3f --- /dev/null +++ b/interface/wx/srchctrl.h @@ -0,0 +1,130 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: srchctrl.h +// Purpose: interface of wxSearchCtrl +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxSearchCtrl + @wxheader{srchctrl.h} + + A search control is a composite control with a search button, a text + control, and a cancel button. + + @beginStyleTable + @style{wxTE_PROCESS_ENTER} + The control will generate the event wxEVT_COMMAND_TEXT_ENTER + (otherwise pressing Enter key is either processed internally by the + control or used for navigation between dialog controls). + @style{wxTE_PROCESS_TAB} + The control will receive wxEVT_CHAR events for TAB pressed - + normally, TAB is used for passing to the next control in a dialog + instead. For the control created with this style, you can still use + Ctrl-Enter to pass to the next control from the keyboard. + @style{wxTE_NOHIDESEL} + By default, the Windows text control doesn't show the selection + when it doesn't have focus - use this style to force it to always + show it. It doesn't do anything under other platforms. + @style{wxTE_LEFT} + The text in the control will be left-justified (default). + @style{wxTE_CENTRE} + The text in the control will be centered (currently wxMSW and + wxGTK2 only). + @style{wxTE_RIGHT} + The text in the control will be right-justified (currently wxMSW + and wxGTK2 only). + @style{wxTE_CAPITALIZE} + On PocketPC and Smartphone, causes the first letter to be + capitalized. + @endStyleTable + + @library{wxcore} + @category{FIXME} + + @see wxTextCtrl::Create, wxValidator +*/ +class wxSearchCtrl : public wxTextCtrl +{ +public: + /** + Default constructor + */ + wxSearchCtrl(); + + /** + Constructor, creating and showing a text control. + + @param parent + Parent window. Should not be @NULL. + @param id + Control identifier. A value of -1 denotes a default value. + @param value + Default text value. + @param pos + Text control position. + @param size + Text control size. + @param style + Window style. See wxSearchCtrl. + @param validator + Window validator. + @param name + Window name. + + @see wxTextCtrl::Create, wxValidator + */ + wxSearchCtrl(wxWindow* parent, wxWindowID id, + const wxString& value = "", + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = wxSearchCtrlNameStr); + + /** + Destructor, destroying the search control. + */ + ~wxSearchCtrl(); + + /** + Returns a pointer to the search control's menu object or @NULL if there is no + menu attached. + */ + virtual wxMenu* GetMenu(); + + /** + Returns the search button visibility value. + If there is a menu attached, the search button will be visible regardless of + the search + button visibility value. + This always returns @false in Mac OS X v10.3 + */ + virtual bool IsSearchButtonVisible(); + + /** + Sets the search control's menu object. If there is already a menu associated + with + the search control it is deleted. + + @param menu + Menu to attach to the search control. + */ + virtual void SetMenu(wxMenu* menu); + + /** + Shows or hides the cancel button. + */ + virtual void ShowCancelButton(bool show); + + /** + Sets the search button visibility value on the search control. + If there is a menu attached, the search button will be visible regardless of + the search + button visibility value. + This has no effect in Mac OS X v10.3 + */ + virtual void ShowSearchButton(bool show); +}; + diff --git a/interface/wx/sstream.h b/interface/wx/sstream.h new file mode 100644 index 0000000000..9fb340b705 --- /dev/null +++ b/interface/wx/sstream.h @@ -0,0 +1,72 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: sstream.h +// Purpose: interface of wxStringInputStream +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxStringInputStream + @wxheader{sstream.h} + + This class implements an input stream which reads data from a string. It + supports seeking. + + @library{wxbase} + @category{streams} +*/ +class wxStringInputStream : public wxInputStream +{ +public: + /** + Creates a new read-only stream using the specified string. Note that the string + is copied by the stream so if the original string is modified after using this + constructor, changes to it are not reflected when reading from stream. + */ + wxStringInputStream(const wxString& s); +}; + + + +/** + @class wxStringOutputStream + @wxheader{sstream.h} + + This class implements an output stream which writes data either to a + user-provided or internally allocated string. Note that currently this stream + does not support seeking but can tell its current position. + + @library{wxbase} + @category{streams} +*/ +class wxStringOutputStream : public wxOutputStream +{ +public: + /** + Construct a new stream object writing the data to a string. + + If the provided pointer is non-@NULL, data will be written to it. + Otherwise, an internal string is used for the data written to this + stream, use GetString() to get access to it. + + If @a str is used, data written to the stream is appended to the current + contents of it, i.e. the string is not cleared here. However if it is not + empty, the positions returned by wxOutputStream::TellO will be + offset by the initial string length, i.e. initial stream position will be the + initial length of the string and not 0. + + Notice that the life time of @a conv must be greater than the life time + of this object itself as it stores a reference to it. Also notice that + with default value of this argument the data written to the stream must + be valid UTF-8, pass @c wxConvISO8859_1 to deal with arbitrary 8 bit + data. + */ + wxStringOutputStream(wxString str = NULL, wxMBConv& conv = wxConvUTF8); + + /** + Returns the string containing all the data written to the stream so far. + */ + const wxString& GetString() const; +}; + diff --git a/interface/wx/stackwalk.h b/interface/wx/stackwalk.h new file mode 100644 index 0000000000..782b5268e5 --- /dev/null +++ b/interface/wx/stackwalk.h @@ -0,0 +1,169 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: stackwalk.h +// Purpose: interface of wxStackWalker +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxStackWalker + @wxheader{stackwalk.h} + + wxStackWalker allows an application to enumerate, or walk, the stack frames + (the function callstack). + It is mostly useful in only two situations: + inside wxApp::OnFatalException function to + programmatically get the location of the crash and, in debug builds, in + wxApp::OnAssertFailure to report the caller of the failed + assert. + + wxStackWalker works by repeatedly calling + the wxStackWalker::OnStackFrame method for each frame in the + stack, so to use it you must derive your own class from it and override this + method. + + This class will not return anything except raw stack frame addresses if the + debug information is not available. Under Win32 this means that the PDB file + matching the program being executed should be present. Note that if you use + Microsoft Visual C++ compiler, you can create PDB files even for the programs + built in release mode and it doesn't affect the program size (at least if you + don't forget to add @c /opt:ref option which is suppressed by using + @c /debug linker option by default but should be always enabled for + release builds). Under Unix, you need to compile your program with debugging + information (usually using @c -g compiler and linker options) to get the + file and line numbers information, however function names should be available + even without it. Of course, all this is only @true if you build using a recent + enough version of GNU libc which provides the @c backtrace() function + needed to walk the stack. + + @ref overview_debuggingoverview "debugging overview" for how to make it + available. + + @library{wxbase} + @category{FIXME} + + @see wxStackFrame +*/ +class wxStackWalker +{ +public: + /** + Constructor does nothing, use Walk() to walk the + stack. + */ + wxStackWalker(); + + /** + Destructor does nothing neither but should be virtual as this class is used as + a base one. + */ + ~wxStackWalker(); + + /** + This function must be overrided to process the given frame. + */ + void OnStackFrame(const wxStackFrame& frame); + + /** + Enumerate stack frames from the current location, skipping the initial + number of them (this can be useful when Walk() is called from some known + location and you don't want to see the first few frames anyhow; also + notice that Walk() frame itself is not included if skip = 1). + Up to @a maxDepth frames are walked from the innermost to the outermost one. + */ + void Walk(size_t skip = 1, size_t maxDepth = 200); + + /** + Enumerate stack frames from the location of uncaught exception. + This method can only be called from + wxApp::OnFatalException. + Up to @a maxDepth frames are walked from the innermost to the outermost one. + */ + void WalkFromException(size_t maxDepth = 200); +}; + + + +/** + @class wxStackFrame + @wxheader{stackwalk.h} + + wxStackFrame represents a single stack frame, or a single function in the call + stack, and is used exclusively together with + wxStackWalker, see there for a more detailed + discussion. + + @library{wxbase} + @category{FIXME} + + @see wxStackWalker +*/ +class wxStackFrame +{ +public: + /** + Return the address of this frame. + */ + void* GetAddress() const; + + /** + Return the name of the file containing this frame, empty if + unavailable (typically because debug info is missing). + Use HasSourceLocation() to check whether + the file name is available. + */ + wxString GetFileName() const; + + /** + Get the level of this frame (deepest/innermost one is 0). + */ + size_t GetLevel() const; + + /** + Return the line number of this frame, 0 if unavailable. + + @see GetFileName() + */ + size_t GetLine() const; + + /** + Get the module this function belongs to (empty if not available). + */ + wxString GetModule() const; + + /** + Return the unmangled (if possible) name of the function containing this + frame. + */ + wxString GetName() const; + + /** + Return the return address of this frame. + */ + size_t GetOffset() const; + + /** + Get the name, type and value (in text form) of the given parameter. + Any pointer may be @NULL if you're not interested in the corresponding + value. + Return @true if at least some values could be retrieved. + This function currently is only implemented under Win32 and requires a PDB + file. + */ + bool GetParam(size_t n, wxString* type, wxString* name, + wxString* value) const; + + /** + Return the number of parameters of this function (may return 0 if we + can't retrieve the parameters info even although the function does have + parameters). + */ + size_t GetParamCount() const; + + /** + Return @true if we have the file name and line number for this frame. + */ + bool HasSourceLocation() const; +}; + diff --git a/interface/wx/statbmp.h b/interface/wx/statbmp.h new file mode 100644 index 0000000000..d18ff1fe39 --- /dev/null +++ b/interface/wx/statbmp.h @@ -0,0 +1,107 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: statbmp.h +// Purpose: interface of wxStaticBitmap +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxStaticBitmap + @wxheader{statbmp.h} + + A static bitmap control displays a bitmap. Native implementations on some + platforms are only meant for display of the small icons in the dialog + boxes. In particular, under Windows 9x the size of bitmap is limited + to 64*64 pixels. + If you want to display larger images portably, you may use generic + implementation wxGenericStaticBitmap declared in . + + @library{wxcore} + @category{ctrl} + + + @see wxStaticBitmap, wxStaticBox +*/ +class wxStaticBitmap : public wxControl +{ +public: + /** + Default constructor + */ + wxStaticBitmap(); + + /** + Constructor, creating and showing a static bitmap control. + + @param parent + Parent window. Should not be @NULL. + @param id + Control identifier. A value of -1 denotes a default value. + @param label + Bitmap label. + @param pos + Window position. + @param size + Window size. + @param style + Window style. See wxStaticBitmap. + @param name + Window name. + + @see Create() + */ + wxStaticBitmap(wxWindow* parent, wxWindowID id, + const wxBitmap& label, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0, + const wxString& name = "staticBitmap"); + + /** + Creation function, for two-step construction. For details see wxStaticBitmap(). + */ + bool Create(wxWindow* parent, wxWindowID id, + const wxBitmap& label, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0, + const wxString& name = "staticBitmap"); + + /** + Returns the bitmap currently used in the control. Notice that this method can + be called even if SetIcon() had been used. + + @see SetBitmap() + */ + wxBitmap GetBitmap() const; + + /** + Returns the icon currently used in the control. Notice that this method can + only be called if SetIcon() had been used: an icon + can't be retrieved from the control if a bitmap had been set (using + wxStaticBitmap::SetBitmap). + + @see SetIcon() + */ + wxIcon GetIcon() const; + + /** + Sets the bitmap label. + + @param label + The new bitmap. + + @see GetBitmap() + */ + virtual void SetBitmap(const wxBitmap& label); + + /** + Sets the label to the given icon. + + @param label + The new icon. + */ + virtual void SetIcon(const wxIcon& label); +}; + diff --git a/interface/wx/statbox.h b/interface/wx/statbox.h new file mode 100644 index 0000000000..b6719749cb --- /dev/null +++ b/interface/wx/statbox.h @@ -0,0 +1,85 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: statbox.h +// Purpose: interface of wxStaticBox +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxStaticBox + @wxheader{statbox.h} + + A static box is a rectangle drawn around other panel items to denote + a logical grouping of items. + + Please note that a static box should @b not be used as the parent for the + controls it contains, instead they should be siblings of each other. Although + using a static box as a parent might work in some versions of wxWidgets, it + results in a crash under, for example, wxGTK. + + Also, please note that because of this, the order in which you create new + controls is important. Create your wxStaticBox control @b before any + siblings that are to appear inside the wxStaticBox in order to preserve the + correct Z-Order of controls. + + @library{wxcore} + @category{ctrl} + + + @see wxStaticText +*/ +class wxStaticBox : public wxControl +{ +public: + /** + Default constructor + */ + wxStaticBox(); + + /** + Constructor, creating and showing a static box. + + @param parent + Parent window. Must not be @NULL. + @param id + Window identifier. The value wxID_ANY indicates a default value. + @param label + Text to be displayed in the static box, the empty string for no label. + @param pos + Window position. If wxDefaultPosition is specified then a default + position is chosen. + @param size + Checkbox size. If the size (-1, -1) is specified then a default size is + chosen. + @param style + Window style. See wxStaticBox. + @param name + Window name. + + @see Create() + */ + wxStaticBox(wxWindow* parent, wxWindowID id, + const wxString& label, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0, + const wxString& name = "staticBox"); + + /** + Destructor, destroying the group box. + */ + ~wxStaticBox(); + + /** + Creates the static box for two-step construction. See wxStaticBox() + for further details. + */ + bool Create(wxWindow* parent, wxWindowID id, + const wxString& label, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0, + const wxString& name = "staticBox"); +}; + diff --git a/interface/wx/statline.h b/interface/wx/statline.h new file mode 100644 index 0000000000..226f28a70a --- /dev/null +++ b/interface/wx/statline.h @@ -0,0 +1,84 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: statline.h +// Purpose: interface of wxStaticLine +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxStaticLine + @wxheader{statline.h} + + A static line is just a line which may be used in a dialog to separate the + groups of controls. The line may be only vertical or horizontal. + + @beginStyleTable + @style{wxLI_HORIZONTAL} + Creates a horizontal line. + @style{wxLI_VERTICAL} + Creates a vertical line. + @endStyleTable + + @library{wxcore} + @category{FIXME} + + @see wxStaticBox +*/ +class wxStaticLine : public wxControl +{ +public: + /** + Default constructor + */ + wxStaticLine(); + + /** + Constructor, creating and showing a static line. + + @param parent + Parent window. Must not be @NULL. + @param id + Window identifier. The value wxID_ANY indicates a default value. + @param pos + Window position. If wxDefaultPosition is specified then a default + position is chosen. + @param size + Size. Note that either the height or the width (depending on + whether the line if horizontal or vertical) is ignored. + @param style + Window style (either wxLI_HORIZONTAL or wxLI_VERTICAL). + @param name + Window name. + + @see Create() + */ + wxStaticLine(wxWindow* parent, wxWindowID id = wxID_ANY, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxLI_HORIZONTAL, + const wxString& name = "staticLine"); + + /** + Creates the static line for two-step construction. See wxStaticLine() + for further details. + */ + bool Create(wxWindow* parent, wxWindowID id = wxID_ANY, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0, + const wxString& name = "staticLine"); + + /** + This static function returns the size which will be given to the smaller + dimension of the static line, i.e. its height for a horizontal line or its + width for a vertical one. + */ + int GetDefaultSize(); + + /** + Returns @true if the line is vertical, @false if horizontal. + */ + bool IsVertical() const; +}; + diff --git a/interface/wx/stattext.h b/interface/wx/stattext.h new file mode 100644 index 0000000000..ee65c9cdc6 --- /dev/null +++ b/interface/wx/stattext.h @@ -0,0 +1,214 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: stattext.h +// Purpose: interface of wxStaticText +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxStaticText + @wxheader{stattext.h} + + A static text control displays one or more lines of read-only text. + + @beginStyleTable + @style{wxALIGN_LEFT} + Align the text to the left + @style{wxALIGN_RIGHT} + Align the text to the right + @style{wxALIGN_CENTRE} + Center the text (horizontally) + @style{wxST_NO_AUTORESIZE} + By default, the control will adjust its size to exactly fit to the + size of the text when SetLabel is called. If this style flag is + given, the control will not change its size (this style is + especially useful with controls which also have wxALIGN_RIGHT or + CENTER style because otherwise they won't make sense any longer + after a call to SetLabel) + @style{wxST_ELLIPSIZE_START} + If the text width exceeds the control width, replace the beginning + of the text with an ellipsis + @style{wxST_ELLIPSIZE_MIDDLE} + Same as above, but replace the text in the middle of the control + with an ellipsis + @style{wxST_ELLIPSIZE_END} + Same as above, but replace the end of the text with an ellipsis + @style{wxST_MARKUP} + Support markup in the label; see SetLabel for more information + @endStyleTable + + @library{wxcore} + @category{ctrl} + + + @see wxStaticBitmap, wxStaticBox +*/ +class wxStaticText : public wxControl +{ +public: + /** + Default constructor. + */ + wxStaticText(); + + /** + Constructor, creating and showing a text control. + + @param parent + Parent window. Should not be @NULL. + @param id + Control identifier. A value of -1 denotes a default value. + @param label + Text label. + @param pos + Window position. + @param size + Window size. + @param style + Window style. See wxStaticText. + @param name + Window name. + + @see Create() + */ + wxStaticText(wxWindow* parent, wxWindowID id, + const wxString& label, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0, + const wxString& name = "staticText"); + + /** + Creation function, for two-step construction. For details see wxStaticText(). + */ + bool Create(wxWindow* parent, wxWindowID id, + const wxString& label, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0, + const wxString& name = "staticText"); + + /** + Returns the contents of the control. + Note that the returned string contains both the mnemonics (@c characters), + if any, and markup tags, if any. + Use GetLabelText() if only the + label text is needed. + */ + wxString GetLabel() const; + + //@{ + /** + The first form returns the control's label without the mnemonics characters (if + any) + and without the markup (if the control has @c wxST_MARKUP style). + The second (static) version returns the given @a label string without the + mnemonics + characters (if any) and without the markup. + */ + wxString GetLabelText(); + const static wxString GetLabelText(const wxString& label); + //@} + + /** + Sets the static text label and updates the controls size to exactly fit the + label unless the control has wxST_NO_AUTORESIZE flag. + This function allows to set decorated static label text on platforms which + support it (currently only GTK+ 2). For the other platforms, the markup is + ignored. + The supported tags are: + + b + + bold text + + big + + bigger text + + i + + italic text + + s + + strike-through text + + sub + + subscript text + + sup + + superscript text + + small + + smaller text + + tt + + monospaced text + + u + + underlined text + + span + + generic formatter tag; see Pango Markup for more information. + + Note that the string must be well-formed (e.g. all tags must be correctly + closed) + otherwise it can be not shown correctly or at all. + Also note that you need to escape the following special characters: + + @b Special character + + @b Escape as + + @c + + @c amp; or as @c + + @c ' + + @c apos; + + @c " + + @c quot; + + @c + + @c lt; + + @c + + @c gt; + + The non-escaped ampersand @c characters are interpreted as + mnemonics; see wxControl::SetLabel. + + Example: + + @param label + The new label to set. It may contain newline characters and the markup tags + described above. + */ + virtual void SetLabel(const wxString& label); + + /** + This functions wraps the controls label so that each of its lines becomes at + most @a width pixels wide if possible (the lines are broken at words + boundaries so it might not be the case if words are too long). If @e width + is negative, no wrapping is done. Note that this width is not + necessarily the total width of the control, since a few pixels for the + border (depending on the controls border style) may be added. + + @since 2.6.2 + */ + void Wrap(int width); +}; + diff --git a/interface/wx/statusbr.h b/interface/wx/statusbr.h new file mode 100644 index 0000000000..2d4ca10da5 --- /dev/null +++ b/interface/wx/statusbr.h @@ -0,0 +1,233 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: statusbr.h +// Purpose: interface of wxStatusBar +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxStatusBar + @wxheader{statusbr.h} + + A status bar is a narrow window that can be placed along the bottom of a frame + to give + small amounts of status information. It can contain one or more fields, one or + more of which can + be variable length according to the size of the window. + + wxWindow + + wxEvtHandler + + wxObject + + @beginStyleTable + @style{wxST_SIZEGRIP} + On Windows 95, displays a gripper at right-hand side of the status + bar. + @endStyleTable + + @library{wxcore} + @category{miscwnd} + + @see wxFrame, @ref overview_samplestatbar "Status bar sample" +*/ +class wxStatusBar : public wxWindow +{ +public: + //@{ + /** + Constructor, creating the window. + + @param parent + The window parent, usually a frame. + @param id + The window identifier. It may take a value of -1 to indicate a default + value. + @param style + The window style. See wxStatusBar. + @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 + individual windows. + + @see Create() + */ + wxStatusBar(); + wxStatusBar(wxWindow* parent, wxWindowID id = wxID_ANY, + long style = wxST_SIZEGRIP, + const wxString& name = "statusBar"); + //@} + + /** + Destructor. + */ + ~wxStatusBar(); + + /** + Creates the window, for two-step construction. + See wxStatusBar() for details. + */ + bool Create(wxWindow* parent, wxWindowID id = wxID_ANY, + long style = wxST_SIZEGRIP, + const wxString& name = "statusBar"); + + /** + Returns the size and position of a field's internal bounding rectangle. + + @param i + The field in question. + @param rect + The rectangle values are placed in this variable. + + @return @true if the field index is valid, @false otherwise. + + @see wxRect + */ + virtual bool GetFieldRect(int i, wxRect& rect) const; + + /** + Returns the number of fields in the status bar. + */ + int GetFieldsCount() const; + + /** + Returns the string associated with a status bar field. + + @param i + The number of the status field to retrieve, starting from zero. + + @return The status field string if the field is valid, otherwise the + empty string. + + @see SetStatusText() + */ + virtual wxString GetStatusText(int i = 0) const; + + /** + Sets the field text to the top of the stack, and pops the stack of saved + strings. + + @see PushStatusText() + */ + void PopStatusText(int field = 0); + + /** + Saves the current field text in a per field stack, and sets the field text + to the string passed as argument. + */ + void PushStatusText(const wxString& string, int field = 0); + + /** + Sets the number of fields, and optionally the field widths. + + @param number + The number of fields. + @param widths + An array of n integers interpreted in the same way as + in SetStatusWidths + */ + virtual void SetFieldsCount(int number = 1, int* widths = NULL); + + /** + Sets the minimal possible height for the status bar. The real height may be + bigger than the height specified here depending on the size of the font used by + the status bar. + */ + void SetMinHeight(int height); + + /** + Sets the styles of the fields in the status line which can make fields appear + flat + or raised instead of the standard sunken 3D border. + + @param n + The number of fields in the status bar. Must be equal to the + number passed to SetFieldsCount the last + time it was called. + @param styles + Contains an array of n integers with the styles for each field. There + are three possible styles: + + + + + + + + wxSB_NORMAL + + + + + (default) The field appears sunken with a standard 3D border. + + + + + + wxSB_FLAT + + + + + No border is painted around the field so that it appears flat. + + + + + + wxSB_RAISED + + + + + A raised 3D border is painted around the field. + */ + virtual void SetStatusStyles(int n, int* styles); + + /** + Sets the text for one field. + + @param text + The text to be set. Use an empty string ("") to clear the field. + @param i + The field to set, starting from zero. + + @see GetStatusText(), wxFrame::SetStatusText + */ + virtual void SetStatusText(const wxString& text, int i = 0); + + /** + Sets the widths of the fields in the status line. There are two types of + fields: fixed widths one and variable width fields. For the fixed width fields + you should specify their (constant) width in pixels. For the variable width + fields, specify a negative number which indicates how the field should expand: + the space left for all variable width fields is divided between them according + to the absolute value of this number. A variable width field with width of -2 + gets twice as much of it as a field with width -1 and so on. + For example, to create one fixed width field of width 100 in the right part of + the status bar and two more fields which get 66% and 33% of the remaining + space correspondingly, you should use an array containing -2, -1 and 100. + + @param n + The number of fields in the status bar. Must be equal to the + number passed to SetFieldsCount the last + time it was called. + @param widths + Contains an array of n integers, each of which is + either an absolute status field width in pixels if positive or indicates a + variable width field if negative. + + @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. + + @see SetFieldsCount(), wxFrame::SetStatusWidths + */ + virtual void SetStatusWidths(int n, int* widths); +}; + diff --git a/interface/wx/stc/stc.h b/interface/wx/stc/stc.h new file mode 100644 index 0000000000..53f286e8f4 --- /dev/null +++ b/interface/wx/stc/stc.h @@ -0,0 +1,2746 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: stc/stc.h +// Purpose: interface of wxStyledTextEvent +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxStyledTextEvent + @headerfile stc.h wx/stc/stc.h + + The type of events sent from wxStyledTextCtrl. + + TODO + + @library{wxbase} + @category{FIXME} +*/ +class wxStyledTextEvent : public wxCommandEvent +{ +public: + //@{ + /** + + */ + wxStyledTextEvent(wxEventType commandType = 0, int id = 0); + wxStyledTextEvent(const wxStyledTextEvent& event); + //@} + + /** + + */ + wxEvent* Clone() const; + + /** + + */ + bool GetAlt() const; + + /** + + */ + bool GetControl() const; + + /** + + */ + bool GetDragAllowMove(); + + /** + + */ + wxDragResult GetDragResult(); + + /** + + */ + wxString GetDragText(); + + /** + + */ + int GetFoldLevelNow() const; + + /** + + */ + int GetFoldLevelPrev() const; + + /** + + */ + int GetKey() const; + + /** + + */ + int GetLParam() const; + + /** + + */ + int GetLength() const; + + /** + + */ + int GetLine() const; + + /** + + */ + int GetLinesAdded() const; + + /** + + */ + int GetListType() const; + + /** + + */ + int GetMargin() const; + + /** + + */ + int GetMessage() const; + + /** + + */ + int GetModificationType() const; + + /** + + */ + int GetModifiers() const; + + /** + + */ + int GetPosition() const; + + /** + + */ + bool GetShift() const; + + /** + + */ + wxString GetText() const; + + /** + + */ + int GetWParam() const; + + /** + + */ + int GetX() const; + + /** + + */ + int GetY() const; + + /** + + */ + void SetDragAllowMove(bool val); + + /** + + */ + void SetDragResult(wxDragResult val); + + /** + + */ + void SetDragText(const wxString& val); + + /** + + */ + void SetFoldLevelNow(int val); + + /** + + */ + void SetFoldLevelPrev(int val); + + /** + + */ + void SetKey(int k); + + /** + + */ + void SetLParam(int val); + + /** + + */ + void SetLength(int len); + + /** + + */ + void SetLine(int val); + + /** + + */ + void SetLinesAdded(int num); + + /** + + */ + void SetListType(int val); + + /** + + */ + void SetMargin(int val); + + /** + + */ + void SetMessage(int val); + + /** + + */ + void SetModificationType(int t); + + /** + + */ + void SetModifiers(int m); + + /** + + */ + void SetPosition(int pos); + + /** + + */ + void SetText(const wxString& t); + + /** + + */ + void SetWParam(int val); + + /** + + */ + void SetX(int val); + + /** + + */ + void SetY(int val); +}; + + + +/** + @class wxStyledTextCtrl + @headerfile stc.h wx/stc/stc.h + + A wxWidgets implementation of the Scintilla source code editing component. + + As well as features found in standard text editing components, Scintilla + includes + features especially useful when editing and debugging source code. These + include + support for syntax styling, error indicators, code completion and call tips. + The + selection margin can contain markers like those used in debuggers to indicate + breakpoints and the current line. Styling choices are more open than with many + editors, allowing the use of proportional fonts, bold and italics, multiple + foreground and background colours and multiple fonts. + + wxStyledTextCtrl is a 1 to 1 mapping of "raw" scintilla interface, whose + documentation + can be found in the Scintilla website. + + @library{wxbase} + @category{stc} + + @see wxStyledTextEvent +*/ +class wxStyledTextCtrl : public wxControl +{ +public: + /** + Ctor. + */ + wxStyledTextCtrl::wxStyledTextCtrl(wxWindow* parent, + wxWindowID id = wxID_ANY, + const wxPoint pos = wxDefaultPosition, + const wxSize size = wxDefaultSize, + long style = 0, + const wxString name = "stcwindow"); + + /** + Extend life of document. + */ + void AddRefDocument(void* docPointer); + + /** + Add array of cells to document. + */ + void AddStyledText(const wxMemoryBuffer& data); + + /** + BEGIN generated section. The following code is automatically generated + by gen_iface.py. Do not edit this file. Edit stc.h.in instead + and regenerate + Add text to the document at current position. + */ + void AddText(const wxString& text); + + /** + The following methods are nearly equivallent to their similarly named + cousins above. The difference is that these methods bypass wxString + and always use a char* even if used in a unicode build of wxWidgets. + In that case the character data will be utf-8 encoded since that is + what is used internally by Scintilla in unicode builds. + Add text to the document at current position. + */ + void AddTextRaw(const char* text); + + /** + Enlarge the document to a particular size of text bytes. + */ + void Allocate(int bytes); + + /** + Append a string to the end of the document without changing the selection. + */ + void AppendText(const wxString& text); + + /** + Append a string to the end of the document without changing the selection. + */ + void AppendTextRaw(const char* text); + + /** + Is there an auto-completion list visible? + */ + bool AutoCompActive(); + + /** + Remove the auto-completion list from the screen. + */ + void AutoCompCancel(); + + /** + User has selected an item so remove the list and insert the selection. + */ + void AutoCompComplete(); + + /** + Retrieve whether or not autocompletion is hidden automatically when nothing + matches. + */ + bool AutoCompGetAutoHide(); + + /** + Retrieve whether auto-completion cancelled by backspacing before start. + */ + bool AutoCompGetCancelAtStart(); + + /** + Retrieve whether a single item auto-completion list automatically choose the + item. + */ + bool AutoCompGetChooseSingle(); + + /** + Get currently selected item position in the auto-completion list + */ + int AutoCompGetCurrent(); + + /** + Retrieve whether or not autocompletion deletes any word characters + after the inserted text upon completion. + */ + bool AutoCompGetDropRestOfWord(); + + /** + Retrieve state of ignore case flag. + */ + bool AutoCompGetIgnoreCase(); + + /** + Set the maximum height, in rows, of auto-completion and user lists. + */ + int AutoCompGetMaxHeight(); + + /** + Get the maximum width, in characters, of auto-completion and user lists. + */ + int AutoCompGetMaxWidth(); + + /** + Retrieve the auto-completion list separator character. + */ + int AutoCompGetSeparator(); + + /** + Retrieve the auto-completion list type-separator character. + */ + int AutoCompGetTypeSeparator(); + + /** + Retrieve the position of the caret when the auto-completion list was displayed. + */ + int AutoCompPosStart(); + + /** + Select the item in the auto-completion list that starts with a string. + */ + void AutoCompSelect(const wxString& text); + + /** + Set whether or not autocompletion is hidden automatically when nothing matches. + */ + void AutoCompSetAutoHide(bool autoHide); + + /** + Should the auto-completion list be cancelled if the user backspaces to a + position before where the box was created. + */ + void AutoCompSetCancelAtStart(bool cancel); + + /** + Should a single item auto-completion list automatically choose the item. + */ + void AutoCompSetChooseSingle(bool chooseSingle); + + /** + Set whether or not autocompletion deletes any word characters + after the inserted text upon completion. + */ + void AutoCompSetDropRestOfWord(bool dropRestOfWord); + + /** + Define a set of characters that when typed will cause the autocompletion to + choose the selected item. + */ + void AutoCompSetFillUps(const wxString& characterSet); + + /** + Set whether case is significant when performing auto-completion searches. + */ + void AutoCompSetIgnoreCase(bool ignoreCase); + + /** + Set the maximum height, in rows, of auto-completion and user lists. + The default is 5 rows. + */ + void AutoCompSetMaxHeight(int rowCount); + + /** + Set the maximum width, in characters, of auto-completion and user lists. + Set to 0 to autosize to fit longest item, which is the default. + */ + void AutoCompSetMaxWidth(int characterCount); + + /** + Change the separator character in the string setting up an auto-completion list. + Default is space but can be changed if items contain space. + */ + void AutoCompSetSeparator(int separatorCharacter); + + /** + Change the type-separator character in the string setting up an auto-completion + list. + Default is '?' but can be changed if items contain '?'. + */ + void AutoCompSetTypeSeparator(int separatorCharacter); + + /** + Display a auto-completion list. + The lenEntered parameter indicates how many characters before + the caret should be used to provide context. + */ + void AutoCompShow(int lenEntered, const wxString& itemList); + + /** + Define a set of character that when typed cancel the auto-completion list. + */ + void AutoCompStops(const wxString& characterSet); + + /** + Dedent the selected lines. + */ + void BackTab(); + + /** + Start a sequence of actions that is undone and redone as a unit. + May be nested. + */ + void BeginUndoAction(); + + /** + Highlight the character at a position indicating there is no matching brace. + */ + void BraceBadLight(int pos); + + /** + Highlight the characters at two positions. + */ + void BraceHighlight(int pos1, int pos2); + + /** + Find the position of a matching brace or INVALID_POSITION if no match. + */ + int BraceMatch(int pos); + + /** + Is there an active call tip? + */ + bool CallTipActive(); + + /** + Remove the call tip from the screen. + */ + void CallTipCancel(); + + /** + Retrieve the position where the caret was before displaying the call tip. + */ + int CallTipPosAtStart(); + + /** + Set the background colour for the call tip. + */ + void CallTipSetBackground(const wxColour& back); + + /** + Set the foreground colour for the call tip. + */ + void CallTipSetForeground(const wxColour& fore); + + /** + Set the foreground colour for the highlighted part of the call tip. + */ + void CallTipSetForegroundHighlight(const wxColour& fore); + + /** + Highlight a segment of the definition. + */ + void CallTipSetHighlight(int start, int end); + + /** + Show a call tip containing a definition near position pos. + */ + void CallTipShow(int pos, const wxString& definition); + + /** + Enable use of STYLE_CALLTIP and set call tip tab size in pixels. + */ + void CallTipUseStyle(int tabSize); + + /** + Will a paste succeed? + */ + bool CanPaste(); + + /** + Are there any redoable actions in the undo history? + */ + bool CanRedo(); + + /** + Are there any undoable actions in the undo history? + */ + bool CanUndo(); + + /** + Cancel any modes such as call tip or auto-completion list display. + */ + void Cancel(); + + /** + Move caret left one character. + */ + void CharLeft(); + + /** + Move caret left one character extending selection to new caret position. + */ + void CharLeftExtend(); + + /** + Move caret left one character, extending rectangular selection to new caret + position. + */ + void CharLeftRectExtend(); + + /** + Move caret right one character. + */ + void CharRight(); + + /** + Move caret right one character extending selection to new caret position. + */ + void CharRightExtend(); + + /** + Move caret right one character, extending rectangular selection to new caret + position. + */ + void CharRightRectExtend(); + + /** + Set the last x chosen value to be the caret x position. + */ + void ChooseCaretX(); + + /** + Clear the selection. + */ + void Clear(); + + /** + Delete all text in the document. + */ + void ClearAll(); + + /** + Set all style bytes to 0, remove all folding information. + */ + void ClearDocumentStyle(); + + /** + Clear all the registered images. + */ + void ClearRegisteredImages(); + + /** + When key+modifier combination km is pressed perform msg. + */ + void CmdKeyAssign(int key, int modifiers, int cmd); + + /** + When key+modifier combination km is pressed do nothing. + */ + void CmdKeyClear(int key, int modifiers); + + /** + Drop all key mappings. + */ + void CmdKeyClearAll(); + + /** + Perform one of the operations defined by the wxSTC_CMD_* constants. + */ + void CmdKeyExecute(int cmd); + + /** + Colourise a segment of the document using the current lexing language. + */ + void Colourise(int start, int end); + + /** + Convert all line endings in the document to one mode. + */ + void ConvertEOLs(int eolMode); + + /** + Copy the selection to the clipboard. + */ + void Copy(); + + /** + Copy a range of text to the clipboard. Positions are clipped into the document. + */ + void CopyRange(int start, int end); + + /** + Copy argument text to the clipboard. + */ + void CopyText(int length, const wxString& text); + + /** + + */ + bool Create(wxWindow* parent, wxWindowID id = wxID_ANY, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0, + const wxString& name = wxSTCNameStr); + + /** + Create a new document object. + Starts with reference count of 1 and not selected into editor. + */ + void* CreateDocument(); + + /** + Cut the selection to the clipboard. + */ + void Cut(); + + /** + Delete back from the current position to the start of the line. + */ + void DelLineLeft(); + + /** + Delete forwards from the current position to the end of the line. + */ + void DelLineRight(); + + /** + Delete the word to the left of the caret. + */ + void DelWordLeft(); + + /** + Delete the word to the right of the caret. + */ + void DelWordRight(); + + /** + Delete the selection or if no selection, the character before the caret. + */ + void DeleteBack(); + + /** + Delete the selection or if no selection, the character before the caret. + Will not delete the character before at the start of a line. + */ + void DeleteBackNotLine(); + + /** + Allow for simulating a DnD DragOver + */ + wxDragResult DoDragOver(wxCoord x, wxCoord y, wxDragResult def); + + /** + Allow for simulating a DnD DropText + */ + bool DoDropText(long x, long y, const wxString& data); + + /** + Find the document line of a display line taking hidden lines into account. + */ + int DocLineFromVisible(int lineDisplay); + + /** + Move caret to last position in document. + */ + void DocumentEnd(); + + /** + Move caret to last position in document extending selection to new caret + position. + */ + void DocumentEndExtend(); + + /** + Move caret to first position in document. + */ + void DocumentStart(); + + /** + Move caret to first position in document extending selection to new caret + position. + */ + void DocumentStartExtend(); + + /** + Switch from insert to overtype mode or the reverse. + */ + void EditToggleOvertype(); + + /** + Delete the undo history. + */ + void EmptyUndoBuffer(); + + /** + End a sequence of actions that is undone and redone as a unit. + */ + void EndUndoAction(); + + /** + Ensure the caret is visible. + */ + void EnsureCaretVisible(); + + /** + Ensure a particular line is visible by expanding any header line hiding it. + */ + void EnsureVisible(int line); + + /** + Ensure a particular line is visible by expanding any header line hiding it. + Use the currently set visibility policy to determine which range to display. + */ + void EnsureVisibleEnforcePolicy(int line); + + /** + Find the position of a column on a line taking into account tabs and + multi-byte characters. If beyond end of line, return line end position. + */ + int FindColumn(int line, int column); + + /** + Find some text in the document. + */ + int FindText(int minPos, int maxPos, const wxString& text, + int flags = 0); + + /** + Insert a Form Feed character. + */ + void FormFeed(); + + /** + On Windows, will draw the document into a display context such as a printer. + */ + int FormatRange(bool doDraw, int startPos, int endPos, + wxDC* draw, wxDC* target, + wxRect renderRect, + wxRect pageRect); + + /** + Returns the position of the opposite end of the selection to the caret. + */ + int GetAnchor(); + + /** + Does a backspace pressed when caret is within indentation unindent? + */ + bool GetBackSpaceUnIndents(); + + /** + Is drawing done first into a buffer or direct to the screen? + */ + bool GetBufferedDraw(); + + /** + Get the foreground colour of the caret. + */ + wxColour GetCaretForeground(); + + /** + Get the background alpha of the caret line. + */ + int GetCaretLineBackAlpha(); + + /** + Get the colour of the background of the line containing the caret. + */ + wxColour GetCaretLineBackground(); + + /** + Is the background of the line containing the caret in a different colour? + */ + bool GetCaretLineVisible(); + + /** + Get the time in milliseconds that the caret is on and off. + */ + int GetCaretPeriod(); + + /** + Can the caret preferred x position only be changed by explicit movement + commands? + */ + bool GetCaretSticky(); + + /** + Returns the width of the insert mode caret. + */ + int GetCaretWidth(); + + /** + Returns the character byte at the position. + */ + int GetCharAt(int pos); + + /** + Get the code page used to interpret the bytes of the document as characters. + */ + int GetCodePage(); + + /** + Retrieve the column number of a position, taking tab width into account. + */ + int GetColumn(int pos); + + /** + Get the way control characters are displayed. + */ + int GetControlCharSymbol(); + + /** + + */ + wxString GetCurLine(int* OUTPUT); + + /** + + */ + wxCharBuffer GetCurLineRaw(int* OUTPUT); + + /** + END of generated section + Others... + Returns the line number of the line with the caret. + */ + int GetCurrentLine(); + + /** + Returns the position of the caret. + */ + int GetCurrentPos(); + + /** + Retrieve a pointer to the document object. + */ + void* GetDocPointer(); + + /** + Retrieve the current end of line mode - one of CRLF, CR, or LF. + */ + int GetEOLMode(); + + /** + Retrieve the colour used in edge indication. + */ + wxColour GetEdgeColour(); + + /** + Retrieve the column number which text should be kept within. + */ + int GetEdgeColumn(); + + /** + Retrieve the edge highlight mode. + */ + int GetEdgeMode(); + + /** + Retrieve whether the maximum scroll position has the last + line at the bottom of the view. + */ + bool GetEndAtLastLine(); + + /** + Retrieve the position of the last correctly styled character. + */ + int GetEndStyled(); + + /** + Retrieve the display line at the top of the display. + */ + int GetFirstVisibleLine(); + + /** + Is a header line expanded? + */ + bool GetFoldExpanded(int line); + + /** + Retrieve the fold level of a line. + */ + int GetFoldLevel(int line); + + /** + Find the parent line of a child line. + */ + int GetFoldParent(int line); + + /** + Get the highlighted indentation guide column. + */ + int GetHighlightGuide(); + + /** + Retrieve indentation size. + */ + int GetIndent(); + + /** + Are the indentation guides visible? + */ + bool GetIndentationGuides(); + + /** + Find the last child line of a header line. + */ + int GetLastChild(int line, int level); + + /** + Can be used to prevent the EVT_CHAR handler from adding the char + */ + bool GetLastKeydownProcessed(); + + /** + Retrieve the degree of caching of layout information. + */ + int GetLayoutCache(); + + /** + Returns the number of characters in the document. + */ + int GetLength(); + + /** + Retrieve the lexing language of the document. + */ + int GetLexer(); + + /** + Retrieve the contents of a line. + */ + wxString GetLine(int line); + + /** + Returns the number of lines in the document. There is always at least one. + */ + int GetLineCount(); + + /** + Get the position after the last visible characters on a line. + */ + int GetLineEndPosition(int line); + + /** + Retrieve the position before the first non indentation character on a line. + */ + int GetLineIndentPosition(int line); + + /** + Retrieve the number of columns that a line is indented. + */ + int GetLineIndentation(int line); + + /** + Retrieve the contents of a line. + */ + wxCharBuffer GetLineRaw(int line); + + /** + Retrieve the position of the end of the selection at the given line + (INVALID_POSITION if no selection on this line). + */ + int GetLineSelEndPosition(int line); + + /** + Retrieve the position of the start of the selection at the given line + (INVALID_POSITION if no selection on this line). + */ + int GetLineSelStartPosition(int line); + + /** + Retrieve the extra styling information for a line. + */ + int GetLineState(int line); + + /** + Is a line visible? + */ + bool GetLineVisible(int line); + + /** + Returns the size in pixels of the left margin. + */ + int GetMarginLeft(); + + /** + Retrieve the marker mask of a margin. + */ + int GetMarginMask(int margin); + + /** + Returns the size in pixels of the right margin. + */ + int GetMarginRight(); + + /** + Retrieve the mouse click sensitivity of a margin. + */ + bool GetMarginSensitive(int margin); + + /** + Retrieve the type of a margin. + */ + int GetMarginType(int margin); + + /** + Retrieve the width of a margin in pixels. + */ + int GetMarginWidth(int margin); + + /** + Retrieve the last line number that has line state. + */ + int GetMaxLineState(); + + /** + Get which document modification events are sent to the container. + */ + int GetModEventMask(); + + /** + Is the document different from when it was last saved? + */ + bool GetModify(); + + /** + Get whether mouse gets captured. + */ + bool GetMouseDownCaptures(); + + /** + Retrieve the time the mouse must sit still to generate a mouse dwell event. + */ + int GetMouseDwellTime(); + + /** + Returns @true if overtype mode is active otherwise @false is returned. + */ + bool GetOvertype(); + + /** + Get convert-on-paste setting + */ + bool GetPasteConvertEndings(); + + /** + Returns the print colour mode. + */ + int GetPrintColourMode(); + + /** + Returns the print magnification. + */ + int GetPrintMagnification(); + + /** + Is printing line wrapped? + */ + int GetPrintWrapMode(); + + /** + Retrieve a 'property' value previously set with SetProperty. + */ + wxString GetProperty(const wxString& key); + + /** + Retrieve a 'property' value previously set with SetProperty, + with '$()' variable replacement on returned buffer. + */ + wxString GetPropertyExpanded(const wxString& key); + + /** + Retrieve a 'property' value previously set with SetProperty, + interpreted as an int AFTER any '$()' variable replacement. + */ + int GetPropertyInt(const wxString& key); + + /** + In read-only mode? + */ + bool GetReadOnly(); + + /** + Get cursor type. + */ + int GetSTCCursor(); + + /** + Get internal focus flag. + */ + bool GetSTCFocus(); + + /** + Retrieve the document width assumed for scrolling. + */ + int GetScrollWidth(); + + /** + Get the search flags used by SearchInTarget. + */ + int GetSearchFlags(); + + /** + Get the alpha of the selection. + */ + int GetSelAlpha(); + + /** + Retrieve the selected text. + */ + wxString GetSelectedText(); + + /** + Retrieve the selected text. + */ + wxCharBuffer GetSelectedTextRaw(); + + /** + + */ + void GetSelection(int* OUTPUT, int* OUTPUT); + + /** + Returns the position at the end of the selection. + */ + int GetSelectionEnd(); + + /** + Get the mode of the current selection. + */ + int GetSelectionMode(); + + /** + Returns the position at the start of the selection. + */ + int GetSelectionStart(); + + /** + Get error status. + */ + int GetStatus(); + + /** + Returns the style byte at the position. + */ + int GetStyleAt(int pos); + + /** + Retrieve number of bits in style bytes used to hold the lexical state. + */ + int GetStyleBits(); + + /** + Retrieve the number of bits the current lexer needs for styling. + */ + int GetStyleBitsNeeded(); + + /** + Retrieve a buffer of cells. + */ + wxMemoryBuffer GetStyledText(int startPos, int endPos); + + /** + Does a tab pressed when caret is within indentation indent? + */ + bool GetTabIndents(); + + /** + Retrieve the visible size of a tab. + */ + int GetTabWidth(); + + /** + Get the position that ends the target. + */ + int GetTargetEnd(); + + /** + Get the position that starts the target. + */ + int GetTargetStart(); + + /** + Retrieve all the text in the document. + */ + wxString GetText(); + + /** + Retrieve the number of characters in the document. + */ + int GetTextLength(); + + /** + Retrieve a range of text. + */ + wxString GetTextRange(int startPos, int endPos); + + /** + Retrieve a range of text. + */ + wxCharBuffer GetTextRangeRaw(int startPos, int endPos); + + /** + Retrieve all the text in the document. + */ + wxCharBuffer GetTextRaw(); + + /** + Is drawing done in two phases with backgrounds drawn before foregrounds? + */ + bool GetTwoPhaseDraw(); + + /** + Is undo history being collected? + */ + bool GetUndoCollection(); + + /** + Returns the current UseAntiAliasing setting. + */ + bool GetUseAntiAliasing(); + + /** + Is the horizontal scroll bar visible? + */ + bool GetUseHorizontalScrollBar(); + + /** + Retrieve whether tabs will be used in indentation. + */ + bool GetUseTabs(); + + /** + Is the vertical scroll bar visible? + */ + bool GetUseVerticalScrollBar(); + + /** + Are the end of line characters visible? + */ + bool GetViewEOL(); + + /** + Are white space characters currently visible? + Returns one of SCWS_* constants. + */ + int GetViewWhiteSpace(); + + /** + Retrieve whether text is word wrapped. + */ + int GetWrapMode(); + + /** + Retrive the start indent for wrapped lines. + */ + int GetWrapStartIndent(); + + /** + Retrive the display mode of visual flags for wrapped lines. + */ + int GetWrapVisualFlags(); + + /** + Retrive the location of visual flags for wrapped lines. + */ + int GetWrapVisualFlagsLocation(); + + /** + + */ + int GetXOffset(); + + /** + Retrieve the zoom level. + */ + int GetZoom(); + + /** + Set caret to start of a line and ensure it is visible. + */ + void GotoLine(int line); + + /** + Set caret to a position and ensure it is visible. + */ + void GotoPos(int pos); + + /** + Make a range of lines invisible. + */ + void HideLines(int lineStart, int lineEnd); + + /** + Draw the selection in normal style or with selection highlighted. + */ + void HideSelection(bool normal); + + /** + Move caret to first position on line. + */ + void Home(); + + /** + Move caret to first position on display line. + */ + void HomeDisplay(); + + /** + Move caret to first position on display line extending selection to + new caret position. + */ + void HomeDisplayExtend(); + + /** + Move caret to first position on line extending selection to new caret position. + */ + void HomeExtend(); + + /** + Move caret to first position on line, extending rectangular selection to new + caret position. + */ + void HomeRectExtend(); + + /** + These are like their namesakes Home(Extend)?, LineEnd(Extend)?, VCHome(Extend)? + except they behave differently when word-wrap is enabled: + They go first to the start / end of the display line, like (Home|LineEnd)Display + The difference is that, the cursor is already at the point, it goes on to the + start + or end of the document line, as appropriate for (Home|LineEnd|VCHome)(Extend)?. + */ + void HomeWrap(); + + /** + + */ + void HomeWrapExtend(); + + /** + Retrieve the foreground colour of an indicator. + */ + wxColour IndicatorGetForeground(int indic); + + /** + Retrieve the style of an indicator. + */ + int IndicatorGetStyle(int indic); + + /** + Set the foreground colour of an indicator. + */ + void IndicatorSetForeground(int indic, const wxColour& fore); + + /** + Set an indicator to plain, squiggle or TT. + */ + void IndicatorSetStyle(int indic, int style); + + /** + Insert string at a position. + */ + void InsertText(int pos, const wxString& text); + + /** + Insert string at a position. + */ + void InsertTextRaw(int pos, const char* text); + + /** + Copy the line containing the caret. + */ + void LineCopy(); + + /** + Cut the line containing the caret. + */ + void LineCut(); + + /** + Delete the line containing the caret. + */ + void LineDelete(); + + /** + Move caret down one line. + */ + void LineDown(); + + /** + Move caret down one line extending selection to new caret position. + */ + void LineDownExtend(); + + /** + Move caret down one line, extending rectangular selection to new caret position. + */ + void LineDownRectExtend(); + + /** + Duplicate the current line. + */ + void LineDuplicate(); + + /** + Move caret to last position on line. + */ + void LineEnd(); + + /** + Move caret to last position on display line. + */ + void LineEndDisplay(); + + /** + Move caret to last position on display line extending selection to new + caret position. + */ + void LineEndDisplayExtend(); + + /** + Move caret to last position on line extending selection to new caret position. + */ + void LineEndExtend(); + + /** + Move caret to last position on line, extending rectangular selection to new + caret position. + */ + void LineEndRectExtend(); + + /** + + */ + void LineEndWrap(); + + /** + + */ + void LineEndWrapExtend(); + + /** + Retrieve the line containing a position. + */ + int LineFromPosition(int pos); + + /** + How many characters are on a line, not including end of line characters? + */ + int LineLength(int line); + + /** + Scroll horizontally and vertically. + */ + void LineScroll(int columns, int lines); + + /** + Scroll the document down, keeping the caret visible. + */ + void LineScrollDown(); + + /** + Scroll the document up, keeping the caret visible. + */ + void LineScrollUp(); + + /** + Switch the current line with the previous. + */ + void LineTranspose(); + + /** + Move caret up one line. + */ + void LineUp(); + + /** + Move caret up one line extending selection to new caret position. + */ + void LineUpExtend(); + + /** + Move caret up one line, extending rectangular selection to new caret position. + */ + void LineUpRectExtend(); + + /** + Join the lines in the target. + */ + void LinesJoin(); + + /** + Retrieves the number of lines completely visible. + */ + int LinesOnScreen(); + + /** + Split the lines in the target into lines that are less wide than pixelWidth + where possible. + */ + void LinesSplit(int pixelWidth); + + /** + Load the contents of filename into the editor + */ + bool LoadFile(const wxString& filename); + + /** + Transform the selection to lower case. + */ + void LowerCase(); + + /** + Add a marker to a line, returning an ID which can be used to find or delete the + marker. + */ + int MarkerAdd(int line, int markerNumber); + + /** + Add a set of markers to a line. + */ + void MarkerAddSet(int line, int set); + + /** + Set the symbol used for a particular marker number, + and optionally the fore and background colours. + */ + void MarkerDefine(int markerNumber, int markerSymbol, + const wxColour& foreground = wxNullColour, + const wxColour& background = wxNullColour); + + /** + Define a marker from a bitmap + */ + void MarkerDefineBitmap(int markerNumber, const wxBitmap& bmp); + + /** + Delete a marker from a line. + */ + void MarkerDelete(int line, int markerNumber); + + /** + Delete all markers with a particular number from all lines. + */ + void MarkerDeleteAll(int markerNumber); + + /** + Delete a marker. + */ + void MarkerDeleteHandle(int handle); + + /** + Get a bit mask of all the markers set on a line. + */ + int MarkerGet(int line); + + /** + Retrieve the line number at which a particular marker is located. + */ + int MarkerLineFromHandle(int handle); + + /** + Find the next line after lineStart that includes a marker in mask. + */ + int MarkerNext(int lineStart, int markerMask); + + /** + Find the previous line before lineStart that includes a marker in mask. + */ + int MarkerPrevious(int lineStart, int markerMask); + + /** + Set the alpha used for a marker that is drawn in the text area, not the margin. + */ + void MarkerSetAlpha(int markerNumber, int alpha); + + /** + Set the background colour used for a particular marker number. + */ + void MarkerSetBackground(int markerNumber, const wxColour& back); + + /** + Set the foreground colour used for a particular marker number. + */ + void MarkerSetForeground(int markerNumber, const wxColour& fore); + + /** + Move the caret inside current view if it's not there already. + */ + void MoveCaretInsideView(); + + /** + Insert a new line, may use a CRLF, CR or LF depending on EOL mode. + */ + void NewLine(); + + /** + Move caret one page down. + */ + void PageDown(); + + /** + Move caret one page down extending selection to new caret position. + */ + void PageDownExtend(); + + /** + Move caret one page down, extending rectangular selection to new caret position. + */ + void PageDownRectExtend(); + + /** + Move caret one page up. + */ + void PageUp(); + + /** + Move caret one page up extending selection to new caret position. + */ + void PageUpExtend(); + + /** + Move caret one page up, extending rectangular selection to new caret position. + */ + void PageUpRectExtend(); + + /** + Move caret between paragraphs (delimited by empty lines). + */ + void ParaDown(); + + /** + + */ + void ParaDownExtend(); + + /** + + */ + void ParaUp(); + + /** + + */ + void ParaUpExtend(); + + /** + Paste the contents of the clipboard into the document replacing the selection. + */ + void Paste(); + + /** + Retrieve the point in the window where a position is displayed. + */ + wxPoint PointFromPosition(int pos); + + /** + Given a valid document position, return the next position taking code + page into account. Maximum value returned is the last position in the document. + */ + int PositionAfter(int pos); + + /** + Given a valid document position, return the previous position taking code + page into account. Returns 0 if passed 0. + */ + int PositionBefore(int pos); + + /** + Retrieve the position at the start of a line. + */ + int PositionFromLine(int line); + + /** + Find the position from a point within the window. + */ + int PositionFromPoint(wxPoint pt); + + /** + Find the position from a point within the window but return + INVALID_POSITION if not close to text. + */ + int PositionFromPointClose(int x, int y); + + /** + Redoes the next action on the undo history. + */ + void Redo(); + + /** + Register an image for use in autocompletion lists. + */ + void RegisterImage(int type, const wxBitmap& bmp); + + /** + Release a reference to the document, deleting document if it fades to black. + */ + void ReleaseDocument(void* docPointer); + + /** + Replace the selected text with the argument text. + */ + void ReplaceSelection(const wxString& text); + + /** + Replace the target text with the argument text. + Text is counted so it can contain NULs. + Returns the length of the replacement text. + */ + int ReplaceTarget(const wxString& text); + + /** + Replace the target text with the argument text after + d processing. + Text is counted so it can contain NULs. + Looks for + d where d is between 1 and 9 and replaces these with the strings + matched in the last search operation which were surrounded by + ( and + ). + Returns the length of the replacement text including any change + caused by processing the + d patterns. + */ + int ReplaceTargetRE(const wxString& text); + + /** + Write the contents of the editor to filename + */ + bool SaveFile(const wxString& filename); + + /** + Scroll enough to make the given column visible + */ + void ScrollToColumn(int column); + + /** + Scroll enough to make the given line visible + */ + void ScrollToLine(int line); + + /** + Sets the current caret position to be the search anchor. + */ + void SearchAnchor(); + + /** + Search for a counted string in the target and set the target to the found + range. Text is counted so it can contain NULs. + Returns length of range or -1 for failure in which case target is not moved. + */ + int SearchInTarget(const wxString& text); + + /** + Find some text starting at the search anchor. + Does not ensure the selection is visible. + */ + int SearchNext(int flags, const wxString& text); + + /** + Find some text starting at the search anchor and moving backwards. + Does not ensure the selection is visible. + */ + int SearchPrev(int flags, const wxString& text); + + /** + Select all the text in the document. + */ + void SelectAll(); + + /** + Duplicate the selection. If selection empty duplicate the line containing the + caret. + */ + void SelectionDuplicate(); + + /** + Is the selection rectangular? The alternative is the more common stream + selection. + */ + bool SelectionIsRectangle(); + + /** + Send a message to Scintilla + */ + long SendMsg(int msg, long wp = 0, long lp = 0); + + /** + Set the selection anchor to a position. The anchor is the opposite + end of the selection from the caret. + */ + void SetAnchor(int posAnchor); + + /** + Sets whether a backspace pressed when caret is within indentation unindents. + */ + void SetBackSpaceUnIndents(bool bsUnIndents); + + /** + If drawing is buffered then each line of text is drawn into a bitmap buffer + before drawing it to the screen to avoid flicker. + */ + void SetBufferedDraw(bool buffered); + + /** + Set the foreground colour of the caret. + */ + void SetCaretForeground(const wxColour& fore); + + /** + Set background alpha of the caret line. + */ + void SetCaretLineBackAlpha(int alpha); + + /** + Set the colour of the background of the line containing the caret. + */ + void SetCaretLineBackground(const wxColour& back); + + /** + Display the background of the line containing the caret in a different colour. + */ + void SetCaretLineVisible(bool show); + + /** + Get the time in milliseconds that the caret is on and off. 0 = steady on. + */ + void SetCaretPeriod(int periodMilliseconds); + + /** + Stop the caret preferred x position changing when the user types. + */ + void SetCaretSticky(bool useCaretStickyBehaviour); + + /** + Set the width of the insert mode caret. + */ + void SetCaretWidth(int pixelWidth); + + /** + Reset the set of characters for whitespace and word characters to the defaults. + */ + void SetCharsDefault(); + + /** + Set the code page used to interpret the bytes of the document as characters. + */ + void SetCodePage(int codePage); + + /** + Change the way control characters are displayed: + If symbol is 32, keep the drawn way, else, use the given character. + */ + void SetControlCharSymbol(int symbol); + + /** + Sets the position of the caret. + */ + void SetCurrentPos(int pos); + + /** + Change the document object used. + */ + void SetDocPointer(void* docPointer); + + /** + Set the current end of line mode. + */ + void SetEOLMode(int eolMode); + + /** + Change the colour used in edge indication. + */ + void SetEdgeColour(const wxColour& edgeColour); + + /** + Set the column number of the edge. + If text goes past the edge then it is highlighted. + */ + void SetEdgeColumn(int column); + + /** + The edge may be displayed by a line (EDGE_LINE) or by highlighting text that + goes beyond it (EDGE_BACKGROUND) or not displayed at all (EDGE_NONE). + */ + void SetEdgeMode(int mode); + + /** + Sets the scroll range so that maximum scroll position has + the last line at the bottom of the view (default). + Setting this to @false allows scrolling one page below the last line. + */ + void SetEndAtLastLine(bool endAtLastLine); + + /** + Show the children of a header line. + */ + void SetFoldExpanded(int line, bool expanded); + + /** + Set some style options for folding. + */ + void SetFoldFlags(int flags); + + /** + Set the fold level of a line. + This encodes an integer level along with flags indicating whether the + line is a header and whether it is effectively white space. + */ + void SetFoldLevel(int line, int level); + + /** + Set the colours used as a chequerboard pattern in the fold margin + */ + void SetFoldMarginColour(bool useSetting, const wxColour& back); + + /** + + */ + void SetFoldMarginHiColour(bool useSetting, const wxColour& fore); + + /** + Set the horizontal scrollbar to use instead of the ont that's built-in. + */ + void SetHScrollBar(wxScrollBar* bar); + + /** + Set the highlighted indentation guide column. + 0 = no highlighted guide. + */ + void SetHighlightGuide(int column); + + /** + Set a back colour for active hotspots. + */ + void SetHotspotActiveBackground(bool useSetting, + const wxColour& back); + + /** + Set a fore colour for active hotspots. + */ + void SetHotspotActiveForeground(bool useSetting, + const wxColour& fore); + + /** + Enable / Disable underlining active hotspots. + */ + void SetHotspotActiveUnderline(bool underline); + + /** + Limit hotspots to single line so hotspots on two lines don't merge. + */ + void SetHotspotSingleLine(bool singleLine); + + /** + Set the number of spaces used for one level of indentation. + */ + void SetIndent(int indentSize); + + /** + Show or hide indentation guides. + */ + void SetIndentationGuides(bool show); + + /** + Set up the key words used by the lexer. + */ + void SetKeyWords(int keywordSet, const wxString& keyWords); + + /** + + */ + void SetLastKeydownProcessed(bool val); + + /** + Sets the degree of caching of layout information. + */ + void SetLayoutCache(int mode); + + /** + Set the lexing language of the document. + */ + void SetLexer(int lexer); + + /** + Set the lexing language of the document based on string name. + */ + void SetLexerLanguage(const wxString& language); + + /** + Change the indentation of a line to a number of columns. + */ + void SetLineIndentation(int line, int indentSize); + + /** + Used to hold extra styling information for each line. + */ + void SetLineState(int line, int state); + + /** + Sets the size in pixels of the left margin. + */ + void SetMarginLeft(int pixelWidth); + + /** + Set a mask that determines which markers are displayed in a margin. + */ + void SetMarginMask(int margin, int mask); + + /** + Sets the size in pixels of the right margin. + */ + void SetMarginRight(int pixelWidth); + + /** + Make a margin sensitive or insensitive to mouse clicks. + */ + void SetMarginSensitive(int margin, bool sensitive); + + /** + Set a margin to be either numeric or symbolic. + */ + void SetMarginType(int margin, int marginType); + + /** + Set the width of a margin to a width expressed in pixels. + */ + void SetMarginWidth(int margin, int pixelWidth); + + /** + Set the left and right margin in the edit area, measured in pixels. + */ + void SetMargins(int left, int right); + + /** + Set which document modification events are sent to the container. + */ + void SetModEventMask(int mask); + + /** + Set whether the mouse is captured when its button is pressed. + */ + void SetMouseDownCaptures(bool captures); + + /** + Sets the time the mouse must sit still to generate a mouse dwell event. + */ + void SetMouseDwellTime(int periodMilliseconds); + + /** + Set to overtype (@true) or insert mode. + */ + void SetOvertype(bool overtype); + + /** + Enable/Disable convert-on-paste for line endings + */ + void SetPasteConvertEndings(bool convert); + + /** + Modify colours when printing for clearer printed text. + */ + void SetPrintColourMode(int mode); + + /** + Sets the print magnification added to the point size of each style for printing. + */ + void SetPrintMagnification(int magnification); + + /** + Set printing to line wrapped (SC_WRAP_WORD) or not line wrapped (SC_WRAP_NONE). + */ + void SetPrintWrapMode(int mode); + + /** + Set up a value that may be used by a lexer for some optional feature. + */ + void SetProperty(const wxString& key, const wxString& value); + + /** + Set to read only or read write. + */ + void SetReadOnly(bool readOnly); + + /** + Sets the cursor to one of the SC_CURSOR* values. + */ + void SetSTCCursor(int cursorType); + + /** + Change internal focus flag. + */ + void SetSTCFocus(bool focus); + + /** + Remember the current position in the undo history as the position + at which the document was saved. + */ + void SetSavePoint(); + + /** + Sets the document width assumed for scrolling. + */ + void SetScrollWidth(int pixelWidth); + + /** + Set the search flags used by SearchInTarget. + */ + void SetSearchFlags(int flags); + + /** + Set the alpha of the selection. + */ + void SetSelAlpha(int alpha); + + /** + Set the background colour of the selection and whether to use this setting. + */ + void SetSelBackground(bool useSetting, const wxColour& back); + + /** + Set the foreground colour of the selection and whether to use this setting. + */ + void SetSelForeground(bool useSetting, const wxColour& fore); + + /** + Select a range of text. + */ + void SetSelection(int start, int end); + + /** + Sets the position that ends the selection - this becomes the currentPosition. + */ + void SetSelectionEnd(int pos); + + /** + Set the selection mode to stream (SC_SEL_STREAM) or rectangular + (SC_SEL_RECTANGLE) or + by lines (SC_SEL_LINES). + */ + void SetSelectionMode(int mode); + + /** + Sets the position that starts the selection - this becomes the anchor. + */ + void SetSelectionStart(int pos); + + /** + Change error status - 0 = OK. + */ + void SetStatus(int statusCode); + + /** + Divide each styling byte into lexical class bits (default: 5) and indicator + bits (default: 3). If a lexer requires more than 32 lexical states, then this + is used to expand the possible states. + */ + void SetStyleBits(int bits); + + /** + Set the styles for a segment of the document. + */ + void SetStyleBytes(int length, char* styleBytes); + + /** + Change style from current styling position for length characters to a style + and move the current styling position to after this newly styled segment. + */ + void SetStyling(int length, int style); + + /** + Sets whether a tab pressed when caret is within indentation indents. + */ + void SetTabIndents(bool tabIndents); + + /** + Change the visible size of a tab to be a multiple of the width of a space + character. + */ + void SetTabWidth(int tabWidth); + + /** + Sets the position that ends the target which is used for updating the + document without affecting the scroll position. + */ + void SetTargetEnd(int pos); + + /** + Sets the position that starts the target which is used for updating the + document without affecting the scroll position. + */ + void SetTargetStart(int pos); + + /** + Replace the contents of the document with the argument text. + */ + void SetText(const wxString& text); + + /** + Replace the contents of the document with the argument text. + */ + void SetTextRaw(const char* text); + + /** + In twoPhaseDraw mode, drawing is performed in two phases, first the background + and then the foreground. This avoids chopping off characters that overlap the + next run. + */ + void SetTwoPhaseDraw(bool twoPhase); + + /** + Choose between collecting actions into the undo + history and discarding them. + */ + void SetUndoCollection(bool collectUndo); + + /** + Specify whether anti-aliased fonts should be used. Will have no effect + on some platforms, but on some (wxMac for example) can greatly improve + performance. + */ + void SetUseAntiAliasing(bool useAA); + + /** + Show or hide the horizontal scroll bar. + */ + void SetUseHorizontalScrollBar(bool show); + + /** + Indentation will only use space characters if useTabs is @false, otherwise + it will use a combination of tabs and spaces. + */ + void SetUseTabs(bool useTabs); + + /** + Show or hide the vertical scroll bar. + */ + void SetUseVerticalScrollBar(bool show); + + /** + Set the vertical scrollbar to use instead of the ont that's built-in. + */ + void SetVScrollBar(wxScrollBar* bar); + + /** + Make the end of line characters visible or invisible. + */ + void SetViewEOL(bool visible); + + /** + Make white space characters invisible, always visible or visible outside + indentation. + */ + void SetViewWhiteSpace(int viewWS); + + /** + Set the way the display area is determined when a particular line + is to be moved to by Find, FindNext, GotoLine, etc. + */ + void SetVisiblePolicy(int visiblePolicy, int visibleSlop); + + /** + Set the background colour of all whitespace and whether to use this setting. + */ + void SetWhitespaceBackground(bool useSetting, + const wxColour& back); + + /** + Set the set of characters making up whitespace for when moving or selecting by + word. + Should be called after SetWordChars. + */ + void SetWhitespaceChars(const wxString& characters); + + /** + Set the foreground colour of all whitespace and whether to use this setting. + */ + void SetWhitespaceForeground(bool useSetting, + const wxColour& fore); + + /** + Set the set of characters making up words for when moving or selecting by word. + First sets deaults like SetCharsDefault. + */ + void SetWordChars(const wxString& characters); + + /** + Sets whether text is word wrapped. + */ + void SetWrapMode(int mode); + + /** + Set the start indent for wrapped lines. + */ + void SetWrapStartIndent(int indent); + + /** + Set the display mode of visual flags for wrapped lines. + */ + void SetWrapVisualFlags(int wrapVisualFlags); + + /** + Set the location of visual flags for wrapped lines. + */ + void SetWrapVisualFlagsLocation(int wrapVisualFlagsLocation); + + /** + Set the way the caret is kept visible when going sideway. + The exclusion zone is given in pixels. + */ + void SetXCaretPolicy(int caretPolicy, int caretSlop); + + /** + Get and Set the xOffset (ie, horizonal scroll position). + */ + void SetXOffset(int newOffset); + + /** + Set the way the line the caret is on is kept visible. + The exclusion zone is given in lines. + */ + void SetYCaretPolicy(int caretPolicy, int caretSlop); + + /** + Set the zoom level. This number of points is added to the size of all fonts. + It may be positive to magnify or negative to reduce. + */ + void SetZoom(int zoom); + + /** + Make a range of lines visible. + */ + void ShowLines(int lineStart, int lineEnd); + + /** + Start notifying the container of all key presses and commands. + */ + void StartRecord(); + + /** + Set the current styling position to pos and the styling mask to mask. + The styling mask can be used to protect some bits in each styling byte from + modification. + */ + void StartStyling(int pos, int mask); + + /** + Stop notifying the container of all key presses and commands. + */ + void StopRecord(); + + /** + Move caret to bottom of page, or one page down if already at bottom of page. + */ + void StutteredPageDown(); + + /** + Move caret to bottom of page, or one page down if already at bottom of page, + extending selection to new caret position. + */ + void StutteredPageDownExtend(); + + /** + Move caret to top of page, or one page up if already at top of page. + */ + void StutteredPageUp(); + + /** + Move caret to top of page, or one page up if already at top of page, extending + selection to new caret position. + */ + void StutteredPageUpExtend(); + + /** + Clear all the styles and make equivalent to the global default style. + */ + void StyleClearAll(); + + /** + Reset the default style to its state at startup + */ + void StyleResetDefault(); + + /** + Set the background colour of a style. + */ + void StyleSetBackground(int style, const wxColour& back); + + /** + Set a style to be bold or not. + */ + void StyleSetBold(int style, bool bold); + + /** + Set a style to be mixed case, or to force upper or lower case. + */ + void StyleSetCase(int style, int caseForce); + + /** + Set a style to be changeable or not (read only). + Experimental feature, currently buggy. + */ + void StyleSetChangeable(int style, bool changeable); + + /** + Set the character set of the font in a style. Converts the Scintilla + character set values to a wxFontEncoding. + */ + void StyleSetCharacterSet(int style, int characterSet); + + /** + Set a style to have its end of line filled or not. + */ + void StyleSetEOLFilled(int style, bool filled); + + /** + Set the font of a style. + */ + void StyleSetFaceName(int style, const wxString& fontName); + + /** + Set style size, face, bold, italic, and underline attributes from + a wxFont's attributes. + */ + void StyleSetFont(int styleNum, wxFont& font); + + /** + Set all font style attributes at once. + */ + void StyleSetFontAttr(int styleNum, int size, + const wxString& faceName, + bool bold, + bool italic, + bool underline, + wxFontEncoding encoding = wxFONTENCODING_DEFAULT); + + /** + Set the font encoding to be used by a style. + */ + void StyleSetFontEncoding(int style, wxFontEncoding encoding); + + /** + Set the foreground colour of a style. + */ + void StyleSetForeground(int style, const wxColour& fore); + + /** + Set a style to be a hotspot or not. + */ + void StyleSetHotSpot(int style, bool hotspot); + + /** + Set a style to be italic or not. + */ + void StyleSetItalic(int style, bool italic); + + /** + Set the size of characters of a style. + */ + void StyleSetSize(int style, int sizePoints); + + /** + Extract style settings from a spec-string which is composed of one or + more of the following comma separated elements: + bold turns on bold + italic turns on italics + fore:[name or #RRGGBB] sets the foreground colour + back:[name or #RRGGBB] sets the background colour + face:[facename] sets the font face name to use + size:[num] sets the font size in points + eol turns on eol filling + underline turns on underlining + */ + void StyleSetSpec(int styleNum, const wxString& spec); + + /** + Set a style to be underlined or not. + */ + void StyleSetUnderline(int style, bool underline); + + /** + Set a style to be visible or not. + */ + void StyleSetVisible(int style, bool visible); + + /** + If selection is empty or all on one line replace the selection with a tab + character. + If more than one line selected, indent the lines. + */ + void Tab(); + + /** + Make the target range start and end be the same as the selection range start + and end. + */ + void TargetFromSelection(); + + /** + Retrieve the height of a particular line of text in pixels. + */ + int TextHeight(int line); + + /** + Measure the pixel width of some text in a particular style. + NUL terminated text argument. + Does not handle tab or control characters. + */ + int TextWidth(int style, const wxString& text); + + /** + Switch between sticky and non-sticky: meant to be bound to a key. + */ + void ToggleCaretSticky(); + + /** + Switch a header line between expanded and contracted. + */ + void ToggleFold(int line); + + /** + Undo one action in the undo history. + */ + void Undo(); + + /** + Transform the selection to upper case. + */ + void UpperCase(); + + /** + Set whether a pop up menu is displayed automatically when the user presses + the wrong mouse button. + */ + void UsePopUp(bool allowPopUp); + + /** + Display a list of strings and send notification when user chooses one. + */ + void UserListShow(int listType, const wxString& itemList); + + /** + Move caret to before first visible character on line. + If already there move to first character on line. + */ + void VCHome(); + + /** + Like VCHome but extending selection to new caret position. + */ + void VCHomeExtend(); + + /** + Move caret to before first visible character on line. + If already there move to first character on line. + In either case, extend rectangular selection to new caret position. + */ + void VCHomeRectExtend(); + + /** + + */ + void VCHomeWrap(); + + /** + + */ + void VCHomeWrapExtend(); + + /** + Find the display line of a document line taking hidden lines into account. + */ + int VisibleFromDocLine(int line); + + /** + Get position of end of word. + */ + int WordEndPosition(int pos, bool onlyWordCharacters); + + /** + Move caret left one word. + */ + void WordLeft(); + + /** + Move caret left one word, position cursor at end of word. + */ + void WordLeftEnd(); + + /** + Move caret left one word, position cursor at end of word, extending selection + to new caret position. + */ + void WordLeftEndExtend(); + + /** + Move caret left one word extending selection to new caret position. + */ + void WordLeftExtend(); + + /** + Move to the previous change in capitalisation. + */ + void WordPartLeft(); + + /** + Move to the previous change in capitalisation extending selection + to new caret position. + */ + void WordPartLeftExtend(); + + /** + Move to the change next in capitalisation. + */ + void WordPartRight(); + + /** + Move to the next change in capitalisation extending selection + to new caret position. + */ + void WordPartRightExtend(); + + /** + Move caret right one word. + */ + void WordRight(); + + /** + Move caret right one word, position cursor at end of word. + */ + void WordRightEnd(); + + /** + Move caret right one word, position cursor at end of word, extending selection + to new caret position. + */ + void WordRightEndExtend(); + + /** + Move caret right one word extending selection to new caret position. + */ + void WordRightExtend(); + + /** + Get position of start of word. + */ + int WordStartPosition(int pos, bool onlyWordCharacters); + + /** + The number of display lines needed to wrap a document line + */ + int WrapCount(int line); + + /** + Magnify the displayed text by increasing the sizes by 1 point. + */ + void ZoomIn(); + + /** + Make the displayed text smaller by decreasing the sizes by 1 point. + */ + void ZoomOut(); +}; + diff --git a/interface/wx/stdpaths.h b/interface/wx/stdpaths.h new file mode 100644 index 0000000000..8c2769b3c3 --- /dev/null +++ b/interface/wx/stdpaths.h @@ -0,0 +1,218 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: stdpaths.h +// Purpose: interface of wxStandardPaths +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxStandardPaths + @wxheader{stdpaths.h} + + wxStandardPaths returns the standard locations in the file system and should be + used by applications to find their data files in a portable way. + + In the description of the methods below, the example return values are given + for the Unix, Windows and Mac OS X systems, however please note that these are + just the examples and the actual values may differ. For example, under Windows: + the system administrator may change the standard directories locations, i.e. + the Windows directory may be named @c W:\\Win2003 instead of + the default @c C:\\Windows. + + The strings @c appname and @c username should be + replaced with the value returned by wxApp::GetAppName + and the name of the currently logged in user, respectively. The string + @c prefix is only used under Unix and is @c /usr/local by + default but may be changed using wxStandardPaths::SetInstallPrefix. + + The directories returned by the methods of this class may or may not exist. If + they don't exist, it's up to the caller to create them, wxStandardPaths doesn't + do it. + + Finally note that these functions only work with standardly packaged + applications. I.e. under Unix you should follow the standard installation + conventions and under Mac you should create your application bundle according + to the Apple guidelines. Again, this class doesn't help you to do it. + + This class is MT-safe: its methods may be called concurrently from different + threads without additional locking. + + @library{wxbase} + @category{file} + + @see wxFileConfig + */ +class wxStandardPaths +{ +public: + /** + Returns reference to the unique global standard paths object. + */ + static wxStandardPathsBase Get(); + + /** + Return the directory containing the system config files. + Example return values: + - Unix: @c /etc + - Windows: @c C:\\Documents @c and @c Settings\\All @c Users\\Application Data + - Mac: @c /Library/Preferences + + @see wxFileConfig + */ + wxString GetConfigDir() const; + + /** + Return the location of the applications global, i.e. not user-specific, + data files. + Example return values: + - Unix: @c prefix/share/appname + - Windows: the directory where the executable file is located + - Mac: @c appname.app/Contents/SharedSupport bundle subdirectory + + @see GetLocalDataDir() + */ + wxString GetDataDir() const; + + /** + Return the directory containing the current user's documents. + Example return values: + - Unix: @c ~ (the home directory) + - Windows: @c C:\\Documents @c and @c Settings\\username\\Documents + - Mac: @c ~/Documents + + @since 2.7.0 + */ + wxString GetDocumentsDir() const; + + /** + Return the directory and the filename for the current executable. + Example return values: + - Unix: @c /usr/local/bin/exename + - Windows: @c C:\\Programs\\AppFolder\\exename.exe + - Mac: @c /Programs/exename + */ + wxString GetExecutablePath() const; + + /** + @note This function is only available under Unix. + Return the program installation prefix, e.g. @c /usr, @c /opt or + @c /home/zeitlin. + If the prefix had been previously by SetInstallPrefix(), returns that + value, otherwise tries to determine it automatically (Linux only right + now) and finally returns the default @c /usr/local value if it failed. + */ + wxString GetInstallPrefix() const; + + /** + Return the location for application data files which are host-specific and + can't, or shouldn't, be shared with the other machines. + This is the same as GetDataDir() except + under Unix where it returns @c /etc/appname. + */ + wxString GetLocalDataDir() const; + + /** + Return the localized resources directory containing the resource files of the + specified category for the given language. + In general this is just the same as @a lang subdirectory of + GetResourcesDir() (or @c lang.lproj under Mac OS X) but is something quite + different for message catalog category under Unix where it returns the standard + @c prefix/share/locale/lang/LC_MESSAGES directory. + + @since 2.7.0 + */ + wxString GetLocalizedResourcesDir(const wxString& lang, + ResourceCat category = ResourceCat_None) const; + + /** + Return the directory where the loadable modules (plugins) live. + Example return values: + - Unix: @c prefix/lib/appname + - Windows: the directory of the executable file + - Mac: @c appname.app/Contents/PlugIns bundle subdirectory + + @see wxDynamicLibrary + */ + wxString GetPluginsDir() const; + + /** + Return the directory where the application resource files are located. The + resources are the auxiliary data files needed for the application to run and + include, for example, image and sound files it might use. + This function is the same as GetDataDir() for + all platforms except Mac OS X. + Example return values: + - Unix: @c prefix/share/@e appname + - Windows: the directory where the executable file is located + - Mac: @c appname.app/Contents/Resources bundle subdirectory + + @since 2.7.0 + + @see GetLocalizedResourcesDir() + */ + wxString GetResourcesDir() const; + + /** + Return the directory for storing temporary files. To create unique temporary + files, + it is best to use wxFileName::CreateTempFileName for correct behaviour when + multiple processes are attempting to create temporary files. + + @since 2.7.2 + */ + wxString GetTempDir() const; + + /** + Return the directory for the user config files: + - Unix: @c ~ (the home directory) + - Windows: @c C:\\Documents @c and @c Settings\\username\\Application Data + - Mac: @c ~/Library/Preferences + Only use this method if you have a single configuration file to put in this + directory, otherwise GetUserDataDir() is + more appropriate. + */ + wxString GetUserConfigDir() const; + + /** + Return the directory for the user-dependent application data files: + - Unix: @c ~/.appname + - Windows: @c C:\\Documents @c and @c Settings\\username\Application @c Data\appname + - Mac: @c ~/Library/Application @c Support/appname + */ + wxString GetUserDataDir() const; + + /** + Return the directory for user data files which shouldn't be shared with + the other machines. + This is the same as GetUserDataDir() for all platforms except Windows where it returns + @c C:\\Documents @c and @c Settings\\username\\Local @c Settings\\Application @c Data\appname + */ + wxString GetUserLocalDataDir() const; + + /** + @note This function is only available under Unix. + Lets wxStandardPaths know about the real program installation prefix on a Unix + system. By default, the value returned by + GetInstallPrefix() is used. + Although under Linux systems the program prefix may usually be determined + automatically, portable programs should call this function. Usually the prefix + is set during program configuration if using GNU autotools and so it is enough + to pass its value defined in @c config.h to this function. + */ + void SetInstallPrefix(const wxString& prefix); + + /** + Controls what application information is used when constructing paths that + should be unique to this program, such as the application data directory, the + plugins directory on Unix, etc. + Valid values for @a info are @c AppInfo_None and either one or + combination of @c AppInfo_AppName and @c AppInfo_VendorName. The + first one tells this class to not use neither application nor vendor name in + the paths. + By default, only the application name is used under Unix systems but both + application and vendor names are used under Windows and Mac. + */ + void UseAppInfo(int info); +}; + diff --git a/interface/wx/stockitem.h b/interface/wx/stockitem.h new file mode 100644 index 0000000000..61f958d3ee --- /dev/null +++ b/interface/wx/stockitem.h @@ -0,0 +1,31 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: stockitem.h +// Purpose: interface of global functions +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** @ingroup group_funcmacro_misc */ +//@{ + +/** + Returns label that should be used for given @a id element. + + @param id + Given id of the wxMenuItem, wxButton, wxToolBar tool, etc. + @param withCodes + If @false then strip accelerator code from the label; useful for + getting labels without accelerator char code like for toolbar tooltip + or on platforms without traditional keyboard like smartphones. + @param accelerator + Optional accelerator string automatically added to label; useful for + building labels for wxMenuItem. + + @header{wx/stockitem.h} +*/ +wxString wxGetStockLabel(wxWindowID id, bool withCodes = true, + const wxString& accelerator = wxEmptyString); + +//@} + diff --git a/interface/wx/stopwatch.h b/interface/wx/stopwatch.h new file mode 100644 index 0000000000..3dfba4a146 --- /dev/null +++ b/interface/wx/stopwatch.h @@ -0,0 +1,106 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: stopwatch.h +// Purpose: interface of wxStopWatch +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxStopWatch + @wxheader{stopwatch.h} + + The wxStopWatch class allow you to measure time intervals. For example, you may + use it to measure the time elapsed by some function: + + @code + wxStopWatch sw; + CallLongRunningFunction(); + wxLogMessage("The long running function took %ldms to execute", + sw.Time()); + sw.Pause(); + ... stopwatch is stopped now ... + sw.Resume(); + CallLongRunningFunction(); + wxLogMessage("And calling it twice took $ldms in all", sw.Time()); + @endcode + + @library{wxbase} + @category{misc} + + @see wxTimer +*/ +class wxStopWatch +{ +public: + /** + Constructor. This starts the stop watch. + */ + wxStopWatch(); + + /** + Pauses the stop watch. Call Resume() to resume + time measuring again. + If this method is called several times, @c Resume() must be called the same + number of times to really resume the stop watch. You may, however, call + Start() to resume it unconditionally. + */ + void Pause(); + + /** + Resumes the stop watch which had been paused with + Pause(). + */ + void Resume(); + + /** + (Re)starts the stop watch with a given initial value. + */ + void Start(long milliseconds = 0); + + /** + Returns the time in milliseconds since the start (or restart) or the last call + of + Pause(). + */ + long Time() const; +}; + + + +// ============================================================================ +// Global functions/macros +// ============================================================================ + +/** @ingroup group_funcmacro_time */ +//@{ + +/** + Returns the number of seconds since local time 00:00:00 Jan 1st 1970. + + @see wxDateTime::Now() + + @header{wx/stopwatch.h} +*/ +long wxGetLocalTime(); + +/** + Returns the number of milliseconds since local time 00:00:00 Jan 1st 1970. + + @see wxDateTime::Now(), wxLongLong + + @header{wx/stopwatch.h} +*/ +wxLongLong wxGetLocalTimeMillis(); + +/** + Returns the number of seconds since GMT 00:00:00 Jan 1st 1970. + + @see wxDateTime::Now() + + @header{wx/stopwatch.h} +*/ +long wxGetUTCTime(); + +//@} + diff --git a/interface/wx/strconv.h b/interface/wx/strconv.h new file mode 100644 index 0000000000..1843a27e13 --- /dev/null +++ b/interface/wx/strconv.h @@ -0,0 +1,483 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: strconv.h +// Purpose: interface of wxMBConvUTF7 +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxMBConv + @wxheader{strconv.h} + + This class is the base class of a hierarchy of classes capable of + converting text strings between multibyte (SBCS or DBCS) encodings and + Unicode. + + This is an abstract base class which defines the operations implemented by + all different conversion classes. The derived classes don't add any new + operations of their own (except, possibly, some non-default constructors) + and so you should simply use this class ToWChar() and FromWChar() (or + cMB2WC() and cWC2MB()) methods with the objects of the derived class. + + In the documentation for this and related classes please notice that + length of the string refers to the number of characters in the string + not counting the terminating @c NUL, if any. While the size of the string + is the total number of bytes in the string, including any trailing @c NUL. + Thus, length of wide character string @c L"foo" is 3 while its size can + be either 8 or 16 depending on whether @c wchar_t is 2 bytes (as + under Windows) or 4 (Unix). + + @library{wxbase} + @category{conv} + + @see wxCSConv, wxEncodingConverter, @ref overview_mbconv "wxMBConv classes overview" +*/ +class wxMBConv +{ +public: + /** + Trivial default constructor. + */ + wxMBConv(); + + /** + This pure virtual function is overridden in each of the derived classes + to return a new copy of the object it is called on. + + It is used for copying the conversion objects while preserving their + dynamic type. + */ + virtual wxMBConv* Clone() const = 0; + + /** + This function returns 1 for most of the multibyte encodings in which the + string is terminated by a single @c NUL, 2 for UTF-16 and 4 for UTF-32 for + which the string is terminated with 2 and 4 @c NUL characters respectively. + The other cases are not currently supported and @c wxCONV_FAILED + (defined as -1) is returned for them. + */ + size_t GetMBNulLen() const; + + /** + Returns the maximal value which can be returned by GetMBNulLen() for + any conversion object. + + Currently this value is 4. + + This method can be used to allocate the buffer with enough space for the + trailing @c NUL characters for any encoding. + */ + const size_t GetMaxMBNulLen(); + + /** + Convert multibyte string to a wide character one. + + This is the most general function for converting a multibyte string to + a wide string, cMB2WC() may be often more convenient, however this + function is the most efficient one as it allows to avoid any + unnecessary copying. + + The main case is when @a dst is not @NULL and @a srcLen is not + @c wxNO_LEN (which is defined as @c (size_t)-1): then the function + converts exactly @a srcLen bytes starting at @a src into wide string + which it output to @e dst. If the length of the resulting wide + string is greater than @e dstLen, an error is returned. Note that if + @a srcLen bytes don't include @c NUL characters, the resulting wide + string is not @c NUL-terminated neither. + + If @a srcLen is @c wxNO_LEN, the function supposes that the string is + properly (i.e. as necessary for the encoding handled by this + conversion) @c NUL-terminated and converts the entire string, including + any trailing @c NUL bytes. In this case the wide string is also @c + NUL-terminated. + + Finally, if @a dst is @NULL, the function returns the length of the + needed buffer. + + Example of use of this function: + @code + size_t dstLen = conv.ToWChar(NULL, 0, src); + if ( dstLen == wxCONV_FAILED ) + ... handle error ... + wchar_t *dst = new wchar_t[dstLen]; + if ( conv.ToWChar(dst, dstLen, src) == wxCONV_FAILED ) + ... handle error ... + @endcode + + Notice that when passing the explicit source length the output will + @e not be @c NUL terminated if you pass @c strlen(str) as parameter. + Either leave @a srcLen as default @c wxNO_LEN or add one to @c strlen + result if you want the output to be @c NUL terminated. + + @param dst + Pointer to output buffer of the size of at least @a dstLen or @NULL. + @param dstLen + Maximal number of characters to be written to the output buffer if + @dst is non-@NULL, unused otherwise. + @param src + Point to the source string, must not be @NULL. + @param + The number of characters of the source string to convert or @c + wxNO_LEN (default parameter) to convert everything up to and + including the terminating @c NUL character(s). + @return + The number of character written (or which would have been written + if it were non-@NULL) to @a dst or @c wxCONV_FAILED on error. + */ + virtual size_t ToWChar(wchar_t* dst, size_t dstLen, + const char* src, + size_t srcLen = wxNO_LEN) const; + + /** + Converts wide character string to multibyte. + + This function has the same semantics as ToWChar() except that it + converts a wide string to multibyte one. As with ToWChar(), it may be + more convenient to use cWC2MB() when working with @c NUL terminated + strings. + + @param dst + Pointer to output buffer of the size of at least @a dstLen or @NULL. + @param dstLen + Maximal number of characters to be written to the output buffer if + @dst is non-@NULL, unused otherwise. + @param src + Point to the source string, must not be @NULL. + @param + The number of characters of the source string to convert or @c + wxNO_LEN (default parameter) to convert everything up to and + including the terminating @c NUL character. + @return + The number of character written (or which would have been written + if it were non-@NULL) to @a dst or @c wxCONV_FAILED on error. + */ + virtual size_t FromWChar(char* dst, size_t dstLen, + const wchar_t* src, + size_t srcLen = wxNO_LEN) const; + + //@{ + /** + Converts from multibyte encoding to Unicode by calling MB2WC() and + allocating a temporary wxWCharBuffer to hold the result. + + The first overload takes a @c NUL-terminated input string. The second + one takes a string of exactly the specified length and the string may + include or not the trailing @c NUL character(s). If the string is not + @c NUL-terminated, a temporary @c NUL-terminated copy of it suitable + for passing to wxMBConv::MB2WC is made, so it is more efficient to + ensure that the string is does have the appropriate number of @c NUL + bytes (which is usually 1 but may be 2 or 4 for UTF-16 or UTF-32, see + wxMBConv::GetMBNulLen), especially for long strings. + + If @a outLen is not-@NULL, it receives the length of the converted + string. + */ + const wxWCharBuffer cMB2WC(const char* in) const; + const wxWCharBuffer cMB2WC(const char* in, size_t inLen, size_t *outLen) const; + //@} + + //@{ + /** + Converts from multibyte encoding to the current wxChar type (which + depends on whether wxUSE_UNICODE is set to 1). + + If wxChar is char, it returns the parameter unaltered. If wxChar is + wchar_t, it returns the result in a wxWCharBuffer. The macro wxMB2WXbuf + is defined as the correct return type (without const). + */ + const char* cMB2WX(const char* psz) const; + const wxWCharBuffer cMB2WX(const char* psz) const; + //@} + + //@{ + /** + Converts from Unicode to multibyte encoding by calling WC2MB and + allocating a temporary wxCharBuffer to hold the result. + + The second overload of this function allows to convert a string of the + given length @e inLen, whether it is @c NUL-terminated or not (for wide + character strings, unlike for the multibyte ones, a single @c NUL is + always enough). But notice that just as with @ref wxMBConv::mb2wc + cMB2WC, it is more efficient to pass an already terminated string to + this function as otherwise a copy is made internally. If @a outLen is + not-@NULL, it receives the length of the converted string. + */ + const wxCharBuffer cWC2MB(const wchar_t* in) const; + const wxCharBuffer cWC2MB(const wchar_t* in, size_t inLen, size_t *outLen) const; + //@} + + //@{ + /** + Converts from Unicode to the current wxChar type. + + If wxChar is wchar_t, it returns the parameter unaltered. If wxChar is + char, it returns the result in a wxCharBuffer. The macro wxWC2WXbuf is + defined as the correct return type (without const). + */ + const wchar_t* cWC2WX(const wchar_t* psz) const; + const wxCharBuffer cWC2WX(const wchar_t* psz) const; + //@} + + //@{ + /** + Converts from the current wxChar type to multibyte encoding. + + If wxChar is char, it returns the parameter unaltered. If wxChar is + wchar_t, it returns the result in a wxCharBuffer. The macro wxWX2MBbuf + is defined as the correct return type (without const). + */ + const char* cWX2MB(const wxChar* psz) const; + const wxCharBuffer cWX2MB(const wxChar* psz) const; + //@} + + //@{ + /** + Converts from the current wxChar type to Unicode. + + If wxChar is wchar_t, it returns the parameter unaltered. If wxChar is + char, it returns the result in a wxWCharBuffer. The macro wxWX2WCbuf is + defined as the correct return type (without const). + */ + const wchar_t* cWX2WC(const wxChar* psz) const; + const wxWCharBuffer cWX2WC(const wxChar* psz) const; + //@} + + /** + @deprecated This function is deprecated, please use ToWChar() instead. + + Converts from a string @a in in multibyte encoding to Unicode putting up to + @a outLen characters into the buffer @e out. + + If @a out is @NULL, only the length of the string which would result + from the conversion is calculated and returned. Note that this is the + length and not size, i.e. the returned value does not include the + trailing @c NUL. But when the function is called with a non-@NULL @a + out buffer, the @a outLen parameter should be one more to allow to + properly @c NUL-terminate the string. + + @param out + The output buffer, may be @NULL if the caller is only + interested in the length of the resulting string + @param in + The NUL-terminated input string, cannot be @NULL + @param outLen + The length of the output buffer but including + NUL, ignored if out is @NULL + + @return The length of the converted string excluding the trailing NUL. + */ + virtual size_t MB2WC(wchar_t* out, const char* in, size_t outLen) const; + + /** + @deprecated This function is deprecated, please use FromWChar() instead. + + Converts from Unicode to multibyte encoding. + The semantics of this function (including the return value meaning) is + the same as for wxMBConv::MB2WC. Notice that when the function is + called with a non-@NULL buffer, the @a n parameter should be the size + of the buffer and so it should take into account the trailing @c NUL, + which might take two or four bytes for some encodings (UTF-16 and + UTF-32) and not one. + */ + virtual size_t WC2MB(char* buf, const wchar_t* psz, size_t n) const; +}; + + +/** + @class wxMBConvUTF7 + @wxheader{strconv.h} + + This class converts between the UTF-7 encoding and Unicode. + It has one predefined instance, @b wxConvUTF7. + + Notice that, unlike all the other conversion objects, this converter is + stateful, i.e. it remembers its state from the last call to its ToWChar() + or FromWChar() and assumes it is called on the continuation of the same + string when the same method is called again. This assumption is only made + if an explicit length is specified as parameter to these functions as if an + entire @c NUL terminated string is processed the state doesn't need to be + remembered. + + This also means that, unlike the other predefined conversion objects, + @b wxConvUTF7 is @em not thread-safe. + + @library{wxbase} + @category{conv} + + @see wxMBConvUTF8, @ref overview_mbconv "wxMBConv classes overview" +*/ +class wxMBConvUTF7 : public wxMBConv +{ +}; + + + +/** + @class wxMBConvUTF8 + @wxheader{strconv.h} + + This class converts between the UTF-8 encoding and Unicode. + It has one predefined instance, @b wxConvUTF8. + + @library{wxbase} + @category{conv} + + @see wxMBConvUTF7, @ref overview_mbconv "wxMBConv classes overview" +*/ +class wxMBConvUTF8 : public wxMBConv +{ +}; + + + +/** + @class wxMBConvUTF16 + @wxheader{strconv.h} + + This class is used to convert between multibyte encodings and UTF-16 Unicode + encoding (also known as UCS-2). + + Unlike UTF-8 encoding, UTF-16 uses words and not bytes and hence depends + on the byte ordering: big or little endian. Hence this class is provided in + two versions: wxMBConvUTF16LE and wxMBConvUTF16BE and wxMBConvUTF16 itself + is just a typedef for one of them (native for the given platform, e.g. LE + under Windows and BE under Mac). + + @library{wxbase} + @category{conv} + + @see wxMBConvUTF8, wxMBConvUTF32, @ref overview_mbconv "wxMBConv classes overview" +*/ +class wxMBConvUTF16 : public wxMBConv +{ +}; + + +/** + @class wxMBConvUTF32 + @wxheader{strconv.h} + + This class is used to convert between multibyte encodings and UTF-32 + Unicode encoding (also known as UCS-4). + Unlike UTF-8 encoding, UTF-32 uses (double) words and not bytes and hence + depends on the byte ordering: big or little endian. Hence this class is + provided in two versions: wxMBConvUTF32LE and wxMBConvUTF32BE and + wxMBConvUTF32 itself is just a typedef for one of them (native for the + given platform, e.g. LE under Windows and BE under Mac). + + @library{wxbase} + @category{conv} + + @see wxMBConvUTF8, wxMBConvUTF16, @ref overview_mbconv "wxMBConv classes overview" +*/ +class wxMBConvUTF32 : public wxMBConv +{ +}; + + + + +/** + @class wxCSConv + @wxheader{strconv.h} + + This class converts between any character set supported by the system and + Unicode. + + Please notice that this class uses system-provided conversion functions, + e.g. @c MultiByteToWideChar() and @c WideCharToMultiByte() under MSW and @c + iconv(3) under Unix systems and as such may support different encodings and + different encoding names on different platforms (although all relatively + common encodings are supported should be supported everywhere). + + It has one predefined instance, @b wxConvLocal, for the default user + character set. + + @library{wxbase} + @category{conv} + + @see wxMBConv, wxEncodingConverter, @ref overview_mbconv "wxMBConv classes overview" +*/ +class wxCSConv : public wxMBConv +{ +public: + /** + Constructor. + + You can specify the name of the character set you want to convert + from/to. If the character set name is not recognized, ISO 8859-1 is + used as fall back, use IsOk() to test for this. + + @param charset The name of the encoding, shouldn't be empty. + */ + wxCSConv(const wxString& charset); + + /** + Constructor. + + You can specify an encoding constant for the character set you want to + convert from/to. Use IsOk() after construction to check whether the + encoding is supported by the current system. + + @param encoding Any valid (i.e. not wxFONTENCODING_MAX) font encoding. + */ + wxCSConv(wxFontEncoding encoding); + + /** + Returns @true if the charset (or the encoding) given at constructor is + really available to use. + + Returns @false if ISO 8859-1 will be used instead. + + Note this does not mean that a given string will be correctly + converted. A malformed string may still make conversion functions + return @c wxCONV_FAILED. + + @since 2.8.2 + */ + bool IsOk() const; +}; + + + +/** + @class wxMBConvFile + @wxheader{strconv.h} + + This class used to define the class instance @b wxConvFileName, but + nowadays @b wxConvFileName is either of type wxConvLibc (on most platforms) + or wxConvUTF8 (on MacOS X). + + @b wxConvFileName converts filenames between filesystem multibyte encoding + and Unicode. @b wxConvFileName can also be set to a something else at + run-time which is used e.g. by wxGTK to use a class which checks the + environment variable @b G_FILESYSTEM_ENCODING indicating that filenames + should not be interpreted as UTF8 and also for converting invalid UTF8 + characters (e.g. if there is a filename in iso8859_1) to strings with octal + values. + + Since some platforms (such as Win32) use Unicode in the filenames, + and others (such as Unix) use multibyte encodings, this class should only + be used directly if wxMBFILES is defined to 1. A convenience macro, + @c wxFNCONV, is defined to @c wxConvFileName->cWX2MB in this case. You + could use it like this: + + @code + wxChar *name = wxT("rawfile.doc"); + FILE *fil = fopen(wxFNCONV(name), "r"); + @endcode + + (although it would be better to just use wxFopen(name, "r") in this + particular case, you only need to use this class for functions taking file + names not wrapped by wxWidgets.) + + @library{wxbase} + @category{conv} + + @see @ref overview_mbconv "wxMBConv classes overview" +*/ +class wxMBConvFile : public wxMBConv +{ +public: +}; diff --git a/interface/wx/stream.h b/interface/wx/stream.h new file mode 100644 index 0000000000..532ac2d28d --- /dev/null +++ b/interface/wx/stream.h @@ -0,0 +1,774 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: stream.h +// Purpose: interface of wxCountingOutputStream +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxCountingOutputStream + @wxheader{stream.h} + + wxCountingOutputStream is a specialized output stream which does not write any + data anywhere, + instead it counts how many bytes would get written if this were a normal + stream. This + can sometimes be useful or required if some data gets serialized to a stream or + compressed + by using stream compression and thus the final size of the stream cannot be + known other + than pretending to write the stream. One case where the resulting size would + have to be + known is if the data has to be written to a piece of memory and the memory has + to be + allocated before writing to it (which is probably always the case when writing + to a + memory stream). + + @library{wxbase} + @category{streams} +*/ +class wxCountingOutputStream : public wxOutputStream +{ +public: + /** + Creates a wxCountingOutputStream object. + */ + wxCountingOutputStream(); + + /** + Destructor. + */ + ~wxCountingOutputStream(); + + /** + Returns the current size of the stream. + */ + size_t GetSize() const; +}; + + + +/** + @class wxBufferedInputStream + @wxheader{stream.h} + + This stream acts as a cache. It caches the bytes read from the specified + input stream (See wxFilterInputStream). + It uses wxStreamBuffer and sets the default in-buffer size to 1024 bytes. + This class may not be used without some other stream to read the data + from (such as a file stream or a memory stream). + + @library{wxbase} + @category{streams} + + @see wxStreamBuffer, wxInputStream, wxBufferedOutputStream +*/ +class wxBufferedInputStream : public wxFilterInputStream +{ +public: + +}; + + + +/** + @class wxStreamBuffer + @wxheader{stream.h} + + + @library{wxbase} + @category{streams} + + @see wxStreamBase +*/ +class wxStreamBuffer +{ +public: + //@{ + /** + Constructor. It initializes the stream buffer with the data of the specified + stream buffer. The new stream buffer has the same attributes, size, position + and they share the same buffer. This will cause problems if the stream to + which the stream buffer belong is destroyed and the newly cloned stream + buffer continues to be used, trying to call functions in the (destroyed) + stream. It is advised to use this feature only in very local area of the + program. + + @see @ref setbufferio() wxStreamBuffer:SetBufferIO + */ + wxStreamBuffer(wxStreamBase& stream, BufMode mode); + wxStreamBuffer(BufMode mode); + wxStreamBuffer(const wxStreamBuffer& buffer); + //@} + + /** + Destructor. It finalizes all IO calls and frees all internal buffers if + necessary. + */ + wxStreamBuffer(); + + /** + Fill the IO buffer. + */ + bool FillBuffer(); + + /** + Toggles the fixed flag. Usually this flag is toggled at the same time as + @e flushable. This flag allows (when it has the @false value) or forbids + (when it has the @true value) the stream buffer to resize dynamically the IO + buffer. + + @see SetBufferIO() + */ + void Fixed(bool fixed); + + /** + Flushes the IO buffer. + */ + bool FlushBuffer(); + + /** + Toggles the flushable flag. If @a flushable is disabled, no data are sent + to the parent stream. + */ + void Flushable(bool flushable); + + /** + Returns a pointer on the end of the stream buffer. + */ + void* GetBufferEnd() const; + + /** + Returns a pointer on the current position of the stream buffer. + */ + void* GetBufferPos() const; + + /** + Returns the size of the buffer. + */ + size_t GetBufferSize() const; + + /** + Returns a pointer on the start of the stream buffer. + */ + void* GetBufferStart() const; + + /** + Gets a single char from the stream buffer. It acts like the Read call. + + @see Read() + */ + char GetChar(); + + /** + Returns the amount of available data in the buffer. + */ + size_t GetDataLeft(); + + /** + Returns the current position (counted in bytes) in the stream buffer. + */ + off_t GetIntPosition() const; + + /** + Returns the amount of bytes read during the last IO call to the parent stream. + */ + size_t GetLastAccess() const; + + /** + Puts a single char to the stream buffer. + + @see Read() + */ + void PutChar(char c); + + //@{ + /** + Copies data to @e buffer. The function returns when @a buffer is full or when + there isn't + any more data in the current buffer. + + @see Write() + */ + size_t Read(void* buffer, size_t size); + Return value size_t Read(wxStreamBuffer* buffer); + //@} + + /** + Resets to the initial state variables concerning the buffer. + */ + void ResetBuffer(); + + /** + Changes the current position. + @a mode may be one of the following: + + @b wxFromStart + + The position is counted from the start of the stream. + + @b wxFromCurrent + + The position is counted from the current position of the stream. + + @b wxFromEnd + + The position is counted from the end of the stream. + + @return Upon successful completion, it returns the new offset as + measured in bytes from the beginning of the stream. + Otherwise, it returns wxInvalidOffset. + */ + off_t Seek(off_t pos, wxSeekMode mode); + + //@{ + /** + Destroys or invalidates the previous IO buffer and allocates a new one of the + specified size. + + @see Fixed(), Flushable() + */ + void SetBufferIO(char* buffer_start, char* buffer_end); + Remarks See also + wxStreamBuffer constructor + + wxStreamBuffer::Fixed + + wxStreamBuffer::Flushable + void SetBufferIO(size_t bufsize); + //@} + + /** + Sets the current position (in bytes) in the stream buffer. + */ + void SetIntPosition(size_t pos); + + /** + Returns the parent stream of the stream buffer. + */ + wxStreamBase* Stream(); + + /** + Gets the current position in the stream. This position is calculated from + the @e real position in the stream and from the internal buffer position: so + it gives you the position in the @e real stream counted from the start of + the stream. + + @return Returns the current position in the stream if possible, + wxInvalidOffset in the other case. + */ + off_t Tell() const; + + /** + Truncates the buffer to the current position. + Note: Truncate() cannot be used to enlarge the buffer. This is + usually not needed since the buffer expands automatically. + */ + void Truncate(); + + //@{ + /** + See Read(). + */ + size_t Write(const void* buffer, size_t size); + size_t Write(wxStreamBuffer* buffer); + //@} +}; + + + +/** + @class wxOutputStream + @wxheader{stream.h} + + wxOutputStream is an abstract base class which may not be used directly. + + @library{wxbase} + @category{streams} +*/ +class wxOutputStream : public wxStreamBase +{ +public: + /** + Creates a dummy wxOutputStream object. + */ + wxOutputStream(); + + /** + Destructor. + */ + ~wxOutputStream(); + + /** + Closes the stream, returning @false if an error occurs. The + stream is closed implicitly in the destructor if Close() is not + called explicitly. + If this stream wraps another stream or some other resource such + as a file, then the underlying resource is closed too if it is owned + by this stream, or left open otherwise. + */ + bool Close(); + + /** + Returns the number of bytes written during the last + Write(). It may return 0 even if there is no + error on the stream if it is only temporarily impossible to write to it. + */ + size_t LastWrite() const; + + /** + Puts the specified character in the output queue and increments the + stream position. + */ + void PutC(char c); + + /** + Changes the stream current position. + + @param pos + Offset to seek to. + @param mode + One of wxFromStart, wxFromEnd, wxFromCurrent. + + @return The new stream position or wxInvalidOffset on error. + */ + off_t SeekO(off_t pos, wxSeekMode mode = wxFromStart); + + /** + Returns the current stream position. + */ + off_t TellO() const; + + //@{ + /** + Reads data from the specified input stream and stores them + in the current stream. The data is read until an error is raised + by one of the two streams. + */ + wxOutputStream Write(const void* buffer, size_t size); + wxOutputStream Write(wxInputStream& stream_in); + //@} +}; + + + +/** + @class wxFilterClassFactory + @wxheader{stream.h} + + Allows the creation of filter streams to handle compression formats such + as gzip and bzip2. + + For example, given a filename you can search for a factory that will + handle it and create a stream to decompress it: + + @code + factory = wxFilterClassFactory::Find(filename, wxSTREAM_FILEEXT); + if (factory) + stream = factory-NewStream(new wxFFileInputStream(filename)); + @endcode + + wxFilterClassFactory::Find can also search + for a factory by MIME type, HTTP encoding or by wxFileSystem protocol. + The available factories can be enumerated + using @ref wxFilterClassFactory::getfirst "GetFirst() and GetNext". + + @library{wxbase} + @category{FIXME} + + @see wxFilterInputStream, wxFilterOutputStream, wxArchiveClassFactory, @ref + overview_wxarc "Archive formats such as zip" +*/ +class wxFilterClassFactory : public wxObject +{ +public: + /** + Returns @true if this factory can handle the given protocol, MIME type, HTTP + encoding or file extension. + When using wxSTREAM_FILEEXT for the second parameter, the first parameter + can be a complete filename rather than just an extension. + */ + bool CanHandle(const wxString& protocol, + wxStreamProtocolType type = wxSTREAM_PROTOCOL) const; + + /** + A static member that finds a factory that can handle a given protocol, MIME + type, HTTP encoding or file extension. Returns a pointer to the class + factory if found, or @NULL otherwise. It does not give away ownership of the + factory. + When using wxSTREAM_FILEEXT for the second parameter, the first parameter + can be a complete filename rather than just an extension. + */ + static const wxFilterClassFactory* Find(const wxString& protocol, + wxStreamProtocolType type = wxSTREAM_PROTOCOL); + + //@{ + /** + GetFirst and GetNext can be used to enumerate the available factories. + For example, to list them: + + GetFirst()/GetNext() return a pointer to a factory or @NULL if no more + are available. They do not give away ownership of the factory. + */ + static const wxFilterClassFactory* GetFirst() const; + const wxFilterClassFactory* GetNext() const; + //@} + + /** + Returns the wxFileSystem protocol supported by this factory. Equivalent + to wxString(*GetProtcols()). + */ + wxString GetProtocol() const; + + /** + Returns the protocols, MIME types, HTTP encodings or file extensions + supported by this factory, as an array of null terminated strings. It does + not give away ownership of the array or strings. + For example, to list the file extensions a factory supports: + */ + const wxChar* const* GetProtocols(wxStreamProtocolType type = wxSTREAM_PROTOCOL) const; + + //@{ + /** + Create a new input or output stream to decompress or compress a given stream. + If the parent stream is passed as a pointer then the new filter stream + takes ownership of it. If it is passed by reference then it does not. + */ + wxFilterInputStream* NewStream(wxInputStream& stream) const; + const wxFilterOutputStream* NewStream(wxOutputStream& stream) const; + const wxFilterInputStream* NewStream(wxInputStream* stream) const; + const wxFilterOutputStream* NewStream(wxOutputStream* stream) const; + //@} + + /** + Remove the file extension of @a location if it is one of the file + extensions handled by this factory. + */ + wxString PopExtension(const wxString& location) const; + + /** + Adds this class factory to the list returned + by @ref getfirst() GetFirst()/GetNext. + It is not necessary to do this to use the filter streams. It is usually + used when implementing streams, typically the implementation will + add a static instance of its factory class. + It can also be used to change the order of a factory already in the list, + bringing it to the front. This isn't a thread safe operation + so can't be done when other threads are running that will be using the list. + The list does not take ownership of the factory. + */ + void PushFront(); + + /** + Removes this class factory from the list returned + by @ref getfirst() GetFirst()/GetNext. + Removing from the list isn't a thread safe operation + so can't be done when other threads are running that will be using the list. + The list does not own the factories, so removing a factory does not delete it. + */ + void Remove(); +}; + + + +/** + @class wxFilterOutputStream + @wxheader{stream.h} + + A filter stream has the capability of a normal + stream but it can be placed on top of another stream. So, for example, it + can compress, encrypt the data which are passed to it and write them to another + stream. + + @library{wxbase} + @category{streams} + + @see wxFilterClassFactory, wxFilterInputStream +*/ +class wxFilterOutputStream : public wxOutputStream +{ +public: + //@{ + /** + Initializes a "filter" stream. + If the parent stream is passed as a pointer then the new filter stream + takes ownership of it. If it is passed by reference then it does not. + */ + wxFilterOutputStream(wxOutputStream& stream); + wxFilterOutputStream(wxOutputStream* stream); + //@} +}; + + + +/** + @class wxFilterInputStream + @wxheader{stream.h} + + A filter stream has the capability of a normal stream but it can be placed on + top + of another stream. So, for example, it can uncompress or decrypt the data which + are read + from another stream and pass it to the requester. + + @library{wxbase} + @category{streams} + + @see wxFilterClassFactory, wxFilterOutputStream +*/ +class wxFilterInputStream : public wxInputStream +{ +public: + //@{ + /** + Initializes a "filter" stream. + If the parent stream is passed as a pointer then the new filter stream + takes ownership of it. If it is passed by reference then it does not. + */ + wxFilterInputStream(wxInputStream& stream); + wxFilterInputStream(wxInputStream* stream); + //@} +}; + + + +/** + @class wxBufferedOutputStream + @wxheader{stream.h} + + This stream acts as a cache. It caches the bytes to be written to the specified + output stream (See wxFilterOutputStream). The + data is only written when the cache is full, when the buffered stream is + destroyed or when calling SeekO(). + + This class may not be used without some other stream to write the data + to (such as a file stream or a memory stream). + + @library{wxbase} + @category{streams} + + @see wxStreamBuffer, wxOutputStream +*/ +class wxBufferedOutputStream : public wxFilterOutputStream +{ +public: + /** + Creates a buffered stream using a buffer of a default size of 1024 bytes for + cashing + the stream @e parent. + */ + wxBufferedOutputStream(const wxOutputStream& parent); + + /** + Destructor. Calls Sync() and destroys the internal buffer. + */ + ~wxBufferedOutputStream(); + + /** + Calls Sync() and changes the stream position. + */ + off_t SeekO(off_t pos, wxSeekMode mode); + + /** + Flushes the buffer and calls Sync() on the parent stream. + */ + void Sync(); +}; + + + +/** + @class wxInputStream + @wxheader{stream.h} + + wxInputStream is an abstract base class which may not be used directly. + + @library{wxbase} + @category{streams} +*/ +class wxInputStream : public wxStreamBase +{ +public: + /** + Creates a dummy input stream. + */ + wxInputStream(); + + /** + Destructor. + */ + ~wxInputStream(); + + /** + Returns @true if some data is available in the stream right now, so that + calling Read() wouldn't block. + */ + bool CanRead() const; + + /** + Returns @true after an attempt has been made to read past the end of the + stream. + */ + bool Eof() const; + + /** + Returns the first character in the input queue and removes it, + blocking until it appears if necessary. + */ + char GetC(); + + /** + Returns the last number of bytes read. + */ + size_t LastRead() const; + + /** + Returns the first character in the input queue without removing it. + */ + char Peek(); + + //@{ + /** + Reads data from the input queue and stores it in the specified output stream. + The data is read until an error is raised by one of the two streams. + + @return This function returns a reference on the current object, so the + user can test any states of the stream right away. + */ + wxInputStream Read(void* buffer, size_t size); + Warning Return value + This function returns a reference on the current object, so the user can test + any states of the stream right away. + wxInputStream& Read(wxOutputStream& stream_out); + //@} + + /** + Changes the stream current position. + + @param pos + Offset to seek to. + @param mode + One of wxFromStart, wxFromEnd, wxFromCurrent. + + @return The new stream position or wxInvalidOffset on error. + */ + off_t SeekI(off_t pos, wxSeekMode mode = wxFromStart); + + /** + Returns the current stream position. + */ + off_t TellI() const; + + //@{ + /** + This function acts like the previous one except that it takes only one + character: it is sometimes shorter to use than the generic function. + */ + size_t Ungetch(const char* buffer, size_t size); + Return value bool Ungetch(char c); + //@} +}; + + + +/** + @class wxStreamBase + @wxheader{stream.h} + + This class is the base class of most stream related classes in wxWidgets. It + must + not be used directly. + + @library{wxbase} + @category{streams} + + @see wxStreamBuffer +*/ +class wxStreamBase +{ +public: + /** + Creates a dummy stream object. It doesn't do anything. + */ + wxStreamBase(); + + /** + Destructor. + */ + ~wxStreamBase(); + + /** + This function returns the last error. + + @b wxSTREAM_NO_ERROR + + No error occurred. + + @b wxSTREAM_EOF + + An End-Of-File occurred. + + @b wxSTREAM_WRITE_ERROR + + A generic error occurred on the last write call. + + @b wxSTREAM_READ_ERROR + + A generic error occurred on the last read call. + */ + wxStreamError GetLastError() const; + + /** + Returns the length of the stream in bytes. If the length cannot be determined + (this is always the case for socket streams for example), returns + @c wxInvalidOffset. + + @since 2.5.4 + */ + wxFileOffset GetLength() const; + + /** + GetLength() + This function returns the size of the stream. For example, for a file it is the + size of the file. + */ + size_t GetSize() const; + + /** + Returns @true if no error occurred on the stream. + + @see GetLastError() + */ + virtual bool IsOk() const; + + /** + Returns @true if the streams supports seeking to arbitrary offsets. + */ + bool IsSeekable() const; + + /** + Internal function. It is called when the stream wants to read data of the + specified size. It should return the size that was actually read. + */ + size_t OnSysRead(void* buffer, size_t bufsize); + + /** + Internal function. It is called when the stream needs to change the + current position. + */ + off_t OnSysSeek(off_t pos, wxSeekMode mode); + + /** + Internal function. Is is called when the stream needs to know the + real position. + */ + off_t OnSysTell() const; + + /** + See OnSysRead(). + */ + size_t OnSysWrite(const void* buffer, size_t bufsize); +}; + diff --git a/interface/wx/string.h b/interface/wx/string.h new file mode 100644 index 0000000000..25c36a1d8d --- /dev/null +++ b/interface/wx/string.h @@ -0,0 +1,1377 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: string.h +// Purpose: interface of wxStringBuffer +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxStringBuffer + @wxheader{string.h} + + This tiny class allows to conveniently access the wxString + internal buffer as a writable pointer without any risk of forgetting to restore + the string to the usable state later. + + For example, assuming you have a low-level OS function called + @c GetMeaningOfLifeAsString(char *) returning the value in the provided + buffer (which must be writable, of course) you might call it like this: + + @code + wxString theAnswer; + GetMeaningOfLifeAsString(wxStringBuffer(theAnswer, 1024)); + if ( theAnswer != "42" ) + { + wxLogError("Something is very wrong!"); + } + @endcode + + Note that the exact usage of this depends on whether on not wxUSE_STL is + enabled. If + wxUSE_STL is enabled, wxStringBuffer creates a separate empty character buffer, + and + if wxUSE_STL is disabled, it uses GetWriteBuf() from wxString, keeping the same + buffer + wxString uses intact. In other words, relying on wxStringBuffer containing the + old + wxString data is probably not a good idea if you want to build your program in + both + with and without wxUSE_STL. + + @library{wxbase} + @category{FIXME} +*/ +class wxStringBuffer +{ +public: + /** + Constructs a writable string buffer object associated with the given string + and containing enough space for at least @a len characters. Basically, this + is equivalent to calling wxString::GetWriteBuf and + saving the result. + */ + wxStringBuffer(const wxString& str, size_t len); + + /** + Restores the string passed to the constructor to the usable state by calling + wxString::UngetWriteBuf on it. + */ + ~wxStringBuffer(); + + /** + Returns the writable pointer to a buffer of the size at least equal to the + length specified in the constructor. + */ + wxStringCharType* operator wxStringCharType *(); +}; + + + +/** + @class wxString + @wxheader{string.h} + + wxString is a class representing a Unicode character string. + wxString uses @c std::string internally to store its content + unless this is not supported by the compiler or disabled + specifically when building wxWidgets. Therefore wxString + inherits many features from @c std::string's. Most + implementations of @std::string are thread-safe and don't + use reference counting. By default, wxString uses @c std::string + internally even if wxUSE_STL is not defined. + + Since wxWidgets 3.0 wxString internally uses UCS-2 (basically 2-byte per + character wchar_t) under Windows and UTF-8 under Unix, Linux and + OS X to store its content. Much work has been done to make existing + code using ANSI string literals work as before. If you need to have a + wxString that uses wchar_t on Unix and Linux, too, you can specify + this on the command line with the @c configure @c --disable-utf8 switch. + + As a consequence of this change, iterating over a wxString by index + can become inefficient in UTF8 mode and iterators should be used instead: + + @code + wxString s = "hello"; + wxString::const_iterator i; + for (i = s.begin(); i != s.end(); ++i) + { + wxUniChar uni_ch = *i; + // do something with it + } + @endcode + + Please see the + @ref overview_string "wxString overview" and the + @ref overview_unicode "Unicode overview" for more information + about it. + + wxString uses the current locale encoding to convert any C string + literal to Unicode. The same is done for converting to and from + @c std::string and for the return value of c_str(). For this + conversion, the @a wxConvLibc class instance is used. See wxCSConv and wxMBConv. + + wxString implements most of the methods of the @c std::string class. + These standard functions are only listed here, but they are not + fully documented in this manual. Please see the STL documentation. + The behaviour of all these functions is identical to the behaviour + described there. + + You may notice that wxString sometimes has several functions which do + the same thing like, for example, Length(), Len() and length() which + all return the string length. In all cases of such duplication the + @c std::string compatible method should be used. + + Anything may be concatenated (appended to) with a string. However, you can't + append something to a C string (including literal constants), so to do this it + should be converted to a wxString first. + + @li operator<<() + @li operator+=() + @li operator+() + @li Append() + @li Prepend() + + A string may be constructed either from a C string, (some number of copies of) + a single character or a wide (UNICODE) string. For all constructors (except the + default which creates an empty string) there is also a corresponding assignment + operator. + + @li wxString() + @li operator=() + @li ~wxString() + + The MakeXXX() variants modify the string in place, while the other functions + return a new string which contains the original text converted to the upper or + lower case and leave the original string unchanged. + + @li MakeUpper() + @li Upper() + @li MakeLower() + @li Lower() + + Many functions in this section take a character index in the string. As with C + strings and/or arrays, the indices start from 0, so the first character of a + string is string[0]. Attempt to access a character beyond the end of the + string (which may be even 0 if the string is empty) will provoke an assert + failure in @ref overview_debugging "debug build", but no checks are + done in release builds. + This section also contains both implicit and explicit conversions to C style + strings. Although implicit conversion is quite convenient, it is advised to use + explicit c_str() method for the sake of clarity. + + @li GetChar() + @li GetWritableChar() + @li SetChar() + @li Last() + @li operator[]() + @li c_str() + @li mb_str() + @li wc_str() + @li fn_str() + + The default comparison function Cmp() is case-sensitive and + so is the default version of IsSameAs(). For case + insensitive comparisons you should use CmpNoCase() or + give a second parameter to IsSameAs. This last function is may be more + convenient if only equality of the strings matters because it returns a boolean + @true value if the strings are the same and not 0 (which is usually @false + in C)as Cmp() does. + Matches() is a poor man's regular expression matcher: it only understands + '*' and '?' metacharacters in the sense of DOS command line interpreter. + StartsWith() is helpful when parsing a line of text which should start + with some predefined prefix and is more efficient than doing direct string + comparison as you would also have to precalculate the length of the prefix then. + + @li Cmp() + @li CmpNoCase() + @li IsSameAs() + @li Matches() + @li StartsWith() + @li EndsWith() + + The string provides functions for conversion to signed and unsigned integer and + floating point numbers. All three functions take a pointer to the variable to + put the numeric value in and return @true if the @b entire string could be + converted to a number. + + @li ToLong() + @li ToLongLong() + @li ToULong() + @li ToULongLong() + @li ToDouble() + + These are "advanced" functions and they will be needed quite rarely. + Alloc() and Shrink() are only interesting for optimization purposes. + wxStringBuffer and wxStringBufferLength classes may be very useful + when working with some external API which requires the caller to provide + a writable buffer. + + @li Alloc() + @li Shrink() + @li wxStringBuffer + @li wxStringBufferLength + + Misc. other string functions. + + @li Trim() + @li Truncate() + @li Pad() + + These functions return the string length and check whether the string + is empty or empty it. + + @li Len() + @li IsEmpty() + @li operator!() + @li Empty() + @li Clear() + + + These functions allow to extract substring from this string. All of them don't + modify the original string and return a new string containing the extracted + substring. + + @li Mid() + @li operator()() + @li Left() + @li Right() + @li BeforeFirst() + @li BeforeLast() + @li AfterFirst() + @li AfterLast() + @li StartsWith() + @li EndsWith() + + These functions replace the standard @e strchr() and @e strstr() + functions. + + @li Find() + @li Replace() + + Both formatted versions (Printf/() and stream-like insertion operators + exist (for basic types only). Additionally, the Format() function allows + to use simply append formatted value to a string: + + @li Format() + @li FormatV() + @li Printf() + @li PrintfV() + @li operator>>() + + These functions are deprecated, please consider using new wxWidgets 2.0 + functions instead of them (or, even better, std::string compatible variants). + + Contains(), First(), Freq(), IsAscii(), IsNull(), + IsNumber(), IsWord(), Last(), Length(), LowerCase(), Remove(), Strip(), + SubString(), UpperCase() + + @library{wxbase} + @category{data} + + @stdobjects + ::Objects:, ::wxEmptyString, + + @see @ref overview_string "wxString overview", @ref overview_unicode + "Unicode overview" +*/ +class wxString +{ +public: + /** + An 'invalid' value for string index + */ + static const size_t npos; + + /** + @name Standard types + */ + //@{ + typedef wxUniChar value_type; + typedef wxUniChar char_type; + typedef wxUniCharRef reference; + typedef wxChar* pointer; + typedef const wxChar* const_pointer; + typedef size_t size_type; + typedef wxUniChar const_reference; + //@} + + /** + Default constructor + */ + wxString(); + + /** + Creates a string from another string. Just increases the ref + count by 1. + */ + wxString(const wxString& stringSrc); + + + /** + Constructs a string from the string literal @e psz using + the current locale encoding to convert it to Unicode (wxConvLibc). + */ + wxString(const char *psz); + + /** + Constructs a string from the string literal @e psz using + @e conv to convert it Unicode. + */ + wxString(const char *psz, const wxMBConv& conv); + + /** + Constructs a string from the first @e nLength character of the string literal @e psz using + the current locale encoding to convert it to Unicode (wxConvLibc). + */ + wxString(const char *psz, size_t nLength); + + /** + Constructs a string from the first @e nLength character of the string literal @e psz using + @e conv to convert it Unicode. + */ + wxString(const char *psz, const wxMBConv& conv, size_t nLength); + + /** + Constructs a string from the string literal @e pwz. + */ + wxString(const wchar_t *pwz); + + /** + Constructs a string from the first @e nLength characters of the string literal @e pwz. + */ + wxString(const wchar_t *pwz, size_t nLength); + + /** + Constructs a string from @e buf using the using + the current locale encoding to convert it to Unicode. + */ + wxString(const wxCharBuffer& buf); + + /** + Constructs a string from @e buf. + */ + wxString(const wxWCharBuffer& buf); + + /** + Constructs a string from @e str using the using the current locale encoding + to convert it to Unicode (wxConvLibc). + */ + wxString(const std::string& str); + + /** + Constructs a string from @e str. + */ + wxString(const std::wstring& str); + + + /** + String destructor. Note that this is not virtual, so wxString must not be + inherited from. + */ + ~wxString(); + + /** + Gets all the characters after the first occurrence of @e ch. + Returns the empty string if @e ch is not found. + */ + wxString AfterFirst(wxUniChar ch) const; + + /** + Gets all the characters after the last occurrence of @e ch. + Returns the whole string if @e ch is not found. + */ + wxString AfterLast(wxUniChar ch) const; + + /** + Preallocate enough space for wxString to store @a nLen characters. + + Please note that this method does the same thing as the standard + reserve() one and shouldn't be used in new code. + + This function may be used to increase speed when the string is + constructed by repeated concatenation as in + + @code + // delete all vowels from the string + wxString DeleteAllVowels(const wxString& original) + { + wxString result; + + size_t len = original.length(); + + result.Alloc(len); + + for ( size_t n = 0; n < len; n++ ) + { + if ( strchr("aeuio", tolower(original[n])) == NULL ) + result += original[n]; + } + + return result; + } + @endcode + + because it will avoid the need to reallocate string memory many times + (in case of long strings). Note that it does not set the maximal length + of a string -- it will still expand if more than @a nLen characters are + stored in it. Also, it does not truncate the existing string (use + Truncate() for this) even if its current length is greater than @a nLen. + + @return @true if memory was successfully allocated, @false otherwise. + */ + bool Alloc(size_t nLen); + + /** + Appends the string literal @e psz. + */ + wxString& Append(const char* psz); + + /** + Appends the wide string literal @e pwz. + */ + wxString& Append(const wchar_t* pwz) + + /** + Appends the string literal @e psz with max length @e nLen. + */ + wxString& Append(const char* psz, size_t nLen); + + /** + Appends the wide string literal @e psz with max length @e nLen. + */ + wxString& Append(const wchar_t* pwz, size_t nLen) + + /** + Appends the string @e s. + */ + wxString &Append(const wxString &s); + + /** + Appends the character @e ch @e count times. + */ + wxString &Append(wxUniChar ch, size_t count = 1u); + + /** + Gets all characters before the first occurrence of @e ch. + Returns the whole string if @a ch is not found. + */ + wxString BeforeFirst(wxUniChar ch) const; + + /** + Gets all characters before the last occurrence of @e ch. + Returns the empty string if @a ch is not found. + */ + wxString BeforeLast(wxUniChar ch) const; + + + /** + Empties the string and frees memory occupied by it. + See also: Empty() + */ + void Clear(); + + /** + Returns a deep copy of the string. + + That is, the returned string is guaranteed to not share data with this + string when using reference-counted wxString implementation. + + This method is primarily useful for passing strings between threads + (because wxString is not thread-safe). Unlike creating a copy using + @c wxString(c_str()), Clone() handles embedded NULs correctly. + + @since 2.9.0 + */ + wxString Clone() const; + + /** + Case-sensitive comparison. + Returns a positive value if the string is greater than the argument, + zero if it is equal to it or a negative value if it is less than the + argument (same semantics as the standard @c strcmp() function). + + See also CmpNoCase(), IsSameAs(). + */ + int Cmp(const wxString& s) const; + + /** + Case-insensitive comparison. + Returns a positive value if the string is greater than the argument, + zero if it is equal to it or a negative value if it is less than the + argument (same semantics as the standard @c strcmp() function). + + See also Cmp(), IsSameAs(). + */ + int CmpNoCase(const wxString& s) const; + + + //@{ + /** + Comparison operators + */ + bool operator ==(const wxString& x, const wxString& y); + bool operator ==(const wxString& x, wxUniChar ch); + bool operator !=(const wxString& x, const wxString& y); + bool operator !=(const wxString& x, wxUniChar ch); + bool operator(const wxString& x, const wxString& y); + bool operator(const wxString& x, wxUniChar ch); + bool operator =(const wxString& x, const wxString& y); + bool operator =(const wxString& x, wxUniChar ch); + bool operator(const wxString& x, const wxString& y); + bool operator(const wxString& x, wxUniChar ch); + bool operator =(const wxString& x, const wxString& y); + bool operator =(const wxString& x, wxUniChar ch); + //@} + + + /** + Returns @true if target appears anywhere in wxString; else @false. + This is a wxWidgets 1.xx compatibility function; you should not use it in new + code. + */ + bool Contains(const wxString& str) const; + + + /** + Makes the string empty, but doesn't free memory occupied by the string. + See also: Clear(). + */ + void Empty(); + + /** + This function can be used to test if the string ends with the specified + @e suffix. If it does, the function will return @true and put the + beginning of the string before the suffix into @e rest string if it is not + @NULL. Otherwise, the function returns @false and doesn't + modify the @e rest. + */ + bool EndsWith(const wxString& suffix, wxString *rest = NULL) const; + + /** + Searches for the given character @e ch. Returns the position or + @c wxNOT_FOUND if not found. + */ + int Find(wxUniChar ch, bool fromEnd = false) const; + + /** + Searches for the given string @e sub. Returns the starting position or + @c wxNOT_FOUND if not found. + */ + int Find(const wxString& sub) const; + + //@{ + /** + Same as Find(). + This is a wxWidgets 1.xx compatibility function; + you should not use it in new code. + */ + int First(wxUniChar ch) const; + int First(const wxString& str) const; + //@} + + /** + This static function returns the string containing the result of calling + Printf() with the passed parameters on it. + + @see FormatV(), Printf() + */ + static wxString Format(const wxChar format, ...); + + /** + This static function returns the string containing the result of calling + PrintfV() with the passed parameters on it. + + @see Format(), PrintfV() + */ + static wxString FormatV(const wxChar format, va_list argptr); + + /** + Returns the number of occurrences of @e ch in the string. + This is a wxWidgets 1.xx compatibility function; you should not + use it in new code. + */ + int Freq(wxUniChar ch) const; + + //@{ + /** + Converts given buffer of binary data from 8-bit string to wxString. In + Unicode build, the string is interpreted as being in ISO-8859-1 + encoding. The version without @e len parameter takes NUL-terminated + data. + + This is a convenience method useful when storing binary data in + wxString. It should be used @em only for that purpose and only in + conjunction with To8BitData(). Use mb_str() for conversion of character + data to known encoding. + + @since 2.8.4 + + @see wxString::To8BitData() + */ + static wxString From8BitData(const char* buf, size_t len); + static wxString From8BitData(const char* buf); + //@} + + //@{ + /** + Converts the string or character from an ASCII, 7-bit form + to the native wxString representation. + */ + static wxString FromAscii(const char* s); + static wxString FromAscii(const unsigned char* s); + static wxString FromAscii(const char* s, size_t len); + static wxString FromAscii(const unsigned char* s, size_t len); + static wxString FromAscii(char c); + //@} + + //@{ + /** + Converts C string encoded in UTF-8 to wxString. + Note that this method assumes that @a s is a valid UTF-8 sequence and + doesn't do any validation in release builds, it's validity is only checked in + debug builds. + */ + static wxString FromUTF8(const char* s); + static wxString FromUTF8(const char* s, size_t len); + //@} + + /** + Returns the character at position @a n (read-only). + */ + wxUniChar GetChar(size_t n) const; + + /** + wxWidgets compatibility conversion. Same as c_str(). + */ + const wxCStrData* GetData() const; + + /** + Returns a reference to the character at position @e n. + */ + wxUniCharRef GetWritableChar(size_t n); + + /** + Returns a writable buffer of at least @a len bytes. + It returns a pointer to a new memory block, and the + existing data will not be copied. + Call UngetWriteBuf() as soon as possible to put the + string back into a reasonable state. + This method is deprecated, please use wxStringBuffer or + wxStringBufferLength instead. + */ + wxStringCharType* GetWriteBuf(size_t len); + + /** + Returns @true if the string contains only ASCII characters. + This is a wxWidgets 1.xx compatibility function; you should not use it in new + code. + */ + bool IsAscii() const; + + /** + Returns @true if the string is empty. + */ + bool IsEmpty() const; + + /** + Returns @true if the string is empty (same as wxString::IsEmpty). + This is a wxWidgets 1.xx compatibility function; you should not use it in new + code. + */ + bool IsNull() const; + + /** + Returns @true if the string is an integer (with possible sign). + This is a wxWidgets 1.xx compatibility function; you should not use it in new + code. + */ + bool IsNumber() const; + + //@{ + /** + Test whether the string is equal to the single character @e c. The test is + case-sensitive if @a caseSensitive is @true (default) or not if it is @c + @false. + Returns @true if the string is equal to the character, @false otherwise. + See also Cmp(), CmpNoCase() + */ + bool IsSameAs(const wxString &s, bool caseSensitive = true) const; + bool IsSameAs(wxUniChar ch, bool caseSensitive = true) const; + //@} + + /** + Returns @true if the string is a word. + This is a wxWidgets 1.xx compatibility function; you should not use it in new + code. + */ + bool IsWord() const; + + //@{ + /** + Returns a reference to the last character (writable). + This is a wxWidgets 1.xx compatibility function; + you should not use it in new code. + */ + wxUniCharRef Last(); + const wxUniChar Last(); + //@} + + /** + Returns the first @a count characters of the string. + */ + wxString Left(size_t count) const; + + /** + Returns the length of the string. + */ + size_t Len() const; + + /** + Returns the length of the string (same as Len). + This is a wxWidgets 1.xx compatibility function; you should not use it in new + code. + */ + size_t Length() const; + + /** + Returns this string converted to the lower case. + */ + wxString Lower() const; + + /** + Same as MakeLower. + This is a wxWidgets 1.xx compatibility function; you should not use it in new + code. + */ + void LowerCase(); + + /** + Converts all characters to lower case and returns the result. + */ + wxString& MakeLower(); + + /** + Converts all characters to upper case and returns the result. + */ + wxString& MakeUpper(); + + /** + Returns @true if the string contents matches a mask containing '*' and '?'. + */ + bool Matches(const wxString& mask) const; + + /** + Returns a substring starting at @e first, with length @e count, or the rest of + the string if @a count is the default value. + */ + wxString Mid(size_t first, size_t count = wxSTRING_MAXLEN) const; + + + /** + Adds @a count copies of @a pad to the beginning, or to the end of the + string (the default). Removes spaces from the left or from the right (default). + */ + wxString& Pad(size_t count, wxUniChar pad = ' ', + bool fromRight = true); + + /** + Prepends @a str to this string, returning a reference to this string. + */ + wxString& Prepend(const wxString& str); + + /** + Similar to the standard function @e sprintf(). Returns the number of + characters written, or an integer less than zero on error. + Note that if @c wxUSE_PRINTF_POS_PARAMS is set to 1, then this function supports + Unix98-style positional parameters: + + @note This function will use a safe version of @e vsprintf() (usually called + @e vsnprintf()) whenever available to always allocate the buffer of correct + size. Unfortunately, this function is not available on all platforms and the + dangerous @e vsprintf() will be used then which may lead to buffer overflows. + */ + int Printf(const wxChar* pszFormat, ...); + + /** + Similar to vprintf. Returns the number of characters written, or an integer + less than zero + on error. + */ + int PrintfV(const wxChar* pszFormat, va_list argPtr); + + //@{ + /** + Removes @a len characters from the string, starting at @e pos. + This is a wxWidgets 1.xx compatibility function; you should not use it in new + code. + */ + wxString Remove(size_t pos); + wxString Remove(size_t pos, size_t len); + //@} + + /** + Removes the last character. + */ + wxString RemoveLast(); + + /** + Replace first (or all) occurrences of substring with another one. + @e replaceAll: global replace (default), or only the first occurrence. + Returns the number of replacements made. + */ + size_t Replace(const wxString& strOld, const wxString& strNew, + bool replaceAll = true); + + /** + Returns the last @a count characters. + */ + wxString Right(size_t count) const; + + /** + Sets the character at position @e n. + */ + void SetChar(size_t n, wxUniChar ch); + + /** + Minimizes the string's memory. This can be useful after a call to + Alloc() if too much memory were preallocated. + */ + void Shrink(); + + /** + This function can be used to test if the string starts with the specified + @e prefix. If it does, the function will return @true and put the rest + of the string (i.e. after the prefix) into @a rest string if it is not + @NULL. Otherwise, the function returns @false and doesn't modify the + @e rest. + */ + bool StartsWith(const wxString& prefix, wxString *rest = NULL) const; + + /** + Strip characters at the front and/or end. The same as Trim except that it + doesn't change this string. + This is a wxWidgets 1.xx compatibility function; you should not use it in new + code. + */ + wxString Strip(stripType s = trailing) const; + + /** + Returns the part of the string between the indices @a from and @e to + inclusive. + This is a wxWidgets 1.xx compatibility function, use Mid() + instead (but note that parameters have different meaning). + */ + wxString SubString(size_t from, size_t to) const; + + //@{ + /** + Converts the string to an 8-bit string in ISO-8859-1 encoding in the + form of a wxCharBuffer (Unicode builds only). + + This is a convenience method useful when storing binary data in + wxString. It should be used @em only for this purpose. It is only valid + to call this method on strings created using From8BitData(). + + @since 2.8.4 + + @see wxString::From8BitData() + */ + const char* To8BitData() const; + const wxCharBuffer To8BitData() const; + //@} + + //@{ + /** + Converts the string to an ASCII, 7-bit string in the form of + a wxCharBuffer (Unicode builds only) or a C string (ANSI builds). + Note that this conversion only works if the string contains only ASCII + characters. The @ref mbstr() mb_str method provides more + powerful means of converting wxString to C string. + */ + const char* ToAscii() const; + const wxCharBuffer ToAscii() const; + //@} + + /** + Attempts to convert the string to a floating point number. Returns @true on + success (the number is stored in the location pointed to by @e val) or @false + if the string does not represent such number (the value of @a val is not + modified in this case). + + @see ToLong(), ToULong() + */ + bool ToDouble(double val) const; + + /** + Attempts to convert the string to a signed integer in base @e base. Returns + @true on success in which case the number is stored in the location + pointed to by @a val or @false if the string does not represent a + valid number in the given base (the value of @a val is not modified + in this case). + The value of @a base must be comprised between 2 and 36, inclusive, or + be a special value 0 which means that the usual rules of @c C numbers are + applied: if the number starts with @c 0x it is considered to be in base + 16, if it starts with @c 0 - in base 8 and in base 10 otherwise. Note + that you may not want to specify the base 0 if you are parsing the numbers + which may have leading zeroes as they can yield unexpected (to the user not + familiar with C) results. + + @see ToDouble(), ToULong() + */ + bool ToLong(long val, int base = 10) const; + + /** + This is exactly the same as ToLong() but works with 64 + bit integer numbers. + Notice that currently it doesn't work (always returns @false) if parsing of 64 + bit numbers is not supported by the underlying C run-time library. Compilers + with C99 support and Microsoft Visual C++ version 7 and higher do support this. + + @see ToLong(), ToULongLong() + */ + bool ToLongLong(wxLongLong_t val, int base = 10) const; + + /** + Attempts to convert the string to an unsigned integer in base @e base. + Returns @true on success in which case the number is stored in the + location pointed to by @a val or @false if the string does not + represent a valid number in the given base (the value of @a val is not + modified in this case). Please notice that this function + behaves in the same way as the standard @c strtoul() and so it simply + converts negative numbers to unsigned representation instead of rejecting them + (e.g. -1 is returned as @c ULONG_MAX). + See ToLong() for the more detailed + description of the @a base parameter. + + @see ToDouble(), ToLong() + */ + bool ToULong(unsigned long val, int base = 10) const; + + /** + This is exactly the same as ToULong() but works with 64 + bit integer numbers. + Please see ToLongLong() for additional remarks. + */ + bool ToULongLong(wxULongLong_t val, int base = 10) const; + + //@{ + /** + Same as utf8_str(). + */ + const char* ToUTF8() const; + const wxCharBuffer ToUF8() const; + //@} + + /** + Removes white-space (space, tabs, form feed, newline and carriage return) from + the left or from the right end of the string (right is default). + */ + wxString& Trim(bool fromRight = true); + + /** + Truncate the string to the given length. + */ + wxString& Truncate(size_t len); + + //@{ + /** + Puts the string back into a reasonable state (in which it can be used + normally), after + GetWriteBuf() was called. + The version of the function without the @a len parameter will calculate the + new string length itself assuming that the string is terminated by the first + @c NUL character in it while the second one will use the specified length + and thus is the only version which should be used with the strings with + embedded @c NULs (it is also slightly more efficient as @c strlen() + doesn't have to be called). + This method is deprecated, please use + wxStringBuffer or + wxStringBufferLength instead. + */ + void UngetWriteBuf(); + void UngetWriteBuf(size_t len); + //@} + + /** + Returns this string converted to upper case. + */ + wxString Upper() const; + + /** + The same as MakeUpper. + This is a wxWidgets 1.xx compatibility function; you should not use it in new + code. + */ + void UpperCase(); + + /** + Returns a pointer to the string data (@c const char* when using UTF-8 + internally, @c const wchar_t* when using UCS-2 internally). + + Note that the returned value is not convertible to @c char* or + @c wchar_t*, use char_str() or wchar_str() if you need to pass + string value to a function expecting non-const pointer. + */ + const wxCStrData c_str() const; + + /** + Returns an object with string data that is implicitly convertible to + @c char* pointer. Note that any change to the returned buffer is lost and so + this function is only usable for passing strings to legacy libraries that + don't have const-correct API. Use wxStringBuffer if you want to modify + the string. + + @see c_str() + */ + wxWritableCharBuffer char_str(const wxMBConv& conv = wxConvLibc) const; + + /** + Returns buffer of the specified type containing the string data. + + This method is only useful in template code, otherwise you should + directly call mb_str() or wc_str() if you need to retrieve a narrow or + wide string from this wxString. The template parameter @a t should be + either @c char or @c wchar_t. + + Notice that retrieving a char buffer in UTF-8 build will return the + internal string representation in UTF-8 while in wchar_t build the char + buffer will contain the conversion of the string to the encoding of the + current locale (and so can fail). + + @param len If non-@NULL, filled with the length of the returned buffer. + @return + buffer containing the string contents in the specified type, + notice that it may be @NULL if the conversion failed (e.g. Unicode + string couldn't be converted to the current encoding when @a T is + @c char). + */ + template + wxCharTypeBuffer tchar_str(size_t *len = NULL) const; + + //@{ + /** + Returns string representation suitable for passing to OS' functions + for file handling. + */ + const wchar_t* fn_str() const; + const char* fn_str() const; + const wxCharBuffer fn_str() const; + //@} + + //@{ + /** + Returns multibyte (C string) representation of the string. + In Unicode build, converts using @e conv's wxMBConv::cWC2MB + method and returns wxCharBuffer. In ANSI build, this function + is same as c_str(). + The macro wxWX2MBbuf is defined as the correct return type (without const). + + @see wxMBConv, c_str(), wc_str(), fn_str(), char_str() + */ + const char* mb_str(const wxMBConv& conv = wxConvLibc) const; + const wxCharBuffer mb_str(const wxMBConv& conv = wxConvLibc) const; + //@} + + /** + Extraction from a stream. + */ + friend istream operator(istream& is, wxString& str); + + //@{ + /** + These functions work as C++ stream insertion operators: they insert the given + value into the string. Precision or format cannot be set using them, you can + use Printf() for this. + */ + wxString operator(const wxString& str); + wxString operator(wxUniChar ch); + wxString operator(int i); + wxString operator(float f); + wxString operator(double d); + //@} + + /** + Same as Mid (substring extraction). + */ + wxString operator ()(size_t start, size_t len); + + //@{ + /** + Concatenation: these operators return a new string equal to the + concatenation of the operands. + */ + wxString operator +(const wxString& x, const wxString& y); + wxString operator +(const wxString& x, wxUniChar y); + //@} + + //@{ + /** + Concatenation in place: the argument is appended to the string. + */ + void operator +=(const wxString& str); + void operator +=(wxUniChar c); + //@} + + //@{ + /** + Assignment: the effect of each operation is the same as for the corresponding + constructor (see @ref construct() "wxString constructors"). + */ + wxString operator =(const wxString& str); + wxString operator =(wxUniChar c); + //@} + + //@{ + /** + Element extraction. + */ + wxUniChar operator [](size_t i) const; + wxUniCharRef operator [](size_t i); + //@} + + /** + Empty string is @false, so !string will only return @true if the + string is empty. + + See also IsEmpty(). + */ + bool operator!() const; + + + //@{ + /** + Converts the strings contents to UTF-8 and returns it either as a + temporary wxCharBuffer object or as a pointer to the internal + string contents in UTF-8 build. + */ + const char* utf8_str() const; + const wxCharBuffer utf8_str() const; + //@} + + //@{ + /** + Converts the strings contents to the wide character represention + and returns it as a temporary wxWCharBuffer object or returns a + pointer to the internal string contents in wide character mode. + + The macro wxWX2WCbuf is defined as the correct return + type (without const). + + @see wxMBConv, c_str(), mb_str(), fn_str(), wchar_str() + */ + const wchar_t* wc_str() const; + const wxWCharBuffer wc_str() const; + //@} + + /** + Returns an object with string data that is implicitly convertible to + @c char* pointer. Note that changes to the returned buffer may or may + not be lost (depending on the build) and so this function is only usable for + passing strings to legacy libraries that don't have const-correct API. Use + wxStringBuffer if you want to modify the string. + + @see mb_str(), wc_str(), fn_str(), c_str(), char_str() + */ + wxWritableWCharBuffer wchar_str() const; + + /** + @name Iterator interface + + These methods return iterators to the beginnnig or + end of the string. + */ + //@{ + const_iterator begin() const; + iterator begin(); + const_iterator end() const; + iterator end(); + + const_reverse_iterator rbegin() const; + reverse_iterator rbegin(); + const_reverse_iterator rend() const; + reverse_iterator rend(); + //@} + + /** + @name STL interface + + The supported STL functions are listed here. Please see any + STL reference for their documentation. + */ + //@{ + size_t length() const; + size_type size() const; + size_type max_size() const; + size_type capacity() const; + void reserve(size_t sz); + + void resize(size_t nSize, wxUniChar ch = '\0'); + + wxString& append(const wxString& str, size_t pos, size_t n); + wxString& append(const wxString& str); + wxString& append(const char *sz, size_t n); + wxString& append(const wchar_t *sz, size_t n); + wxString& append(size_t n, wxUniChar ch); + wxString& append(const_iterator first, const_iterator last); + + wxString& assign(const wxString& str, size_t pos, size_t n); + wxString& assign(const wxString& str); + wxString& assign(const char *sz, size_t n); + wxString& assign(const wchar_t *sz, size_t n); + wxString& assign(size_t n, wxUniChar ch); + wxString& assign(const_iterator first, const_iterator last); + + void clear(); + + int compare(const wxString& str) const; + int compare(size_t nStart, size_t nLen, const wxString& str) const; + int compare(size_t nStart, size_t nLen, + const wxString& str, size_t nStart2, size_t nLen2) const; + int compare(size_t nStart, size_t nLen, + const char* sz, size_t nCount = npos) const; + int compare(size_t nStart, size_t nLen, + const wchar_t* sz, size_t nCount = npos) const; + + bool empty() const; + + wxString& erase(size_type pos = 0, size_type n = npos); + iterator erase(iterator first, iterator last); + iterator erase(iterator first); + + size_t find(const wxString& str, size_t nStart = 0) const; + size_t find(const char* sz, size_t nStart = 0, size_t n = npos) const; + size_t find(const wchar_t* sz, size_t nStart = 0, size_t n = npos) const; + size_t find(wxUniChar ch, size_t nStart = 0) const; + + wxString& insert(size_t nPos, const wxString& str); + wxString& insert(size_t nPos, const wxString& str, size_t nStart, size_t n); + wxString& insert(size_t nPos, const char *sz, size_t n); + wxString& insert(size_t nPos, const wchar_t *sz, size_t n); + wxString& insert(size_t nPos, size_t n, wxUniChar ch); + iterator insert(iterator it, wxUniChar ch); + void insert(iterator it, const_iterator first, const_iterator last); + void insert(iterator it, size_type n, wxUniChar ch); + + wxString& replace(size_t nStart, size_t nLen, const wxString& str); + wxString& replace(size_t nStart, size_t nLen, size_t nCount, wxUniChar ch); + wxString& replace(size_t nStart, size_t nLen, + const wxString& str, size_t nStart2, size_t nLen2); + wxString& replace(size_t nStart, size_t nLen, + const char* sz, size_t nCount); + wxString& replace(size_t nStart, size_t nLen, + const wchar_t* sz, size_t nCount); + wxString& replace(size_t nStart, size_t nLen, + const wxString& s, size_t nCount); + wxString& replace(iterator first, iterator last, const wxString& s); + wxString& replace(iterator first, iterator last, const char* s, size_type n); + wxString& replace(iterator first, iterator last, const wchar_t* s, size_type n); + wxString& replace(iterator first, iterator last, size_type n, wxUniChar ch); + wxString& replace(iterator first, iterator last, + const_iterator first1, const_iterator last1); + wxString& replace(iterator first, iterator last, + const char *first1, const char *last1); + wxString& replace(iterator first, iterator last, + const wchar_t *first1, const wchar_t *last1); + + size_t rfind(const wxString& str, size_t nStart = npos) const; + size_t rfind(const char* sz, size_t nStart = npos, size_t n = npos) const; + size_t rfind(const wchar_t* sz, size_t nStart = npos, size_t n = npos) const; + size_t rfind(wxUniChar ch, size_t nStart = npos) const; + + wxString substr(size_t nStart = 0, size_t nLen = npos) const; + + void swap(wxString& str); + + //@} + +}; + + +/** + FIXME +*/ +wxString Objects: +; + +/** + FIXME +*/ +wxString wxEmptyString; + + + + +/** + @class wxStringBufferLength + @wxheader{string.h} + + This tiny class allows to conveniently access the wxString + internal buffer as a writable pointer without any risk of forgetting to restore + the string to the usable state later, and allows the user to set the internal + length of the string. + + For example, assuming you have a low-level OS function called + @c int GetMeaningOfLifeAsString(char *) copying the value in the provided + buffer (which must be writable, of course), and returning the actual length + of the string, you might call it like this: + + @code + wxString theAnswer; + wxStringBuffer theAnswerBuffer(theAnswer, 1024); + int nLength = GetMeaningOfLifeAsString(theAnswerBuffer); + theAnswerBuffer.SetLength(nLength); + if ( theAnswer != "42" ) + { + wxLogError("Something is very wrong!"); + } + @endcode + + Note that the exact usage of this depends on whether on not wxUSE_STL is + enabled. If + wxUSE_STL is enabled, wxStringBuffer creates a separate empty character buffer, + and + if wxUSE_STL is disabled, it uses GetWriteBuf() from wxString, keeping the same + buffer + wxString uses intact. In other words, relying on wxStringBuffer containing the + old + wxString data is probably not a good idea if you want to build your program in + both + with and without wxUSE_STL. + + Note that SetLength @c must be called before wxStringBufferLength destructs. + + @library{wxbase} + @category{FIXME} +*/ +class wxStringBufferLength +{ +public: + /** + Constructs a writable string buffer object associated with the given string + and containing enough space for at least @a len characters. Basically, this + is equivalent to calling wxString::GetWriteBuf and + saving the result. + */ + wxStringBufferLength(const wxString& str, size_t len); + + /** + Restores the string passed to the constructor to the usable state by calling + wxString::UngetWriteBuf on it. + */ + ~wxStringBufferLength(); + + /** + Sets the internal length of the string referred to by wxStringBufferLength to + @a nLength characters. + Must be called before wxStringBufferLength destructs. + */ + void SetLength(size_t nLength); + + /** + Returns the writable pointer to a buffer of the size at least equal to the + length specified in the constructor. + */ + wxChar* operator wxChar *(); +}; + diff --git a/interface/wx/sysopt.h b/interface/wx/sysopt.h new file mode 100644 index 0000000000..1c8286536a --- /dev/null +++ b/interface/wx/sysopt.h @@ -0,0 +1,78 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: sysopt.h +// Purpose: interface of wxSystemOptions +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxSystemOptions + @wxheader{sysopt.h} + + wxSystemOptions stores option/value pairs that wxWidgets itself or + applications can use to alter behaviour at run-time. It can be + used to optimize behaviour that doesn't deserve a distinct API, + but is still important to be able to configure. + + These options are currently recognised by wxWidgets. + + @library{wxbase} + @category{misc} + + @see wxSystemOptions::SetOption, wxSystemOptions::GetOptionInt, + wxSystemOptions::HasOption +*/ +class wxSystemOptions : public wxObject +{ +public: + /** + Default constructor. You don't need to create an instance of wxSystemOptions + since all of its functions are static. + */ + wxSystemOptions(); + + /** + Gets an option. The function is case-insensitive to @e name. + Returns empty string if the option hasn't been set. + + @see SetOption(), GetOptionInt(), + HasOption() + */ + wxString GetOption(const wxString& name) const; + + /** + Gets an option as an integer. The function is case-insensitive to @e name. + If the option hasn't been set, this function returns 0. + + @see SetOption(), GetOption(), + HasOption() + */ + int GetOptionInt(const wxString& name) const; + + /** + Returns @true if the given option is present. The function is + case-insensitive to @e name. + + @see SetOption(), GetOption(), + GetOptionInt() + */ + bool HasOption(const wxString& name) const; + + /** + Returns @true if the option with the given @a name had been set to 0 + value. This is mostly useful for boolean options for which you can't use + @c GetOptionInt(name) == 0 as this would also be @true if the option + hadn't been set at all. + */ + bool IsFalse(const wxString& name) const; + + //@{ + /** + Sets an option. The function is case-insensitive to @e name. + */ + void SetOption(const wxString& name, const wxString& value); + void SetOption(const wxString& name, int value); + //@} +}; + diff --git a/interface/wx/tarstrm.h b/interface/wx/tarstrm.h new file mode 100644 index 0000000000..5edbc5add8 --- /dev/null +++ b/interface/wx/tarstrm.h @@ -0,0 +1,354 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: tarstrm.h +// Purpose: interface of wxTarInputStream +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxTarInputStream + @wxheader{tarstrm.h} + + Input stream for reading tar files. + + wxTarInputStream::GetNextEntry returns an + wxTarEntry object containing the meta-data + for the next entry in the tar (and gives away ownership). Reading from + the wxTarInputStream then returns the entry's data. Eof() becomes @true + after an attempt has been made to read past the end of the entry's data. + When there are no more entries, GetNextEntry() returns @NULL and sets Eof(). + + Tar entries are seekable if the parent stream is seekable. In practice this + usually means they are only seekable if the tar is stored as a local file and + is not compressed. + + @library{wxbase} + @category{streams} + + @see @ref overview_wxarcbyname "Looking up an archive entry by name" +*/ +class wxTarInputStream : public wxArchiveInputStream +{ +public: + //@{ + /** + Constructor. In a Unicode build the second parameter @a conv is + used to translate fields from the standard tar header into Unicode. It has + no effect on the stream's data. @a conv is only used for the standard + tar headers, any pax extended headers are always UTF-8 encoded. + If the parent stream is passed as a pointer then the new filter stream + takes ownership of it. If it is passed by reference then it does not. + */ + wxTarInputStream(wxInputStream& stream, + wxMBConv& conv = wxConvLocal); + wxTarInputStream(wxInputStream* stream, + wxMBConv& conv = wxConvLocal); + //@} + + /** + Closes the current entry. On a non-seekable stream reads to the end of + the current entry first. + */ + bool CloseEntry(); + + /** + Closes the current entry if one is open, then reads the meta-data for + the next entry and returns it in a wxTarEntry + object, giving away ownership. The stream is then open and can be read. + */ + wxTarEntry* GetNextEntry(); + + /** + Closes the current entry if one is open, then opens the entry specified + by the @a entry object. + @a entry should be from the same tar file, and the tar should + be on a seekable stream. + */ + bool OpenEntry(wxTarEntry& entry); +}; + + + +/** + @class wxTarClassFactory + @wxheader{tarstrm.h} + + Class factory for the tar archive format. See the base class + for details. + + @library{wxbase} + @category{FIXME} + + @see @ref overview_wxarc "Archive formats such as zip", @ref + overview_wxarcgeneric "Generic archive programming", wxTarEntry, wxTarInputStream, wxTarOutputStream +*/ +class wxTarClassFactory : public wxArchiveClassFactory +{ +public: + +}; + + + +/** + @class wxTarOutputStream + @wxheader{tarstrm.h} + + Output stream for writing tar files. + + wxTarOutputStream::PutNextEntry is used to create + a new entry in the output tar, then the entry's data is written to the + wxTarOutputStream. Another call to PutNextEntry() closes the current + entry and begins the next. + + @library{wxbase} + @category{streams} + + @see @ref overview_wxarc "Archive formats such as zip", wxTarEntry, + wxTarInputStream +*/ +class wxTarOutputStream : public wxArchiveOutputStream +{ +public: + //@{ + /** + If the parent stream is passed as a pointer then the new filter stream + takes ownership of it. If it is passed by reference then it does not. + In a Unicode build the third parameter @a conv is used to translate the + headers fields into an 8-bit encoding. It has no effect on the stream's data. + When the @a format is @e wxTAR_PAX, pax extended headers are generated + when any header field will not fit the standard tar header block or if it + uses any non-ascii characters. + Extended headers are stored as extra 'files' within the tar, and will be + extracted as such by any other tar program that does not understand them. + The @a conv parameter only affect the standard tar headers, the extended + headers are always UTF-8 encoded. + When the @a format is @e wxTAR_USTAR, no extended headers are + generated, and instead a warning message is logged if any header field + overflows. + */ + wxTarOutputStream(wxOutputStream& stream, + wxTarFormat format = wxTAR_PAX, + wxMBConv& conv = wxConvLocal); + wxTarOutputStream(wxOutputStream* stream, + wxTarFormat format = wxTAR_PAX, + wxMBConv& conv = wxConvLocal); + //@} + + /** + The destructor calls Close() to finish + writing the tar if it has not been called already. + */ + ~wxTarOutputStream(); + + /** + Finishes writing the tar, returning @true if successful. + Called by the destructor if not called explicitly. + */ + bool Close(); + + /** + Close the current entry. It is called implicitly whenever another new + entry is created with CopyEntry() + or PutNextEntry(), or + when the tar is closed. + */ + bool CloseEntry(); + + /** + See wxArchiveOutputStream::CopyArchiveMetaData. + For the tar format this function does nothing. + */ + bool CopyArchiveMetaData(wxTarInputStream& s); + + /** + Takes ownership of @a entry and uses it to create a new entry + in the tar. @a entry is then opened in @a inputStream and its contents + copied to this stream. + For some other archive formats CopyEntry() is much more efficient than + transferring the data using Read() and Write() since it will copy them + without decompressing and recompressing them. For tar however it makes + no difference. + For tars on seekable streams, @a entry must be from the same tar file + as @e stream. For non-seekable streams, @a entry must also be the + last thing read from @e inputStream. + */ + bool CopyEntry(wxTarEntry* entry, wxTarInputStream& inputStream); + + //@{ + /** + The tar is zero padded to round its size up to @e BlockingFactor * 512 bytes. + Defaults to 10 for @e wxTAR_PAX and 20 for @e wxTAR_USTAR + (see the @ref wxtaroutputstream() constructor), as + specified in the POSIX standards. + */ + int GetBlockingFactor(); + const void SetBlockingFactor(int factor); + //@} + + /** + ) + Create a new directory entry + (see wxArchiveEntry::IsDir) + with the given name and timestamp. + PutNextEntry() can + also be used to create directory entries, by supplying a name with + a trailing path separator. + */ + bool PutNextDirEntry(const wxString& name); + + //@{ + /** + , @b wxFileOffset@e size = wxInvalidOffset) + Create a new entry with the given name, timestamp and size. + */ + bool PutNextEntry(wxTarEntry* entry); + bool PutNextEntry(const wxString& name); + //@} +}; + + + +/** + @class wxTarEntry + @wxheader{tarstrm.h} + + Holds the meta-data for an entry in a tar. + + @library{wxbase} + @category{FIXME} + + @see @ref overview_wxarc "Archive formats such as zip", wxTarInputStream, + wxTarOutputStream +*/ +class wxTarEntry : public wxArchiveEntry +{ +public: + //@{ + /** + Copy constructor. + */ + wxTarEntry(const wxString& name = wxEmptyString); + wxTarEntry(const wxTarEntry& entry); + //@} + + //@{ + /** + The entry's access time stamp. See also + wxArchiveEntry::Get/SetDateTime. + */ + wxDateTime GetAccessTime(); + const void SetAccessTime(const wxDateTime& dt); + //@} + + //@{ + /** + The entry's creation time stamp. See also + wxArchiveEntry::Get/SetDateTime. + */ + wxDateTime GetCreateTime(); + const void SetCreateTime(const wxDateTime& dt); + //@} + + //@{ + /** + OS specific IDs defining a device, these are only meaningful when + TypeFlag() is set to @e wxTAR_CHRTYPE + or @e wxTAR_BLKTYPE. + */ + int GetDevMajor(); + const int GetDevMinor(); + const void SetDevMajor(int dev); + void SetDevMinor(int dev); + //@} + + //@{ + /** + The user ID and group ID that has @ref mode() permissions over + this entry. These values aren't usually useful unless the file will only be + restored to the same system it originated from. @ref unamegname() + "Get/SetGroupName and + Get/SetUserName" can be used instead. + */ + int GetGroupId(); + const int GetUserId(); + const void SetGroupId(int id); + void SetUserId(int id); + //@} + + //@{ + /** + The names of the user and group that has @ref mode() permissions + over this entry. These are not present in very old tars. + */ + wxString GetGroupName(); + const wxString GetUserName(); + const void SetGroupName(const wxString& group); + void SetUserName(const wxString& user); + //@} + + //@{ + /** + The filename of a previous entry in the tar that this entry is a link to. + Only meaningful when TypeFlag() is set + to @e wxTAR_LNKTYPE or @e wxTAR_SYMTYPE. + */ + wxString GetLinkName(); + const void SetLinkName(const wxString& link); + //@} + + //@{ + /** + UNIX permission bits for this entry. Giving read, write and execute permissions + to the file's @ref unamegname() "User and Group" and to others. + Symbols are defined for them in wx/file.h. + */ + int GetMode(); + const void SetMode(int mode); + //@} + + //@{ + /** + The size of the entry's data in bytes. + The tar archive format stores the entry's size ahead of the entry's data. + Therefore when creating an archive on a non-seekable stream it is necessary to + supply the correct size when each entry is created. For seekable streams this + is not necessary as wxTarOutputStream will attempt + to seek back and fix the entry's header when the entry is closed, though it is + still more efficient if the size is given beforehand. + */ + void SetSize(wxFileOffset size) const; + wxFileOffset GetSize() const; + //@} + + //@{ + /** + Returns the type of the entry. It should be one of the following: + + When creating archives use just these values. When reading archives + any other values should be treated as @e wxTAR_REGTYPE. + */ + int GetTypeFlag(); + const void SetTypeFlag(int type); + //@} + + //@{ + /** + A static member that translates a filename into the internal format used + within the archive. If the third parameter is provided, the bool pointed + to is set to indicate whether the name looks like a directory name + (i.e. has a trailing path separator). + */ + wxString GetInternalName(); + const wxString GetInternalName(const wxString& name, + wxPathFormat format = wxPATH_NATIVE, + bool* pIsDir = NULL); + //@} + + /** + Assignment operator. + */ + wxTarEntry& operator operator=(const wxTarEntry& entry); +}; + diff --git a/interface/wx/taskbar.h b/interface/wx/taskbar.h new file mode 100644 index 0000000000..9eb2faaefb --- /dev/null +++ b/interface/wx/taskbar.h @@ -0,0 +1,77 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: taskbar.h +// Purpose: interface of wxTaskBarIcon +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxTaskBarIcon + @wxheader{taskbar.h} + + This class represents a taskbar icon. A taskbar icon is an icon that appears in + the 'system tray' and responds to mouse clicks, optionally with a tooltip above it to help provide information. + + @library{wxadv} + @category{FIXME} +*/ +class wxTaskBarIcon : public wxEvtHandler +{ +public: + /** + Default constructor. + */ + wxTaskBarIcon(); + + /** + Destroys the wxTaskBarIcon object, removing the icon if not already removed. + */ + ~wxTaskBarIcon(); + + /** + This method is called by the library when the user requests popup menu + (on Windows and Unix platforms, this is when the user right-clicks the icon). + Override this function in order to provide popup menu associated with the icon. + If CreatePopupMenu returns @NULL (this happens by default), + no menu is shown, otherwise the menu is + displayed and then deleted by the library as soon as the user dismisses it. + The events can be handled by a class derived from wxTaskBarIcon. + */ + virtual wxMenu* CreatePopupMenu(); + + /** + This method is similar to wxWindow::Destroy and can + be used to schedule the task bar icon object for the delayed destruction: it + will be deleted during the next event loop iteration, which allows the task bar + icon to process any pending events for it before being destroyed. + */ + void Destroy(); + + /** + Returns @true if SetIcon() was called with no subsequent RemoveIcon(). + */ + bool IsIconInstalled(); + + /** + Returns @true if the object initialized successfully. + */ + bool IsOk(); + + /** + Pops up a menu at the current mouse position. The events can be handled by + a class derived from wxTaskBarIcon. + */ + bool PopupMenu(wxMenu* menu); + + /** + Removes the icon previously set with SetIcon(). + */ + bool RemoveIcon(); + + /** + Sets the icon, and optional tooltip text. + */ + bool SetIcon(const wxIcon& icon, const wxString& tooltip); +}; + diff --git a/interface/wx/textctrl.h b/interface/wx/textctrl.h new file mode 100644 index 0000000000..c4f03743d5 --- /dev/null +++ b/interface/wx/textctrl.h @@ -0,0 +1,1615 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: textctrl.h +// Purpose: interface of wxTextAttr +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxTextAttr + @wxheader{textctrl.h} + + wxTextAttr represents the character and paragraph attributes, or style, + for a range of text in a wxTextCtrl or wxRichTextCtrl. + + When setting up a wxTextAttr object, pass a bitlist mask to + wxTextAttr::SetFlags to indicate which style elements should be changed. As + a convenience, when you call a setter such as SetFont, the relevant bit + will be set. + + @library{wxcore} + @category{richtext} + + @see wxTextCtrl, wxRichTextCtrl +*/ +class wxTextAttr +{ +public: + //@{ + /** + Constructors. + */ + wxTextAttr(); + wxTextAttr(const wxColour& colText, + const wxColour& colBack = wxNullColour, + const wxFont& font = wxNullFont, + wxTextAttrAlignment alignment = wxTEXT_ALIGNMENT_DEFAULT); + wxTextAttr(const wxTextAttr& attr); + //@} + + /** + Applies the attributes in @a style to the original object, but not those + attributes from @a style that are the same as those in @a compareWith (if passed). + */ + bool Apply(const wxTextAttr& style, + const wxTextAttr* compareWith = NULL); + + /** + Creates a font from the font attributes. + */ + wxFont CreateFont() const; + + /** + Returns the alignment flags. + See SetAlignment() for a list of available styles. + */ + wxTextAttrAlignment GetAlignment() const; + + /** + Returns the background colour. + */ + const wxColour GetBackgroundColour() const; + + /** + Returns a string containing the name of the font associated with the bullet + symbol. + Only valid for attributes with wxTEXT_ATTR_BULLET_SYMBOL. + */ + const wxString GetBulletFont() const; + + /** + Returns the standard bullet name, applicable if the bullet style is + wxTEXT_ATTR_BULLET_STYLE_STANDARD. + Currently the following standard bullet names are supported: + @c standard/circle + @c standard/square + @c standard/diamond + @c standard/triangle + For wxRichTextCtrl users only: if you wish your rich text controls to support + further bullet graphics, you can derive a + class from wxRichTextRenderer or wxRichTextStdRenderer, override @c + DrawStandardBullet and @c EnumerateStandardBulletNames, and + set an instance of the class using wxRichTextBuffer::SetRenderer. + */ + const wxString GetBulletName() const; + + /** + Returns the bullet number. + */ + int GetBulletNumber() const; + + /** + Returns the bullet style. + See SetBulletStyle() for a list of available styles. + */ + int GetBulletStyle() const; + + /** + Returns the bullet text, which could be a symbol, or (for example) cached + outline text. + */ + const wxString GetBulletText() const; + + /** + Returns the name of the character style. + */ + const wxString GetCharacterStyleName() const; + + /** + Returns flags indicating which attributes are applicable. + See SetFlags() for a list of available flags. + */ + long GetFlags() const; + + /** + Creates and returns a font specified by the font attributes in the wxTextAttr + object. Note that + wxTextAttr does not store a wxFont object, so this is only a temporary font. + For greater + efficiency, access the font attributes directly. + */ + wxFont GetFont() const; + + /** + Gets the font attributes from the given font, using only the attributes + specified by @a flags. + */ + bool GetFontAttributes(const wxFont& font, + int flags = wxTEXT_ATTR_FONT); + + /** + Returns the font encoding. + */ + wxFontEncoding GetFontEncoding() const; + + /** + Returns the font face name. + */ + const wxString GetFontFaceName() const; + + /** + Returns the font size in points. + */ + int GetFontSize() const; + + /** + Returns the font style. + */ + int GetFontStyle() const; + + /** + Returns @true if the font is underlined. + */ + bool GetFontUnderlined() const; + + /** + Returns the font weight. + */ + int GetFontWeight() const; + + /** + Returns the left indent in tenths of a millimetre. + */ + long GetLeftIndent() const; + + /** + Returns the left sub-indent in tenths of a millimetre. + */ + long GetLeftSubIndent() const; + + /** + Returns the line spacing value, one of wxTEXT_ATTR_LINE_SPACING_NORMAL, + wxTEXT_ATTR_LINE_SPACING_HALF, and wxTEXT_ATTR_LINE_SPACING_TWICE. + */ + int GetLineSpacing() const; + + /** + Returns the name of the list style. + */ + const wxString GetListStyleName() const; + + /** + Returns the outline level. + */ + bool GetOutlineLevel() const; + + /** + Returns the space in tenths of a millimeter after the paragraph. + */ + int GetParagraphSpacingAfter() const; + + /** + Returns the space in tenths of a millimeter before the paragraph. + */ + int GetParagraphSpacingBefore() const; + + /** + Returns the name of the paragraph style. + */ + const wxString GetParagraphStyleName() const; + + /** + Returns the right indent in tenths of a millimeter. + */ + long GetRightIndent() const; + + /** + Returns an array of tab stops, each expressed in tenths of a millimeter. Each + stop + is measured from the left margin and therefore each value must be larger than + the last. + */ + const wxArrayInt GetTabs() const; + + /** + Returns the text foreground colour. + */ + const wxColour GetTextColour() const; + + /** + Returns the text effect bits of interest. See SetFlags() for further + information. + */ + int GetTextEffectFlags() const; + + /** + Returns the text effects, a bit list of styles. See SetTextEffects() for + details. + */ + int GetTextEffects() const; + + /** + Returns the URL for the content. Content with wxTEXT_ATTR_URL style + causes wxRichTextCtrl to show a hand cursor over it, and wxRichTextCtrl + generates + a wxTextUrlEvent when the content is clicked. + */ + const wxString GetURL() const; + + /** + Returns @true if the attribute object specifies alignment. + */ + bool HasAlignment() const; + + /** + Returns @true if the attribute object specifies a background colour. + */ + bool HasBackgroundColour() const; + + /** + Returns @true if the attribute object specifies a standard bullet name. + */ + bool HasBulletName() const; + + /** + Returns @true if the attribute object specifies a bullet number. + */ + bool HasBulletNumber() const; + + /** + Returns @true if the attribute object specifies a bullet style. + */ + bool HasBulletStyle() const; + + /** + Returns @true if the attribute object specifies bullet text (usually + specifying a symbol). + */ + bool HasBulletText() const; + + /** + Returns @true if the attribute object specifies a character style name. + */ + bool HasCharacterStyleName() const; + + /** + Returns @true if the @a flag is present in the attribute object's flag + bitlist. + */ + bool HasFlag(long flag) const; + + /** + Returns @true if the attribute object specifies any font attributes. + */ + bool HasFont() const; + + /** + Returns @true if the attribute object specifies an encoding. + */ + bool HasFontEncoding() const; + + /** + Returns @true if the attribute object specifies a font face name. + */ + bool HasFontFaceName() const; + + /** + Returns @true if the attribute object specifies italic style. + */ + bool HasFontItalic() const; + + /** + Returns @true if the attribute object specifies a font point size. + */ + bool HasFontSize() const; + + /** + Returns @true if the attribute object specifies either underlining or no + underlining. + */ + bool HasFontUnderlined() const; + + /** + Returns @true if the attribute object specifies font weight (bold, light or + normal). + */ + bool HasFontWeight() const; + + /** + Returns @true if the attribute object specifies a left indent. + */ + bool HasLeftIndent() const; + + /** + Returns @true if the attribute object specifies line spacing. + */ + bool HasLineSpacing() const; + + /** + Returns @true if the attribute object specifies a list style name. + */ + bool HasListStyleName() const; + + /** + Returns @true if the attribute object specifies an outline level. + */ + bool HasOutlineLevel() const; + + /** + Returns @true if the attribute object specifies a page break before this + paragraph. + */ + bool HasPageBreak() const; + + /** + Returns @true if the attribute object specifies spacing after a paragraph. + */ + bool HasParagraphSpacingAfter() const; + + /** + Returns @true if the attribute object specifies spacing before a paragraph. + */ + bool HasParagraphSpacingBefore() const; + + /** + Returns @true if the attribute object specifies a paragraph style name. + */ + bool HasParagraphStyleName() const; + + /** + Returns @true if the attribute object specifies a right indent. + */ + bool HasRightIndent() const; + + /** + Returns @true if the attribute object specifies tab stops. + */ + bool HasTabs() const; + + /** + Returns @true if the attribute object specifies a text foreground colour. + */ + bool HasTextColour() const; + + /** + Returns @true if the attribute object specifies text effects. + */ + bool HasTextEffects() const; + + /** + Returns @true if the attribute object specifies a URL. + */ + bool HasURL() const; + + /** + Returns @true if the object represents a character style, that is, + the flags specify a font or a text background or foreground colour. + */ + bool IsCharacterStyle() const; + + /** + Returns @false if we have any attributes set, @true otherwise. + */ + bool IsDefault() const; + + /** + Returns @true if the object represents a paragraph style, that is, + the flags specify alignment, indentation, tabs, paragraph spacing, or + bullet style. + */ + bool IsParagraphStyle() const; + + //@{ + /** + Creates a new @c wxTextAttr which is a merge of @a base and + @a overlay. Properties defined in @a overlay take precedence over those + in @a base. Properties undefined/invalid in both are undefined in the + result. + */ + void Merge(const wxTextAttr& overlay); + static wxTextAttr Merge(const wxTextAttr& base, + const wxTextAttr& overlay); + //@} + + /** + Sets the paragraph alignment. These are the possible values for @a alignment: + + Of these, wxTEXT_ALIGNMENT_JUSTIFIED is unimplemented. In future justification + may be supported + when printing or previewing, only. + */ + void SetAlignment(wxTextAttrAlignment alignment); + + /** + Sets the background colour. + */ + void SetBackgroundColour(const wxColour& colBack); + + /** + Sets the name of the font associated with the bullet symbol. + Only valid for attributes with wxTEXT_ATTR_BULLET_SYMBOL. + */ + void SetBulletFont(const wxString& font); + + /** + Sets the standard bullet name, applicable if the bullet style is + wxTEXT_ATTR_BULLET_STYLE_STANDARD. + See GetBulletName() for a list + of supported names, and how to expand the range of supported types. + */ + void SetBulletName(const wxString& name); + + /** + Sets the bullet number. + */ + void SetBulletNumber(int n); + + /** + Sets the bullet style. The following styles can be passed: + + Currently wxTEXT_ATTR_BULLET_STYLE_BITMAP is not supported. + */ + void SetBulletStyle(int style); + + /** + Sets the bullet text, which could be a symbol, or (for example) cached outline + text. + */ + void SetBulletText(const wxString text); + + /** + Sets the character style name. + */ + void SetCharacterStyleName(const wxString& name); + + /** + Sets the flags determining which styles are being specified. The following + flags can be passed in a bitlist: + */ + void SetFlags(long flags); + + /** + Sets the attributes for the given font. Note that wxTextAttr does not store an + actual wxFont object. + */ + void SetFont(const wxFont& font); + + /** + Sets the font encoding. + */ + void SetFontEncoding(wxFontEncoding encoding); + + /** + Sets the paragraph alignment. + */ + void SetFontFaceName(const wxString& faceName); + + /** + Sets the font size in points. + */ + void SetFontSize(int pointSize); + + /** + Sets the font style (normal, italic or slanted). + */ + void SetFontStyle(int fontStyle); + + /** + Sets the font underlining. + */ + void SetFontUnderlined(bool underlined); + + /** + Sets the font weight. + */ + void SetFontWeight(int fontWeight); + + /** + Sets the left indent and left subindent in tenths of a millimetre. + The sub-indent is an offset from the left of the paragraph, and is used for all + but the + first line in a paragraph. A positive value will cause the first line to appear + to the left + of the subsequent lines, and a negative value will cause the first line to be + indented + relative to the subsequent lines. + wxRichTextBuffer uses indentation to render a bulleted item. The left indent is + the distance between + the margin and the bullet. The content of the paragraph, including the first + line, starts + at leftMargin + leftSubIndent. So the distance between the left edge of the + bullet and the + left of the actual paragraph is leftSubIndent. + */ + void SetLeftIndent(int indent, int subIndent = 0); + + /** + Sets the line spacing. @a spacing is a multiple, where 10 means single-spacing, + 15 means 1.5 spacing, and 20 means double spacing. The following constants are + defined for convenience: + */ + void SetLineSpacing(int spacing); + + /** + Sets the list style name. + */ + void SetListStyleName(const wxString& name); + + /** + Specifies the outline level. Zero represents normal text. At present, the + outline level is + not used, but may be used in future for determining list levels and for + applications + that need to store document structure information. + */ + void SetOutlineLevel(int level); + + /** + Specifies a page break before this paragraph. + */ + void SetPageBreak(bool pageBreak = true); + + /** + Sets the spacing after a paragraph, in tenths of a millimetre. + */ + void SetParagraphSpacingAfter(int spacing); + + /** + Sets the spacing before a paragraph, in tenths of a millimetre. + */ + void SetParagraphSpacingBefore(int spacing); + + /** + Sets the name of the paragraph style. + */ + void SetParagraphStyleName(const wxString& name); + + /** + Sets the right indent in tenths of a millimetre. + */ + void SetRightIndent(int indent); + + /** + Sets the tab stops, expressed in tenths of a millimetre. + Each stop is measured from the left margin and therefore each value must be + larger than the last. + */ + void SetTabs(const wxArrayInt& tabs); + + /** + Sets the text foreground colout. + */ + void SetTextColour(const wxColour& colText); + + /** + Sets the text effect bits of interest. You should also pass wxTEXT_ATTR_EFFECTS + to SetFlags(). + See SetFlags() for further information. + */ + void SetTextEffectFlags(int flags); + + /** + Sets the text effects, a bit list of styles. + The following styles can be passed: + + Of these, only wxTEXT_ATTR_EFFECT_CAPITALS and wxTEXT_ATTR_EFFECT_STRIKETHROUGH + are implemented. + wxTEXT_ATTR_EFFECT_CAPITALS capitalises text when displayed (leaving the case + of the actual buffer + text unchanged), and wxTEXT_ATTR_EFFECT_STRIKETHROUGH draws a line through text. + To set effects, you should also pass wxTEXT_ATTR_EFFECTS to SetFlags(), and call + SetTextEffectFlags() with the styles (taken from the + above set) that you are interested in setting. + */ + void SetTextEffects(int effects); + + /** + Sets the URL for the content. Sets the wxTEXT_ATTR_URL style; content with this + style + causes wxRichTextCtrl to show a hand cursor over it, and wxRichTextCtrl + generates + a wxTextUrlEvent when the content is clicked. + */ + void SetURL(const wxString& url); + + /** + Assignment from a wxTextAttr object. + */ + void operator operator=(const wxTextAttr& attr); +}; + +/** + Describes the possible return values of wxTextCtrl::HitTest(). + + The element names correspond to the relationship between the point asked + for and the character returned, e.g. @c wxTE_HT_BEFORE means that the point + is before (leftward or upward) it and so on. + */ +enum wxTextCtrlHitTestResult +{ + /// Indicates that wxTextCtrl::HitTest() is not implemented on this + /// platform. + wxTE_HT_UNKNOWN = -2, + + /// The point is before the character returned. + wxTE_HT_BEFORE, + + /// The point is directly on the character returned. + wxTE_HT_ON_TEXT, + + /// The point is below the last line of the control. + wxTE_HT_BELOW, + + /// The point is beyond the end of line containing the character returned. + wxTE_HT_BEYOND +}; + + +/** + @class wxTextCtrl + @wxheader{textctrl.h} + + A text control allows text to be displayed and edited. + + It may be single line or multi-line. + + @beginStyleTable + @style{wxTE_PROCESS_ENTER} + The control will generate the event wxEVT_COMMAND_TEXT_ENTER + (otherwise pressing Enter key is either processed internally by the + control or used for navigation between dialog controls). + @style{wxTE_PROCESS_TAB} + The control will receive wxEVT_CHAR events for TAB pressed - + normally, TAB is used for passing to the next control in a dialog + instead. For the control created with this style, you can still use + Ctrl-Enter to pass to the next control from the keyboard. + @style{wxTE_MULTILINE} + The text control allows multiple lines. + @style{wxTE_PASSWORD} + The text will be echoed as asterisks. + @style{wxTE_READONLY} + The text will not be user-editable. + @style{wxTE_RICH} + Use rich text control under Win32, this allows to have more than + 64KB of text in the control even under Win9x. This style is ignored + under other platforms. + @style{wxTE_RICH2} + Use rich text control version 2.0 or 3.0 under Win32, this style is + ignored under other platforms + @style{wxTE_AUTO_URL} + Highlight the URLs and generate the wxTextUrlEvents when mouse + events occur over them. This style is only supported for wxTE_RICH + Win32 and multi-line wxGTK2 text controls. + @style{wxTE_NOHIDESEL} + By default, the Windows text control doesn't show the selection + when it doesn't have focus - use this style to force it to always + show it. It doesn't do anything under other platforms. + @style{wxHSCROLL} + A horizontal scrollbar will be created and used, so that text won't + be wrapped. No effect under wxGTK1. + @style{wxTE_NO_VSCROLL} + For multiline controls only: vertical scrollbar will never be + created. This limits the amount of text which can be entered into + the control to what can be displayed in it under MSW but not under + GTK2. Currently not implemented for the other platforms. + @style{wxTE_LEFT} + The text in the control will be left-justified (default). + @style{wxTE_CENTRE} + The text in the control will be centered (currently wxMSW and + wxGTK2 only). + @style{wxTE_RIGHT} + The text in the control will be right-justified (currently wxMSW + and wxGTK2 only). + @style{wxTE_DONTWRAP} + Same as wxHSCROLL style: don't wrap at all, show horizontal + scrollbar instead. + @style{wxTE_CHARWRAP} + Wrap the lines too long to be shown entirely at any position + (wxUniv and wxGTK2 only). + @style{wxTE_WORDWRAP} + Wrap the lines too long to be shown entirely at word boundaries + (wxUniv and wxGTK2 only). + @style{wxTE_BESTWRAP} + Wrap the lines at word boundaries or at any other character if + there are words longer than the window width (this is the default). + @style{wxTE_CAPITALIZE} + On PocketPC and Smartphone, causes the first letter to be + capitalized. + @endStyleTable + + + @section textctrl_text_format wxTextCtrl Text Format + + The multiline text controls always store the text as a sequence of lines + separated by @c '\\n' characters, i.e. in the Unix text format even on + non-Unix platforms. This allows the user code to ignore the differences + between the platforms but at a price: the indices in the control such as + those returned by GetInsertionPoint() or GetSelection() can @b not be used + as indices into the string returned by GetValue() as they're going to be + slightly off for platforms using @c "\\r\\n" as separator (as Windows + does). + + Instead, if you need to obtain a substring between the 2 indices obtained + from the control with the help of the functions mentioned above, you should + use GetRange(). And the indices themselves can only be passed to other + methods, for example SetInsertionPoint() or SetSelection(). + + To summarize: never use the indices returned by (multiline) wxTextCtrl as + indices into the string it contains, but only as arguments to be passed + back to the other wxTextCtrl methods. This problem doesn't arise for + single-line platforms however where the indices in the control do + correspond to the positions in the value string. + + + @section textctrl_styles wxTextCtrl Styles. + + Multi-line text controls support styling, i.e. provide a possibility to set + colours and font for individual characters in it (note that under Windows + @c wxTE_RICH style is required for style support). To use the styles you + can either call SetDefaultStyle() before inserting the text or call + SetStyle() later to change the style of the text already in the control + (the first solution is much more efficient). + + In either case, if the style doesn't specify some of the attributes (for + example you only want to set the text colour but without changing the font + nor the text background), the values of the default style will be used for + them. If there is no default style, the attributes of the text control + itself are used. + + So the following code correctly describes what it does: the second call to + SetDefaultStyle() doesn't change the text foreground colour (which stays + red) while the last one doesn't change the background colour (which stays + grey): + + @code + text->SetDefaultStyle(wxTextAttr(*wxRED)); + text->AppendText("Red text\n"); + text->SetDefaultStyle(wxTextAttr(wxNullColour, *wxLIGHT_GREY)); + text->AppendText("Red on grey text\n"); + text->SetDefaultStyle(wxTextAttr(*wxBLUE); + text->AppendText("Blue on grey text\n"); + @endcode + + + @section textctrl_cpp_streams wxTextCtrl and C++ Streams + + This class multiply-inherits from @c std::streambuf (except for some really + old compilers using non-standard iostream library), allowing code such as + the following: + + @code + wxTextCtrl *control = new wxTextCtrl(...); + + ostream stream(control) + + stream << 123.456 << " some text\n"; + stream.flush(); + @endcode + + Note that even if your compiler doesn't support this (the symbol + @c wxHAS_TEXT_WINDOW_STREAM has value of 0 then) you can still use + wxTextCtrl itself in a stream-like manner: + + @code + wxTextCtrl *control = new wxTextCtrl(...); + + *control << 123.456 << " some text\n"; + @endcode + + However the possibility to create an ostream associated with wxTextCtrl may + be useful if you need to redirect the output of a function taking an + ostream as parameter to a text control. + + Another commonly requested need is to redirect @c std::cout to the text + control. This may be done in the following way: + + @code + #include + + wxTextCtrl *control = new wxTextCtrl(...); + + std::streambuf *sbOld = std::cout.rdbuf(); + std::cout.rdbuf(control); + + // use cout as usual, the output appears in the text control + ... + + std::cout.rdbuf(sbOld); + @endcode + + But wxWidgets provides a convenient class to make it even simpler so + instead you may just do + + @code + #include + + wxTextCtrl *control = new wxTextCtrl(...); + + wxStreamToTextRedirector redirect(control); + + // all output to cout goes into the text control until the exit from + // current scope + @endcode + + See wxStreamToTextRedirector for more details. + + + @section textctrl_event_handling Event Handling. + + The following commands are processed by default event handlers in + wxTextCtrl: @c wxID_CUT, @c wxID_COPY, @c wxID_PASTE, @c wxID_UNDO, @c + wxID_REDO. The associated UI update events are also processed + automatically, when the control has the focus. + + To process input from a text control, use these event handler macros to + direct input to member functions that take a wxCommandEvent argument. + + @beginEventTable{wxCommandEvent} + @event{EVT_TEXT(id, func)} + Respond to a wxEVT_COMMAND_TEXT_UPDATED event, generated when the text + changes. Notice that this event will be sent when the text controls + contents changes -- whether this is due to user input or comes from the + program itself (for example, if SetValue() is called); see + ChangeValue() for a function which does not send this event. This + event is however not sent during the control creation. + @event{EVT_TEXT_ENTER(id, func)} + Respond to a wxEVT_COMMAND_TEXT_ENTER event, generated when enter is + pressed in a text control which must have wxTE_PROCESS_ENTER style for + this event to be generated. + @event{EVT_TEXT_URL(id, func)} + A mouse event occurred over an URL in the text control (wxMSW and + wxGTK2 only currently). + @event{EVT_TEXT_MAXLEN(id, func)} + This event is generated when the user tries to enter more text into the + control than the limit set by SetMaxLength(), see its description. + @endEventTable + + @library{wxcore} + @category{ctrl} + + + @see wxTextCtrl::Create, wxValidator +*/ +class wxTextCtrl : public wxControl +{ +public: + //@{ + /** + Constructor, creating and showing a text control. + @see Create() + */ + wxTextCtrl(); + + /** + Constructor, creating and showing a text control. + + @param parent + Parent window. Should not be @NULL. + @param id + Control identifier. A value of -1 denotes a default value. + @param value + Default text value. + @param pos + Text control position. + @param size + Text control size. + @param style + Window style. See wxTextCtrl. + @param validator + Window validator. + @param name + Window name. + + @remarks The horizontal scrollbar (wxHSCROLL style flag) will only be + created for multi-line text controls. Without a horizontal + scrollbar, text lines that don't fit in the control's size will be + wrapped (but no newline character is inserted). Single line + controls don't have a horizontal scrollbar, the text is + automatically scrolled so that the insertion point is always + visible. + + @see Create(), wxValidator + */ + wxTextCtrl(wxWindow* parent, wxWindowID id, + const wxString& value = "", + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = wxTextCtrlNameStr); + //@} + + /** + Destructor, destroying the text control. + */ + ~wxTextCtrl(); + + /** + Appends the text to the end of the text control. + + @param text + Text to write to the text control. + + @remarks After the text is appended, the insertion point will be at the + end of the text control. If this behaviour is not desired, the + programmer should use GetInsertionPoint and SetInsertionPoint. + + @see WriteText() + */ + void AppendText(const wxString& text); + + /** + Call this function to enable auto-completion of the text typed in a + single-line text control using the given @a choices. + + Notice that currently this function is only implemented in wxGTK2 and + wxMSW ports and does nothing under the other platforms. + + @since 2.9.0 + + @return + @true if the auto-completion was enabled or @false if the operation + failed, typically because auto-completion is not supported by the + current platform. + + @see AutoCompleteFileNames() + */ + bool AutoComplete(const wxArrayString& choices); + + /** + Call this function to enable auto-completion of the text typed in a + single-line text control using all valid file system paths. + + Notice that currently this function is only implemented in wxGTK2 port + and does nothing under the other platforms. + + @since 2.9.0 + + @return + @true if the auto-completion was enabled or @false if the operation + failed, typically because auto-completion is not supported by the + current platform. + + @see AutoComplete() + */ + bool AutoCompleteFileNames(); + + /** + Returns @true if the selection can be copied to the clipboard. + */ + virtual bool CanCopy(); + + /** + Returns @true if the selection can be cut to the clipboard. + */ + virtual bool CanCut(); + + /** + Returns @true if the contents of the clipboard can be pasted into the + text control. + + On some platforms (Motif, GTK) this is an approximation and returns + @true if the control is editable, @false otherwise. + */ + virtual bool CanPaste(); + + /** + Returns @true if there is a redo facility available and the last + operation can be redone. + */ + virtual bool CanRedo(); + + /** + Returns @true if there is an undo facility available and the last + operation can be undone. + */ + virtual bool CanUndo(); + + /** + Sets the text value and marks the control as not-modified (which means + that IsModified() would return @false immediately after the call to + SetValue). + + This functions does not generate the @c wxEVT_COMMAND_TEXT_UPDATED + event but otherwise is identical to SetValue(). + See @ref overview_progevent "this topic" for more information. + + @since 2.7.1 + + @param value + The new value to set. It may contain newline characters if the text + control is multi-line. + */ + virtual void ChangeValue(const wxString& value); + + /** + Clears the text in the control. + + Note that this function will generate a @c wxEVT_COMMAND_TEXT_UPDATED + event, i.e. its effect is identical to calling @c SetValue(""). + */ + virtual void Clear(); + + /** + Copies the selected text to the clipboard. + */ + virtual void Copy(); + + /** + Creates the text control for two-step construction. + + This method should be called if the default constructor was used for + the control creation. Its parameters have the same meaning as for the + non-default constructor. + */ + bool Create(wxWindow* parent, wxWindowID id, + const wxString& value = "", + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = wxTextCtrlNameStr); + + /** + Copies the selected text to the clipboard and removes the selection. + */ + virtual void Cut(); + + /** + Resets the internal modified flag as if the current changes had been + saved. + */ + void DiscardEdits(); + + /** + This functions inserts into the control the character which would have + been inserted if the given key event had occurred in the text control. + + The @a event object should be the same as the one passed to @c + EVT_KEY_DOWN handler previously by wxWidgets. Please note that this + function doesn't currently work correctly for all keys under any + platform but MSW. + + @return + @true if the event resulted in a change to the control, @false + otherwise. + */ + bool EmulateKeyPress(const wxKeyEvent& event); + + /** + Returns the style currently used for the new text. + + @see SetDefaultStyle() + */ + const wxTextAttr GetDefaultStyle() const; + + /** + Returns the insertion point, or cursor, position. + + This is defined as the zero based index of the character position to + the right of the insertion point. For example, if the insertion point + is at the end of the single-line text control, it is equal to both + GetLastPosition() and GetValue().length() (but notice that the latter + equality is not necessarily true for multiline edit controls which may + use multiple new line characters). + */ + virtual long GetInsertionPoint() const; + + /** + Returns the zero based index of the last position in the text control, + which is equal to the number of characters in the control. + */ + virtual wxTextPos GetLastPosition() const; + + /** + Gets the length of the specified line, not including any trailing + newline character(s). + + @param lineNo + Line number (starting from zero). + + @return + The length of the line, or -1 if @a lineNo was invalid. + */ + int GetLineLength(long lineNo) const; + + /** + Returns the contents of a given line in the text control, not including + any trailing newline character(s). + + @param lineNo + The line number, starting from zero. + + @return + The contents of the line. + */ + wxString GetLineText(long lineNo) const; + + /** + Returns the number of lines in the text control buffer. + + @remarks Note that even empty text controls have one line (where the + insertion point is), so GetNumberOfLines() never + returns 0. + */ + int GetNumberOfLines() const; + + /** + Returns the string containing the text starting in the positions + @a from and up to @a to in the control. + + The positions must have been returned by another wxTextCtrl method. + Please note that the positions in a multiline wxTextCtrl do @b not + correspond to the indices in the string returned by GetValue() because + of the different new line representations (@c CR or @c CR LF) and so + this method should be used to obtain the correct results instead of + extracting parts of the entire value. It may also be more efficient, + especially if the control contains a lot of data. + */ + virtual wxString GetRange(long from, long to) const; + + /** + Gets the current selection span. + + If the returned values are equal, there was no selection. Please note + that the indices returned may be used with the other wxTextCtrl methods + but don't necessarily represent the correct indices into the string + returned by GetValue() for multiline controls under Windows (at least,) + you should use GetStringSelection() to get the selected text. + + @param from + The returned first position. + @param to + The returned last position. + */ + virtual void GetSelection(long* from, long* to) const; + + /** + Gets the text currently selected in the control. + + If there is no selection, the returned string is empty. + */ + virtual wxString GetStringSelection(); + + /** + Returns the style at this position in the text control. + + Not all platforms support this function. + + @return + @true on success, @false if an error occurred (this may also mean + that the styles are not supported under this platform). + + @see SetStyle(), wxTextAttr + */ + bool GetStyle(long position, wxTextAttr& style); + + /** + Gets the contents of the control. + Notice that for a multiline text control, the lines will be separated + by (Unix-style) @c \\n characters, even under Windows where they are + separated by a @c \\r\\n sequence in the native control. + */ + wxString GetValue() const; + + /** + This function finds the character at the specified position expressed + in pixels. + + If the return code is not @c wxTE_HT_UNKNOWN the row and column of the + character closest to this position are returned in the @a col and @a + row parameters (unless the pointers are @NULL which is allowed). Please + note that this function is currently only implemented in wxUniv, wxMSW + and wxGTK2 ports. + + @see PositionToXY(), XYToPosition() + */ + wxTextCtrlHitTestResult HitTest(const wxPoint& pt, + wxTextCoord col, + wxTextCoord row) const; + + /** + Returns @true if the controls contents may be edited by user (note that + it always can be changed by the program). + + In other words, this functions returns @true if the control hasn't been + put in read-only mode by a previous call to SetEditable(). + */ + bool IsEditable() const; + + /** + Returns @true if the control is currently empty. + + This is the same as @c GetValue().empty() but can be much more + efficient for the multiline controls containing big amounts of text. + + @since 2.7.1 + */ + bool IsEmpty() const; + + /** + Returns @true if the text has been modified by user. + + Note that calling SetValue() doesn't make the control modified. + + @see MarkDirty() + */ + bool IsModified() const; + + /** + Returns @true if this is a multi line edit control and @false + otherwise. + + @see IsSingleLine() + */ + bool IsMultiLine() const; + + /** + Returns @true if this is a single line edit control and @false + otherwise. + + @see @ref IsSingleLine() IsMultiLine + */ + bool IsSingleLine() const; + + /** + Loads and displays the named file, if it exists. + + @param filename + The filename of the file to load. + @param fileType + The type of file to load. This is currently ignored in wxTextCtrl. + + @return + @true if successful, @false otherwise. + */ + bool LoadFile(const wxString& filename, + int fileType = wxTEXT_TYPE_ANY); + + /** + Mark text as modified (dirty). + + @see IsModified() + */ + void MarkDirty(); + + /** + This event handler function implements default drag and drop behaviour, + which is to load the first dropped file into the control. + + @param event + The drop files event. + + @remarks This is not implemented on non-Windows platforms. + + @see wxDropFilesEvent + */ + void OnDropFiles(wxDropFilesEvent& event); + + /** + Pastes text from the clipboard to the text item. + */ + virtual void Paste(); + + /** + Converts given position to a zero-based column, line number pair. + + @param pos + Position. + @param x + Receives zero based column number. + @param y + Receives zero based line number. + + @return + @true on success, @false on failure (most likely due to a too large + position parameter). + + @see XYToPosition() + */ + bool PositionToXY(long pos, long* x, long* y) const; + + /** + If there is a redo facility and the last operation can be redone, + redoes the last operation. + + Does nothing if there is no redo facility. + */ + virtual void Redo(); + + /** + Removes the text starting at the first given position up to (but not + including) the character at the last position. + + @param from + The first position. + @param to + The last position. + */ + virtual void Remove(long from, long to); + + /** + Replaces the text starting at the first position up to (but not + including) the character at the last position with the given text. + + @param from + The first position. + @param to + The last position. + @param value + The value to replace the existing text with. + */ + virtual void Replace(long from, long to, const wxString& value); + + /** + Saves the contents of the control in a text file. + + @param filename + The name of the file in which to save the text. + @param fileType + The type of file to save. This is currently ignored in wxTextCtrl. + + @return + @true if the operation was successful, @false otherwise. + */ + bool SaveFile(const wxString& filename, + int fileType = wxTEXT_TYPE_ANY); + + /** + Changes the default style to use for the new text which is going to be + added to the control using WriteText() or AppendText(). + + If either of the font, foreground, or background colour is not set in + @a style, the values of the previous default style are used for them. + If the previous default style didn't set them neither, the global font + or colours of the text control itself are used as fall back. However if + the @a style parameter is the default wxTextAttr, then the default + style is just reset (instead of being combined with the new style which + wouldn't change it at all). + + @param style + The style for the new text. + + @return + @true on success, @false if an error occurred (this may also mean + that the styles are not supported under this platform). + + @see GetDefaultStyle() + */ + bool SetDefaultStyle(const wxTextAttr& style); + + /** + Makes the text item editable or read-only, overriding the + @b wxTE_READONLY flag. + + @param editable + If @true, the control is editable. If @false, the control is + read-only. + + @see IsEditable() + */ + virtual void SetEditable(const bool editable); + + /** + Sets the insertion point at the given position. + + @param pos + Position to set. + */ + virtual void SetInsertionPoint(long pos); + + /** + Sets the insertion point at the end of the text control. + + This is equivalent to calling wxTextCtrl::SetInsertionPoint() with + wxTextCtrl::GetLastPosition() argument. + */ + virtual void SetInsertionPointEnd(); + + /** + This function sets the maximum number of characters the user can enter + into the control. + + In other words, it allows to limit the text value length to @a len not + counting the terminating @c NUL character. If @a len is 0, the + previously set max length limit, if any, is discarded and the user may + enter as much text as the underlying native text control widget + supports (typically at least 32Kb). If the user tries to enter more + characters into the text control when it already is filled up to the + maximal length, a @c wxEVT_COMMAND_TEXT_MAXLEN event is sent to notify + the program about it (giving it the possibility to show an explanatory + message, for example) and the extra input is discarded. Note that in + wxGTK this function may only be used with single line text controls. + */ + virtual void SetMaxLength(unsigned long len); + + /** + Marks the control as being modified by the user or not. + + @see MarkDirty(), DiscardEdits() + */ + void SetModified(bool modified); + + /** + Selects the text starting at the first position up to (but not + including) the character at the last position. + + If both parameters are equal to -1 all text in the control is selected. + + @param from + The first position. + @param to + The last position. + + @see SelectAll() + */ + virtual void SetSelection(long from, long to); + + /** + Selects all text in the control. + + @see SetSelection() + */ + virtual void SelectAll(); + + /** + Changes the style of the given range. + + If any attribute within @a style is not set, the corresponding + attribute from GetDefaultStyle() is used. + + @param start + The start of the range to change. + @param end + The end of the range to change. + @param style + The new style for the range. + + @return + @true on success, @false if an error occurred (this may also mean + that the styles are not supported under this platform). + + @see GetStyle(), wxTextAttr + */ + bool SetStyle(long start, long end, const wxTextAttr& style); + + /** + Sets the text value and marks the control as not-modified (which means + that IsModified() would return @false immediately after the call to + SetValue). + + Note that this function generates a @c wxEVT_COMMAND_TEXT_UPDATED + event, to avoid this you can use ChangeValue() instead. + + @param value + The new value to set. It may contain newline characters if the text + control is multi-line. + */ + virtual void SetValue(const wxString& value); + + /** + Makes the line containing the given position visible. + + @param pos + The position that should be visible. + */ + void ShowPosition(long pos); + + /** + If there is an undo facility and the last operation can be undone, + undoes the last operation. + + Does nothing if there is no undo facility. + */ + virtual void Undo(); + + /** + Writes the text into the text control at the current insertion position. + + @param text + Text to write to the text control. + + @remarks Newlines in the text string are the only control characters + allowed, and they will cause appropriate line breaks. See () and + AppendText() for more convenient ways of writing to the window. + */ + void WriteText(const wxString& text); + + /** + Converts the given zero based column and line number to a position. + + @param x + The column number. + @param y + The line number. + + @return + The position value, or -1 if x or y was invalid. + */ + long XYToPosition(long x, long y); + + //@{ + /** + Operator definitions for appending to a text control. + + These operators can be used as with the standard C++ streams, for + example: + @code + wxTextCtrl *wnd = new wxTextCtrl(my_frame); + + (*wnd) << "Welcome to text control number " << 1 << ".\n"; + @endcode + */ + + wxTextCtrl& operator<<(const wxString& s); + wxTextCtrl& operator<<(int i); + wxTextCtrl& operator<<(long i); + wxTextCtrl& operator<<(float f); + wxTextCtrl& operator<<(double d); + wxTextCtrl& operator<<(char c); + wxTextCtrl& operator<<(wchar_t c); + //@} +}; + + + +/** + @class wxStreamToTextRedirector + @wxheader{textctrl.h} + + This class can be used to (temporarily) redirect all output sent to a C++ + ostream object to a wxTextCtrl instead. + + @note Some compilers and/or build configurations don't support multiply + inheriting wxTextCtrl from @c std::streambuf in which + case this class is not compiled in. You also must have @c wxUSE_STD_IOSTREAM + option on (i.e. set to 1) in your setup.h to be able to use it. Under Unix, + specify @c --enable-std_iostreams switch when running configure for this. + + Example of usage: + + @code + using namespace std; + + wxTextCtrl *text = new wxTextCtrl(...); + + { + wxStreamToTextRedirector redirect(text); + + // this goes to the text control + cout "Hello, text!" endl; + } + + // this goes somewhere else, presumably to stdout + cout "Hello, console!" endl; + @endcode + + + @library{wxcore} + @category{logging} + + @see wxTextCtrl +*/ +class wxStreamToTextRedirector +{ +public: + /** + The constructor starts redirecting output sent to @a ostr or @a cout for + the default parameter value to the text control @a text. + + @param text + The text control to append output too, must be non-@NULL + @param ostr + The C++ stream to redirect, cout is used if it is @NULL + */ + wxStreamToTextRedirector(wxTextCtrl text, ostream* ostr = NULL); + + /** + When a wxStreamToTextRedirector object is destroyed, the redirection is ended + and any output sent to the C++ ostream which had been specified at the time of + the object construction will go to its original destination. + */ + ~wxStreamToTextRedirector(); +}; + diff --git a/interface/wx/textdlg.h b/interface/wx/textdlg.h new file mode 100644 index 0000000000..dc7245790d --- /dev/null +++ b/interface/wx/textdlg.h @@ -0,0 +1,136 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: textdlg.h +// Purpose: interface of wxPasswordEntryDialog +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxPasswordEntryDialog + @wxheader{textdlg.h} + + This class represents a dialog that requests a one-line password string from + the user. + It is implemented as a generic wxWidgets dialog. + + @library{wxbase} + @category{cmndlg} + + @see @ref overview_wxpasswordentrydialogoverview "wxPassowrdEntryDialog + overview" +*/ +class wxPasswordEntryDialog : public wxTextEntryDialog +{ +public: + +}; + + + +/** + @class wxTextEntryDialog + @wxheader{textdlg.h} + + This class represents a dialog that requests a one-line text string from the + user. + It is implemented as a generic wxWidgets dialog. + + @library{wxbase} + @category{cmndlg} + + @see @ref overview_wxtextentrydialogoverview "wxTextEntryDialog overview" +*/ +class wxTextEntryDialog : public wxDialog +{ +public: + /** + Constructor. Use ShowModal() to show the dialog. + + @param parent + Parent window. + @param message + Message to show on the dialog. + @param defaultValue + The default value, which may be the empty string. + @param style + A dialog style, specifying the buttons (wxOK, wxCANCEL) + and an optional wxCENTRE style. Additionally, wxTextCtrl styles (such as + wxTE_PASSWORD) may be specified here. + @param pos + Dialog position. + */ + wxTextEntryDialog(wxWindow* parent, const wxString& message, + const wxString& caption = "Please enter text", + const wxString& defaultValue = "", + long style = wxOK | wxCANCEL | wxCENTRE, + const wxPoint& pos = wxDefaultPosition); + + /** + Destructor. + */ + ~wxTextEntryDialog(); + + /** + Returns the text that the user has entered if the user has pressed OK, or the + original value + if the user has pressed Cancel. + */ + wxString GetValue() const; + + /** + Sets the default text value. + */ + void SetValue(const wxString& value); + + /** + Shows the dialog, returning wxID_OK if the user pressed OK, and wxID_CANCEL + otherwise. + */ + int ShowModal(); +}; + + + +// ============================================================================ +// Global functions/macros +// ============================================================================ + +/** @ingroup group_funcmacro_dialog */ +//@{ + +/** + Pop up a dialog box with title set to @e caption, @c message, and a + @c default_value. The user may type in text and press OK to return this + text, or press Cancel to return the empty string. + + If @c centre is @true, the message text (which may include new line + characters) is centred; if @false, the message is left-justified. + + @header{wx/textdlg.h} +*/ +wxString wxGetTextFromUser(const wxString& message, + const wxString& caption = "Input text", + const wxString& default_value = "", + wxWindow* parent = NULL, + int x = wxDefaultCoord, + int y = wxDefaultCoord, + bool centre = true); + +/** + Similar to wxGetTextFromUser() but the text entered in the dialog is not + shown on screen but replaced with stars. This is intended to be used for + entering passwords as the function name implies. + + @header{wx/textdlg.h} +*/ +wxString wxGetPasswordFromUser(const wxString& message, + const wxString& caption = "Input text", + const wxString& default_value = "", + wxWindow* parent = NULL, + int x = wxDefaultCoord, + int y = wxDefaultCoord, + bool centre = true); + +//@} + diff --git a/interface/wx/textfile.h b/interface/wx/textfile.h new file mode 100644 index 0000000000..ca8b2d8da1 --- /dev/null +++ b/interface/wx/textfile.h @@ -0,0 +1,241 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: textfile.h +// Purpose: interface of wxTextFile +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxTextFile + @wxheader{textfile.h} + + The wxTextFile is a simple class which allows to work with text files on line by + line basis. It also understands the differences in line termination characters + under different platforms and will not do anything bad to files with "non + native" line termination sequences - in fact, it can be also used to modify the + text files and change the line termination characters from one type (say DOS) to + another (say Unix). + + One word of warning: the class is not at all optimized for big files and thus + it will load the file entirely into memory when opened. Of course, you should + not + work in this way with large files (as an estimation, anything over 1 Megabyte is + surely too big for this class). On the other hand, it is not a serious + limitation for small files like configuration files or program sources + which are well handled by wxTextFile. + + The typical things you may do with wxTextFile in order are: + + Create and open it: this is done with either + wxTextFile::Create or wxTextFile::Open + function which opens the file (name may be specified either as the argument to + these functions or in the constructor), reads its contents in memory (in the + case of @c Open()) and closes it. + Work with the lines in the file: this may be done either with "direct + access" functions like wxTextFile::GetLineCount and + wxTextFile::GetLine (@e operator[] does exactly the same + but looks more like array addressing) or with "sequential access" functions + which include wxTextFile::GetFirstLine/ + wxTextFile::GetNextLine and also + wxTextFile::GetLastLine/wxTextFile::GetPrevLine. + For the sequential access functions the current line number is maintained: it is + returned by wxTextFile::GetCurrentLine and may be + changed with wxTextFile::GoToLine. + Add/remove lines to the file: wxTextFile::AddLine and + wxTextFile::InsertLine add new lines while + wxTextFile::RemoveLine deletes the existing ones. + wxTextFile::Clear resets the file to empty. + Save your changes: notice that the changes you make to the file will @b not be + saved automatically; calling wxTextFile::Close or doing + nothing discards them! To save the changes you must explicitly call + wxTextFile::Write - here, you may also change the line + termination type if you wish. + + + @library{wxbase} + @category{file} + + @see wxFile +*/ +class wxTextFile +{ +public: + /** + Constructor does not load the file into memory, use Open() to do it. + */ + wxTextFile(const wxString& strFile) const; + + /** + Destructor does nothing. + */ + ~wxTextFile() const; + + /** + Adds a line to the end of file. + */ + void AddLine(const wxString& str, + wxTextFileType type = typeDefault) const; + + /** + Delete all lines from the file, set current line number to 0. + */ + void Clear() const; + + /** + Closes the file and frees memory, @b losing all changes. Use Write() + if you want to save them. + */ + bool Close() const; + + //@{ + /** + Creates the file with the given name or the name which was given in the + @ref ctor() constructor. The array of file lines is initially + empty. + It will fail if the file already exists, Open() should + be used in this case. + */ + bool Create() const; + const bool Create(const wxString& strFile) const; + //@} + + /** + Returns @true if the current line is the last one. + */ + bool Eof() const; + + /** + Return @true if file exists - the name of the file should have been specified + in the constructor before calling Exists(). + */ + bool Exists() const; + + /** + Returns the current line: it has meaning only when you're using + GetFirstLine()/GetNextLine() functions, it doesn't get updated when + you're using "direct access" functions like GetLine(). GetFirstLine() and + GetLastLine() also change the value of the current line, as well as + GoToLine(). + */ + size_t GetCurrentLine() const; + + /** + Get the line termination string corresponding to given constant. @e typeDefault + is + the value defined during the compilation and corresponds to the native format + of the platform, i.e. it will be wxTextFileType_Dos under Windows, + wxTextFileType_Unix under Unix (including Mac OS X when compiling with the + Apple Developer Tools) and wxTextFileType_Mac under Mac OS (including + Mac OS X when compiling with CodeWarrior). + */ + static const char* GetEOL(wxTextFileType type = typeDefault) const; + + /** + This method together with GetNextLine() + allows more "iterator-like" traversal of the list of lines, i.e. you may + write something like: + */ + wxString GetFirstLine() const; + + /** + Gets the last line of the file. Together with + GetPrevLine() it allows to enumerate the lines + in the file from the end to the beginning like this: + */ + wxString GetLastLine(); + + /** + Retrieves the line number @a n from the file. The returned line may be + modified but you shouldn't add line terminator at the end - this will be done + by wxTextFile. + */ + wxString GetLine(size_t n) const; + + /** + Get the number of lines in the file. + */ + size_t GetLineCount() const; + + /** + Get the type of the line (see also wxTextFile::GetEOL) + */ + wxTextFileType GetLineType(size_t n) const; + + /** + Get the name of the file. + */ + const char* GetName() const; + + /** + Gets the next line (see GetFirstLine() for + the example). + */ + wxString GetNextLine(); + + /** + Gets the previous line in the file. + */ + wxString GetPrevLine(); + + /** + Changes the value returned by GetCurrentLine() + and used by wxTextFile::GetFirstLine/GetNextLine(). + */ + void GoToLine(size_t n) const; + + /** + Guess the type of file (which is supposed to be opened). If sufficiently + many lines of the file are in DOS/Unix/Mac format, the corresponding value will + be returned. If the detection mechanism fails wxTextFileType_None is returned. + */ + wxTextFileType GuessType() const; + + /** + Insert a line before the line number @e n. + */ + void InsertLine(const wxString& str, size_t n, + wxTextFileType type = typeDefault) const; + + /** + Returns @true if the file is currently opened. + */ + bool IsOpened() const; + + //@{ + /** + ) + Open() opens the file with the given name or the name which was given in the + @ref ctor() constructor and also loads file in memory on + success. It will fail if the file does not exist, + Create() should be used in this case. + The @e conv argument is only meaningful in Unicode build of wxWidgets when + it is used to convert the file to wide character representation. + */ + bool Open() const; + const bool Open(const wxString& strFile) const; + //@} + + /** + Delete line number @a n from the file. + */ + void RemoveLine(size_t n) const; + + /** + ) + Change the file on disk. The @a typeNew parameter allows you to change the + file format (default argument means "don't change type") and may be used to + convert, for example, DOS files to Unix. + The @e conv argument is only meaningful in Unicode build of wxWidgets when + it is used to convert all lines to multibyte representation before writing them + them to physical file. + Returns @true if operation succeeded, @false if it failed. + */ + bool Write(wxTextFileType typeNew = wxTextFileType_None) const; + + /** + The same as GetLine(). + */ + wxString operator[](size_t n) const; +}; + diff --git a/interface/wx/tglbtn.h b/interface/wx/tglbtn.h new file mode 100644 index 0000000000..4a679c7ee1 --- /dev/null +++ b/interface/wx/tglbtn.h @@ -0,0 +1,170 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: tglbtn.h +// Purpose: interface of wxBitmapToggleButton +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + + +/** + @class wxToggleButton + @wxheader{tglbtn.h} + + wxToggleButton is a button that stays pressed when clicked by the user. In + other words, it is similar to wxCheckBox in + functionality but looks like a wxButton. + + Since wxWidgets version 2.9.0 this control emits an update UI event. + + You can see wxToggleButton in action in the sixth page of the + controls() sample. + + @beginEventTable{wxCommandEvent} + @event{EVT_TOGGLEBUTTON(id, func)} + Handles a toggle button click event. + @endEventTable + + @library{wxcore} + @category{ctrl} + + + @see wxCheckBox, wxButton, wxBitmapToggleButton +*/ +class wxToggleButton : public wxControl +{ +public: + //@{ + /** + Constructor, creating and showing a toggle button. + + @param parent + Parent window. Must not be @NULL. + @param id + Toggle button identifier. The value wxID_ANY indicates a default value. + @param label + Text to be displayed next to the toggle button. + @param pos + Toggle button position. If wxDefaultPosition is specified then a + default position is chosen. + @param size + Toggle button size. If wxDefaultSize is specified then a + default size is chosen. + @param style + Window style. See wxToggleButton. + @param validator + Window validator. + @param name + Window name. + + @see Create(), wxValidator + */ + wxToggleButton(); + wxToggleButton(wxWindow* parent, wxWindowID id, + const wxString& label, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0, + const wxValidator& val = wxDefaultValidator, + const wxString& name = "checkBox"); + //@} + + /** + Destructor, destroying the toggle button. + */ + virtual ~wxToggleButton(); + + /** + Creates the toggle button for two-step construction. See wxToggleButton() + for details. + */ + bool Create(wxWindow* parent, wxWindowID id, + const wxString& label, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0, + const wxValidator& val = wxDefaultValidator, + const wxString& name = "checkBox"); + + /** + Gets the state of the toggle button. + + @return Returns @true if it is pressed, @false otherwise. + */ + bool GetValue() const; + + /** + Sets the toggle button to the given state. This does not cause a + @c EVT_TOGGLEBUTTON event to be emitted. + + @param state + If @true, the button is pressed. + */ + void SetValue(bool state); +}; + + +/** + @class wxBitmapToggleButton + @wxheader{tglbtn.h} + + wxBitmapToggleButton is a wxToggleButton + that contains a bitmap instead of text. + + This control emits an update UI event. + + @beginEventTable{wxCommandEvent} + @event{EVT_TOGGLEBUTTON(id, func)} + Handles a toggle button click event. + @endEventTable + + @library{wxcore} + @category{ctrl} + +*/ +class wxBitmapToggleButton : public wxControl +{ +public: + //@{ + /** + Constructor, creating and showing a toggle button with the bitmap @e label. + Internally calls Create(). + */ + wxBitmapToggleButton(); + wxBitmapToggleButton(wxWindow* parent, wxWindowID id, + const wxBitmap& label, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0, + const wxValidator& val = wxDefaultValidator, + const wxString& name = "checkBox"); + //@} + + /** + Create method for two-step construction. + */ + bool Create(wxWindow* parent, wxWindowID id, + const wxBitmap& label, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0, + const wxValidator& val = wxDefaultValidator, + const wxString& name = "checkBox"); + + /** + Gets the state of the toggle button. + + @return Returns @true if it is pressed, @false otherwise. + */ + virtual bool GetValue() const; + + /** + Sets the toggle button to the given state. This does not cause a + @c EVT_TOGGLEBUTTON event to be emitted. + + @param state + If @true, the button is pressed. + */ + virtual void SetValue(bool state); +}; + diff --git a/interface/wx/thread.h b/interface/wx/thread.h new file mode 100644 index 0000000000..2c47ea1fdb --- /dev/null +++ b/interface/wx/thread.h @@ -0,0 +1,1017 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: thread.h +// Purpose: interface of wxCondition +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxCondition + @wxheader{thread.h} + + wxCondition variables correspond to pthread conditions or to Win32 event + objects. They may be used in a multithreaded application to wait until the + given condition becomes @true which happens when the condition becomes signaled. + + For example, if a worker thread is doing some long task and another thread has + to wait until it is finished, the latter thread will wait on the condition + object and the worker thread will signal it on exit (this example is not + perfect because in this particular case it would be much better to just + wxThread::Wait for the worker thread, but if there are several + worker threads it already makes much more sense). + + Note that a call to wxCondition::Signal may happen before the + other thread calls wxCondition::Wait and, just as with the + pthread conditions, the signal is then lost and so if you want to be sure that + you don't miss it you must keep the mutex associated with the condition + initially locked and lock it again before calling + wxCondition::Signal. Of course, this means that this call is + going to block until wxCondition::Wait is called by another + thread. + + @library{wxbase} + @category{threading} + + @see wxThread, wxMutex +*/ +class wxCondition +{ +public: + /** + Default and only constructor. The @a mutex must be locked by the caller + before calling Wait() function. + Use IsOk() to check if the object was successfully + initialized. + */ + wxCondition(wxMutex& mutex); + + /** + Destroys the wxCondition object. The destructor is not virtual so this class + should not be used polymorphically. + */ + ~wxCondition(); + + /** + Broadcasts to all waiting threads, waking all of them up. Note that this method + may be called whether the mutex associated with this condition is locked or + not. + + @see Signal() + */ + void Broadcast(); + + /** + Returns @true if the object had been initialized successfully, @false + if an error occurred. + */ + bool IsOk() const; + + /** + Signals the object waking up at most one thread. If several threads are waiting + on the same condition, the exact thread which is woken up is undefined. If no + threads are waiting, the signal is lost and the condition would have to be + signalled again to wake up any thread which may start waiting on it later. + Note that this method may be called whether the mutex associated with this + condition is locked or not. + + @see Broadcast() + */ + void Signal(); + + /** + Waits until the condition is signalled. + This method atomically releases the lock on the mutex associated with this + condition (this is why it must be locked prior to calling Wait) and puts the + thread to sleep until Signal() or + Broadcast() is called. It then locks the mutex + again and returns. + Note that even if Signal() had been called before + Wait without waking up any thread, the thread would still wait for another one + and so it is important to ensure that the condition will be signalled after + Wait or the thread may sleep forever. + + @return Returns wxCOND_NO_ERROR on success, another value if an error + occurred. + + @see WaitTimeout() + */ + wxCondError Wait(); + + /** + Waits until the condition is signalled or the timeout has elapsed. + This method is identical to Wait() except that it + returns, with the return code of @c wxCOND_TIMEOUT as soon as the given + timeout expires. + + @param milliseconds + Timeout in milliseconds + */ + wxCondError WaitTimeout(unsigned long milliseconds); +}; + + + +/** + @class wxCriticalSectionLocker + @wxheader{thread.h} + + This is a small helper class to be used with wxCriticalSection + objects. A wxCriticalSectionLocker enters the critical section in the + constructor and leaves it in the destructor making it much more difficult to + forget to leave a critical section (which, in general, will lead to serious + and difficult to debug problems). + + Example of using it: + + @code + void Set Foo() + { + // gs_critSect is some (global) critical section guarding access to the + // object "foo" + wxCriticalSectionLocker locker(gs_critSect); + + if ( ... ) + { + // do something + ... + + return; + } + + // do something else + ... + + return; + } + @endcode + + Without wxCriticalSectionLocker, you would need to remember to manually leave + the critical section before each @c return. + + @library{wxbase} + @category{threading} + + @see wxCriticalSection, wxMutexLocker +*/ +class wxCriticalSectionLocker +{ +public: + /** + Constructs a wxCriticalSectionLocker object associated with given + @a criticalsection and enters it. + */ + wxCriticalSectionLocker(wxCriticalSection& criticalsection); + + /** + Destructor leaves the critical section. + */ + ~wxCriticalSectionLocker(); +}; + + + +/** + @class wxThreadHelper + @wxheader{thread.h} + + The wxThreadHelper class is a mix-in class that manages a single background + thread. By deriving from wxThreadHelper, a class can implement the thread + code in its own wxThreadHelper::Entry method + and easily share data and synchronization objects between the main thread + and the worker thread. Doing this prevents the awkward passing of pointers + that is needed when the original object in the main thread needs to + synchronize with its worker thread in its own wxThread derived object. + + For example, wxFrame may need to make some calculations + in a background thread and then display the results of those calculations in + the main window. + + Ordinarily, a wxThread derived object would be created + with the calculation code implemented in + wxThread::Entry. To access the inputs to the + calculation, the frame object would often to pass a pointer to itself to the + thread object. Similarly, the frame object would hold a pointer to the + thread object. Shared data and synchronization objects could be stored in + either object though the object without the data would have to access the + data through a pointer. + + However, with wxThreadHelper, the frame object and the thread object are + treated as the same object. Shared data and synchronization variables are + stored in the single object, eliminating a layer of indirection and the + associated pointers. + + @library{wxbase} + @category{threading} + + @see wxThread +*/ +class wxThreadHelper +{ +public: + /** + This constructor simply initializes a member variable. + */ + wxThreadHelper(); + + /** + The destructor frees the resources associated with the thread. + */ + ~wxThreadHelper(); + + /** + Creates a new thread. The thread object is created in the suspended state, and + you + should call @ref wxThread::Run GetThread()-Run to start running + it. You may optionally specify the stack size to be allocated to it (Ignored on + platforms that don't support setting it explicitly, eg. Unix). + + @return One of: + */ + wxThreadError Create(unsigned int stackSize = 0); + + /** + This is the entry point of the thread. This function is pure virtual and must + be implemented by any derived class. The thread execution will start here. + The returned value is the thread exit code which is only useful for + joinable threads and is the value returned by + @ref wxThread::Wait GetThread()-Wait. + This function is called by wxWidgets itself and should never be called + directly. + */ + virtual ExitCode Entry(); + + /** + This is a public function that returns the wxThread object + associated with the thread. + */ + wxThread* GetThread(); + + /** + wxThread * m_thread + the actual wxThread object. + */ +}; + + + +/** + @class wxCriticalSection + @wxheader{thread.h} + + A critical section object is used for exactly the same purpose as + mutexes(). The only difference is that under Windows platform + critical sections are only visible inside one process, while mutexes may be + shared among processes, so using critical sections is slightly more + efficient. The terminology is also slightly different: mutex may be locked (or + acquired) and unlocked (or released) while critical section is entered and left + by the program. + + Finally, you should try to use + wxCriticalSectionLocker class whenever + possible instead of directly using wxCriticalSection for the same reasons + wxMutexLocker is preferrable to + wxMutex - please see wxMutex for an example. + + @library{wxbase} + @category{threading} + + @see wxThread, wxCondition, wxCriticalSectionLocker +*/ +class wxCriticalSection +{ +public: + /** + Default constructor initializes critical section object. + */ + wxCriticalSection(); + + /** + Destructor frees the resources. + */ + ~wxCriticalSection(); + + /** + Enter the critical section (same as locking a mutex). There is no error return + for this function. After entering the critical section protecting some global + data the thread running in critical section may safely use/modify it. + */ + void Enter(); + + /** + Leave the critical section allowing other threads use the global data protected + by it. There is no error return for this function. + */ + void Leave(); +}; + + + +/** + @class wxThread + @wxheader{thread.h} + + A thread is basically a path of execution through a program. Threads are + sometimes called @e light-weight processes, but the fundamental difference + between threads and processes is that memory spaces of different processes are + separated while all threads share the same address space. + + While it makes it much easier to share common data between several threads, it + also makes it much easier to shoot oneself in the foot, so careful use of + synchronization objects such as mutexes() or @ref wxCriticalSection + "critical sections" is recommended. In addition, don't create global thread + objects because they allocate memory in their constructor, which will cause + problems for the memory checking system. + + @section overview_typeswxthread Types of wxThreads + There are two types of threads in wxWidgets: @e detached and @e joinable, + modeled after the the POSIX thread API. This is different from the Win32 API + where all threads are joinable. + + By default wxThreads in wxWidgets use the detached behavior. Detached threads + delete themselves once they have completed, either by themselves when they + complete processing or through a call to Delete(), and thus + must be created on the heap (through the new operator, for example). + Conversely, joinable threads do not delete themselves when they are done + processing and as such are safe to create on the stack. Joinable threads + also provide the ability for one to get value it returned from Entry() + through Wait(). + + You shouldn't hurry to create all the threads joinable, however, because this + has a disadvantage as well: you @b must Wait() for a joinable thread or the + system resources used by it will never be freed, and you also must delete the + corresponding wxThread object yourself if you did not create it on the stack. + In contrast, detached threads are of the "fire-and-forget" kind: you only have to + start a detached thread and it will terminate and destroy itself. + + @section overview_deletionwxthread wxThread Deletion + Regardless of whether it has terminated or not, you should call + Wait() on a joinable thread to release its memory, as outlined in + @ref overview_typeswxthread "Types of wxThreads". If you created + a joinable thread on the heap, remember to delete it manually with the delete + operator or similar means as only detached threads handle this type of memory + management. + + Since detached threads delete themselves when they are finished processing, + you should take care when calling a routine on one. If you are certain the + thread is still running and would like to end it, you may call Delete() + to gracefully end it (which implies that the thread will be deleted after + that call to Delete()). It should be implied that you should never attempt + to delete a detached thread with the delete operator or similar means. + As mentioned, Wait() or Delete() attempts to gracefully terminate a + joinable and detached thread, respectively. It does this by waiting until + the thread in question calls TestDestroy() or ends processing (returns + from wxThread::Entry). + + Obviously, if the thread does call TestDestroy() and does not end the calling + thread will come to halt. This is why it is important to call TestDestroy() in + the Entry() routine of your threads as often as possible. + As a last resort you can end the thread immediately through Kill(). It is + strongly recommended that you do not do this, however, as it does not free + the resources associated with the object (although the wxThread object of + detached threads will still be deleted) and could leave the C runtime + library in an undefined state. + + @section overview_secondarythreads wxWidgets Calls in Secondary Threads + All threads other than the "main application thread" (the one + wxApp::OnInit or your main function runs in, for example) are considered + "secondary threads". These include all threads created by Create() or the + corresponding constructors. + + GUI calls, such as those to a wxWindow or wxBitmap are explicitly not safe + at all in secondary threads and could end your application prematurely. + This is due to several reasons, including the underlying native API and + the fact that wxThread does not run a GUI event loop similar to other APIs + as MFC. + + A workaround for some wxWidgets ports is calling wxMutexGUIEnter() + before any GUI calls and then calling wxMutexGUILeave() afterwords. However, + the recommended way is to simply process the GUI calls in the main thread + through an event that is posted by either wxQueueEvent(). + This does not imply that calls to these classes are thread-safe, however, + as most wxWidgets classes are not thread-safe, including wxString. + + @section overview_pollwxThread Don't Poll a wxThread + A common problem users experience with wxThread is that in their main thread + they will check the thread every now and then to see if it has ended through + IsRunning(), only to find that their application has run into problems + because the thread is using the default behavior and has already deleted + itself. Naturally, they instead attempt to use joinable threads in place + of the previous behavior. However, polling a wxThread for when it has ended + is in general a bad idea - in fact calling a routine on any running wxThread + should be avoided if possible. Instead, find a way to notify yourself when + the thread has ended. + + Usually you only need to notify the main thread, in which case you can + post an event to it via wxPostEvent() or wxEvtHandler::AddPendingEvent. + In the case of secondary threads you can call a routine of another class + when the thread is about to complete processing and/or set the value of + a variable, possibly using mutexes() and/or other synchronization means + if necessary. + + @library{wxbase} + @category{threading} + @see wxMutex, wxCondition, wxCriticalSection +*/ +class wxThread +{ +public: + /** + This constructor creates a new detached (default) or joinable C++ + thread object. It does not create or start execution of the real thread -- + for this you should use the Create() and Run() methods. + + The possible values for @a kind parameters are: + - @b wxTHREAD_DETACHED - Creates a detached thread. + - @b wxTHREAD_JOINABLE - Creates a joinable thread. + */ + wxThread(wxThreadKind kind = wxTHREAD_DETACHED); + + /** + The destructor frees the resources associated with the thread. Notice that you + should never delete a detached thread -- you may only call + Delete() on it or wait until it terminates (and auto + destructs) itself. Because the detached threads delete themselves, they can + only be allocated on the heap. + Joinable threads should be deleted explicitly. The Delete() and Kill() functions + will not delete the C++ thread object. It is also safe to allocate them on + stack. + */ + ~wxThread(); + + /** + Creates a new thread. The thread object is created in the suspended state, + and you should call Run() to start running it. You may optionally + specify the stack size to be allocated to it (Ignored on platforms that don't + support setting it explicitly, eg. Unix system without + @c pthread_attr_setstacksize). If you do not specify the stack size, + the system's default value is used. + @b Warning: It is a good idea to explicitly specify a value as systems' + default values vary from just a couple of KB on some systems (BSD and + OS/2 systems) to one or several MB (Windows, Solaris, Linux). So, if you + have a thread that requires more than just a few KB of memory, you will + have mysterious problems on some platforms but not on the common ones. On the + other hand, just indicating a large stack size by default will give you + performance issues on those systems with small default stack since those + typically use fully committed memory for the stack. On the contrary, if + use a lot of threads (say several hundred), virtual adress space can get tight + unless you explicitly specify a smaller amount of thread stack space for each + thread. + + @return One of: + - @b wxTHREAD_NO_ERROR - No error. + - @b wxTHREAD_NO_RESOURCE - There were insufficient resources to create the thread. + - @b wxTHREAD_NO_RUNNING - The thread is already running + */ + wxThreadError Create(unsigned int stackSize = 0); + + /** + Calling Delete() gracefully terminates a + detached thread, either when the thread calls TestDestroy() or finished + processing. + (Note that while this could work on a joinable thread you simply should not + call this routine on one as afterwards you may not be able to call + Wait() to free the memory of that thread). + See @ref overview_deletionwxthread "wxThread deletion" for a broader + explanation of this routine. + */ + wxThreadError Delete(); + + /** + This is the entry point of the thread. This function is pure virtual and must + be implemented by any derived class. The thread execution will start here. + The returned value is the thread exit code which is only useful for + joinable threads and is the value returned by Wait(). + This function is called by wxWidgets itself and should never be called + directly. + */ + virtual ExitCode Entry(); + + /** + This is a protected function of the wxThread class and thus can only be called + from a derived class. It also can only be called in the context of this + thread, i.e. a thread can only exit from itself, not from another thread. + This function will terminate the OS thread (i.e. stop the associated path of + execution) and also delete the associated C++ object for detached threads. + OnExit() will be called just before exiting. + */ + void Exit(ExitCode exitcode = 0); + + /** + Returns the number of system CPUs or -1 if the value is unknown. + + @see SetConcurrency() + */ + static int GetCPUCount(); + + /** + Returns the platform specific thread ID of the current thread as a + long. This can be used to uniquely identify threads, even if they are + not wxThreads. + */ + static unsigned long GetCurrentId(); + + /** + Gets the thread identifier: this is a platform dependent number that uniquely + identifies the + thread throughout the system during its existence (i.e. the thread identifiers + may be reused). + */ + unsigned long GetId() const; + + /** + Gets the priority of the thread, between zero and 100. + + The following priorities are defined: + - @b WXTHREAD_MIN_PRIORITY: 0 + - @b WXTHREAD_DEFAULT_PRIORITY: 50 + - @b WXTHREAD_MAX_PRIORITY: 100 + */ + int GetPriority() const; + + /** + Returns @true if the thread is alive (i.e. started and not terminating). + Note that this function can only safely be used with joinable threads, not + detached ones as the latter delete themselves and so when the real thread is + no longer alive, it is not possible to call this function because + the wxThread object no longer exists. + */ + bool IsAlive() const; + + /** + Returns @true if the thread is of the detached kind, @false if it is a + joinable + one. + */ + bool IsDetached() const; + + /** + Returns @true if the calling thread is the main application thread. + */ + static bool IsMain(); + + /** + Returns @true if the thread is paused. + */ + bool IsPaused() const; + + /** + Returns @true if the thread is running. + This method may only be safely used for joinable threads, see the remark in + IsAlive(). + */ + bool IsRunning() const; + + /** + Immediately terminates the target thread. @b This function is dangerous and + should + be used with extreme care (and not used at all whenever possible)! The resources + allocated to the thread will not be freed and the state of the C runtime library + may become inconsistent. Use Delete() for detached + threads or Wait() for joinable threads instead. + For detached threads Kill() will also delete the associated C++ object. + However this will not happen for joinable threads and this means that you will + still have to delete the wxThread object yourself to avoid memory leaks. + In neither case OnExit() of the dying thread will be + called, so no thread-specific cleanup will be performed. + This function can only be called from another thread context, i.e. a thread + cannot kill itself. + It is also an error to call this function for a thread which is not running or + paused (in the latter case, the thread will be resumed first) -- if you do it, + a @b wxTHREAD_NOT_RUNNING error will be returned. + */ + wxThreadError Kill(); + + /** + Called when the thread exits. This function is called in the context of the + thread associated with the wxThread object, not in the context of the main + thread. This function will not be called if the thread was + @ref Kill() killed. + This function should never be called directly. + */ + void OnExit(); + + /** + Suspends the thread. Under some implementations (Win32), the thread is + suspended immediately, under others it will only be suspended when it calls + TestDestroy() for the next time (hence, if the + thread doesn't call it at all, it won't be suspended). + This function can only be called from another thread context. + */ + wxThreadError Pause(); + + /** + Resumes a thread suspended by the call to Pause(). + This function can only be called from another thread context. + */ + wxThreadError Resume(); + + /** + Starts the thread execution. Should be called after + Create(). + This function can only be called from another thread context. + */ + wxThreadError Run(); + + /** + Sets the thread concurrency level for this process. This is, roughly, the + number of threads that the system tries to schedule to run in parallel. + The value of 0 for @a level may be used to set the default one. + Returns @true on success or @false otherwise (for example, if this function is + not implemented for this platform -- currently everything except Solaris). + */ + static bool SetConcurrency(size_t level); + + /** + Sets the priority of the thread, between 0 and 100. It can only be set + after calling Create() but before calling + Run(). + + The following priorities are defined: + - @b WXTHREAD_MIN_PRIORITY: 0 + - @b WXTHREAD_DEFAULT_PRIORITY: 50 + - @b WXTHREAD_MAX_PRIORITY: 100 + */ + void SetPriority(int priority); + + /** + Pauses the thread execution for the given amount of time. + + This is the same as wxMilliSleep(). + */ + static void Sleep(unsigned long milliseconds); + + /** + This function should be called periodically by the thread to ensure that + calls to Pause() and Delete() will work. If it returns @true, the thread + should exit as soon as possible. Notice that under some platforms (POSIX), + implementation of Pause() also relies on this function being called, so + not calling it would prevent both stopping and suspending thread from working. + */ + virtual bool TestDestroy(); + + /** + Return the thread object for the calling thread. @NULL is returned if + the calling thread is the main (GUI) thread, but IsMain() should be used + to test whether the thread is really the main one because @NULL may also + be returned for the thread not created with wxThread class. Generally + speaking, the return value for such a thread is undefined. + */ + static wxThread* This(); + + /** + Waits for a joinable thread to terminate and returns the value the thread + returned from Entry() or @c (ExitCode)-1 on error. Notice that, unlike + Delete() doesn't cancel the thread in any way so the caller waits for as + long as it takes to the thread to exit. + You can only Wait() for joinable (not detached) threads. + This function can only be called from another thread context. + See @ref overview_deletionwxthread "wxThread deletion" for a broader + explanation of this routine. + */ + ExitCode Wait() const; + + /** + Give the rest of the thread time slice to the system allowing the other + threads to run. + Note that using this function is @b strongly discouraged, since in + many cases it indicates a design weakness of your threading model (as + does using Sleep functions). + Threads should use the CPU in an efficient manner, i.e. they should + do their current work efficiently, then as soon as the work is done block + on a wakeup event (wxCondition, wxMutex, select(), poll(), ...) + which will get signalled e.g. by other threads or a user device once further + thread work is available. Using Yield or Sleep + indicates polling-type behaviour, since we're fuzzily giving up our timeslice + and wait until sometime later we'll get reactivated, at which time we + realize that there isn't really much to do and Yield again... + The most critical characteristic of Yield is that it's operating system + specific: there may be scheduler changes which cause your thread to not + wake up relatively soon again, but instead many seconds later, + causing huge performance issues for your application. @b with a + well-behaving, CPU-efficient thread the operating system is likely to properly + care for its reactivation the moment it needs it, whereas with + non-deterministic, Yield-using threads all bets are off and the system + scheduler is free to penalize drastically, and this effect gets worse + with increasing system load due to less free CPU resources available. + You may refer to various Linux kernel sched_yield discussions for more + information. + See also Sleep(). + */ + void Yield(); +}; + +/** + @class wxSemaphore + @wxheader{thread.h} + + wxSemaphore is a counter limiting the number of threads concurrently accessing + a shared resource. This counter is always between 0 and the maximum value + specified during the semaphore creation. When the counter is strictly greater + than 0, a call to wxSemaphore::Wait returns immediately and + decrements the counter. As soon as it reaches 0, any subsequent calls to + wxSemaphore::Wait block and only return when the semaphore + counter becomes strictly positive again as the result of calling + wxSemaphore::Post which increments the counter. + + In general, semaphores are useful to restrict access to a shared resource + which can only be accessed by some fixed number of clients at the same time. For + example, when modeling a hotel reservation system a semaphore with the counter + equal to the total number of available rooms could be created. Each time a room + is reserved, the semaphore should be acquired by calling + wxSemaphore::Wait and each time a room is freed it should be + released by calling wxSemaphore::Post. + + @library{wxbase} + @category{threading} +*/ +class wxSemaphore +{ +public: + /** + Specifying a @a maxcount of 0 actually makes wxSemaphore behave as if + there is no upper limit. If maxcount is 1, the semaphore behaves almost as a + mutex (but unlike a mutex it can be released by a thread different from the one + which acquired it). + @a initialcount is the initial value of the semaphore which must be between + 0 and @a maxcount (if it is not set to 0). + */ + wxSemaphore(int initialcount = 0, int maxcount = 0); + + /** + Destructor is not virtual, don't use this class polymorphically. + */ + ~wxSemaphore(); + + /** + Increments the semaphore count and signals one of the waiting + threads in an atomic way. Returns wxSEMA_OVERFLOW if the count + would increase the counter past the maximum. + + @return One of: + */ + wxSemaError Post(); + + /** + Same as Wait(), but returns immediately. + + @return One of: + */ + wxSemaError TryWait(); + + /** + Wait indefinitely until the semaphore count becomes strictly positive + and then decrement it and return. + + @return One of: + */ + wxSemaError Wait(); +}; + + + +/** + @class wxMutexLocker + @wxheader{thread.h} + + This is a small helper class to be used with wxMutex + objects. A wxMutexLocker acquires a mutex lock in the constructor and releases + (or unlocks) the mutex in the destructor making it much more difficult to + forget to release a mutex (which, in general, will promptly lead to serious + problems). See wxMutex for an example of wxMutexLocker + usage. + + @library{wxbase} + @category{threading} + + @see wxMutex, wxCriticalSectionLocker +*/ +class wxMutexLocker +{ +public: + /** + Constructs a wxMutexLocker object associated with mutex and locks it. + Call @ref IsOk() IsLocked to check if the mutex was + successfully locked. + */ + wxMutexLocker(wxMutex& mutex); + + /** + Destructor releases the mutex if it was successfully acquired in the ctor. + */ + ~wxMutexLocker(); + + /** + Returns @true if mutex was acquired in the constructor, @false otherwise. + */ + bool IsOk() const; +}; + + + +/** + @class wxMutex + @wxheader{thread.h} + + A mutex object is a synchronization object whose state is set to signaled when + it is not owned by any thread, and nonsignaled when it is owned. Its name comes + from its usefulness in coordinating mutually-exclusive access to a shared + resource as only one thread at a time can own a mutex object. + + Mutexes may be recursive in the sense that a thread can lock a mutex which it + had already locked before (instead of dead locking the entire process in this + situation by starting to wait on a mutex which will never be released while the + thread is waiting) but using them is not recommended under Unix and they are + @b not recursive there by default. The reason for this is that recursive + mutexes are not supported by all Unix flavours and, worse, they cannot be used + with wxCondition. On the other hand, Win32 mutexes are + always recursive. + + For example, when several threads use the data stored in the linked list, + modifications to the list should only be allowed to one thread at a time + because during a new node addition the list integrity is temporarily broken + (this is also called @e program invariant). + + @library{wxbase} + @category{threading} + + @see wxThread, wxCondition, wxMutexLocker, wxCriticalSection +*/ +class wxMutex +{ +public: + /** + Default constructor. + */ + wxMutex(wxMutexType type = wxMUTEX_DEFAULT); + + /** + Destroys the wxMutex object. + */ + ~wxMutex(); + + /** + Locks the mutex object. This is equivalent to + LockTimeout() with infinite timeout. + + @return One of: + */ + wxMutexError Lock(); + + /** + Try to lock the mutex object during the specified time interval. + + @return One of: + */ + wxMutexError LockTimeout(unsigned long msec); + + /** + Tries to lock the mutex object. If it can't, returns immediately with an error. + + @return One of: + */ + wxMutexError TryLock(); + + /** + Unlocks the mutex object. + + @return One of: + */ + wxMutexError Unlock(); +}; + + + +// ============================================================================ +// Global functions/macros +// ============================================================================ + +/** @ingroup group_funcmacro_thread */ +//@{ + +/** + This macro declares a (static) critical section object named @a cs if + @c wxUSE_THREADS is 1 and does nothing if it is 0. + + @header{wx/thread.h} +*/ +#define wxCRIT_SECT_DECLARE(cs) + +/** + This macro declares a critical section object named @a cs if + @c wxUSE_THREADS is 1 and does nothing if it is 0. As it doesn't include + the @c static keyword (unlike wxCRIT_SECT_DECLARE()), it can be used to + declare a class or struct member which explains its name. + + @header{wx/thread.h} +*/ +#define wxCRIT_SECT_DECLARE_MEMBER(cs) + +/** + This macro creates a wxCriticalSectionLocker named @a name and associated + with the critical section @a cs if @c wxUSE_THREADS is 1 and does nothing + if it is 0. + + @header{wx/thread.h} +*/ +#define wxCRIT_SECT_LOCKER(name, cs) + +/** + This macro combines wxCRIT_SECT_DECLARE() and wxCRIT_SECT_LOCKER(): it + creates a static critical section object and also the lock object + associated with it. Because of this, it can be only used inside a function, + not at global scope. For example: + + @code + int IncCount() + { + static int s_counter = 0; + + wxCRITICAL_SECTION(counter); + + return ++s_counter; + } + @endcode + + Note that this example assumes that the function is called the first time + from the main thread so that the critical section object is initialized + correctly by the time other threads start calling it, if this is not the + case this approach can @b not be used and the critical section must be made + a global instead. + + @header{wx/thread.h} +*/ +#define wxCRITICAL_SECTION(name) + +/** + This macro is equivalent to + @ref wxCriticalSection::Leave "critical_section.Leave()" if + @c wxUSE_THREADS is 1 and does nothing if it is 0. + + @header{wx/thread.h} +*/ +#define wxLEAVE_CRIT_SECT(critical_section) + +/** + This macro is equivalent to + @ref wxCriticalSection::Enter "critical_section.Enter()" if + @c wxUSE_THREADS is 1 and does nothing if it is 0. + + @header{wx/thread.h} +*/ +#define wxENTER_CRIT_SECT(critical_section) + +/** + Returns @true if this thread is the main one. Always returns @true if + @c wxUSE_THREADS is 0. + + @header{wx/thread.h} +*/ +bool wxIsMainThread(); + +/** + This function must be called when any thread other than the main GUI thread + wants to get access to the GUI library. This function will block the + execution of the calling thread until the main thread (or any other thread + holding the main GUI lock) leaves the GUI library and no other thread will + enter the GUI library until the calling thread calls wxMutexGuiLeave(). + + Typically, these functions are used like this: + + @code + void MyThread::Foo(void) + { + // before doing any GUI calls we must ensure that + // this thread is the only one doing it! + + wxMutexGuiEnter(); + + // Call GUI here: + my_window-DrawSomething(); + + wxMutexGuiLeave(); + } + @endcode + + This function is only defined on platforms which support preemptive + threads. + + @note Under GTK, no creation of top-level windows is allowed in any thread + but the main one. + + @header{wx/thread.h} +*/ +void wxMutexGuiEnter(); + +/** + This function is only defined on platforms which support preemptive + threads. + + @see wxMutexGuiEnter() + + @header{wx/thread.h} +*/ +void wxMutexGuiLeave(); + +//@} + diff --git a/interface/wx/timer.h b/interface/wx/timer.h new file mode 100644 index 0000000000..49de74c8ef --- /dev/null +++ b/interface/wx/timer.h @@ -0,0 +1,184 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: timer.h +// Purpose: interface of wxTimer +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxTimer + @wxheader{timer.h} + + The wxTimer class allows you to execute code at specified intervals. Its + precision is platform-dependent, but in general will not be better than 1ms nor + worse than 1s. + + There are three different ways to use this class: + + You may derive a new class from wxTimer and override the + wxTimer::Notify member to perform the required action. + Or you may redirect the notifications to any + wxEvtHandler derived object by using the non-default + constructor or wxTimer::SetOwner. Then use the @c EVT_TIMER + macro to connect it to the event handler which will receive + wxTimerEvent notifications. + Or you may use a derived class and the @c EVT_TIMER + macro to connect it to an event handler defined in the derived class. + If the default constructor is used, the timer object will be its + own owner object, since it is derived from wxEvtHandler. + + In any case, you must start the timer with wxTimer::Start + after constructing it before it actually starts sending notifications. It can + be stopped later with wxTimer::Stop. + + @note A timer can only be used from the main thread. + + @library{wxbase} + @category{misc} + + @see wxStopWatch +*/ +class wxTimer : public wxEvtHandler +{ +public: + //@{ + /** + Creates a timer and associates it with @e owner. Please see + SetOwner() for the description of parameters. + */ + wxTimer(); + wxTimer(wxEvtHandler* owner, int id = -1); + //@} + + /** + Destructor. Stops the timer if it is running. + */ + ~wxTimer(); + + /** + Returns the ID of the events generated by this timer. + */ + int GetId() const; + + /** + Returns the current interval for the timer (in milliseconds). + */ + int GetInterval() const; + + /** + Returns the current @e owner of the timer. + If non-@NULL this is the event handler which will receive the + @ref overview_wxtimerevent "timer events" when the timer is running. + */ + wxEvtHandler GetOwner() const; + + /** + Returns @true if the timer is one shot, i.e. if it will stop after firing the + first notification automatically. + */ + bool IsOneShot() const; + + /** + Returns @true if the timer is running, @false if it is stopped. + */ + bool IsRunning() const; + + /** + This member should be overridden by the user if the default constructor was + used and SetOwner() wasn't called. + Perform whatever action which is to be taken periodically here. + */ + void Notify(); + + /** + Associates the timer with the given @a owner object. When the timer is + running, the owner will receive @ref overview_wxtimerevent "timer events" with + id equal to @a id specified here. + */ + void SetOwner(wxEvtHandler* owner, int id = -1); + + /** + (Re)starts the timer. If @a milliseconds parameter is -1 (value by default), + the previous value is used. Returns @false if the timer could not be started, + @true otherwise (in MS Windows timers are a limited resource). + If @a oneShot is @false (the default), the Notify() + function will be called repeatedly until the timer is stopped. If @true, + it will be called only once and the timer will stop automatically. To make your + code more readable you may also use the following symbolic constants: + + wxTIMER_CONTINUOUS + + Start a normal, continuously running, timer + + wxTIMER_ONE_SHOT + + Start a one shot timer + + If the timer was already running, it will be stopped by this method before + restarting it. + */ + bool Start(int milliseconds = -1, bool oneShot = false); + + /** + Stops the timer. + */ + void Stop(); +}; + + + +/** + @class wxTimerEvent + @wxheader{timer.h} + + wxTimerEvent object is passed to the event handler of timer events. + + For example: + + @code + class MyFrame : public wxFrame + { + public: + ... + void OnTimer(wxTimerEvent& event); + + private: + wxTimer m_timer; + }; + + BEGIN_EVENT_TABLE(MyFrame, wxFrame) + EVT_TIMER(TIMER_ID, MyFrame::OnTimer) + END_EVENT_TABLE() + + MyFrame::MyFrame() + : m_timer(this, TIMER_ID) + { + m_timer.Start(1000); // 1 second interval + } + + void MyFrame::OnTimer(wxTimerEvent& event) + { + // do whatever you want to do every second here + } + @endcode + + @library{wxbase} + @category{events} + + @see wxTimer +*/ +class wxTimerEvent : public wxEvent +{ +public: + /** + Returns the interval of the timer which generated this event. + */ + int GetInterval() const; + + /** + Returns the timer object which generated this event. + */ + wxTimer GetTimer() const; +}; + diff --git a/interface/wx/tipdlg.h b/interface/wx/tipdlg.h new file mode 100644 index 0000000000..4b68bf8fb6 --- /dev/null +++ b/interface/wx/tipdlg.h @@ -0,0 +1,114 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: tipdlg.h +// Purpose: interface of wxTipProvider +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxTipProvider + @wxheader{tipdlg.h} + + This is the class used together with wxShowTip() function. + It must implement wxTipProvider::GetTip function and return the + current tip from it (different tip each time it is called). + + You will never use this class yourself, but you need it to show startup tips + with wxShowTip. Also, if you want to get the tips text from elsewhere than a + simple text file, you will want to derive a new class from wxTipProvider and + use it instead of the one returned by wxCreateFileTipProvider(). + + @library{wxadv} + @category{FIXME} + + @see @ref overview_tipsoverview "Startup tips overview", ::wxShowTip +*/ +class wxTipProvider +{ +public: + /** + Constructor. + + @param currentTip + The starting tip index. + */ + wxTipProvider(size_t currentTip); + + /** + Returns the index of the current tip (i.e. the one which would be returned by + GetTip). + The program usually remembers the value returned by this function after calling + wxShowTip(). Note that it is not the same as the value which + was passed to wxShowTip + 1 because the user might have pressed the "Next" + button in the tip dialog. + */ + size_t GetCurrentTip() const; + + /** + Return the text of the current tip and pass to the next one. This function is + pure virtual, it should be implemented in the derived classes. + */ + wxString GetTip(); + + /** + Returns a modified tip. This function will be called immediately after read, + and before being check whether it is a comment, an empty string or a string + to translate. You can optionally override this in your custom user-derived + class + to optionally to modify the tip as soon as it is read. You can return any + modification to the string. If you return wxEmptyString, then this tip is + skipped, and the next one is read. + */ + virtual wxString PreProcessTip(const wxString& tip); +}; + + + +// ============================================================================ +// Global functions/macros +// ============================================================================ + +/** @ingroup group_funcmacro_dialog */ +//@{ + +/** + This function creates a wxTipProvider which may be used with wxShowTip(). + + @param filename + The name of the file containing the tips, one per line. + @param currentTip + The index of the first tip to show. Normally this index is remembered + between the 2 program runs. + + @see @ref overview_tips + + @header{wx/tipdlg.h} +*/ +wxTipProvider* wxCreateFileTipProvider(const wxString& filename, + size_t currentTip); + +/** + This function shows a "startup tip" to the user. The return value is the + state of the "Show tips at startup" checkbox. + + @param parent + The parent window for the modal dialog. + @param tipProvider + An object which is used to get the text of the tips. It may be created + with the wxCreateFileTipProvider() function. + @param showAtStartup + Should be true if startup tips are shown, false otherwise. This is + used as the initial value for "Show tips at startup" checkbox which is + shown in the tips dialog. + + @see @ref overview_tips + + @header{wx/tipdlg.h} +*/ +bool wxShowTip(wxWindow *parent, + wxTipProvider *tipProvider, + bool showAtStartup = true); + +//@} + diff --git a/interface/wx/tipwin.h b/interface/wx/tipwin.h new file mode 100644 index 0000000000..ef4a08e2a4 --- /dev/null +++ b/interface/wx/tipwin.h @@ -0,0 +1,72 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: tipwin.h +// Purpose: interface of wxTipWindow +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxTipWindow + @wxheader{tipwin.h} + + Shows simple text in a popup tip window on creation. This is used by + wxSimpleHelpProvider to show popup help. The + window automatically destroys itself when the user clicks on it or it loses the + focus. + + You may also use this class to emulate the tooltips when you need finer + control over them than what the standard tooltips provide. + + @library{wxcore} + @category{managedwnd} +*/ +class wxTipWindow : public wxWindow +{ +public: + /** + Constructor. The tip is shown immediately after the window is constructed. + + @param parent + The parent window, must be non-@NULL + @param text + The text to show, may contain the new line characters + @param maxLength + The length of each line, in pixels. Set to a very large + value to avoid wrapping lines + @param windowPtr + Simply passed to + SetTipWindowPtr below, please see its + documentation for the description of this parameter + @param rectBounds + If non-@NULL, passed to + SetBoundingRect below, please see its + documentation for the description of this parameter + */ + wxTipWindow(wxWindow* parent, const wxString& text, + wxCoord maxLength = 100, + wxTipWindow** windowPtr = NULL, + wxRect* rectBounds = NULL); + + /** + By default, the tip window disappears when the user clicks the mouse or presses + a keyboard key or if it loses focus in any other way - for example because the + user switched to another application window. + Additionally, if a non-empty @a rectBound is provided, the tip window will + also automatically close if the mouse leaves this area. This is useful to + dismiss the tip mouse when the mouse leaves the object it is associated with. + + @param rectBound + The bounding rectangle for the mouse in the screen coordinates + */ + void SetBoundingRect(const wxRect& rectBound); + + /** + When the tip window closes itself (which may happen at any moment and + unexpectedly to the caller) it may @NULL out the pointer pointed to by + @e it windowPtr. This is helpful to avoid dereferencing the tip window which + had been already closed and deleted. + */ + void SetTipWindowPtr(wxTipWindow** windowPtr); +}; + diff --git a/interface/wx/tokenzr.h b/interface/wx/tokenzr.h new file mode 100644 index 0000000000..f576de6b5e --- /dev/null +++ b/interface/wx/tokenzr.h @@ -0,0 +1,161 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: tokenzr.h +// Purpose: interface of wxStringTokenizer +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + The behaviour of wxStringTokenizer is governed by the + wxStringTokenizer::wxStringTokenizer() or wxStringTokenizer::SetString() + with the parameter @e mode, which may be one of the following: +*/ +enum wxStringTokenizerMode +{ + wxTOKEN_INVALID = -1, ///< Invalid tokenizer mode. + + /** + Default behaviour: wxStringTokenizer will behave in the same way as + @c strtok() (::wxTOKEN_STRTOK) if the delimiters string only contains + white space characters but, unlike the standard function, it will + behave like ::wxTOKEN_RET_EMPTY, returning empty tokens if this is not + the case. This is helpful for parsing strictly formatted data where + the number of fields is fixed but some of them may be empty (i.e. + @c TAB or comma delimited text files). + */ + wxTOKEN_DEFAULT, + + /** + In this mode, the empty tokens in the middle of the string will be returned, + i.e. @c "a::b:" will be tokenized in three tokens @c 'a', " and @c 'b'. Notice + that all trailing delimiters are ignored in this mode, not just the last one, + i.e. a string @c "a::b::" would still result in the same set of tokens. + */ + wxTOKEN_RET_EMPTY, + + /** + In this mode, empty trailing tokens (including the one after the last delimiter + character) will be returned as well. The string @c "a::b:" will be tokenized in + four tokens: the already mentioned ones and another empty one as the last one + and a string @c "a::b::" will have five tokens. + */ + wxTOKEN_RET_EMPTY_ALL, + + /** + In this mode, the delimiter character after the end of the current token (there + may be none if this is the last token) is returned appended to the token. + Otherwise, it is the same mode as ::wxTOKEN_RET_EMPTY. Notice that there is no + mode like this one but behaving like ::wxTOKEN_RET_EMPTY_ALL instead of + ::wxTOKEN_RET_EMPTY, use ::wxTOKEN_RET_EMPTY_ALL and + wxStringTokenizer::GetLastDelimiter() to emulate it. + */ + wxTOKEN_RET_DELIMS, + + /** + In this mode the class behaves exactly like the standard @c strtok() function: + the empty tokens are never returned. + */ + wxTOKEN_STRTOK +}; + +/** + @class wxStringTokenizer + @wxheader{tokenzr.h} + + wxStringTokenizer helps you to break a string up into a number of tokens. + It replaces the standard C function @c strtok() and also extends it in a + number of ways. + + To use this class, you should create a wxStringTokenizer object, give it the + string to tokenize and also the delimiters which separate tokens in the string + (by default, white space characters will be used). + + Then wxStringTokenizer::GetNextToken() may be called repeatedly until + wxStringTokenizer::HasMoreTokens() returns @false. + + For example: + + @code + wxStringTokenizer tokenizer("first:second:third:fourth", ":"); + while ( tokenizer.HasMoreTokens() ) + { + wxString token = tokenizer.GetNextToken(); + + // process token here + } + @endcode + + @library{wxbase} + @category{data} + + @see wxStringTokenize() +*/ +class wxStringTokenizer : public wxObject +{ +public: + /** + Default constructor. You must call SetString() before calling any other + methods. + */ + wxStringTokenizer(); + /** + Constructor. Pass the string to tokenize, a string containing + delimiters, and the @a mode specifying how the string should be + tokenized. + + @see SetString() + */ + wxStringTokenizer(const wxString& str, + const wxString& delims = " \t\r\n", + wxStringTokenizerMode mode = wxTOKEN_DEFAULT); + + /** + Returns the number of tokens remaining in the input string. The number + of tokens returned by this function is decremented each time + GetNextToken() is called and when it reaches 0, HasMoreTokens() + returns @false. + */ + int CountTokens() const; + + /** + Returns the delimiter which ended scan for the last token returned by + GetNextToken() or @c NUL if there had been no calls to this function + yet or if it returned the trailing empty token in + ::wxTOKEN_RET_EMPTY_ALL mode. + + @since 2.7.0 + */ + wxChar GetLastDelimiter(); + + /** + Returns the next token or empty string if the end of string was reached. + */ + wxString GetNextToken() const; + + /** + Returns the current position (i.e. one index after the last returned + token or 0 if GetNextToken() has never been called) in the original + string. + */ + size_t GetPosition() const; + + /** + Returns the part of the starting string without all token already extracted. + */ + wxString GetString() const; + + /** + Returns @true if the tokenizer has further tokens, @false if none are left. + */ + bool HasMoreTokens() const; + + /** + Initializes the tokenizer. Pass the string to tokenize, a string + containing delimiters, and the @a mode specifying how the string + should be tokenized. + */ + void SetString(const wxString& to_tokenize, + const wxString& delims = " \t\r\n", + wxStringTokenizerMode mode = wxTOKEN_DEFAULT); +}; diff --git a/interface/wx/toolbar.h b/interface/wx/toolbar.h new file mode 100644 index 0000000000..c7deafc8bc --- /dev/null +++ b/interface/wx/toolbar.h @@ -0,0 +1,767 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: toolbar.h +// Purpose: interface of wxToolBar +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxToolBar + @wxheader{toolbar.h} + + The name wxToolBar is defined to be a synonym for one of the following + classes: + + - @b wxToolBar95 - The native Windows 95 toolbar. Used on Windows 95, NT 4 + and above. + - @b wxToolBarMSW - A Windows implementation. Used on 16-bit Windows. + - @b wxToolBarGTK - The GTK toolbar. + + You may also create a toolbar that is managed by the frame, by calling + wxFrame::CreateToolBar(). 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. + + The meaning of a "separator" is a vertical line under Windows and simple + space under GTK+. + + @b wxToolBar95: Note that this toolbar paints tools to reflect + system-wide colours. If you use more than 16 colours in your tool + bitmaps, you may wish to suppress this behaviour, otherwise system + colours in your bitmaps will inadvertently be mapped to system colours. + To do this, set the msw.remap system option before creating the toolbar: + + @code + wxSystemOptions::SetOption(wxT("msw.remap"), 0); + @endcode + + If you wish to use 32-bit images (which include an alpha channel for + transparency) use: + + @code + wxSystemOptions::SetOption(wxT("msw.remap"), 2); + @endcode + + Then colour remapping is switched off, and a transparent background + used. But only use this option under Windows XP with true colour: + + @code + if (wxTheApp->GetComCtl32Version() >= 600 && ::wxDisplayDepth() >= 32) + @endcode + + There are several different types of tools you can add to a toolbar. These + types are controlled by the ::wxItemKind enumeration. + + @beginStyleTable + @style{wxTB_FLAT} + Gives the toolbar a flat look (Windows and GTK only). + @style{wxTB_DOCKABLE} + Makes the toolbar floatable and dockable (GTK only). + @style{wxTB_HORIZONTAL} + Specifies horizontal layout (default). + @style{wxTB_VERTICAL} + Specifies vertical layout. + @style{wxTB_TEXT} + Shows the text in the toolbar buttons; by default only icons are shown. + @style{wxTB_NOICONS} + Specifies no icons in the toolbar buttons; by default they are shown. + @style{wxTB_NODIVIDER} + Specifies no divider (border) above the toolbar (Windows only) + @style{wxTB_NOALIGN} + Specifies no alignment with the parent window (Windows only, not very + useful). + @style{wxTB_HORZ_LAYOUT} + Shows the text and the icons alongside, not vertically stacked (Windows + and GTK 2 only). This style must be used with @c wxTB_TEXT. + @style{wxTB_HORZ_TEXT} + Combination of @c wxTB_HORZ_LAYOUT and @c wxTB_TEXT. + @style{wxTB_NO_TOOLTIPS} + Don't show the short help tooltips for the tools when the mouse hovers + over them. + @style{wxTB_BOTTOM} + Align the toolbar at the bottom of parent window. + @style{wxTB_RIGHT} + Align the toolbar at the right side of parent window. + @endStyleTable + + See also @ref overview_windowstyles. Note that the Win32 native toolbar + ignores @c wxTB_NOICONS style. Also, toggling the @c wxTB_TEXT works only + if the style was initially on. + + @beginEventTable{wxCommandEvent} + @event{EVT_TOOL(id, func)} + Process a @c wxEVT_COMMAND_TOOL_CLICKED event (a synonym for @c + wxEVT_COMMAND_MENU_SELECTED). Pass the id of the tool. + @event{EVT_MENU(id, func)} + The same as EVT_TOOL(). + @event{EVT_TOOL_RANGE(id1, id2, func)} + Process a @c wxEVT_COMMAND_TOOL_CLICKED event for a range of + identifiers. Pass the ids of the tools. + @event{EVT_MENU_RANGE(id1, id2, func)} + The same as EVT_TOOL_RANGE(). + @event{EVT_TOOL_RCLICKED(id, func)} + Process a @c wxEVT_COMMAND_TOOL_RCLICKED event. Pass the id of the + tool. + @event{EVT_TOOL_RCLICKED_RANGE(id1, id2, func)} + Process a @c wxEVT_COMMAND_TOOL_RCLICKED event for a range of ids. Pass + the ids of the tools. + @event{EVT_TOOL_ENTER(id, func)} + Process a @c wxEVT_COMMAND_TOOL_ENTER event. Pass the id of the toolbar + itself. The value of wxCommandEvent::GetSelection() is the tool id, or + -1 if the mouse cursor has moved off a tool. + @event{EVT_TOOL_DROPDOWN(id, func)} + Process a @c wxEVT_COMMAND_TOOL_DROPDOWN_CLICKED event. If unhandled, + displays the default dropdown menu set using + wxToolBar::SetDropdownMenu(). + @endEventTable + + The toolbar class emits menu commands in the same way that a frame menubar + does, so you can use one EVT_MENU() macro for both a menu item and a toolbar + button. The event handler functions take a wxCommandEvent argument. For most + event macros, the identifier of the tool is passed, but for EVT_TOOL_ENTER() + the toolbar window identifier is passed and the tool identifier is retrieved + from the wxCommandEvent. This is because the identifier may be -1 when the + mouse moves off a tool, and -1 is not allowed as an identifier in the event + system. + + @library{wxcore} + @category{miscwnd} + + @see @ref overview_toolbar +*/ +class wxToolBar : public wxControl +{ +public: + /** + Default constructor. + */ + wxToolBar(); + + /** + Constructs a toolbar. + + @param parent + Pointer to a parent window. + @param id + Window identifier. If -1, will automatically create an identifier. + @param pos + Window position. ::wxDefaultPosition is (-1, -1) which indicates that + wxWidgets should generate a default position for the window. If + using the wxWindow class directly, supply an actual position. + @param size + Window size. ::wxDefaultSize is (-1, -1) which indicates that + wxWidgets should generate a default size for the window. + @param style + Window style. See wxToolBar for details. + @param name + Window name. + + @remarks After a toolbar is created, you use AddTool() and perhaps + AddSeparator(), and then you must call Realize() to construct and + display the toolbar tools. + */ + wxToolBar(wxWindow* parent, wxWindowID id, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxTB_HORIZONTAL | wxBORDER_NONE, + const wxString& name = wxPanelNameStr); + + /** + Toolbar destructor. + */ + ~wxToolBar(); + + /** + Adds a new check (or toggle) tool to the toolbar. The parameters are the + same as in AddTool(). + + @see AddTool() + */ + wxToolBarToolBase* AddCheckTool(int toolId, + const wxString& label, + const wxBitmap& bitmap1, + const wxBitmap& bitmap2, + const wxString& shortHelpString = "", + const wxString& longHelpString = "", + wxObject* clientData = NULL); + + /** + Adds any control to the toolbar, typically e.g. a wxComboBox. + + @param control + The control to be added. + @param label + Text to be displayed near the control. + + @remarks + wxMSW: the label is only displayed if there is enough space + available below the embedded control. + + @remarks + wxMac: labels are only displayed if wxWidgets is built with @c + wxMAC_USE_NATIVE_TOOLBAR set to 1 + */ + bool AddControl(wxControl* control, const wxString label = ""); + + /** + Adds a new radio tool to the toolbar. Consecutive radio tools form a + radio group such that exactly one button in the group is pressed at any + moment, in other words whenever a button in the group is pressed the + previously pressed button is automatically released. You should avoid + having the radio groups of only one element as it would be impossible + for the user to use such button. + + By default, the first button in the radio group is initially pressed, + the others are not. + + + @see AddTool() + */ + wxToolBarToolBase* AddRadioTool(int toolId, + const wxString& label, + const wxBitmap& bitmap1, + const wxBitmap& bitmap2, + const wxString& shortHelpString = "", + const wxString& longHelpString = "", + wxObject* clientData = NULL); + + /** + Adds a separator for spacing groups of tools. + + @see AddTool(), SetToolSeparation() + */ + void AddSeparator(); + + /** + Adds a tool to the toolbar. + + @param tool + The tool to be added. + + @remarks After you have added tools to a toolbar, you must call + Realize() in order to have the tools appear. + + @see AddSeparator(), AddCheckTool(), AddRadioTool(), + InsertTool(), DeleteTool(), Realize(), SetDropdownMenu() + */ + wxToolBarToolBase* AddTool(wxToolBarToolBase* tool); + + /** + Adds a tool to the toolbar. This most commonly used version has fewer + parameters than the full version below which specifies the more rarely + used button features. + + @param toolId + An integer by which the tool may be identified in subsequent + operations. + @param label + The string to be displayed with the tool. + @param bitmap + The primary tool bitmap. + @param shortHelp + This string is used for the tools tooltip. + @param kind + May be ::wxITEM_NORMAL for a normal button (default), ::wxITEM_CHECK + for a checkable tool (such tool stays pressed after it had been + toggled) or ::wxITEM_RADIO for a checkable tool which makes part of + a radio group of tools each of which is automatically unchecked + whenever another button in the group is checked. ::wxITEM_DROPDOWN + specifies that a drop-down menu button will appear next to the + tool button (only GTK+ and MSW). Call SetDropdownMenu() afterwards. + + @remarks After you have added tools to a toolbar, you must call + Realize() in order to have the tools appear. + + @see AddSeparator(), AddCheckTool(), AddRadioTool(), + InsertTool(), DeleteTool(), Realize(), SetDropdownMenu() + */ + wxToolBarToolBase* AddTool(int toolId, const wxString& label, + const wxBitmap& bitmap, + const wxString& shortHelp = wxEmptyString, + wxItemKind kind = wxITEM_NORMAL); + + /** + Adds a tool to the toolbar. + + @param toolId + An integer by which the tool may be identified in subsequent + operations. + @param label + The string to be displayed with the tool. + @param bitmap + The primary tool bitmap. + @param bmpDisabled + The bitmap used when the tool is disabled. If it is equal to + ::wxNullBitmap (default), the disabled bitmap is automatically + generated by greying the normal one. + @param shortHelpString + This string is used for the tools tooltip. + @param longHelpString + This string is shown in the statusbar (if any) of the parent frame + when the mouse pointer is inside the tool. + @param kind + May be ::wxITEM_NORMAL for a normal button (default), ::wxITEM_CHECK + for a checkable tool (such tool stays pressed after it had been + toggled) or ::wxITEM_RADIO for a checkable tool which makes part of + a radio group of tools each of which is automatically unchecked + whenever another button in the group is checked. ::wxITEM_DROPDOWN + specifies that a drop-down menu button will appear next to the + tool button (only GTK+ and MSW). Call SetDropdownMenu() afterwards. + @param clientData + An optional pointer to client data which can be retrieved later + using GetToolClientData(). + + @remarks After you have added tools to a toolbar, you must call + Realize() in order to have the tools appear. + + @see AddSeparator(), AddCheckTool(), AddRadioTool(), + InsertTool(), DeleteTool(), Realize(), SetDropdownMenu() + */ + wxToolBarToolBase* AddTool(int toolId, const wxString& label, + const wxBitmap& bitmap, + const wxBitmap& bmpDisabled = wxNullBitmap, + wxItemKind kind = wxITEM_NORMAL, + const wxString& shortHelpString = wxEmptyString, + const wxString& longHelpString = wxEmptyString, + wxObject* clientData = NULL); + + /** + Deletes all the tools in the toolbar. + */ + void ClearTools(); + + /** + Removes the specified tool from the toolbar and deletes it. If you don't + want to delete the tool, but just to remove it from the toolbar (to + possibly add it back later), you may use RemoveTool() instead. + + @note It is unnecessary to call Realize() for the change to take + place, it will happen immediately. + + @returns @true if the tool was deleted, @false otherwise. + + @see DeleteToolByPos() + */ + bool DeleteTool(int toolId); + + /** + This function behaves like DeleteTool() but it deletes the tool at the + specified position and not the one with the given id. + */ + bool DeleteToolByPos(size_t pos); + + /** + Enables or disables the tool. + + @param toolId + Tool to enable or disable. + @param enable + If @true, enables the tool, otherwise disables it. + + @remarks Some implementations will change the visible state of the tool + to indicate that it is disabled. + + + @see GetToolEnabled(), ToggleTool() + */ + void EnableTool(int toolId, bool enable); + + /** + Returns a pointer to the tool identified by @a id or @NULL if no + corresponding tool is found. + */ + wxToolBarToolBase* FindById(int id); + + /** + Returns a pointer to the control identified by @a id or @NULL if no + corresponding control is found. + */ + wxControl* FindControl(int id); + + /** + Finds a tool for the given mouse position. + + @param x + X position. + @param y + Y position. + + @return A pointer to a tool if a tool is found, or @NULL otherwise. + + @remarks Currently not implemented in wxGTK (always returns @NULL + there). + */ + wxToolBarToolBase* FindToolForPosition(wxCoord x, wxCoord y) const; + + /** + Returns the left/right and top/bottom margins, which are also used for + inter-toolspacing. + + @see SetMargins() + */ + wxSize GetMargins() const; + + /** + Returns the size of bitmap that the toolbar expects to have. The default + bitmap size is 16 by 15 pixels. + + @remarks Note that this is the size of the bitmap you pass to AddTool(), + and not the eventual size of the tool button. + + @see SetToolBitmapSize(), GetToolSize() + */ + wxSize GetToolBitmapSize(); + + /** + Get any client data associated with the tool. + + @param toolId + Id of the tool, as passed to AddTool(). + + @return Client data, or @NULL if there is none. + */ + wxObject* GetToolClientData(int toolId) const; + + /** + Called to determine whether a tool is enabled (responds to user input). + + @param toolId + Id of the tool in question. + + @return @true if the tool is enabled, @false otherwise. + + @see EnableTool() + */ + bool GetToolEnabled(int toolId) const; + + /** + Returns the long help for the given tool. + + @param toolId + The tool in question. + + @see SetToolLongHelp(), SetToolShortHelp() + */ + wxString GetToolLongHelp(int toolId) const; + + /** + Returns the value used for packing tools. + + @see SetToolPacking() + */ + int GetToolPacking() const; + + /** + Returns the tool position in the toolbar, or @c wxNOT_FOUND if the tool + is not found. + */ + int GetToolPos(int toolId) const; + + /** + Returns the default separator size. + + @see SetToolSeparation() + */ + int GetToolSeparation() const; + + /** + Returns the short help for the given tool. + + @param toolId + The tool in question. + + @see GetToolLongHelp(), SetToolShortHelp() + */ + wxString GetToolShortHelp(int toolId) const; + + /** + Returns the size of a whole button, which is usually larger than a tool + bitmap because of added 3D effects. + + @see SetToolBitmapSize(), GetToolBitmapSize() + */ + wxSize GetToolSize(); + + /** + Gets the on/off state of a toggle tool. + + @param toolId + The tool in question. + + @return @true if the tool is toggled on, @false otherwise. + + @see ToggleTool() + */ + bool GetToolState(int toolId) const; + + /** + Returns the number of tools in the toolbar. + */ + int GetToolsCount() const; + + /** + Inserts the control into the toolbar at the given position. You must + call Realize() for the change to take place. + + @see AddControl(), InsertTool() + */ + wxToolBarToolBase* InsertControl(size_t pos, wxControl* control); + + /** + Inserts the separator into the toolbar at the given position. You must + call Realize() for the change to take place. + + @see AddSeparator(), InsertTool() + */ + wxToolBarToolBase* InsertSeparator(size_t pos); + + //@{ + /** + Inserts the tool with the specified attributes into the toolbar at the + given position. + + You must call Realize() for the change to take place. + + @see AddTool(), InsertControl(), InsertSeparator() + */ + wxToolBarToolBase* InsertTool(size_t pos, int toolId, + const wxBitmap& bitmap1, + const wxBitmap& bitmap2 = wxNullBitmap, + bool isToggle = false, + wxObject* clientData = NULL, + const wxString& shortHelpString = "", + const wxString& longHelpString = ""); + wxToolBarToolBase* InsertTool(size_t pos, + wxToolBarToolBase* tool); + //@} + + /** + Called when the user clicks on a tool with the left mouse button. This + is the old way of detecting tool clicks; although it will still work, + you should use the EVT_MENU() or EVT_TOOL() macro instead. + + @param toolId + The identifier passed to AddTool(). + @param toggleDown + @true if the tool is a toggle and the toggle is down, otherwise is + @false. + + @return If the tool is a toggle and this function returns @false, the + toggle state (internal and visual) will not be changed. This + provides a way of specifying that toggle operations are not + permitted in some circumstances. + + @see OnMouseEnter(), OnRightClick() + */ + bool OnLeftClick(int toolId, bool toggleDown); + + /** + This is called when the mouse cursor moves into a tool or out of the + toolbar. This is the old way of detecting mouse enter events; + although it will still work, you should use the EVT_TOOL_ENTER() + macro instead. + + @param toolId + Greater than -1 if the mouse cursor has moved into the tool, or -1 + if the mouse cursor has moved. The programmer can override this to + provide extra information about the tool, such as a short + description on the status line. + + @remarks With some derived toolbar classes, if the mouse moves quickly + out of the toolbar, wxWidgets may not be able to detect it. + Therefore this function may not always be called when expected. + */ + void OnMouseEnter(int toolId); + + /** + @deprecated This is the old way of detecting tool right clicks; + although it will still work, you should use the + EVT_TOOL_RCLICKED() macro instead. + + Called when the user clicks on a tool with the right mouse button. The + programmer should override this function to detect right tool clicks. + + @param toolId + The identifier passed to AddTool(). + @param x + The x position of the mouse cursor. + @param y + The y position of the mouse cursor. + + @remarks A typical use of this member might be to pop up a menu. + + @see OnMouseEnter(), OnLeftClick() + */ + void OnRightClick(int toolId, float x, float y); + + /** + This function should be called after you have added tools. + */ + bool Realize(); + + /** + Removes the given tool from the toolbar but doesn't delete it. This + allows to insert/add this tool back to this (or another) toolbar later. + + @note It is unnecessary to call Realize() for the change to take place, + it will happen immediately. + + + @see DeleteTool() + */ + wxToolBarToolBase* RemoveTool(int id); + + /** + Sets the bitmap resource identifier for specifying tool bitmaps as + indices into a custom bitmap. Windows CE only. + */ + void SetBitmapResource(int resourceId); + + /** + Sets the dropdown menu for the tool given by its @e id. The tool itself + will delete the menu when it's no longer needed. Only supported under + GTK+ und MSW. + + If you define a EVT_TOOL_DROPDOWN() handler in your program, you must + call wxEvent::Skip() from it or the menu won't be displayed. + */ + bool SetDropdownMenu(int id, wxMenu* menu); + + /** + Set the values to be used as margins for the toolbar. + + @param x + Left margin, right margin and inter-tool separation value. + @param y + Top margin, bottom margin and inter-tool separation value. + + @remarks This must be called before the tools are added if absolute + positioning is to be used, and the default (zero-size) margins are + to be overridden. + + @see GetMargins() + */ + void SetMargins(int x, int y); + + /** + Set the margins for the toolbar. + + @param size + Margin size. + + @remarks This must be called before the tools are added if absolute + positioning is to be used, and the default (zero-size) margins are + to be overridden. + + @see GetMargins(), wxSize + */ + void SetMargins(const wxSize& size); + + /** + Sets the default size of each tool bitmap. The default bitmap size is 16 + by 15 pixels. + + @param size + The size of the bitmaps in the toolbar. + + @remarks This should be called to tell the toolbar what the tool bitmap + size is. Call it before you add tools. + + @see GetToolBitmapSize(), GetToolSize() + */ + void SetToolBitmapSize(const wxSize& size); + + /** + Sets the client data associated with the tool. + */ + void SetToolClientData(int id, wxObject* clientData); + + /** + Sets the bitmap to be used by the tool with the given ID when the tool + is in a disabled state. This can only be used on Button tools, not + controls. + + @note The native toolbar classes on the main platforms all synthesize + the disabled bitmap from the normal bitmap, so this function will + have no effect on those platforms. + + */ + void SetToolDisabledBitmap(int id, const wxBitmap& bitmap); + + /** + Sets the long help for the given tool. + + @param toolId + The tool in question. + @param helpString + A string for the long help. + + @remarks You might use the long help for displaying the tool purpose on + the status line. + + @see GetToolLongHelp(), SetToolShortHelp(), + */ + void SetToolLongHelp(int toolId, const wxString& helpString); + + /** + Sets the bitmap to be used by the tool with the given ID. This can only + be used on Button tools, not controls. + */ + void SetToolNormalBitmap(int id, const wxBitmap& bitmap); + + /** + Sets the value used for spacing tools. The default value is 1. + + @param packing + The value for packing. + + @remarks The packing is used for spacing in the vertical direction if + the toolbar is horizontal, and for spacing in the horizontal + direction if the toolbar is vertical. + + @see GetToolPacking() + */ + void SetToolPacking(int packing); + + /** + Sets the default separator size. The default value is 5. + + @param separation + The separator size. + + @see AddSeparator() + */ + void SetToolSeparation(int separation); + + /** + Sets the short help for the given tool. + + @param toolId + The tool in question. + @param helpString + The string for the short help. + + @remarks An application might use short help for identifying the tool + purpose in a tooltip. + + + @see GetToolShortHelp(), SetToolLongHelp() + */ + void SetToolShortHelp(int toolId, const wxString& helpString); + + /** + Toggles a tool on or off. This does not cause any event to get emitted. + + @param toolId + Tool in question. + @param toggle + If @true, toggles the tool on, otherwise toggles it off. + + @remarks Only applies to a tool that has been specified as a toggle + tool. + */ + void ToggleTool(int toolId, bool toggle); +}; + diff --git a/interface/wx/toolbook.h b/interface/wx/toolbook.h new file mode 100644 index 0000000000..358adbd212 --- /dev/null +++ b/interface/wx/toolbook.h @@ -0,0 +1,45 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: toolbook.h +// Purpose: interface of wxToolbook +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxToolbook + @wxheader{toolbook.h} + + wxToolbook is a class similar to wxNotebook but which uses a wxToolBar to + show the labels instead of the tabs. + + There is no documentation for this class yet but its usage is identical to + wxNotebook (except for the features clearly related to tabs only), so please + refer to that class documentation for now. You can also use the + @ref page_samples_notebook to see wxToolbook in action. + + @beginStyleTable + @style{wxTBK_BUTTONBAR} + Use wxButtonToolBar-based implementation under Mac OS (ignored under + other platforms). + @style{wxTBK_HORZ_LAYOUT} + Shows the text and the icons alongside, not vertically stacked (only + implement under Windows and GTK 2 platforms as it relies on @c + wxTB_HORZ_LAYOUT flag support). + @endStyleTable + + The common wxBookCtrl styles described in the @ref overview_bookctrl are + also supported. + + @library{wxcore} + @category{miscwnd} + + @see @ref overview_bookctrl, wxBookCtrlBase, wxNotebook, + @ref page_samples_notebook +*/ +class wxToolbook : public wxBookCtrlBase +{ +public: + +}; + diff --git a/interface/wx/tooltip.h b/interface/wx/tooltip.h new file mode 100644 index 0000000000..6d6779198a --- /dev/null +++ b/interface/wx/tooltip.h @@ -0,0 +1,75 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: tooltip.h +// Purpose: interface of wxToolTip +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxToolTip + @wxheader{tooltip.h} + + This class holds information about a tooltip associated with a window (see + wxWindow::SetToolTip()). + + The four static methods, wxToolTip::Enable(), wxToolTip::SetDelay() + wxToolTip::SetAutoPop() and wxToolTip::SetReshow() can be used to globally + alter tooltips behaviour. + + @library{wxcore} + @category{help} +*/ +class wxToolTip : public wxObject +{ +public: + /** + Constructor. + */ + wxToolTip(const wxString& tip); + + /** + Enable or disable tooltips globally. + + @note May not be supported on all platforms (eg. wxCocoa). + */ + static void Enable(bool flag); + + /** + Get the tooltip text. + */ + wxString GetTip() const; + + /** + Get the associated window. + */ + wxWindow* GetWindow() const; + + /** + Set the delay after which the tooltip disappears or how long a tooltip + remains visible. + + @note May not be supported on all platforms (eg. wxCocoa, GTK, Palmos). + */ + static void SetAutoPop(long msecs); + + /** + Set the delay after which the tooltip appears. + + @note May not be supported on all platforms (eg. wxCocoa). + */ + static void SetDelay(long msecs); + + /** + Set the delay between subsequent tooltips to appear. + + @note May not be supported on all platforms (eg. wxCocoa, GTK, Palmos). + */ + static void SetReshow(long msecs); + + /** + Set the tooltip text. + */ + void SetTip(const wxString& tip); +}; + diff --git a/interface/wx/toplevel.h b/interface/wx/toplevel.h new file mode 100644 index 0000000000..f0432e2e68 --- /dev/null +++ b/interface/wx/toplevel.h @@ -0,0 +1,426 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: toplevel.h +// Purpose: interface of wxTopLevelWindow +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + Styles used with wxTopLevelWindow::RequestUserAttention(). +*/ +enum +{ + wxUSER_ATTENTION_INFO = 1, ///< Requests user attention, + wxUSER_ATTENTION_ERROR = 2 ///< Results in a more drastic action. +}; + +/** + Styles used with wxTopLevelWindow::ShowFullScreen(). +*/ +enum +{ + wxFULLSCREEN_NOMENUBAR = 0x0001, ///< Don't display the menu bar. + wxFULLSCREEN_NOTOOLBAR = 0x0002, ///< Don't display toolbar bars. + wxFULLSCREEN_NOSTATUSBAR = 0x0004, ///< Don't display the status bar. + wxFULLSCREEN_NOBORDER = 0x0008, ///< Don't display any border. + wxFULLSCREEN_NOCAPTION = 0x0010, ///< Don't display a caption. + + /** + Combination of all above, will display the least possible. + */ + wxFULLSCREEN_ALL = wxFULLSCREEN_NOMENUBAR | wxFULLSCREEN_NOTOOLBAR | + wxFULLSCREEN_NOSTATUSBAR | wxFULLSCREEN_NOBORDER | + wxFULLSCREEN_NOCAPTION +}; + +/** + @class wxTopLevelWindow + @wxheader{toplevel.h} + + wxTopLevelWindow is a common base class for wxDialog and wxFrame. It is an + abstract base class meaning that you never work with objects of this class + directly, but all of its methods are also applicable for the two classes + above. + + @library{wxcore} + @category{managedwnd} + + @see wxDialog, wxFrame +*/ +class wxTopLevelWindow : public wxWindow +{ +public: + /** + Returns @true if the platform supports making the window translucent. + + @see SetTransparent() + */ + virtual bool CanSetTransparent(); + + /** + A synonym for CentreOnScreen(). + */ + void CenterOnScreen(int direction); + + /** + Centres the window on screen. + + @param direction + Specifies the direction for the centering. May be @c wxHORIZONTAL, + @c wxVERTICAL or @c wxBOTH. + + @see wxWindow::CentreOnParent() + */ + void CentreOnScreen(int direction = wxBOTH); + + /** + Enables or disables the Close button (most often in the right upper + corner of a dialog) and the Close entry of the system menu (most often + in the left upper corner of the dialog). + + Currently only implemented for wxMSW and wxGTK. + + Returns @true if operation was successful. This may be wrong on X11 + (including GTK+) where the window manager may not support this operation + and there is no way to find out. + */ + bool EnableCloseButton(bool enable = true); + + /** + Returns a pointer to the button which is the default for this window, or + @c @NULL. The default button is the one activated by pressing the Enter + key. + */ + wxWindow* GetDefaultItem() const; + + /** + Returns the standard icon of the window. The icon will be invalid if it + hadn't been previously set by SetIcon(). + + @see GetIcons() + */ + const wxIcon GetIcon() const; + + /** + Returns all icons associated with the window, there will be none of them + if neither SetIcon() nor SetIcons() had been called before. Use + GetIcon() to get the main icon of the window. + + @see wxIconBundle + */ + const wxIconBundle GetIcons() const; + + /** + Gets a string containing the window title. + + @see SetTitle() + */ + wxString GetTitle() const; + + /** + Unique to the wxWinCE port. Responds to showing/hiding SIP (soft input + panel) area and resize window accordingly. Override this if you want to + avoid resizing or do additional operations. + */ + virtual bool HandleSettingChange(WXWPARAM wParam, + WXLPARAM lParam); + + /** + Iconizes or restores the window. + + @param iconize + If @true, iconizes the window; if @false, shows and restores it. + + @see IsIconized(), Maximize(), wxIconizeEvent. + */ + void Iconize(bool iconize); + + /** + Returns @true if this window is currently active, i.e. if the user is + currently working with it. + */ + bool IsActive() const; + + /** + Returns @true if this window is expected to be always maximized, either + due to platform policy or due to local policy regarding particular + class. + */ + virtual bool IsAlwaysMaximized() const; + + /** + Returns @true if the window is in fullscreen mode. + + @see ShowFullScreen() + */ + bool IsFullScreen(); + + /** + Returns @true if the window is iconized. + */ + bool IsIconized() const; + + /** + Returns @true if the window is maximized. + */ + bool IsMaximized() const; + + /** + This method is specific to wxUniversal port. + + Returns @true if this window is using native decorations, @false if we + draw them ourselves. + + @see UseNativeDecorations(), + UseNativeDecorationsByDefault() + */ + bool IsUsingNativeDecorations() const; + + /** + Maximizes or restores the window. + + @param maximize + If @true, maximizes the window, otherwise it restores it. + + @see Iconize() + */ + void Maximize(bool maximize); + + /** + Use a system-dependent way to attract users attention to the window when + it is in background. + + @a flags may have the value of either @c ::wxUSER_ATTENTION_INFO + (default) or @c ::wxUSER_ATTENTION_ERROR which results in a more drastic + action. When in doubt, use the default value. + + + @note This function should normally be only used when the application + is not already in foreground. + + This function is currently implemented for Win32 where it flashes + the window icon in the taskbar, and for wxGTK with task bars + supporting it. + + */ + void RequestUserAttention(int flags = wxUSER_ATTENTION_INFO); + + /** + Changes the default item for the panel, usually @a win is a button. + + @see GetDefaultItem() + */ + void SetDefaultItem(wxWindow* win); + + /** + Sets the icon for this window. + + @param icon + The wxIcon to associate with this window. + + @remarks The window takes a 'copy' of @a icon, but since it uses + reference counting, the copy is very quick. It is safe to + delete @a icon after calling this function. + + @see wxIcon + */ + void SetIcon(const wxIcon& icon); + + /** + Sets several icons of different sizes for this window: this allows to + use different icons for different situations (e.g. task switching bar, + taskbar, window title bar) instead of scaling, with possibly bad looking + results, the only icon set by SetIcon(). + + @param icons + The icons to associate with this window. + + @see wxIconBundle. + */ + void SetIcons(const wxIconBundle& icons); + + /** + Sets action or menu activated by pressing left hardware button on the + smart phones. Unavailable on full keyboard machines. + + @param id + Identifier for this button. + @param label + Text to be displayed on the screen area dedicated to this hardware + button. + @param subMenu + The menu to be opened after pressing this hardware button. + + @see SetRightMenu(). + */ + void SetLeftMenu(int id = wxID_ANY, + const wxString& label = wxEmptyString, + wxMenu* subMenu = NULL); + + /** + A simpler interface for setting the size hints than SetSizeHints(). + */ + void SetMaxSize(const wxSize& size); + + /** + A simpler interface for setting the size hints than SetSizeHints(). + */ + void SetMinSize(const wxSize& size); + + /** + Sets action or menu activated by pressing right hardware button on the + smart phones. Unavailable on full keyboard machines. + + @param id + Identifier for this button. + @param label + Text to be displayed on the screen area dedicated to this hardware + button. + @param subMenu + The menu to be opened after pressing this hardware button. + + @see SetLeftMenu(). + */ + void SetRightMenu(int id = wxID_ANY, + const wxString& label = wxEmptyString, + wxMenu* subMenu = NULL); + + /** + If the platform supports it, sets the shape of the window to that + depicted by @a region. The system will not display or respond to any + mouse event for the pixels that lie outside of the region. To reset the + window to the normal rectangular shape simply call SetShape() again with + an empty wxRegion. Returns @true if the operation is successful. + */ + bool SetShape(const wxRegion& region); + + /** + Allows specification of minimum and maximum window sizes, and window + size increments. If a pair of values is not set (or set to -1), no + constraints will be used. + + @param incW + Specifies the increment for sizing the width (GTK/Motif/Xt only). + @param incH + Specifies the increment for sizing the height (GTK/Motif/Xt only). + + @remarks Notice that this function not only prevents the user from + resizing the window outside the given bounds but it also + prevents the program itself from doing it using + wxWindow::SetSize(). + + */ + virtual void SetSizeHints(int minW, int minH, int maxW = -1, + int maxH = -1, + int incW = -1, + int incH = -1); + + /** + Allows specification of minimum and maximum window sizes, and window + size increments. If a pair of values is not set (or set to -1), no + constraints will be used. + + @param incSize + Increment size (only taken into account under X11-based ports such + as wxGTK/wxMotif/wxX11). + + @remarks Notice that this function not only prevents the user from + resizing the window outside the given bounds but it also + prevents the program itself from doing it using + wxWindow::SetSize(). + */ + void SetSizeHints(const wxSize& minSize, + const wxSize& maxSize = wxDefaultSize, + const wxSize& incSize = wxDefaultSize); + + /** + Sets the window title. + + @param title + The window title. + + @see GetTitle() + */ + virtual void SetTitle(const wxString& title); + + /** + If the platform supports it will set the window to be translucent. + + @param alpha + Determines how opaque or transparent the window will be, if the + platform supports the opreration. A value of 0 sets the window to be + fully transparent, and a value of 255 sets the window to be fully + opaque. + */ + virtual bool SetTransparent(int alpha); + + /** + This virtual function is not meant to be called directly but can be + overridden to return @false (it returns @true by default) to allow the + application to close even if this, presumably not very important, window + is still opened. By default, the application stays alive as long as + there are any open top level windows. + */ + virtual bool ShouldPreventAppExit() const; + + /** + Depending on the value of @a show parameter the window is either shown + full screen or restored to its normal state. @a style is a bit list + containing some or all of the following values, which indicate what + elements of the window to hide in full-screen mode: + + - @c ::wxFULLSCREEN_NOMENUBAR + - @c ::wxFULLSCREEN_NOTOOLBAR + - @c ::wxFULLSCREEN_NOSTATUSBAR + - @c ::wxFULLSCREEN_NOBORDER + - @c ::wxFULLSCREEN_NOCAPTION + - @c ::wxFULLSCREEN_ALL (all of the above) + + This function has not been tested with MDI frames. + + @note Showing a window full screen also actually @ref wxWindow::Show() + "Show()"s the window if it isn't shown. + + @see IsFullScreen() + */ + bool ShowFullScreen(bool show, long style = wxFULLSCREEN_ALL); + + /** + This method is specific to wxUniversal port. + + Use native or custom-drawn decorations for this window only. Notice that + to have any effect this method must be called before really creating the + window, i.e. two step creation must be used: + + @code + MyFrame *frame = new MyFrame; // use default ctor + frame->UseNativeDecorations(false); // change from default "true" + frame->Create(parent, title, ...); // really create the frame + @endcode + + @see UseNativeDecorationsByDefault(), + IsUsingNativeDecorations() + */ + void UseNativeDecorations(bool native = true); + + /** + This method is specific to wxUniversal port. + + Top level windows in wxUniversal port can use either system-provided + window decorations (i.e. title bar and various icons, buttons and menus + in it) or draw the decorations themselves. By default the system + decorations are used if they are available, but this method can be + called with @a native set to @false to change this for all windows + created after this point. + + Also note that if @c WXDECOR environment variable is set, then custom + decorations are used by default and so it may make sense to call this + method with default argument if the application can't use custom + decorations at all for some reason. + + @see UseNativeDecorations() + */ + void UseNativeDecorationsByDefault(bool native = true); +}; + diff --git a/interface/wx/tracker.h b/interface/wx/tracker.h new file mode 100644 index 0000000000..67d4bc0a65 --- /dev/null +++ b/interface/wx/tracker.h @@ -0,0 +1,36 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: tracker.h +// Purpose: interface of wxTrackable +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxTrackable + @wxheader{tracker.h} + + Add-on base class for a trackable object. This class maintains an internal + linked list of classes of type wxTrackerNode and calls OnObjectDestroy() on + them if this object is destroyed. The most common usage is by using the + wxWeakRef class template which automates this. This class has no public + API. Its only use is by deriving another class from it to make it trackable. + + @code + class MyClass: public Foo, public wxTrackable + { + // whatever + } + + typedef wxWeakRef MyClassRef; + @endcode + + @library{wxbase} + @category{smartpointers} +*/ +class wxTrackable +{ +public: + +}; + diff --git a/interface/wx/treebase.h b/interface/wx/treebase.h new file mode 100644 index 0000000000..84ffd78598 --- /dev/null +++ b/interface/wx/treebase.h @@ -0,0 +1,129 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: treebase.h +// Purpose: interface of wxTreeItemId +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxTreeItemId + @wxheader{treebase.h} + + An opaque reference to a tree item. + + @library{wxcore} + @category{misc} + + @see wxTreeCtrl, wxTreeItemData, @ref overview_treectrl +*/ +class wxTreeItemId +{ +public: + /** + Default constructor. A wxTreeItemId is not meant to be constructed + explicitly by the user; only those returned by the wxTreeCtrl functions + should be used. + */ + wxTreeItemId(); + + /** + Returns @true if this instance is referencing a valid tree item. + */ + bool IsOk() const; + + //@{ + /** + Operators for comparison between wxTreeItemId objects. + */ + bool operator ==(const wxTreeItemId& item) const; + bool operator !=(const wxTreeItemId& item) const; + //@} + + /** + Antonym of IsOk(), i.e. returns @true only if the item is not valid. + */ + bool operator !() const; +}; + +/** + @class wxTreeItemData + @wxheader{treebase.h} + + wxTreeItemData is some (arbitrary) user class associated with some item. The + main advantage of having this class is that wxTreeItemData objects are + destroyed automatically by the tree and, as this class has virtual + destructor, it means that the memory and any other resources associated with + a tree item will be automatically freed when it is deleted. Note that we + don't use wxObject as the base class for wxTreeItemData because the size of + this class is critical: in many applications, each tree leaf will have + wxTreeItemData associated with it and the number of leaves may be quite big. + + Also please note that because the objects of this class are deleted by the + tree using the operator @c delete, they must always be allocated on the heap + using @c new. + + @library{wxcore} + @category{containers} + + @see wxTreeCtrl +*/ +class wxTreeItemData : public wxClientData +{ +public: + /** + Default constructor. + + @beginWxPythonOnly + The following methods are added in wxPython for accessing the object: + - GetData(): Returns a reference to the Python Object. + - SetData(obj): Associates a new Python Object with the wxTreeItemData. + @endWxPythonOnly + */ + wxTreeItemData(); + + /** + Virtual destructor. + */ + ~wxTreeItemData(); + + /** + Returns the item associated with this node. + */ + const wxTreeItemId GetId(); + + /** + Sets the item associated with this node. + */ + void SetId(const wxTreeItemId& id); +}; + +/** + Indicates which type to associate an image with a wxTreeCtrl item. + + @see wxTreeCtrl::GetItemImage(), wxTreeCtrl::SetItemImage() +*/ +enum wxTreeItemIcon +{ + /** + To get/set the item image for when the item is + @b not selected and @b not expanded. + */ + wxTreeItemIcon_Normal, + /** + To get/set the item image for when the item is + @b selected and @b not expanded. + */ + wxTreeItemIcon_Selected, + /** + To get/set the item image for when the item is + @b not selected and @b expanded. + */ + wxTreeItemIcon_Expanded, + /** + To get/set the item image for when the item is + @b selected and @b expanded. + */ + wxTreeItemIcon_SelectedExpanded, + wxTreeItemIcon_Max +}; diff --git a/interface/wx/treebook.h b/interface/wx/treebook.h new file mode 100644 index 0000000000..c950031b2d --- /dev/null +++ b/interface/wx/treebook.h @@ -0,0 +1,295 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: treebook.h +// Purpose: interface of wxTreebookEvent +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxTreebookEvent + @wxheader{treebook.h} + + This class represents the events generated by a treebook control: currently, + there are four of them. The EVT_TREEBOOK_PAGE_CHANGING() and + EVT_TREEBOOK_PAGE_CHANGED() - have exactly the same behaviour as + wxNotebookEvent. + + The other two EVT_TREEBOOK_NODE_COLLAPSED() and EVT_TREEBOOK_NODE_EXPANDED() + are triggered when page node in the tree control is collapsed/expanded. The + page index could be retreived by calling GetSelection(). + + @beginEventTable{wxTreebookEvent} + @event{EVT_TREEBOOK_PAGE_CHANGED(id, func)} + The page selection was changed. Processes a @c + wxEVT_COMMAND_TREEBOOK_PAGE_CHANGED event. + @event{EVT_TREEBOOK_PAGE_CHANGING(id, func)} + The page selection is about to be changed. Processes a @c + wxEVT_COMMAND_TREEBOOK_PAGE_CHANGING event. This event can be @ref + wxNotifyEvent::Veto() "vetoed". + @event{EVT_TREEBOOK_NODE_COLLAPSED(id, func)} + The page node is going to be collapsed. Processes a @c + wxEVT_COMMAND_TREEBOOK_NODE_COLLAPSED event. + @event{EVT_TREEBOOK_NODE_EXPANDED(id, func)} + The page node is going to be expanded. Processes a @c + wxEVT_COMMAND_TREEBOOK_NODE_EXPANDED event. + @endEventTable + + @library{wxcore} + @category{events} + + @see wxTreebook, wxNotebookEvent +*/ +class wxTreebookEvent : public wxNotifyEvent +{ +public: + /** + @see wxNotebookEvent + */ + wxTreebookEvent(wxEventType commandType = wxEVT_NULL, int id = 0, + int nSel = wxNOT_FOUND, + int nOldSel = wxNOT_FOUND); + + /** + Returns the page that was selected before the change, @c wxNOT_FOUND if + none was selected. + */ + int GetOldSelection() const; + + /** + Returns the currently selected page, or @c wxNOT_FOUND if none was + selected. + + @see wxNotebookEvent::GetSelection() + */ + int GetSelection() const; +}; + + + +/** + @class wxTreebook + @wxheader{treebook.h} + + This class is an extension of the wxNotebook class that allows a tree + structured set of pages to be shown in a control. A classic example is a + netscape preferences dialog that shows a tree of preference sections on + the left and select section page on the right. + + To use the class simply create it and populate with pages using + InsertPage(), InsertSubPage(), AddPage(), AddSubPage(). + + If your tree is no more than 1 level in depth then you could simply use + AddPage() and AddSubPage() to sequentially populate your tree by adding at + every step a page or a subpage to the end of the tree. + + @beginEventTable{wxTreebookEvent} + @event{EVT_TREEBOOK_PAGE_CHANGED(id, func)} + The page selection was changed. Processes a @c + wxEVT_COMMAND_TREEBOOK_PAGE_CHANGED event. + @event{EVT_TREEBOOK_PAGE_CHANGING(id, func)} + The page selection is about to be changed. Processes a @c + wxEVT_COMMAND_TREEBOOK_PAGE_CHANGING event. This event can be @ref + wxNotifyEvent::Veto() "vetoed". + @event{EVT_TREEBOOK_NODE_COLLAPSED(id, func)} + The page node is going to be collapsed. Processes a @c + wxEVT_COMMAND_TREEBOOK_NODE_COLLAPSED event. + @event{EVT_TREEBOOK_NODE_EXPANDED(id, func)} + The page node is going to be expanded. Processes a @c + wxEVT_COMMAND_TREEBOOK_NODE_EXPANDED event. + @endEventTable + + @library{wxcore} + @category{miscwnd} + + @see wxTreebookEvent, wxNotebook, wxTreeCtrl, wxImageList, + @ref overview_bookctrl, @ref page_samples_notebook +*/ +class wxTreebook : public wxBookCtrlBase +{ +public: + /** + Default constructor. + */ + wxTreebook(); + + /** + Creates an empty wxTreebook. + + @param parent + The parent window. Must be non-@NULL. + @param id + The window identifier. + @param pos + The window position. + @param size + The window size. + @param style + The window style. See wxNotebook. + @param name + The name of the control (used only under Motif). + */ + wxTreebook(wxWindow* parent, wxWindowID id, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxBK_DEFAULT, + const wxString& name = wxEmptyString); + + /** + Destroys the wxTreebook object. Also deletes all the pages owned by the + control (inserted previously into it). + */ + ~wxTreebook(); + + /** + Adds a new page. The page is placed at the topmost level after all other + pages. @NULL could be specified for page to create an empty page. + */ + bool AddPage(wxWindow* page, const wxString& text, + bool bSelect = false, + int imageId = wxNOT_FOUND); + + /** + Adds a new child-page to the last top-level page. @NULL could be + specified for page to create an empty page. + */ + bool AddSubPage(wxWindow* page, const wxString& text, + bool bSelect = false, + int imageId = wxNOT_FOUND); + + /** + Sets the image list for the page control and takes ownership of the + list. + + @see wxImageList, SetImageList() + */ + void AssignImageList(wxImageList* imageList); + + /** + Changes the selection for the given page, returning the previous + selection. + + The call to this function does not generate the page changing events. + This is the only difference with SetSelection(). See + @ref overview_eventhandling_prog for more info. + */ + int ChangeSelection(size_t page); + + /** + Shortcut for @ref wxTreebook::ExpandNode() "ExpandNode"( @a pageId, + @false ). + */ + bool CollapseNode(size_t pageId); + + /** + Creates a treebook control. See wxTreebook::wxTreebook() for the + description of the parameters. + */ + bool Create(wxWindow* parent, wxWindowID id, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxBK_DEFAULT, + const wxString& name = wxEmptyString); + + /** + Deletes all pages inserted into the treebook. No event is generated. + */ + bool DeleteAllPages(); + + /** + Deletes the page at the specified position and all its children. Could + trigger page selection change in a case when selected page is removed. + In that case its parent is selected (or the next page if no parent). + */ + bool DeletePage(size_t pagePos); + + /** + Expands (collapses) the @a pageId node. Returns the previous state. May + generate page changing events (if selected page is under the collapsed + branch, then its parent is autoselected). + */ + bool ExpandNode(size_t pageId, bool expand = true); + + /** + Returns the image index for the given page. + */ + int GetPageImage(size_t n) const; + + /** + Returns the parent page of the given one or @c wxNOT_FOUND if this is a + top-level page. + */ + int GetPageParent(size_t page) const; + + /** + Returns the string for the given page. + */ + wxString GetPageText(size_t n) const; + + /** + Returns the currently selected page, or @c wxNOT_FOUND if none was + selected. + + @note This method may return either the previously or newly selected + page when called from the EVT_TREEBOOK_PAGE_CHANGED() handler + depending on the platform and so wxTreebookEvent::GetSelection() + should be used instead in this case. + */ + int GetSelection() const; + + /** + Inserts a new page just before the page indicated by @a pagePos. The new + page is placed before @a pagePos page and on the same level. @NULL could + be specified for page to create an empty page. + */ + bool InsertPage(size_t pagePos, wxWindow* page, + const wxString& text, + bool bSelect = false, + int imageId = wxNOT_FOUND); + + /** + Inserts a sub page under the specified page. + + @NULL could be specified for page to create an empty page. + */ + bool InsertSubPage(size_t pagePos, wxWindow* page, + const wxString& text, + bool bSelect = false, + int imageId = wxNOT_FOUND); + + /** + Returns @true if the page represented by @a pageId is expanded. + */ + bool IsNodeExpanded(size_t pageId) const; + + /** + Sets the image list for the page control. It does not take ownership of + the image list, you must delete it yourself. + + @see wxImageList, AssignImageList() + */ + void SetImageList(wxImageList* imageList); + + /** + Sets the image index for the given @a page. @a imageId is an index into + the image list which was set with SetImageList(). + */ + bool SetPageImage(size_t page, int imageId); + + /** + Sets the @a text for the given @a page. + */ + bool SetPageText(size_t page, const wxString& text); + + /** + @deprecated Please use ChangeSelection() instead. + + Sets the selection for the given page, returning the previous selection. + + The call to this function generates page changing events. + + @see GetSelection(), ChangeSelection() + */ + int SetSelection(size_t n); +}; + diff --git a/interface/wx/treectrl.h b/interface/wx/treectrl.h new file mode 100644 index 0000000000..782a36837e --- /dev/null +++ b/interface/wx/treectrl.h @@ -0,0 +1,989 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: treectrl.h +// Purpose: interface of wxTreeItemData +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + + +/** + @class wxTreeCtrl + @wxheader{treectrl.h} + + A tree control presents information as a hierarchy, with items that may be + expanded to show further items. Items in a tree control are referenced by + wxTreeItemId handles, which may be tested for validity by calling + wxTreeItemId::IsOk(). + + A similar control with a fully native implemtation for GTK+ and OS X + as well is wxDataViewTreeCtrl. + + To intercept events from a tree control, use the event table macros + described in wxTreeEvent. + + @beginStyleTable + @style{wxTR_EDIT_LABELS} + Use this style if you wish the user to be able to edit labels in the + tree control. + @style{wxTR_NO_BUTTONS} + For convenience to document that no buttons are to be drawn. + @style{wxTR_HAS_BUTTONS} + Use this style to show + and - buttons to the left of parent items. + @style{wxTR_NO_LINES} + Use this style to hide vertical level connectors. + @style{wxTR_FULL_ROW_HIGHLIGHT} + Use this style to have the background colour and the selection highlight + extend over the entire horizontal row of the tree control window. (This + flag is ignored under Windows unless you specify @c wxTR_NO_LINES as + well.) + @style{wxTR_LINES_AT_ROOT} + Use this style to show lines between root nodes. Only applicable if @c + wxTR_HIDE_ROOT is set and @c wxTR_NO_LINES is not set. + @style{wxTR_HIDE_ROOT} + Use this style to suppress the display of the root node, effectively + causing the first-level nodes to appear as a series of root nodes. + @style{wxTR_ROW_LINES} + Use this style to draw a contrasting border between displayed rows. + @style{wxTR_HAS_VARIABLE_ROW_HEIGHT} + Use this style to cause row heights to be just big enough to fit the + content. If not set, all rows use the largest row height. The default is + that this flag is unset. Generic only. + @style{wxTR_SINGLE} + For convenience to document that only one item may be selected at a + time. Selecting another item causes the current selection, if any, to be + deselected. This is the default. + @style{wxTR_MULTIPLE} + Use this style to allow a range of items to be selected. If a second + range is selected, the current range, if any, is deselected. + @style{wxTR_DEFAULT_STYLE} + The set of flags that are closest to the defaults for the native control + for a particular toolkit. + @endStyleTable + + See also @ref overview_windowstyles. + + @b Win32 @b notes: + + wxTreeCtrl class uses the standard common treeview control under Win32 + implemented in the system library comctl32.dll. Some versions of this + library are known to have bugs with handling the tree control colours: the + usual symptom is that the expanded items leave black (or otherwise + incorrectly coloured) background behind them, especially for the controls + using non-default background colour. The recommended solution is to upgrade + the comctl32.dll to a newer version: see + http://www.microsoft.com/downloads/details.aspx?familyid=cb2cf3a2-8025-4e8f-8511-9b476a8d35d2 + + @library{wxcore} + @category{ctrl} + + + @see wxDataViewTreeCtrl, wxTreeEvent, wxTreeItemData, @ref overview_treectrl, wxListBox, + wxListCtrl, wxImageList +*/ +class wxTreeCtrl : public wxControl +{ +public: + /** + Default Constructor. + */ + wxTreeCtrl(); + + /** + Constructor, creating and showing a tree control. + + @param parent + Parent window. Must not be @NULL. + @param id + Window identifier. The value @c wxID_ANY indicates a default value. + @param pos + Window position. + @param size + Window size. If wxDefaultSize is specified then the window is sized + appropriately. + @param style + Window style. See wxTreeCtrl. + @param validator + Window validator. + @param name + Window name. + + @see Create(), wxValidator + */ + wxTreeCtrl(wxWindow* parent, wxWindowID id, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxTR_HAS_BUTTONS, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "treeCtrl"); + + + /** + Destructor, destroying the tree control. + */ + ~wxTreeCtrl(); + + /** + Adds the root node to the tree, returning the new item. + + The @a image and @a selImage parameters are an index within the normal + image list specifying the image to use for unselected and selected + items, respectively. If @a image -1 and @a selImage is -1, the same + image is used for both selected and unselected items. + */ + wxTreeItemId AddRoot(const wxString& text, int image = -1, + int selImage = -1, + wxTreeItemData* data = NULL); + + /** + Appends an item to the end of the branch identified by @a parent, return + a new item id. + + The @a image and @a selImage parameters are an index within the normal + image list specifying the image to use for unselected and selected + items, respectively. If @a image -1 and @a selImage is -1, the same + image is used for both selected and unselected items. + */ + wxTreeItemId AppendItem(const wxTreeItemId& parent, + const wxString& text, + int image = -1, + int selImage = -1, + wxTreeItemData* data = NULL); + + /** + Sets the buttons image list. The button images assigned with this method + will be automatically deleted by wxTreeCtrl as appropriate (i.e. it + takes ownership of the list). + + Setting or assigning the button image list enables the display of image + buttons. Once enabled, the only way to disable the display of button + images is to set the button image list to @NULL. + + This function is only available in the generic version. + + @see SetButtonsImageList(). + */ + void AssignButtonsImageList(wxImageList* imageList); + + /** + Sets the normal image list. The image list assigned with this method + will be automatically deleted by wxTreeCtrl as appropriate (i.e. it + takes ownership of the list). + + @see SetImageList(). + */ + void AssignImageList(wxImageList* imageList); + + /** + Sets the state image list. Image list assigned with this method will be + automatically deleted by wxTreeCtrl as appropriate (i.e. it takes + ownership of the list). + + @see SetStateImageList(). + */ + void AssignStateImageList(wxImageList* imageList); + + /** + Collapses the given item. + */ + void Collapse(const wxTreeItemId& item); + + /** + Collapses the root item. + + @see ExpandAll() + */ + void CollapseAll(); + + /** + Collapses this item and all of its children, recursively. + + @see ExpandAllChildren() + */ + void CollapseAllChildren(const wxTreeItemId& item); + + /** + Collapses the given item and removes all children. + */ + void CollapseAndReset(const wxTreeItemId& item); + + /** + Creates the tree control. See wxTreeCtrl::wxTreeCtrl() for further + details. + */ + bool Create(wxWindow* parent, wxWindowID id, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxTR_HAS_BUTTONS, + const wxValidator& validator = wxDefaultValidator, + const wxString& name = "treeCtrl"); + + /** + Deletes the specified item. A EVT_TREE_DELETE_ITEM() event will be + generated. + + This function may cause a subsequent call to GetNextChild() to fail. + */ + void Delete(const wxTreeItemId& item); + + /** + Deletes all items in the control. Note that this may not generate + EVT_TREE_DELETE_ITEM() events under some Windows versions although + normally such event is generated for each removed item. + */ + void DeleteAllItems(); + + /** + Deletes all children of the given item (but not the item itself). Note + that this will @b not generate any events unlike Delete() method. + + If you have called SetItemHasChildren(), you may need to call it again + since DeleteChildren() does not automatically clear the setting. + */ + void DeleteChildren(const wxTreeItemId& item); + + /** + Starts editing the label of the given @a item. This function generates a + EVT_TREE_BEGIN_LABEL_EDIT() event which can be vetoed so that no text + control will appear for in-place editing. + + If the user changed the label (i.e. s/he does not press ESC or leave the + text control without changes, a EVT_TREE_END_LABEL_EDIT() event will be + sent which can be vetoed as well. + + @see EndEditLabel(), wxTreeEvent + */ + void EditLabel(const wxTreeItemId& item); + + /** + Ends label editing. If @a cancelEdit is @true, the edit will be + cancelled. + + @note + This function is currently supported under Windows only. + + @see EditLabel() + */ + void EndEditLabel(bool cancelEdit); + + /** + Scrolls and/or expands items to ensure that the given item is visible. + */ + void EnsureVisible(const wxTreeItemId& item); + + /** + Expands the given item. + */ + void Expand(const wxTreeItemId& item); + + /** + Expands all items in the tree. + */ + void ExpandAll(); + + /** + Expands the given item and all its children recursively. + */ + void ExpandAllChildren(const wxTreeItemId& item); + + /** + Retrieves the rectangle bounding the @a item. If @a textOnly is @true, + only the rectangle around the item's label will be returned, otherwise + the item's image is also taken into account. + + The return value is @true if the rectangle was successfully retrieved or + @c @false if it was not (in this case @a rect is not changed) -- for + example, if the item is currently invisible. + + Notice that the rectangle coordinates are logical, not physical ones. + So, for example, the x coordinate may be negative if the tree has a + horizontal scrollbar and its position is not 0. + + @beginWxPythonOnly + The wxPython version of this method requires only the @a item and @a + textOnly parameters. The return value is either a wxRect object or @c + None. + @endWxPythonOnly + */ + bool GetBoundingRect(const wxTreeItemId& item, wxRect& rect, + bool textOnly = false) const; + + /** + Returns the buttons image list (from which application-defined button + images are taken). + + This function is only available in the generic version. + */ + wxImageList* GetButtonsImageList() const; + + /** + Returns the number of items in the branch. If @a recursively is @true, + returns the total number of descendants, otherwise only one level of + children is counted. + */ + unsigned int GetChildrenCount(const wxTreeItemId& item, + bool recursively = true) const; + + /** + Returns the number of items in the control. + */ + unsigned int GetCount() const; + + /** + Returns the edit control being currently used to edit a label. Returns + @NULL if no label is being edited. + + @note This is currently only implemented for wxMSW. + */ + wxTextCtrl* GetEditControl() const; + + /** + Returns the first child; call GetNextChild() for the next child. + + For this enumeration function you must pass in a 'cookie' parameter + which is opaque for the application but is necessary for the library to + make these functions reentrant (i.e. allow more than one enumeration on + one and the same object simultaneously). The cookie passed to + GetFirstChild() and GetNextChild() should be the same variable. + + Returns an invalid tree item (i.e. wxTreeItemId::IsOk() returns @false) + if there are no further children. + + @beginWxPythonOnly + In wxPython the returned wxTreeItemId and the new cookie value are both + returned as a tuple containing the two values. + @endWxPythonOnly + + @see GetNextChild(), GetNextSibling() + */ + wxTreeItemId GetFirstChild(const wxTreeItemId& item, + wxTreeItemIdValue& cookie) const; + + /** + Returns the first visible item. + */ + wxTreeItemId GetFirstVisibleItem() const; + + /** + Returns the normal image list. + */ + wxImageList* GetImageList() const; + + /** + Returns the current tree control indentation. + */ + int GetIndent() const; + + /** + Returns the background colour of the item. + */ + wxColour GetItemBackgroundColour(const wxTreeItemId& item) const; + + /** + Returns the tree item data associated with the item. + + @see wxTreeItemData + + @beginWxPythonOnly + wxPython provides the following shortcut method: + @li GetPyData(item): Returns the Python Object associated with the + wxTreeItemData for the given item Id. + @endWxPythonOnly + */ + wxTreeItemData* GetItemData(const wxTreeItemId& item) const; + + /** + Returns the font of the item label. + */ + wxFont GetItemFont(const wxTreeItemId& item) const; + + /** + Gets the specified item image. The value of @a which may be: + - ::wxTreeItemIcon_Normal: to get the normal item image. + - ::wxTreeItemIcon_Selected: to get the selected item image (i.e. the + image which is shown when the item is currently selected). + - ::wxTreeItemIcon_Expanded: to get the expanded image (this only makes + sense for items which have children - then this image is shown when + the item is expanded and the normal image is shown when it is + collapsed). + - ::wxTreeItemIcon_SelectedExpanded: to get the selected expanded image + (which is shown when an expanded item is currently selected). + */ + int GetItemImage(const wxTreeItemId& item, + wxTreeItemIcon which = wxTreeItemIcon_Normal) const; + + /** + Returns the item's parent. + */ + wxTreeItemId GetItemParent(const wxTreeItemId& item) const; + + /** + Gets the selected item image (this function is obsolete, use @ref + GetItemImage() "GetItemImage"( @a item, ::wxTreeItemIcon_Selected) + instead). + */ + int GetItemSelectedImage(const wxTreeItemId& item) const; + + /** + Gets the specified item state. + */ + int GetItemState(const wxTreeItemId& item) const; + + /** + Returns the item label. + */ + wxString GetItemText(const wxTreeItemId& item) const; + + /** + Returns the colour of the item label. + */ + wxColour GetItemTextColour(const wxTreeItemId& item) const; + + /** + Returns the last child of the item (or an invalid tree item if this item + has no children). + + @see GetFirstChild(), GetNextSibling(), GetLastChild() + */ + wxTreeItemId GetLastChild(const wxTreeItemId& item) const; + + /** + Returns the next child; call GetFirstChild() for the first child. For + this enumeration function you must pass in a 'cookie' parameter which is + opaque for the application but is necessary for the library to make + these functions reentrant (i.e. allow more than one enumeration on one + and the same object simultaneously). The cookie passed to + GetFirstChild() and GetNextChild() should be the same. + + Returns an invalid tree item if there are no further children. + + @beginWxPythonOnly + In wxPython the returned wxTreeItemId and the new cookie value are both + returned as a tuple containing the two values. + @endWxPythonOnly + + @see GetFirstChild() + */ + wxTreeItemId GetNextChild(const wxTreeItemId& item, + wxTreeItemIdValue& cookie) const; + + /** + Returns the next sibling of the specified item; call GetPrevSibling() + for the previous sibling. + + Returns an invalid tree item if there are no further siblings. + + @see GetPrevSibling() + */ + wxTreeItemId GetNextSibling(const wxTreeItemId& item) const; + + /** + Returns the next visible item or an invalid item if this item is the + last visible one. + + @note The @a item itself must be visible. + */ + wxTreeItemId GetNextVisible(const wxTreeItemId& item) const; + + /** + Returns the previous sibling of the specified item; call + GetNextSibling() for the next sibling. + + Returns an invalid tree item if there are no further children. + + @see GetNextSibling() + */ + wxTreeItemId GetPrevSibling(const wxTreeItemId& item) const; + + /** + Returns the previous visible item or an invalid item if this item is the + first visible one. + + @note The @a item itself must be visible. + */ + wxTreeItemId GetPrevVisible(const wxTreeItemId& item) const; + + /** + Returns @true if the control will use a quick calculation for the best + size, looking only at the first and last items. The default is @false. + + @see SetQuickBestSize() + */ + bool GetQuickBestSize() const; + + /** + Returns the root item for the tree control. + */ + wxTreeItemId GetRootItem() const; + + /** + Returns the selection, or an invalid item if there is no selection. This + function only works with the controls without @c wxTR_MULTIPLE style, + use GetSelections() for the controls which do have this style. + */ + wxTreeItemId GetSelection() const; + + /** + Fills the array of tree items passed in with the currently selected + items. This function can be called only if the control has the @c + wxTR_MULTIPLE style. + + Returns the number of selected items. + + @beginWxPythonOnly + The wxPython version of this method accepts no parameters and returns a + Python list of @ref wxTreeItemId "wxTreeItemId"s. + @endWxPythonOnly + */ + unsigned int GetSelections(wxArrayTreeItemIds& selection) const; + + /** + Returns the state image list (from which application-defined state + images are taken). + */ + wxImageList* GetStateImageList() const; + + /** + Calculates which (if any) item is under the given @a point, returning + the tree item id at this point plus extra information @a flags. @a flags + is a bitlist of the following: + + - @c wxTREE_HITTEST_ABOVE: Above the client area. + - @c wxTREE_HITTEST_BELOW: Below the client area. + - @c wxTREE_HITTEST_NOWHERE: In the client area but below the last item. + - @c wxTREE_HITTEST_ONITEMBUTTON: On the button associated with an item. + - @c wxTREE_HITTEST_ONITEMICON: On the bitmap associated with an item. + - @c wxTREE_HITTEST_ONITEMINDENT: In the indentation associated with an + item. + - @c wxTREE_HITTEST_ONITEMLABEL: On the label (string) associated with + an item. + - @c wxTREE_HITTEST_ONITEMRIGHT: In the area to the right of an item. + - @c wxTREE_HITTEST_ONITEMSTATEICON: On the state icon for a tree view + item that is in a user-defined state. + - @c wxTREE_HITTEST_TOLEFT: To the right of the client area. + - @c wxTREE_HITTEST_TORIGHT: To the left of the client area. + + @beginWxPythonOnly + In wxPython both the wxTreeItemId and the flags are returned as a tuple. + @endWxPythonOnly + */ + wxTreeItemId HitTest(const wxPoint& point, int& flags) const; + + + /** + Inserts an item after a given one (@a previous). + + The @a image and @a selImage parameters are an index within the normal + image list specifying the image to use for unselected and selected + items, respectively. If @a image -1 and @a selImage is -1, the same + image is used for both selected and unselected items. + */ + wxTreeItemId InsertItem(const wxTreeItemId& parent, + const wxTreeItemId& previous, + const wxString& text, + int image = -1, + int selImage = -1, + wxTreeItemData* data = NULL); + + /** + Inserts an item before one identified + by its position (@a before). @a before must be less than the number of + children. + + The @a image and @a selImage parameters are an index within the normal + image list specifying the image to use for unselected and selected + items, respectively. If @a image -1 and @a selImage is -1, the same + image is used for both selected and unselected items. + + @beginWxPythonOnly + In wxPython, this form of this method is called @c InsertItemBefore(). + @endWxPythonOnly + */ + wxTreeItemId InsertItem(const wxTreeItemId& parent, + size_t before, + const wxString& text, + int image = -1, + int selImage = -1, + wxTreeItemData* data = NULL); + + /** + Returns @true if the given item is in bold state. + + @see SetItemBold() + */ + bool IsBold(const wxTreeItemId& item) const; + + /** + Returns @true if the control is empty (i.e. has no items, even no root + one). + */ + bool IsEmpty() const; + + /** + Returns @true if the item is expanded (only makes sense if it has + children). + */ + bool IsExpanded(const wxTreeItemId& item) const; + + /** + Returns @true if the item is selected. + */ + bool IsSelected(const wxTreeItemId& item) const; + + /** + Returns @true if the item is visible on the screen. + */ + bool IsVisible(const wxTreeItemId& item) const; + + /** + Returns @true if the item has children. + */ + bool ItemHasChildren(const wxTreeItemId& item) const; + + /** + Override this function in the derived class to change the sort order of + the items in the tree control. The function should return a negative, + zero or positive value if the first item is less than, equal to or + greater than the second one. + + Please note that you @b must use wxRTTI macros DECLARE_DYNAMIC_CLASS() + and IMPLEMENT_DYNAMIC_CLASS() if you override this function because + otherwise the base class considers that it is not overridden and uses + the default comparison, i.e. sorts the items alphabetically, which + allows it optimize away the calls to the virtual function completely. + + @see SortChildren() + */ + int OnCompareItems(const wxTreeItemId& item1, + const wxTreeItemId& item2); + + /** + Appends an item as the first child of @a parent, return a new item id. + + The @a image and @a selImage parameters are an index within the normal + image list specifying the image to use for unselected and selected + items, respectively. If @a image -1 and @a selImage is -1, the same + image is used for both selected and unselected items. + */ + wxTreeItemId PrependItem(const wxTreeItemId& parent, + const wxString& text, + int image = -1, + int selImage = -1, + wxTreeItemData* data = NULL); + + /** + Scrolls the specified item into view. + */ + void ScrollTo(const wxTreeItemId& item); + + /** + Selects the given item. In multiple selection controls, can be also used + to deselect a currently selected item if the value of @a select is + @false. + */ + void SelectItem(const wxTreeItemId& item, bool select = true); + + /** + Sets the buttons image list (from which application-defined button + images are taken). + + The button images assigned with this method will @b not be deleted by + @ref wxTreeCtrl "wxTreeCtrl"'s destructor, you must delete it yourself. + Setting or assigning the button image list enables the display of image + buttons. Once enabled, the only way to disable the display of button + images is to set the button image list to @NULL. + + @note This function is only available in the generic version. + + @see AssignButtonsImageList(). + */ + void SetButtonsImageList(wxImageList* imageList); + + /** + Sets the normal image list. The image list assigned with this method + will @b not be deleted by @ref wxTreeCtrl "wxTreeCtrl"'s destructor, you + must delete it yourself. + + @see AssignImageList(). + */ + void SetImageList(wxImageList* imageList); + + /** + Sets the indentation for the tree control. + */ + void SetIndent(int indent); + + /** + Sets the colour of the item's background. + */ + void SetItemBackgroundColour(const wxTreeItemId& item, + const wxColour& col); + + /** + Makes item appear in bold font if @a bold parameter is @true or resets + it to the normal state. + + @see IsBold() + */ + void SetItemBold(const wxTreeItemId& item, bool bold = true); + + /** + Sets the item client data. + + @beginWxPythonOnly + - @b SetPyData( @a item, @c obj): Associate the given Python Object with + the wxTreeItemData for the given item Id. + @endWxPythonOnly + + */ + void SetItemData(const wxTreeItemId& item, wxTreeItemData* data); + + + /** + Gives the item the visual feedback for Drag'n'Drop actions, which is + useful if something is dragged from the outside onto the tree control + (as opposed to a DnD operation within the tree control, which already + is implemented internally). + */ + void SetItemDropHighlight(const wxTreeItemId& item, + bool highlight = true); + + /** + Sets the item's font. All items in the tree should have the same height + to avoid text clipping, so the fonts height should be the same for all + of them, although font attributes may vary. + + @see SetItemBold() + */ + void SetItemFont(const wxTreeItemId& item, const wxFont& font); + + /** + Force appearance of the button next to the item. This is useful to + allow the user to expand the items which don't have any children now, + but instead adding them only when needed, thus minimizing memory + usage and loading time. + */ + void SetItemHasChildren(const wxTreeItemId& item, + bool hasChildren = true); + + /** + Sets the specified item's image. See GetItemImage() for the description + of the @a which parameter. + */ + void SetItemImage(const wxTreeItemId& item, int image, + wxTreeItemIcon which = wxTreeItemIcon_Normal); + + /** + Sets the selected item image (this function is obsolete, use @ref + SetItemImage() "SetItemImage"( @a item, ::wxTreeItemIcon_Selected ) + instead). + */ + void SetItemSelectedImage(const wxTreeItemId& item, int selImage); + + /** + Sets the specified item state. The value of @a state may be: + - @c wxTREE_ITEMSTATE_NONE: to disable the item state (the state image will + be not displayed). + - @c wxTREE_ITEMSTATE_NEXT: to set the next item state. + - @c wxTREE_ITEMSTATE_PREV: to set the previous item state. + */ + void SetItemState(const wxTreeItemId& item, int state); + + /** + Sets the item label. + */ + void SetItemText(const wxTreeItemId& item, const wxString& text); + + /** + Sets the colour of the item's text. + */ + void SetItemTextColour(const wxTreeItemId& item, + const wxColour& col); + + /** + If @true is passed, specifies that the control will use a quick + calculation for the best size, looking only at the first and last items. + Otherwise, it will look at all items. The default is @false. + + @see GetQuickBestSize() + */ + void SetQuickBestSize(bool quickBestSize); + + /** + Sets the state image list (from which application-defined state images + are taken). Image list assigned with this method will @b not be deleted + by @ref wxTreeCtrl "wxTreeCtrl"'s destructor, you must delete it + yourself. + + @see AssignStateImageList(). + */ + void SetStateImageList(wxImageList* imageList); + + /** + Sets the mode flags associated with the display of the tree control. The + new mode takes effect immediately. + + @note Generic only; MSW ignores changes. + */ + void SetWindowStyle(long styles); + + /** + Sorts the children of the given item using OnCompareItems(). + You should override that method to change the sort order (the default is + ascending case-sensitive alphabetical order). + + @see wxTreeItemData, OnCompareItems() + */ + void SortChildren(const wxTreeItemId& item); + + /** + Toggles the given item between collapsed and expanded states. + */ + void Toggle(const wxTreeItemId& item); + + /** + Toggles the given item between selected and unselected states. For + multiselection controls only. + */ + void ToggleItemSelection(const wxTreeItemId& item); + + /** + Removes the selection from the currently selected item (if any). + */ + void Unselect(); + + /** + This function either behaves the same as Unselect() if the control + doesn't have @c wxTR_MULTIPLE style, or removes the selection from all + items if it does have this style. + */ + void UnselectAll(); + + /** + Unselects the given item. This works in multiselection controls only. + */ + void UnselectItem(const wxTreeItemId& item); +}; + + + +/** + @class wxTreeEvent + @wxheader{treectrl.h} + + A tree event holds information about events associated with wxTreeCtrl + objects. + + To process input from a tree control, use these event handler macros to + direct input to member functions that take a wxTreeEvent argument. + + @beginEventTable{wxTreeEvent} + @event{EVT_TREE_BEGIN_DRAG(id, func)} + Begin dragging with the left mouse button. + @event{EVT_TREE_BEGIN_RDRAG(id, func)} + Begin dragging with the right mouse button. + @event{EVT_TREE_END_DRAG(id, func)} + End dragging with the left or right mouse button. + @event{EVT_TREE_BEGIN_LABEL_EDIT(id, func)} + Begin editing a label. This can be prevented by calling Veto(). + @event{EVT_TREE_END_LABEL_EDIT(id, func)} + Finish editing a label. This can be prevented by calling Veto(). + @event{EVT_TREE_DELETE_ITEM(id, func)} + Delete an item. + @event{EVT_TREE_GET_INFO(id, func)} + Request information from the application. + @event{EVT_TREE_SET_INFO(id, func)} + Information is being supplied. + @event{EVT_TREE_ITEM_ACTIVATED(id, func)} + The item has been activated, i.e. chosen by double clicking it with + mouse or from keyboard. + @event{EVT_TREE_ITEM_COLLAPSED(id, func)} + The item has been collapsed. + @event{EVT_TREE_ITEM_COLLAPSING(id, func)} + The item is being collapsed. This can be prevented by calling Veto(). + @event{EVT_TREE_ITEM_EXPANDED(id, func)} + The item has been expanded. + @event{EVT_TREE_ITEM_EXPANDING(id, func)} + The item is being expanded. This can be prevented by calling Veto(). + @event{EVT_TREE_ITEM_RIGHT_CLICK(id, func)} + The user has clicked the item with the right mouse button. + @event{EVT_TREE_ITEM_MIDDLE_CLICK(id, func)} + The user has clicked the item with the middle mouse button. + @event{EVT_TREE_SEL_CHANGED(id, func)} + Selection has changed. + @event{EVT_TREE_SEL_CHANGING(id, func)} + Selection is changing. This can be prevented by calling Veto(). + @event{EVT_TREE_KEY_DOWN(id, func)} + A key has been pressed. + @event{EVT_TREE_ITEM_GETTOOLTIP(id, func)} + The opportunity to set the item tooltip is being given to the + application (call SetToolTip()). Windows only. + @event{EVT_TREE_ITEM_MENU(id, func)} + The context menu for the selected item has been requested, either by a + right click or by using the menu key. + @event{EVT_TREE_STATE_IMAGE_CLICK(id, func)} + The state image has been clicked. + @endEventTable + + @library{wxbase} + @category{events} + + @see wxTreeCtrl +*/ +class wxTreeEvent : public wxNotifyEvent +{ +public: + /** + Constructor, used by wxWidgets itself only. + */ + wxTreeEvent(wxEventType commandType, wxTreeCtrl* tree); + + /** + Returns the item (valid for all events). + */ + wxTreeItemId GetItem() const; + + /** + Returns the key code if the event is a key event. Use GetKeyEvent() to + get the values of the modifier keys for this event (i.e. Shift or Ctrl). + */ + int GetKeyCode() const; + + /** + Returns the key event for EVT_TREE_KEY_DOWN() events. + */ + const wxKeyEvent GetKeyEvent() const; + + /** + Returns the label if the event is a begin or end edit label event. + */ + const wxString GetLabel() const; + + /** + Returns the old item index (valid for EVT_TREE_ITEM_CHANGING() and + EVT_TREE_ITEM_CHANGED() events). + */ + wxTreeItemId GetOldItem() const; + + /** + Returns the position of the mouse pointer if the event is a drag or + menu-context event. + + In both cases the position is in client coordinates - i.e. relative to + the wxTreeCtrl window (so that you can pass it directly to e.g. + wxWindow::PopupMenu()). + */ + wxPoint GetPoint() const; + + /** + Returns @true if the label edit was cancelled. This should be called + from within an EVT_TREE_END_LABEL_EDIT() handler. + */ + bool IsEditCancelled() const; + + /** + Set the tooltip for the item (valid for EVT_TREE_ITEM_GETTOOLTIP() + events). Windows only. + */ + void SetToolTip(const wxString& tooltip); +}; diff --git a/interface/wx/txtstrm.h b/interface/wx/txtstrm.h new file mode 100644 index 0000000000..89dd37741a --- /dev/null +++ b/interface/wx/txtstrm.h @@ -0,0 +1,302 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: txtstrm.h +// Purpose: interface of wxTextInputStream +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + + + +/** + @class wxTextInputStream + @wxheader{txtstrm.h} + + This class provides functions that reads text data using an input stream, + allowing you to read text, floats, and integers. + + The wxTextInputStream correctly reads text files (or streams) in DOS, + Macintosh and Unix formats and reports a single newline char as a line + ending. + + wxTextInputStream::operator>>() is overloaded and you can use this class + like a standard C++ iostream. Note, however, that the arguments are the + fixed size types wxUint32, wxInt32 etc and on a typical 32-bit computer, + none of these match to the "long" type (wxInt32 is defined as int on 32-bit + architectures) so that you cannot use long. To avoid problems (here and + elsewhere), make use of wxInt32, wxUint32 and similar types. + + If you're scanning through a file using wxTextInputStream, you should check + for @c EOF @b before reading the next item (word / number), because + otherwise the last item may get lost. You should however be prepared to + receive an empty item (empty string / zero number) at the end of file, + especially on Windows systems. This is unavoidable because most (but not + all) files end with whitespace (i.e. usually a newline). + + For example: + + @code + wxFileInputStream input( "mytext.txt" ); + wxTextInputStream text( input ); + wxUint8 i1; + float f2; + wxString line; + + text >> i1; // read a 8 bit integer. + text >> i1 >> f2; // read a 8 bit integer followed by float. + text >> line; // read a text line + @endcode + + @library{wxbase} + @category{streams} + + @see wxTextOutputStream +*/ +class wxTextInputStream +{ +public: + /** + Constructs a text stream associated to the given input stream. + + @param stream + The underlying input stream. + @param sep + The initial string separator characters. + @param conv + In Unicode build only: The encoding converter used to + convert the bytes in the underlying input stream to characters. + */ + wxTextInputStream(wxInputStream& stream, + const wxString& sep = " \t", + const wxMBConv& conv = wxConvAuto()); + + /** + Destructor. + */ + ~wxTextInputStream(); + + /** + Reads a character, returns 0 if there are no more characters in the + stream. + */ + wxChar GetChar(); + + /** + Reads a unsigned 16 bit integer from the stream. + + See Read8() for the description of the @a base parameter. + */ + wxUint16 Read16(int base = 10); + + /** + Reads a signed 16 bit integer from the stream. + + See Read8() for the description of the @a base parameter. + */ + wxInt16 Read16S(int base = 10); + + /** + Reads a 32 bit unsigned integer from the stream. + + See Read8() for the description of the @a base parameter. + */ + wxUint32 Read32(int base = 10); + + /** + Reads a 32 bit signed integer from the stream. + + See Read8() for the description of the @a base parameter. + */ + wxInt32 Read32S(int base = 10); + + /** + Reads a single unsigned byte from the stream, given in base @a base. + + The value of @a base must be comprised between 2 and 36, inclusive, or + be a special value 0 which means that the usual rules of C numbers are + applied: if the number starts with @c 0x it is considered to be in base + 16, if it starts with 0 - in base 8 and in base 10 otherwise. Note that + you may not want to specify the base 0 if you are parsing the numbers + which may have leading zeroes as they can yield unexpected (to the user + not familiar with C) results. + */ + wxUint8 Read8(int base = 10); + + /** + Reads a single signed byte from the stream. + + See Read8() for the description of the @a base parameter. + */ + wxInt8 Read8S(int base = 10); + + /** + Reads a double (IEEE encoded) from the stream. + */ + double ReadDouble(); + + /** + Reads a line from the input stream and returns it (without the end of + line character). + */ + wxString ReadLine(); + + /** + @deprecated Use ReadLine() or ReadWord() instead. + + Same as ReadLine(). + */ + wxString ReadString(); + + /** + Reads a word (a sequence of characters until the next separator) from + the input stream. + + @see SetStringSeparators() + */ + wxString ReadWord(); + + /** + Sets the characters which are used to define the word boundaries in + ReadWord(). + + The default separators are the @c space and @c TAB characters. + */ + void SetStringSeparators(const wxString& sep); +}; + + +/** + Specifies the end-of-line characters to use with wxTextOutputStream. +*/ +typedef enum +{ + /** + Specifies wxTextOutputStream to use the native end-of-line characters. + */ + wxEOL_NATIVE, + + /** + Specifies wxTextOutputStream to use Unix end-of-line characters. + */ + wxEOL_UNIX, + + /** + Specifies wxTextOutputStream to use Mac end-of-line characters. + */ + wxEOL_MAC, + + /** + Specifies wxTextOutputStream to use DOS end-of-line characters. + */ + wxEOL_DOS +} wxEOL; + + +/** + @class wxTextOutputStream + @wxheader{txtstrm.h} + + This class provides functions that write text data using an output stream, + allowing you to write text, floats, and integers. + + You can also simulate the C++ @c std::cout class: + + @code + wxFFileOutputStream output( stderr ); + wxTextOutputStream cout( output ); + + cout << "This is a text line" << endl; + cout << 1234; + cout << 1.23456; + @endcode + + The wxTextOutputStream writes text files (or streams) on DOS, Macintosh and + Unix in their native formats (concerning the line ending). + + @library{wxbase} + @category{streams} + + @see wxTextInputStream +*/ +class wxTextOutputStream +{ +public: + /** + Constructs a text stream object associated to the given output stream. + + @param stream + The output stream. + @param mode + The end-of-line mode. One of ::wxEOL_NATIVE, ::wxEOL_DOS, + ::wxEOL_MAC and ::wxEOL_UNIX. + @param conv + In Unicode build only: The object used to convert + Unicode text into ASCII characters written to the output stream. + */ + wxTextOutputStream(wxOutputStream& stream, + wxEOL mode = wxEOL_NATIVE, + const wxMBConv& conv = wxConvAuto()); + + /** + Destroys the wxTextOutputStream object. + + Also calls Flush(). + */ + ~wxTextOutputStream(); + + /** + Flushes the stream. + + This method should be called when using stateful encodings (currently + the only example of such encoding in wxWidgets is wxMBConvUTF7) to + write the end of the encoded data to the stream. + + @since 2.9.0 + */ + void Flush(); + + /** + Returns the end-of-line mode. One of ::wxEOL_DOS, ::wxEOL_MAC and + ::wxEOL_UNIX. + */ + wxEOL GetMode(); + + /** + Writes a character to the stream. + */ + void PutChar(wxChar c); + + /** + Set the end-of-line mode. One of ::wxEOL_NATIVE, ::wxEOL_DOS, + ::wxEOL_MAC and ::wxEOL_UNIX. + */ + void SetMode(wxEOL mode = wxEOL_NATIVE); + + /** + Writes the 16 bit integer @a i16 to the stream. + */ + void Write16(wxUint16 i16); + + /** + Writes the 32 bit integer @a i32 to the stream. + */ + void Write32(wxUint32 i32); + + /** + Writes the single byte @a i8 to the stream. + */ + void Write8(wxUint8 i8); + + /** + Writes the double @a f to the stream using the IEEE format. + */ + virtual void WriteDouble(double f); + + /** + Writes @a string as a line. Depending on the end-of-line mode the end of + line ('\\n') characters in the string are converted to the correct line + ending terminator. + */ + virtual void WriteString(const wxString& string); +}; + diff --git a/interface/wx/uri.h b/interface/wx/uri.h new file mode 100644 index 0000000000..4c36e39445 --- /dev/null +++ b/interface/wx/uri.h @@ -0,0 +1,299 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: uri.h +// Purpose: interface of wxURI +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + Host type of URI returned from wxURI::GetHostType(). +*/ +enum wxURIHostType +{ + wxURI_REGNAME, ///< Host is a normal register name (@c "www.mysite.com"). + wxURI_IPV4ADDRESS, ///< Host is a version 4 ip address (@c "192.168.1.100"). + wxURI_IPV6ADDRESS, ///< Host is a version 6 ip address (@c "[aa:aa:aa:aa::aa:aa]:5050"). + wxURI_IPVFUTURE ///< Host is a future ip address, wxURI is unsure what kind. +}; + +/** + @class wxURI + @wxheader{uri.h} + + wxURI is used to extract information from a URI (Uniform Resource + Identifier). + + For information about URIs, see RFC 3986 + . + + In short, a URL is a URI. In other words, URL is a subset of a URI - all + acceptable URLs are also acceptable URIs. + + wxURI automatically escapes invalid characters in a string, so there is no + chance of wxURI "failing" on construction/creation. + + wxURI supports copy construction and standard assignment operators. wxURI + can also be inherited from to provide furthur functionality. + + To obtain individual components you can use one of the GetXXX() methods. + However, you should check HasXXX() before calling a get method, which + determines whether or not the component referred to by the method is + defined according to RFC 2396. Consider an undefined component equivalent + to a @NULL C string. + + Example: + + @code + //protocol will hold the http protocol (i.e. "http") + wxString protocol; + wxURI myuri("http://mysite.com"); + if( myuri.HasScheme() ) + protocol = myuri.GetScheme(); + @endcode + + @note On URIs with a "file" scheme wxURI does not parse the userinfo, + server, or port portion. This is to keep compatability with + wxFileSystem, the old wxURL, and older url specifications. + + @library{wxbase} + @category{data} + + @see wxURL +*/ +class wxURI : public wxObject +{ +public: + /** + Creates an empty URI. + */ + wxURI(); + /** + Constructor for quick creation. + + @param uri + URI (Uniform Resource Identifier) to initialize with. + */ + wxURI(const wxChar* uri); + /** + Copies this URI from another URI. + + @param uri + URI (Uniform Resource Identifier) to initialize with. + */ + wxURI(const wxURI& uri); + + /** + Builds the URI from its individual components and adds proper + separators. + + If the URI is not a reference or is not resolved, the URI that is + returned is the same one passed to the constructor or Create(). + */ + wxString BuildURI() const; + + /** + Builds the URI from its individual components, adds proper separators, + and returns escape sequences to normal characters. + + @note It is preferred to call this over Unescape(BuildURI()) since + BuildUnescapedURI() performs some optimizations over the plain + method. + */ + wxString BuildUnescapedURI() const; + + /** + Creates this URI from the @a uri string. + + Returns the position at which parsing stopped (there is no such thing + as an "invalid" wxURI). + + @param uri + String to initialize from. + */ + const wxChar* Create(const wxString uri); + + /** + Obtains the fragment of this URI. + + The fragment of a URI is the last value of the URI, and is the value + after a "#" character after the path of the URI. + + @c "http://mysite.com/mypath#" + */ + const wxString& GetFragment() const; + + /** + Obtains the host type of this URI, which is one of wxURIHostType. + */ + const wxURIHostType& GetHostType() const; + + /** + Returns the password part of the userinfo component of this URI. Note + that this is explicitly depreciated by RFC 1396 and should generally be + avoided if possible. + + @c "http://:@mysite.com/mypath" + */ + const wxString& GetPassword() const; + + /** + Returns the (normalized) path of the URI. + + The path component of a URI comes directly after the scheme component + if followed by zero or one slashes ('/'), or after the server/port + component. + + Absolute paths include the leading '/' character. + + @c "http://mysite.com" + */ + const wxString& GetPath() const; + + /** + Returns a string representation of the URI's port. + + The Port of a URI is a value after the server, and must come after a + colon (:). + + @c "http://mysite.com:" + + @note You can easily get the numeric value of the port by using + wxAtoi() or wxString::Format(). + */ + const wxString& GetPort() const; + + /** + Returns the Query component of the URI. + + The query component is what is commonly passed to a cgi application, + and must come after the path component, and after a '?' character. + + @c "http://mysite.com/mypath?" + */ + const wxString& GetQuery() const; + + /** + Returns the Scheme component of the URI. + + The first part of the URI. + + @c "://mysite.com" + */ + const wxString& GetScheme() const; + + /** + Returns the Server component of the URI. + + The server of the URI can be a server name or a type of IP address. See + GetHostType() for the possible values for the host type of the server + component. + + @c "http:///mypath" + */ + const wxString& GetServer() const; + + /** + Returns the username part of the userinfo component of this URI. Note + that this is explicitly depreciated by RFC 1396 and should generally be + avoided if possible. + + @c "http://:@mysite.com/mypath" + */ + const wxString& GetUser() const; + + /** + Returns the UserInfo component of the URI. + + The component of a URI before the server component that is postfixed by + a '@' character. + + @c "http://@mysite.com/mypath" + */ + const wxString& GetUserInfo() const; + + /** + Returns @true if the Fragment component of the URI exists. + */ + bool HasFragment() const; + + /** + Returns @true if the Path component of the URI exists. + */ + bool HasPath() const; + + /** + Returns @true if the Port component of the URI exists. + */ + bool HasPort() const; + + /** + Returns @true if the Query component of the URI exists. + */ + bool HasQuery() const; + + /** + Returns @true if the Scheme component of the URI exists. + */ + bool HasScheme() const; + + /** + Returns @true if the Server component of the URI exists. + */ + bool HasServer() const; + + /** + Returns @true if the User component of the URI exists. + */ + bool HasUser() const; + + /** + Returns @true if a valid [absolute] URI, otherwise this URI is a URI + reference and not a full URI, and this function returns @false. + */ + bool IsReference() const; + + /** + Inherits this URI from a base URI - components that do not exist in + this URI are copied from the base, and if this URI's path is not an + absolute path (prefixed by a '/'), then this URI's path is merged with + the base's path. + + For instance, resolving "../mydir" from "http://mysite.com/john/doe" + results in the scheme (http) and server ("mysite.com") being copied + into this URI, since they do not exist. In addition, since the path of + this URI is not absolute (does not begin with '/'), the path of the + base's is merged with this URI's path, resulting in the URI + "http://mysite.com/john/mydir". + + @param base + Base URI to inherit from. Must be a full URI and not a reference. + @param flags + Currently either wxURI_STRICT or 0, in non-strict mode some + compatibility layers are enabled to allow loopholes from RFCs prior + to 2396. + */ + void Resolve(const wxURI& base, int flags = wxURI_STRICT); + + /** + Translates all escape sequences (normal characters and returns the + result. + + If you want to unescape an entire wxURI, use BuildUnescapedURI() + instead, as it performs some optimizations over this method. + + @param uri + String with escaped characters to convert. + */ + wxString Unescape(const wxString& uri); + + /** + Compares this URI to another URI, and returns @true if this URI equals + @a uricomp, otherwise it returns @false. + + @param uricomp + URI to compare to. + */ + void operator ==(const wxURI& uricomp); +}; + diff --git a/interface/wx/url.h b/interface/wx/url.h new file mode 100644 index 0000000000..3d7eea0c99 --- /dev/null +++ b/interface/wx/url.h @@ -0,0 +1,130 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: url.h +// Purpose: interface of wxURL +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + Error types returned from wxURL::GetError(). +*/ +typedef enum { + wxURL_NOERR = 0, ///< No error. + wxURL_SNTXERR, ///< Syntax error in the URL string. + wxURL_NOPROTO, ///< Found no protocol which can get this URL. + wxURL_NOHOST, ///< A host name is required for this protocol. + wxURL_NOPATH, ///< A path is required for this protocol. + wxURL_CONNERR, ///< Connection error. + wxURL_PROTOERR ///< An error occurred during negotiation. +} wxURLError; + +/** + @class wxURL + @wxheader{url.h} + + wxURL is a specialization of wxURI for parsing URLs. Please look at wxURI + documentation for more info about the functions you can use to retrieve the + various parts of the URL (scheme, server, port, etc). + + Supports standard assignment operators, copy constructors, and comparison + operators. + + @library{wxnet} + @category{net} + + @see wxSocketBase, wxProtocol +*/ +class wxURL : public wxURI +{ +public: + /** + Constructs a URL object from the string. The URL must be valid + according to RFC 1738. In particular, file URLs must be of the format + @c "file://hostname/path/to/file", otherwise GetError() will return a + value different from ::wxURL_NOERR. + + It is valid to leave out the hostname but slashes must remain in place, + in other words, a file URL without a hostname must contain three + consecutive slashes (e.g. @c "file:///somepath/myfile"). + + @param url + Url string to parse. + */ + wxURL(const wxString& url = wxEmptyString); + + /** + Destroys the URL object. + */ + ~wxURL(); + + /** + Returns the last error. This error refers to the URL parsing or to the + protocol. It can be one of ::wxURLError. + */ + wxURLError GetError() const; + + /** + Creates a new input stream on the specified URL. You can use all but + seek functionality of wxStream. Seek isn't available on all streams. + For example, HTTP or FTP streams don't deal with it. + + Note that this method is somewhat deprecated, all future wxWidgets + applications should use wxFileSystem instead. + + Example: + + @code + wxURL url("http://a.host/a.dir/a.file"); + if (url.GetError() == wxURL_NOERR) + { + wxInputStream *in_stream; + + in_stream = url.GetInputStream(); + // Then, you can use all IO calls of in_stream (See wxStream) + } + @endcode + + @return Returns the initialized stream. You will have to delete it + yourself. + + @see wxInputStream + */ + wxInputStream* GetInputStream(); + + /** + Returns a reference to the protocol which will be used to get the URL. + */ + wxProtocol GetProtocol(); + + /** + Returns @true if this object is correctly initialized, i.e. if + GetError() returns ::wxURL_NOERR. + */ + bool IsOk() const; + + /** + Sets the default proxy server to use to get the URL. The string + specifies the proxy like this: @c ":". + + @param url_proxy + Specifies the proxy to use. + + @see SetProxy() + */ + static void SetDefaultProxy(const wxString& url_proxy); + + /** + Sets the proxy to use for this URL. + + @see SetDefaultProxy() + */ + void SetProxy(const wxString& url_proxy); + + /** + Initializes this object with the given URL and returns ::wxURL_NOERR if + it's valid (see GetError() for more info). + */ + wxURLError SetURL(const wxString& url); +}; + diff --git a/interface/wx/utils.h b/interface/wx/utils.h new file mode 100644 index 0000000000..41ca90a8b4 --- /dev/null +++ b/interface/wx/utils.h @@ -0,0 +1,1012 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: utils.h +// Purpose: interface of various utility classes and functions +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxWindowDisabler + @wxheader{utils.h} + + This class disables all windows of the application (may be with the + exception of one of them) in its constructor and enables them back in its + destructor. + + This is useful when you want to indicate to the user that the application + is currently busy and cannot respond to user input. + + @library{wxcore} + @category{misc} + + @see wxBusyCursor +*/ +class wxWindowDisabler +{ +public: + /** + Disables all top level windows of the applications. + + If @a disable is @c false nothing is done. This can be convenient if + the windows should be disabled depending on some condition. + + @since 2.9.0 + */ + wxWindowDisabler(bool disable = true); + + /** + Disables all top level windows of the applications with the exception + of @a winToSkip if it is not @NULL. + */ + wxWindowDisabler(wxWindow* winToSkip); + + /** + Reenables the windows disabled by the constructor. + */ + ~wxWindowDisabler(); +}; + + + +/** + @class wxBusyCursor + @wxheader{utils.h} + + This class makes it easy to tell your user that the program is temporarily + busy. Just create a wxBusyCursor object on the stack, and within the + current scope, the hourglass will be shown. + + For example: + + @code + wxBusyCursor wait; + + for (int i = 0; i < 100000; i++) + DoACalculation(); + @endcode + + It works by calling wxBeginBusyCursor() in the constructor, and + wxEndBusyCursor() in the destructor. + + @library{wxcore} + @category{misc} + + @see wxBeginBusyCursor(), wxEndBusyCursor(), wxWindowDisabler +*/ +class wxBusyCursor +{ +public: + /** + Constructs a busy cursor object, calling wxBeginBusyCursor(). + */ + wxBusyCursor(wxCursor* cursor = wxHOURGLASS_CURSOR); + + /** + Destroys the busy cursor object, calling wxEndBusyCursor(). + */ + ~wxBusyCursor(); +}; + + + +/** + @class wxMouseState + @wxheader{utils.h} + + Represents the mouse state. + + The methods of this class generally mirror the corresponding methods of + wxMouseEvent. + + This class is implemented entirely in @, meaning no extra + library needs to be linked to use this class. + + @category{misc} + + @see wxGetMouseState() + */ +class wxMouseState +{ +public: + /** + Default constructor. + */ + wxMouseState(); + + /** + Returns X coordinate of the physical mouse event position. + */ + wxCoord GetX() const; + /** + Returns Y coordinate of the physical mouse event position. + */ + wxCoord GetY() const; + /** + Returns the physical mouse position. + */ + wxPoint GetPosition() const; + + /** + Returns @true if the left mouse button changed to down. + */ + bool LeftDown() const; + /** + Returns @true if the middle mouse button changed to down. + */ + bool MiddleDown() const; + /** + Returns @true if the right mouse button changed to down. + */ + bool RightDown() const; + /** + Returns @true if the first extra button mouse button changed to down. + */ + bool Aux1Down() const; + /** + Returns @true if the second extra button mouse button changed to down. + */ + bool Aux2Down() const; + + /** + Returns @true if the control key is down. + */ + bool ControlDown() const; + /** + Returns @true if the shift key is down. + */ + bool ShiftDown() const; + /** + Returns @true if the alt key is down. + */ + bool AltDown() const; + /** + Returns @true if the meta key is down. + */ + bool MetaDown() const; + /** + Same as MetaDown() under Mac systems, ControlDown() for the others. + */ + bool CmdDown() const; +}; + + +// ============================================================================ +// Global functions/macros +// ============================================================================ + + +/** @ingroup group_funcmacro_dialog */ +//@{ + +/** + Changes the cursor to the given cursor for all windows in the application. + Use wxEndBusyCursor() to revert the cursor back to its previous state. + These two calls can be nested, and a counter ensures that only the outer + calls take effect. + + @see wxIsBusy(), wxBusyCursor + + @header{wx/utils.h} +*/ +void wxBeginBusyCursor(wxCursor* cursor = wxHOURGLASS_CURSOR); + +/** + Changes the cursor back to the original cursor, for all windows in the + application. Use with wxBeginBusyCursor(). + + @see wxIsBusy(), wxBusyCursor + + @header{wx/utils.h} +*/ +void wxEndBusyCursor(); + +/** + Returns @true if between two wxBeginBusyCursor() and wxEndBusyCursor() + calls. + + @see wxBusyCursor. + + @header{wx/utils.h} +*/ +bool wxIsBusy(); + +/** + Ring the system bell. + + @note This function is categorized as a GUI one and so is not thread-safe. + + @header{wx/utils.h} +*/ +void wxBell(); + +/** + Shows a message box with the information about the wxWidgets build used, + including its version, most important build parameters and the version of + the underlying GUI toolkit. This is mainly used for diagnostic purposes + and can be invoked by Ctrl-Alt-middle clicking on any wxWindow which + doesn't otherwise handle this event. + + @since 2.9.0 + + @header{wx/utils.h} +*/ +void wxInfoMessageBox(wxWindow parent = NULL); + +//@} + + + +/** @ingroup group_funcmacro_env */ +//@{ + +/** + This is a macro defined as @c getenv() or its wide char version in Unicode + mode. + + Note that under Win32 it may not return correct value for the variables set + with wxSetEnv(), use wxGetEnv() function instead. + + @header{wx/utils.h} +*/ +wxChar* wxGetenv(const wxString& var); + +/** + Returns the current value of the environment variable @c var in @c value. + @c value may be @NULL if you just want to know if the variable exists and + are not interested in its value. + + Returns @true if the variable exists, @false otherwise. + + @header{wx/utils.h} +*/ +bool wxGetEnv(const wxString& var, wxString* value); + +/** + Sets the value of the environment variable @c var (adding it if necessary) + to @c value. + + Returns @true on success. + + @see wxUnsetEnv() + + @header{wx/utils.h} +*/ +bool wxSetEnv(const wxString& var, const wxString& value); + +/** + Removes the variable @c var from the environment. wxGetEnv() will return + @NULL after the call to this function. + + Returns @true on success. + + @header{wx/utils.h} +*/ +bool wxUnsetEnv(const wxString& var); + +//@} + + + +/** @ingroup group_funcmacro_misc */ +//@{ + +/** + Returns battery state as one of @c wxBATTERY_NORMAL_STATE, + @c wxBATTERY_LOW_STATE, @c wxBATTERY_CRITICAL_STATE, + @c wxBATTERY_SHUTDOWN_STATE or @c wxBATTERY_UNKNOWN_STATE. + @c wxBATTERY_UNKNOWN_STATE is also the default on platforms where this + feature is not implemented (currently everywhere but MS Windows). + + @header{wx/utils.h} +*/ +wxBatteryState wxGetBatteryState(); + +/** + Returns the type of power source as one of @c wxPOWER_SOCKET, + @c wxPOWER_BATTERY or @c wxPOWER_UNKNOWN. @c wxPOWER_UNKNOWN is also the + default on platforms where this feature is not implemented (currently + everywhere but MS Windows). + + @header{wx/utils.h} +*/ +wxPowerType wxGetPowerType(); + +/** + Under X only, returns the current display name. + + @see wxSetDisplayName() + + @header{wx/utils.h} +*/ +wxString wxGetDisplayName(); + +/** + For normal keys, returns @true if the specified key is currently down. + + For togglable keys (Caps Lock, Num Lock and Scroll Lock), returns @true if + the key is toggled such that its LED indicator is lit. There is currently + no way to test whether togglable keys are up or down. + + Even though there are virtual key codes defined for mouse buttons, they + cannot be used with this function currently. + + @header{wx/utils.h} +*/ +bool wxGetKeyState(wxKeyCode key); + +/** + Returns the mouse position in screen coordinates. + + @header{wx/utils.h} +*/ +wxPoint wxGetMousePosition(); + +/** + Returns the current state of the mouse. Returns a wxMouseState instance + that contains the current position of the mouse pointer in screen + coordinates, as well as boolean values indicating the up/down status of the + mouse buttons and the modifier keys. + + @header{wx/utils.h} +*/ +wxMouseState wxGetMouseState(); + +/** + This function enables or disables all top level windows. It is used by + wxSafeYield(). + + @header{wx/utils.h} +*/ +void wxEnableTopLevelWindows(bool enable = true); + +/** + Find the deepest window at the given mouse position in screen coordinates, + returning the window if found, or @NULL if not. + + @header{wx/utils.h} +*/ +wxWindow* wxFindWindowAtPoint(const wxPoint& pt); + +/** + @deprecated Replaced by wxWindow::FindWindowByLabel(). + + Find a window by its label. Depending on the type of window, the label may + be a window title or panel item label. If @a parent is @NULL, the search + will start from all top-level frames and dialog boxes; if non-@NULL, the + search will be limited to the given window hierarchy. The search is + recursive in both cases. + + @header{wx/utils.h} +*/ +wxWindow* wxFindWindowByLabel(const wxString& label, + wxWindow* parent = NULL); + +/** + @deprecated Replaced by wxWindow::FindWindowByName(). + + Find a window by its name (as given in a window constructor or @e Create + function call). If @a parent is @NULL, the search will start from all + top-level frames and dialog boxes; if non-@NULL, the search will be limited + to the given window hierarchy. The search is recursive in both cases. + + If no such named window is found, wxFindWindowByLabel() is called. + + @header{wx/utils.h} +*/ +wxWindow* wxFindWindowByName(const wxString& name, wxWindow* parent = NULL); + +/** + Find a menu item identifier associated with the given frame's menu bar. + + @header{wx/utils.h} +*/ +int wxFindMenuItemId(wxFrame* frame, const wxString& menuString, + const wxString& itemString); + +/** + @deprecated Ids generated by it can conflict with the Ids defined by the + user code, use @c wxID_ANY to assign ids which are guaranteed + to not conflict with the user-defined ids for the controls and + menu items you create instead of using this function. + + Generates an integer identifier unique to this run of the program. + + @header{wx/utils.h} +*/ +long wxNewId(); + +/** + Ensures that Ids subsequently generated by wxNewId() do not clash with the + given @a id. + + @header{wx/utils.h} +*/ +void wxRegisterId(long id); + +/** + Opens the @a url in user's default browser. If the @a flags parameter + contains @c wxBROWSER_NEW_WINDOW flag, a new window is opened for the URL + (currently this is only supported under Windows). The @a url may also be a + local file path (with or without the "file://" prefix), if it doesn't + correspond to an existing file and the URL has no scheme "http://" is + prepended to it by default. + + Returns @true if the application was successfully launched. + + @note For some configurations of the running user, the application which is + launched to open the given URL may be URL-dependent (e.g. a browser + may be used for local URLs while another one may be used for remote + URLs). + + @header{wx/utils.h} +*/ +bool wxLaunchDefaultBrowser(const wxString& url, int flags = 0); + +/** + Loads a user-defined Windows resource as a string. If the resource is + found, the function creates a new character array and copies the data into + it. A pointer to this data is returned. If unsuccessful, @NULL is returned. + + The resource must be defined in the @c .rc file using the following syntax: + + @code + myResource TEXT file.ext + @endcode + + Where @c file.ext is a file that the resource compiler can find. + + This function is available under Windows only. + + @header{wx/utils.h} +*/ +wxString wxLoadUserResource(const wxString& resourceName, + const wxString& resourceType = "TEXT"); + +/** + @deprecated Replaced by wxWindow::Close(). See the + @ref overview_windowdeletion "window deletion overview". + + Tells the system to delete the specified object when all other events have + been processed. In some environments, it is necessary to use this instead + of deleting a frame directly with the delete operator, because some GUIs + will still send events to a deleted window. + + @header{wx/utils.h} +*/ +void wxPostDelete(wxObject* object); + +/** + Under X only, sets the current display name. This is the X host and display + name such as "colonsay:0.0", and the function indicates which display + should be used for creating windows from this point on. Setting the display + within an application allows multiple displays to be used. + + @see wxGetDisplayName() + + @header{wx/utils.h} +*/ +void wxSetDisplayName(const wxString& displayName); + +/** + Strips any menu codes from @a str and returns the result. + + By default, the functions strips both the mnemonics character (@c '&') + which is used to indicate a keyboard shortkey, and the accelerators, which + are used only in the menu items and are separated from the main text by the + @c \t (TAB) character. By using @a flags of @c wxStrip_Mnemonics or + @c wxStrip_Accel to strip only the former or the latter part, respectively. + + Notice that in most cases wxMenuItem::GetLabelFromText() or + wxControl::GetLabelText() can be used instead. + + @header{wx/utils.h} +*/ +wxString wxStripMenuCodes(const wxString& str, int flags = wxStrip_All); + +//@} + + + +/** @ingroup group_funcmacro_networkuseros */ +//@{ + +/** + Copies the user's email address into the supplied buffer, by concatenating + the values returned by wxGetFullHostName() and wxGetUserId(). + + @return @true if successful, @false otherwise. + + @header{wx/utils.h} +*/ +wxString wxGetEmailAddress(); + +/** + @deprecated Use wxGetEmailAddress() instead. + + @param buf Buffer to store the email address in. + @param sz Size of the buffer. + + @return @true if successful, @false otherwise. + + @header{wx/utils.h} +*/ +bool wxGetEmailAddress(char* buf, int sz); + +/** + Returns the amount of free memory in bytes under environments which support + it, and -1 if not supported or failed to perform measurement. + + @header{wx/utils.h} +*/ +wxMemorySize wxGetFreeMemory(); + +/** + Return the (current) user's home directory. + + @see wxGetUserHome(), wxStandardPaths + + @header{wx/utils.h} +*/ +wxString wxGetHomeDir(); + +/** + Copies the current host machine's name into the supplied buffer. Please + note that the returned name is @e not fully qualified, i.e. it does not + include the domain name. + + Under Windows or NT, this function first looks in the environment variable + SYSTEM_NAME; if this is not found, the entry @b HostName in the wxWidgets + section of the WIN.INI file is tried. + + @return The hostname if successful or an empty string otherwise. + + @see wxGetFullHostName() + + @header{wx/utils.h} +*/ +wxString wxGetHostName(); + +/** + @deprecated Use wxGetHostName() instead. + + @param buf Buffer to store the host name in. + @param sz Size of the buffer. + + @return @true if successful, @false otherwise. + + @header{wx/utils.h} +*/ +bool wxGetHostName(char* buf, int sz); + +/** + Returns the FQDN (fully qualified domain host name) or an empty string on + error. + + @see wxGetHostName() + + @header{wx/utils.h} +*/ +wxString wxGetFullHostName(); + +/** + Returns the home directory for the given user. If the @a user is empty + (default value), this function behaves like wxGetHomeDir() (i.e. returns + the current user home directory). + + If the home directory couldn't be determined, an empty string is returned. + + @header{wx/utils.h} +*/ +wxString wxGetUserHome(const wxString& user = ""); + +/** + This function returns the "user id" also known as "login name" under Unix + (i.e. something like "jsmith"). It uniquely identifies the current user (on + this system). Under Windows or NT, this function first looks in the + environment variables USER and LOGNAME; if neither of these is found, the + entry @b UserId in the @b wxWidgets section of the WIN.INI file is tried. + + @return The login name if successful or an empty string otherwise. + + @see wxGetUserName() + + @header{wx/utils.h} +*/ +wxString wxGetUserId(); + +/** + @deprecated Use wxGetUserId() instead. + + @param buf Buffer to store the login name in. + @param sz Size of the buffer. + + @return @true if successful, @false otherwise. + + @header{wx/utils.h} +*/ +bool wxGetUserId(char* buf, int sz); + +/** + This function returns the full user name (something like "Mr. John Smith"). + + Under Windows or NT, this function looks for the entry UserName in the + wxWidgets section of the WIN.INI file. If PenWindows is running, the entry + Current in the section User of the PENWIN.INI file is used. + + @return The full user name if successful or an empty string otherwise. + + @see wxGetUserId() + + @header{wx/utils.h} +*/ +wxString wxGetUserName(); + +/** + @deprecated Use wxGetUserName() instead. + + @param buf Buffer to store the full user name in. + @param sz Size of the buffer. + + @return @true if successful, @false otherwise. + + @header{wx/utils.h} +*/ +bool wxGetUserName(char* buf, int sz); + +/** + Returns the string containing the description of the current platform in a + user-readable form. For example, this function may return strings like + "Windows NT Version 4.0" or "Linux 2.2.2 i386". + + @see wxGetOsVersion() + + @header{wx/utils.h} +*/ +wxString wxGetOsDescription(); + +/** + Gets the version and the operating system ID for currently running OS. See + wxPlatformInfo for more details about wxOperatingSystemId. + + @see wxGetOsDescription(), wxPlatformInfo + + @header{wx/utils.h} +*/ +wxOperatingSystemId wxGetOsVersion(int* major = NULL, int* minor = NULL); + +/** + Returns @true if the operating system the program is running under is 64 + bit. The check is performed at run-time and may differ from the value + available at compile-time (at compile-time you can just check if + sizeof(void*) == 8) since the program could be running in + emulation mode or in a mixed 32/64 bit system (bi-architecture operating + system). + + @note This function is not 100% reliable on some systems given the fact + that there isn't always a standard way to do a reliable check on the + OS architecture. + + @header{wx/utils.h} +*/ +bool wxIsPlatform64Bit(); + +/** + Returns @true if the current platform is little endian (instead of big + endian). The check is performed at run-time. + + @see @ref group_funcmacro_byteorder "Byte Order Functions and Macros" + + @header{wx/utils.h} +*/ +bool wxIsPlatformLittleEndian(); + +//@} + + + +/** @ingroup group_funcmacro_procctrl */ +//@{ + +/** + Executes another program in Unix or Windows. + + In the overloaded versions of this function, if @a flags parameter contains + @c wxEXEC_ASYNC flag (the default), flow of control immediately returns. If + it contains @c wxEXEC_SYNC, the current application waits until the other + program has terminated. + + In the case of synchronous execution, the return value is the exit code of + the process (which terminates by the moment the function returns) and will + be -1 if the process couldn't be started and typically 0 if the process + terminated successfully. Also, while waiting for the process to terminate, + wxExecute() will call wxYield(). Because of this, by default this function + disables all application windows to avoid unexpected reentrancies which + could result from the users interaction with the program while the child + process is running. If you are sure that it is safe to not disable the + program windows, you may pass @c wxEXEC_NODISABLE flag to prevent this + automatic disabling from happening. + + For asynchronous execution, however, the return value is the process id and + zero value indicates that the command could not be executed. As an added + complication, the return value of -1 in this case indicates that we didn't + launch a new process, but connected to the running one (this can only + happen when using DDE under Windows for command execution). In particular, + in this case only, the calling code will not get the notification about + process termination. + + If @a callback isn't @NULL and if execution is asynchronous, + wxProcess::OnTerminate() will be called when the process finishes. + Specifying this parameter also allows you to redirect the standard input + and/or output of the process being launched by calling + wxProcess::Redirect(). If the child process IO is redirected, under Windows + the process window is not shown by default (this avoids having to flush an + unnecessary console for the processes which don't create any windows + anyhow) but a @c wxEXEC_NOHIDE flag can be used to prevent this from + happening, i.e. with this flag the child process window will be shown + normally. + + Under Unix the flag @c wxEXEC_MAKE_GROUP_LEADER may be used to ensure that + the new process is a group leader (this will create a new session if + needed). Calling wxKill() passing wxKILL_CHILDREN will kill this process as + well as all of its children (except those which have started their own + session). + + The @c wxEXEC_NOEVENTS flag prevents processing of any events from taking + place while the child process is running. It should be only used for very + short-lived processes as otherwise the application windows risk becoming + unresponsive from the users point of view. As this flag only makes sense + with @c wxEXEC_SYNC, @c wxEXEC_BLOCK equal to the sum of both of these + flags is provided as a convenience. + + @note Currently wxExecute() can only be used from the main thread, calling + this function from another thread will result in an assert failure in + debug build and won't work. + + @param command + The command to execute and any parameters to pass to it as a single + string, i.e. "emacs file.txt". + @param flags + Must include either wxEXEC_ASYNC or wxEXEC_SYNC and can also include + wxEXEC_NOHIDE, wxEXEC_MAKE_GROUP_LEADER (in either case) or + wxEXEC_NODISABLE and wxEXEC_NOEVENTS or wxEXEC_BLOCK, which is equal to + their combination, in wxEXEC_SYNC case. + @param callback + An optional pointer to wxProcess. + + @see wxShell(), wxProcess, @ref page_samples_exec + + @header{wx/utils.h} + + @beginWxPerlOnly + This function is called @c Wx::ExecuteStdoutStderr and it only takes the + @a command argument, and returns a 3-element list (@c status, @c output, + @c errors), where @c output and @c errors are array references. + @endWxPerlOnly +*/ +long wxExecute(const wxString& command, int flags = wxEXEC_ASYNC, + wxProcess* callback = NULL); + +//@} + +/** @ingroup group_funcmacro_procctrl */ +//@{ +/** + This is an overloaded version of wxExecute(const wxString&,int,wxProcess*), + please see its documentation for general information. + + This version takes an array of values: a command, any number of arguments, + terminated by @NULL. + + @param argv + The command to execute should be the first element of this array, any + additional ones are the command parameters and the array must be + terminated with a @NULL pointer. + @param flags + Must include either wxEXEC_ASYNC or wxEXEC_SYNC and can also include + wxEXEC_NOHIDE, wxEXEC_MAKE_GROUP_LEADER (in either case) or + wxEXEC_NODISABLE and wxEXEC_NOEVENTS or wxEXEC_BLOCK, which is equal to + their combination, in wxEXEC_SYNC case. + @param callback + An optional pointer to wxProcess. + + @header{wx/utils.h} +*/ +long wxExecute(char** argv, int flags = wxEXEC_ASYNC, + wxProcess* callback = NULL); +long wxExecute(wchar_t** argv, int flags = wxEXEC_ASYNC, + wxProcess* callback = NULL); +//@} + +/** @ingroup group_funcmacro_procctrl */ +//@{ + +/** + This is an overloaded version of wxExecute(const wxString&,int,wxProcess*), + please see its documentation for general information. + + This version can be used to execute a process (always synchronously, the + contents of @a flags is or'd with @c wxEXEC_SYNC) and capture its output in + the array @e output. + + @param command + The command to execute and any parameters to pass to it as a single + string. + @param flags + Must include either wxEXEC_ASYNC or wxEXEC_SYNC and can also include + wxEXEC_NOHIDE, wxEXEC_MAKE_GROUP_LEADER (in either case) or + wxEXEC_NODISABLE and wxEXEC_NOEVENTS or wxEXEC_BLOCK, which is equal to + their combination, in wxEXEC_SYNC case. + + @header{wx/utils.h} +*/ +long wxExecute(const wxString& command, wxArrayString& output, + int flags = 0); + +/** + This is an overloaded version of wxExecute(const wxString&,int,wxProcess*), + please see its documentation for general information. + + This version adds the possibility to additionally capture the messages from + standard error output in the @a errors array. + + @param command + The command to execute and any parameters to pass to it as a single + string. + @param flags + Must include either wxEXEC_ASYNC or wxEXEC_SYNC and can also include + wxEXEC_NOHIDE, wxEXEC_MAKE_GROUP_LEADER (in either case) or + wxEXEC_NODISABLE and wxEXEC_NOEVENTS or wxEXEC_BLOCK, which is equal to + their combination, in wxEXEC_SYNC case. + + @header{wx/utils.h} +*/ +long wxExecute(const wxString& command, wxArrayString& output, + wxArrayString& errors, int flags = 0); + +/** + Returns the number uniquely identifying the current process in the system. + If an error occurs, 0 is returned. + + @header{wx/utils.h} +*/ +unsigned long wxGetProcessId(); + +/** + Equivalent to the Unix kill function: send the given signal @a sig to the + process with PID @a pid. The valid signal values are: + + @code + enum wxSignal + { + wxSIGNONE = 0, // verify if the process exists under Unix + wxSIGHUP, + wxSIGINT, + wxSIGQUIT, + wxSIGILL, + wxSIGTRAP, + wxSIGABRT, + wxSIGEMT, + wxSIGFPE, + wxSIGKILL, // forcefully kill, dangerous! + wxSIGBUS, + wxSIGSEGV, + wxSIGSYS, + wxSIGPIPE, + wxSIGALRM, + wxSIGTERM // terminate the process gently + }; + @endcode + + @c wxSIGNONE, @c wxSIGKILL and @c wxSIGTERM have the same meaning under + both Unix and Windows but all the other signals are equivalent to + @c wxSIGTERM under Windows. + + Returns 0 on success, -1 on failure. If the @a rc parameter is not @NULL, + it will be filled with a value of the the @c wxKillError enum: + + @code + enum wxKillError + { + wxKILL_OK, // no error + wxKILL_BAD_SIGNAL, // no such signal + wxKILL_ACCESS_DENIED, // permission denied + wxKILL_NO_PROCESS, // no such process + wxKILL_ERROR // another, unspecified error + }; + @endcode + + The @a flags parameter can be wxKILL_NOCHILDREN (the default), or + wxKILL_CHILDREN, in which case the child processes of this process will be + killed too. Note that under Unix, for wxKILL_CHILDREN to work you should + have created the process by passing wxEXEC_MAKE_GROUP_LEADER to + wxExecute(). + + @see wxProcess::Kill(), wxProcess::Exists(), @ref page_samples_exec + + @header{wx/utils.h} +*/ +int wxKill(long pid, int sig = wxSIGTERM, + wxKillError rc = NULL, int flags = 0); + +/** + Executes a command in an interactive shell window. If no command is + specified, then just the shell is spawned. + + @see wxExecute(), @ref page_samples_exec + + @header{wx/utils.h} +*/ +bool wxShell(const wxString& command = NULL); + +/** + This function shuts down or reboots the computer depending on the value of + the @a flags. + + @note Doing this requires the corresponding access rights (superuser under + Unix, SE_SHUTDOWN privilege under Windows NT) and that this function + is only implemented under Unix and Win32. + + @param flags + Either wxSHUTDOWN_POWEROFF or wxSHUTDOWN_REBOOT + + @return @true on success, @false if an error occurred. + + @header{wx/utils.h} +*/ +bool wxShutdown(wxShutdownFlags flags); + +//@} + + + +/** @ingroup group_funcmacro_time */ +//@{ + +/** + Sleeps for the specified number of microseconds. The microsecond resolution + may not, in fact, be available on all platforms (currently only Unix + platforms with nanosleep(2) may provide it) in which case this is the same + as calling wxMilliSleep() with the argument of @e microseconds/1000. + + @header{wx/utils.h} +*/ +void wxMicroSleep(unsigned long microseconds); + +/** + Sleeps for the specified number of milliseconds. Notice that usage of this + function is encouraged instead of calling usleep(3) directly because the + standard @e usleep() function is not MT safe. + + @header{wx/utils.h} +*/ +void wxMilliSleep(unsigned long milliseconds); + +/** + Returns a string representing the current date and time. + + @header{wx/utils.h} +*/ +wxString wxNow(); + +/** + Sleeps for the specified number of seconds. + + @header{wx/utils.h} +*/ +void wxSleep(int secs); + +/** + @deprecated This function is deprecated because its name is misleading: + notice that the argument is in milliseconds, not microseconds. + Please use either wxMilliSleep() or wxMicroSleep() depending on + the resolution you need. + + Sleeps for the specified number of milliseconds. + + @header{wx/utils.h} +*/ +void wxUsleep(unsigned long milliseconds); + +//@} + diff --git a/interface/wx/valgen.h b/interface/wx/valgen.h new file mode 100644 index 0000000000..00ebc56fd4 --- /dev/null +++ b/interface/wx/valgen.h @@ -0,0 +1,116 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: valgen.h +// Purpose: interface of wxGenericValidator +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxGenericValidator + @wxheader{valgen.h} + + wxGenericValidator performs data transfer (but not validation or filtering) + for the following basic controls: wxButton, wxCheckBox, wxListBox, + wxStaticText, wxRadioButton, wxRadioBox, wxChoice, wxComboBox, wxGauge, + wxSlider, wxScrollBar, wxSpinButton, wxTextCtrl, wxCheckListBox. + + It checks the type of the window and uses an appropriate type for that + window. For example, wxButton and wxTextCtrl transfer data to and from a + wxString variable; wxListBox uses a wxArrayInt; wxCheckBox uses a bool. + + For more information, please see @ref overview_validator. + + @library{wxcore} + @category{validator} + + @see @ref overview_validator, wxValidator, wxTextValidator +*/ +class wxGenericValidator : public wxValidator +{ +public: + /** + Copy constructor. + + @param validator + Validator to copy. + */ + wxGenericValidator(const wxGenericValidator& validator); + /** + Constructor taking a bool pointer. This will be used for wxCheckBox, + wxRadioButton, wxToggleButton and wxBitmapToggleButton. + + @param valPtr + A pointer to a variable that contains the value. This variable + should have a lifetime equal to or longer than the validator + lifetime (which is usually determined by the lifetime of the + window). + */ + wxGenericValidator(bool* valPtr); + /** + Constructor taking a wxString pointer. This will be used for wxButton, + wxComboBox, wxStaticText, wxTextCtrl. + + @param valPtr + A pointer to a variable that contains the value. This variable + should have a lifetime equal to or longer than the validator + lifetime (which is usually determined by the lifetime of the + window). + */ + wxGenericValidator(wxString* valPtr); + /** + Constructor taking an integer pointer. This will be used for wxChoice, + wxGauge, wxScrollBar, wxRadioBox, wxSlider, wxSpinButton and + wxSpinCtrl. + + @param valPtr + A pointer to a variable that contains the value. This variable + should have a lifetime equal to or longer than the validator + lifetime (which is usually determined by the lifetime of the + window). + */ + wxGenericValidator(int* valPtr); + /** + Constructor taking a wxArrayInt pointer. This will be used for + wxListBox, wxCheckListBox. + + @param valPtr + A pointer to a variable that contains the value. This variable + should have a lifetime equal to or longer than the validator + lifetime (which is usually determined by the lifetime of the + window). + */ + wxGenericValidator(wxArrayInt* valPtr); + /** + Constructor taking a wxDateTime pointer. This will be used for + wxDatePickerCtrl. + + @param valPtr + A pointer to a variable that contains the value. This variable + should have a lifetime equal to or longer than the validator + lifetime (which is usually determined by the lifetime of the + window). + */ + wxGenericValidator(wxDateTime* valPtr); + + /** + Destructor. + */ + ~wxGenericValidator(); + + /** + Clones the generic validator using the copy constructor. + */ + virtual wxValidator* Clone() const; + + /** + Transfers the value from the window to the appropriate data type. + */ + virtual bool TransferFromWindow(); + + /** + Transfers the value to the window. + */ + virtual bool TransferToWindow(); +}; + diff --git a/interface/wx/validate.h b/interface/wx/validate.h new file mode 100644 index 0000000000..76f4abd835 --- /dev/null +++ b/interface/wx/validate.h @@ -0,0 +1,116 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: validate.h +// Purpose: interface of wxValidator +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxValidator + @wxheader{validate.h} + + wxValidator is the base class for a family of validator classes that + mediate between a class of control, and application data. + + A validator has three major roles: + + -# To transfer data from a C++ variable or own storage to and from a + control. + -# To validate data in a control, and show an appropriate error message. + -# To filter events (such as keystrokes), thereby changing the behaviour + of the associated control. + + Validators can be plugged into controls dynamically. + + To specify a default, "null" validator, use ::wxDefaultValidator. + + For more information, please see @ref overview_validator. + + @beginWxPythonOnly + If you wish to create a validator class in wxPython you should derive the + class from @c wxPyValidator in order to get Python-aware capabilities for + the various virtual methods. + @endWxPythonOnly + + @library{wxcore} + @category{validator} + + @stdobjects + ::wxDefaultValidator + + @see @ref overview_validator, wxTextValidator, wxGenericValidator +*/ +class wxValidator : public wxEvtHandler +{ +public: + /** + Constructor. + */ + wxValidator(); + + /** + Destructor. + */ + ~wxValidator(); + + /** + All validator classes must implement the Clone() function, which + returns an identical copy of itself. + + This is because validators are passed to control constructors as + references which must be copied. Unlike objects such as pens and + brushes, it does not make sense to have a reference counting scheme to + do this cloning because all validators should have separate data. + + @return This base function returns @NULL. + */ + virtual wxObject* Clone() const; + + /** + Returns the window associated with the validator. + */ + wxWindow* GetWindow() const; + + /** + This functions switches on or turns off the error sound produced by the + validators if an invalid key is pressed. + */ + void SetBellOnError(bool doIt = true); + + /** + Associates a window with the validator. + */ + void SetWindow(wxWindow* window); + + /** + This overridable function is called when the value in the window must + be transferred to the validator. + + @return @false if there is a problem. + */ + virtual bool TransferFromWindow(); + + /** + This overridable function is called when the value associated with the + validator must be transferred to the window. + + @return @false if there is a problem. + */ + virtual bool TransferToWindow(); + + /** + This overridable function is called when the value in the associated + window must be validated. + + @return @false if the value in the window is not valid; you may pop up + an error dialog. + */ + virtual bool Validate(wxWindow* parent); +}; + +/** + An empty, "null" wxValidator instance. +*/ +wxValidator wxDefaultValidator; + diff --git a/interface/wx/valtext.h b/interface/wx/valtext.h new file mode 100644 index 0000000000..27e9ba0c76 --- /dev/null +++ b/interface/wx/valtext.h @@ -0,0 +1,127 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: valtext.h +// Purpose: interface of wxTextValidator +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxTextValidator + @wxheader{valtext.h} + + wxTextValidator validates text controls, providing a variety of filtering + behaviours. + + For more information, please see @ref overview_validator. + + @beginStyleTable + @style{wxFILTER_NONE} + No filtering takes place. + @style{wxFILTER_ASCII} + Non-ASCII characters are filtered out. + @style{wxFILTER_ALPHA} + Non-alpha characters are filtered out. + @style{wxFILTER_ALPHANUMERIC} + Non-alphanumeric characters are filtered out. + @style{wxFILTER_NUMERIC} + Non-numeric characters are filtered out. + @style{wxFILTER_INCLUDE_LIST} + Use an include list. The validator checks if the user input is on + the list, complaining if not. See SetIncludes(). + @style{wxFILTER_EXCLUDE_LIST} + Use an exclude list. The validator checks if the user input is on + the list, complaining if it is. See SetExcludes(). + @style{wxFILTER_INCLUDE_CHAR_LIST} + Use an include list. The validator checks if each input character is + in the list (one character per list element), complaining if not. + See SetIncludes(). + @style{wxFILTER_EXCLUDE_CHAR_LIST} + Use an include list. The validator checks if each input character is + in the list (one character per list element), complaining if it is. + See SetExcludes(). + @endStyleTable + + @library{wxcore} + @category{validator} + + @see @ref overview_validator, wxValidator, wxGenericValidator +*/ +class wxTextValidator : public wxValidator +{ +public: + /** + Default constructor. + */ + wxTextValidator(const wxTextValidator& validator); + /** + Constructor taking a style and optional pointer to a wxString variable. + + @param style + A bitlist of flags documented in the class description. + @param valPtr + A pointer to a wxString variable that contains the value. This + variable should have a lifetime equal to or longer than the + validator lifetime (which is usually determined by the lifetime of + the window). + */ + wxTextValidator(long style = wxFILTER_NONE, wxString* valPtr = NULL); + + /** + Clones the text validator using the copy constructor. + */ + virtual wxValidator* Clone() const; + + /** + Returns a reference to the exclude list (the list of invalid values). + */ + wxArrayString& GetExcludes() const; + + /** + Returns a reference to the include list (the list of valid values). + */ + wxArrayString& GetIncludes() const; + + /** + Returns the validator style. + */ + long GetStyle() const; + + /** + Receives character input from the window and filters it according to + the current validator style. + */ + void OnChar(wxKeyEvent& event); + + /** + Sets the exclude list (invalid values for the user input). + */ + void SetExcludes(const wxArrayString& stringList); + + /** + Sets the include list (valid values for the user input). + */ + void SetIncludes(const wxArrayString& stringList); + + /** + Sets the validator style. + */ + void SetStyle(long style); + + /** + Transfers the value in the text control to the string. + */ + virtual bool TransferFromWindow(); + + /** + Transfers the string value to the text control. + */ + virtual bool TransferToWindow(); + + /** + Validates the window contents against the include or exclude lists, + depending on the validator style. + */ + virtual bool Validate(wxWindow* parent); +}; + diff --git a/interface/wx/variant.h b/interface/wx/variant.h new file mode 100644 index 0000000000..e276cce933 --- /dev/null +++ b/interface/wx/variant.h @@ -0,0 +1,578 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: variant.h +// Purpose: interface of wxVariant +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxVariant + @wxheader{variant.h} + + The wxVariant class represents a container for any type. A variant's value + can be changed at run time, possibly to a different type of value. + + As standard, wxVariant can store values of type bool, wxChar, double, long, + string, string list, time, date, void pointer, list of strings, and list of + variants. However, an application can extend wxVariant's capabilities by + deriving from the class wxVariantData and using the wxVariantData form of + the wxVariant constructor or assignment operator to assign this data to a + variant. Actual values for user-defined types will need to be accessed via + the wxVariantData object, unlike the case for basic data types where + convenience functions such as GetLong() can be used. + + Pointers to any wxObject derived class can also easily be stored in a + wxVariant. wxVariant will then use wxWidgets' built-in RTTI system to set + the type name (returned by GetType()) and to perform type-safety checks at + runtime. + + This class is useful for reducing the programming for certain tasks, such + as an editor for different data types, or a remote procedure call protocol. + + An optional name member is associated with a wxVariant. This might be used, + for example, in CORBA or OLE automation classes, where named parameters are + required. + + Note that as of wxWidgets 2.7.1, wxVariant is + @ref overview_refcount "reference counted". Additionally, the convenience + macros DECLARE_VARIANT_OBJECT() and IMPLEMENT_VARIANT_OBJECT() were added + so that adding (limited) support for conversion to and from wxVariant can + be very easily implemented without modifying either wxVariant or the class + to be stored by wxVariant. Since assignment operators cannot be declared + outside the class, the shift left operators are used like this: + + @code + // in the header file + DECLARE_VARIANT_OBJECT(MyClass) + + // in the implementation file + IMPLEMENT_VARIANT_OBJECT(MyClass) + + // in the user code + wxVariant variant; + MyClass value; + variant << value; + + // or + value << variant; + @endcode + + For this to work, MyClass must derive from wxObject, implement the + @ref overview_rtti "wxWidgets RTTI system" and support the assignment + operator and equality operator for itself. Ideally, it should also be + reference counted to make copying operations cheap and fast. This can be + most easily implemented using the reference counting support offered by + wxObject itself. By default, wxWidgets already implements the shift + operator conversion for a few of its drawing related classes: + + @code + IMPLEMENT_VARIANT_OBJECT(wxColour) + IMPLEMENT_VARIANT_OBJECT(wxImage) + IMPLEMENT_VARIANT_OBJECT(wxIcon) + IMPLEMENT_VARIANT_OBJECT(wxBitmap) + @endcode + + Note that as of wxWidgets 2.9.0, wxVariantData no longer inherits from + wxObject and wxVariant no longer uses the type-unsafe wxList class for list + operations but the type-safe wxVariantList class. Also, wxVariantData now + supports the wxVariantData::Clone() function for implementing the Unshare() + function. wxVariantData::Clone() is implemented automatically by + IMPLEMENT_VARIANT_OBJECT(). + + Since wxVariantData no longer derives from wxObject, any code that tests + the type of the data using wxDynamicCast() will require adjustment. You can + use the macro wxDynamicCastVariantData() with the same arguments as + wxDynamicCast(), to use C++ RTTI type information instead of wxWidgets + RTTI. + + @library{wxbase} + @category{data} + + @see wxVariantData +*/ +class wxVariant : public wxObject +{ +public: + /** + Default constructor. + */ + wxVariant(); + + /** + Constructs a variant directly with a wxVariantData object. wxVariant + will take ownership of the wxVariantData and will not increase its + reference count. + */ + wxVariant(wxVariantData* data, const wxString& name = ""); + + /** + Constructs a variant from another variant by increasing the reference + count. + */ + wxVariant(const wxVariant& variant); + + /** + Constructs a variant from a wide string literal. + */ + wxVariant(const wxChar* value, const wxString& name = ""); + + /** + Constructs a variant from a string. + */ + wxVariant(const wxString& value, const wxString& name = ""); + + /** + Constructs a variant from a wide char. + */ + wxVariant(wxChar value, const wxString& name = ""); + + /** + Constructs a variant from a long. + */ + wxVariant(long value, const wxString& name = ""); + + /** + Constructs a variant from a bool. + */ + wxVariant(bool value, const wxString& name = ""); + + /** + Constructs a variant from a double. + */ + wxVariant(double value, const wxString& name = ""); + + /** + Constructs a variant from a list of variants + */ + wxVariant(const wxVariantList& value, const wxString& name = ""); + + /** + Constructs a variant from a void pointer. + */ + wxVariant(void* value, const wxString& name = ""); + + /** + Constructs a variant from a pointer to an wxObject + derived class. + */ + wxVariant(wxObject* value, const wxString& name = ""); + + /** + Constructs a variant from a wxDateTime. + */ + wxVariant(wxDateTime& val, const wxString& name = ""); + + /** + Constructs a variant from a wxArrayString. + */ + wxVariant(wxArrayString& val, const wxString& name = ""); + + /** + Destructor. + + @note wxVariantData's destructor is protected, so wxVariantData cannot + usually be deleted. Instead, wxVariantData::DecRef() should be + called. See @ref overview_refcount_destruct + "reference-counted object destruction" for more info. + */ + ~wxVariant(); + + + /** + @name List Functionality + */ + //@{ + + /** + Returns the value at @a idx (zero-based). + */ + wxVariant operator [](size_t idx) const; + /** + Returns a reference to the value at @a idx (zero-based). This can be + used to change the value at this index. + */ + wxVariant& operator [](size_t idx); + + /** + Appends a value to the list. + */ + void Append(const wxVariant& value); + + /** + Makes the variant null by deleting the internal data and set the name + to wxEmptyString. + */ + void Clear(); + + /** + Deletes the contents of the list. + */ + void ClearList(); + + /** + Deletes the zero-based @a item from the list. + */ + bool Delete(size_t item); + + /** + Returns the number of elements in the list. + */ + size_t GetCount() const; + + /** + Returns a reference to the wxVariantList class used by wxVariant if + this wxVariant is currently a list of variants. + */ + wxVariantList& GetList() const; + + /** + Inserts a value at the front of the list. + */ + void Insert(const wxVariant& value); + + /** + Makes an empty list. This differs from a null variant which has no + data; a null list is of type list, but the number of elements in the + list is zero. + */ + void NullList(); + + //@} + + + //@{ + /** + Retrieves and converts the value of this variant to the type that + @a value is. + */ + bool Convert(long* value) const; + bool Convert(bool* value) const; + bool Convert(double* value) const; + bool Convert(wxString* value) const; + bool Convert(wxChar* value) const; + bool Convert(wxDateTime* value) const; + //@} + + /** + Returns the string array value. + */ + wxArrayString GetArrayString() const; + + /** + Returns the boolean value. + */ + bool GetBool() const; + + /** + Returns the character value. + */ + wxChar GetChar() const; + + /** + Returns a pointer to the internal variant data. To take ownership of + this data, you must call its wxVariantData::IncRef() method. When you + stop using it, wxVariantData::DecRef() must be called as well. + */ + wxVariantData* GetData() const; + + /** + Returns the date value. + */ + wxDateTime GetDateTime() const; + + /** + Returns the floating point value. + */ + double GetDouble() const; + + /** + Returns the integer value. + */ + long GetLong() const; + + /** + Returns a constant reference to the variant name. + */ + const wxString GetName() const; + + /** + Gets the string value. + */ + wxString GetString() const; + + /** + Returns the value type as a string. + + The built-in types are: + - "bool" + - "char" + - "datetime" + - "double" + - "list" + - "long" + - "string" + - "arrstring" + - "void*" + + If the variant is null, the value type returned is the string "null" + (not the empty string). + */ + wxString GetType() const; + + /** + Gets the void pointer value. + */ + void* GetVoidPtr() const; + + /** + Gets the wxObject pointer value. + */ + wxObject* GetWxObjectPtr() const; + + /** + Returns @true if there is no data associated with this variant, @false + if there is data. + */ + bool IsNull() const; + + /** + Returns @true if @a type matches the type of the variant, @false + otherwise. + */ + bool IsType(const wxString& type) const; + + /** + Returns @true if the data is derived from the class described by + @a type, @false otherwise. + */ + bool IsValueKindOf(const wxClassInfo* type) const; + + /** + Makes the variant null by deleting the internal data. + */ + void MakeNull(); + + /** + Makes a string representation of the variant value (for any type). + */ + wxString MakeString() const; + + /** + Returns @true if @a value matches an element in the list. + */ + bool Member(const wxVariant& value) const; + + /** + Sets the internal variant data, deleting the existing data if there is + any. + */ + void SetData(wxVariantData* data); + + /** + Makes sure that any data associated with this variant is not shared + with other variants. For this to work, wxVariantData::Clone() must be + implemented for the data types you are working with. + wxVariantData::Clone() is implemented for all the default data types. + */ + bool Unshare(); + + //@{ + /** + Inequality test operator. + */ + bool operator !=(const wxVariant& value) const; + bool operator !=(const wxString& value) const; + bool operator !=(const wxChar* value) const; + bool operator !=(wxChar value) const; + bool operator !=(const long value) const; + bool operator !=(const bool value) const; + bool operator !=(const double value) const; + bool operator !=(void* value) const; + bool operator !=(wxObject* value) const; + bool operator !=(const wxVariantList& value) const; + bool operator !=(const wxArrayString& value) const; + bool operator !=(const wxDateTime& value) const; + //@} + + //@{ + /** + Assignment operator, using @ref overview_refcount "reference counting" + if possible. + */ + void operator =(const wxVariant& value); + void operator =(wxVariantData* value); + void operator =(const wxString& value); + void operator =(const wxChar* value); + void operator =(wxChar value); + void operator =(const long value); + void operator =(const bool value); + void operator =(const double value); + void operator =(void* value); + void operator =(wxObject* value); + void operator =(const wxVariantList& value); + void operator =(const wxDateTime& value); + void operator =(const wxArrayString& value); + //@} + + //@{ + /** + Equality test operator. + */ + bool operator ==(const wxVariant& value) const; + bool operator ==(const wxString& value) const; + bool operator ==(const wxChar* value) const; + bool operator ==(wxChar value) const; + bool operator ==(const long value) const; + bool operator ==(const bool value) const; + bool operator ==(const double value) const; + bool operator ==(void* value) const; + bool operator ==(wxObject* value) const; + bool operator ==(const wxVariantList& value) const; + bool operator ==(const wxArrayString& value) const; + bool operator ==(const wxDateTime& value) const; + //@} + + //@{ + /** + Operator for implicit conversion to a long, using GetLong(). + */ + double operator double() const; + long operator long() const; + //@} + + /** + Operator for implicit conversion to a pointer to a void, using + GetVoidPtr(). + */ + void* operator void*() const; + + /** + Operator for implicit conversion to a wxChar, using GetChar(). + */ + char operator wxChar() const; + + /** + Operator for implicit conversion to a pointer to a wxDateTime, using + GetDateTime(). + */ + void* operator wxDateTime() const; + + /** + Operator for implicit conversion to a string, using MakeString(). + */ + wxString operator wxString() const; +}; + + + +/** + @class wxVariantData + @wxheader{variant.h} + + The wxVariantData class is used to implement a new type for wxVariant. + Derive from wxVariantData, and override the pure virtual functions. + + wxVariantData is @ref overview_refcount "reference counted", but you don't + normally have to care about this, as wxVariant manages the count + automatically. However, in case your application needs to take ownership of + wxVariantData, be aware that the object is created with a reference count + of 1, and passing it to wxVariant will not increase this. In other words, + IncRef() needs to be called only if you both take ownership of + wxVariantData and pass it to a wxVariant. Also note that the destructor is + protected, so you can never explicitly delete a wxVariantData instance. + Instead, DecRef() will delete the object automatically when the reference + count reaches zero. + + @library{wxbase} + @category{data} + + @see wxVariant, wxGetVariantCast() +*/ +class wxVariantData +{ +public: + /** + Default constructor. + */ + wxVariantData(); + + /** + This function can be overridden to clone the data. You must implement + this function in order for wxVariant::Unshare() to work for your data. + This function is implemented for all built-in data types. + */ + wxVariantData* Clone() const; + + /** + Decreases reference count. If the count reaches zero, the object is + automatically deleted. + + @note The destructor of wxVariantData is protected, so delete cannot be + used as normal. Instead, DecRef() should be called. + */ + void DecRef(); + + /** + Returns @true if this object is equal to @a data. + */ + bool Eq(wxVariantData& data) const; + + /** + Returns the string type of the data. + */ + wxString GetType() const; + + /** + If the data is a wxObject returns a pointer to the objects wxClassInfo + structure, if the data isn't a wxObject the method returns @NULL. + */ + wxClassInfo* GetValueClassInfo() const; + + /** + Increases reference count. Note that initially wxVariantData has + reference count of 1. + */ + void IncRef(); + + /** + Reads the data from @a stream. + */ + bool Read(ostream& stream); + /** + Reads the data from @a string. + */ + bool Read(wxString& string); + + /** + Writes the data to @a stream. + */ + bool Write(ostream& stream) const; + /** + Writes the data to @a string. + */ + bool Write(wxString& string) const; +}; + + + +// ============================================================================ +// Global functions/macros +// ============================================================================ + +/** @ingroup group_funcmacro_rtti */ +//@{ + +/** + This macro returns a pointer to the data stored in @a var (wxVariant) cast + to the type @a classname if the data is of this type (the check is done + during the run-time) or @NULL otherwise. + + @header{wx/variant.h} + + @see @ref overview_rtti, wxDynamicCast() +*/ +#define wxGetVariantCast(var, classname) + +//@} + diff --git a/interface/wx/vector.h b/interface/wx/vector.h new file mode 100644 index 0000000000..65e39a4a1d --- /dev/null +++ b/interface/wx/vector.h @@ -0,0 +1,177 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: vector.h +// Purpose: interface of wxVector +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @wxheader{vector.h} + + wxVector is a template class which implements most of the @c std::vector + class and can be used like it. + + If wxWidgets is compiled in STL mode, wxVector will just be a typedef to + @c std::vector. Just like for @c std::vector, objects stored in wxVector + need to be @e assignable but don't have to be @e "default constructible". + + Please refer to the STL documentation for further information. + + @nolibrary + @category{containers} + + @see @ref overview_container, wxList, wxArray +*/ +template +class wxVector +{ +public: + typedef size_t size_type; + typedef T value_type; + typedef value_type* iterator; + typedef const value_type* const_iterator; + typedef value_type& reference; + + /** + Constructor. + */ + wxVector(); + + /** + Copy onstructor. + */ + wxVector(const wxVector& c); + + /** + Destructor. + */ + ~wxVector(); + + /** + Returns item at position @a idx. + */ + const value_type& at(size_type idx) const; + + /** + Returns item at position @a idx. + */ + value_type& at(size_type idx); + + /** + Return the last item. + */ + const value_type& back() const; + + /** + Return the last item. + */ + value_type& back(); + + /** + Return iterator to beginning of the vector. + */ + const_iterator begin() const; + + /** + Return iterator to beginning of the vector. + */ + iterator begin(); + + /** + Returns vector's current capacity, i.e. how much memory is allocated. + + @see reserve() + */ + size_type capacity() const; + + /** + Clears the vector. + */ + void clear(); + + /** + Returns @true if the vector is empty. + */ + bool empty() const; + + /** + Returns iterator to the end of the vector. + */ + const_iterator end() const; + + /** + Returns iterator to the end of the vector. + */ + iterator end(); + + /** + Erase item pointed to by iterator @a it. + + @return Iterator pointing to the item immediately after the erased one. + */ + iterator erase(iterator it); + + /** + Erase items in the range @a first to @a last (@a last is not erased). + + @return Iterator pointing to the item immediately after the erased + range. + */ + iterator erase(iterator first, iterator last); + + /** + Returns the first item. + */ + const value_type& front() const; + + /** + Returns the first item. + */ + value_type& front(); + + /** + Insert item @a v at given position @a it. + + @return Iterator for the inserted item. + */ + iterator insert(iterator it, const value_type& v = value_type()); + + /** + Assignment operator. + */ + wxVector& operator=(const wxVector& vb); + + /** + Returns item at position @a idx. + */ + const value_type& operator[](size_type idx) const; + + /** + Returns item at position @a idx. + */ + value_type& operator[](size_type idx); + + /** + Removes the last item. + */ + void pop_back(); + + /** + Adds an item to the end of the vector. + */ + void push_back(const value_type& v); + + /** + Reserves memory for at least @a n items. + + @see capacity() + */ + void reserve(size_type n); + + /** + Returns the size of the vector. + */ + size_type size() const; +}; + diff --git a/interface/wx/version.h b/interface/wx/version.h new file mode 100644 index 0000000000..d3a15946d3 --- /dev/null +++ b/interface/wx/version.h @@ -0,0 +1,44 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: version.h +// Purpose: wxWidgets version numbers +// Author: wxWidgets team +// RCS-ID: $Id: numdlg.h 52425 2008-03-10 15:24:38Z FM $ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** @ingroup group_funcmacro_version */ +//@{ + +/** + This is a macro which evaluates to @true if the current wxWidgets version + is at least major.minor.release. + + For example, to test if the program is compiled with wxWidgets 2.2 or + higher, the following can be done: + + @code + wxString s; + #if wxCHECK_VERSION(2, 2, 0) + if ( s.StartsWith("foo") ) + #else // replacement code for old version + if ( strncmp(s, "foo", 3) == 0 ) + #endif + { + ... + } + @endcode + + @header{wx/version.h} +*/ +#define wxCHECK_VERSION( major, minor, release ) + +/** + Same as wxCHECK_VERSION() but also checks that wxSUBRELEASE_NUMBER is at + least subrel. + + @header{wx/version.h} +*/ +#define wxCHECK_VERSION_FULL( major, minor, release, subrel ) + +//@} + diff --git a/interface/wx/vidmode.h b/interface/wx/vidmode.h new file mode 100644 index 0000000000..a96d3192c9 --- /dev/null +++ b/interface/wx/vidmode.h @@ -0,0 +1,88 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: vidmode.h +// Purpose: interface of wxVideoMode +// Author: wxWidgets team +// RCS-ID: $Id: display.h 52634 2008-03-20 13:45:17Z VS $ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @struct wxVideoMode + @wxheader{display.h} + + Determines the sizes and locations of displays connected to the system. + + @library{wxcore} + @category{misc} + + @stdobjects + ::wxDefaultVideoMode + + @see wxClientDisplayRect(), wxDisplaySize(), wxDisplaySizeMM() +*/ +struct wxVideoMode +{ +public: + /** + Constructs this class using the given parameters. + */ + wxVideoMode(int width = 0, int height = 0, int depth = 0, int freq = 0); + + bool operator==(const wxVideoMode& m) const + bool operator!=(const wxVideoMode& mode) const + + /** + Returns true if this mode matches the other one in the sense that all + non zero fields of the other mode have the same value in this one + (except for refresh which is allowed to have a greater value). + */ + bool Matches(const wxVideoMode& other) const; + + /** + Returns the screen width in pixels (e.g. 640), 0 means unspecified. + */ + int GetWidth() const; + + /** + Returns the screen height in pixels (e.g. 480), 0 means unspecified. + */ + int GetHeight() const; + + /** + Returns bits per pixel (e.g. 32), 1 is monochrome and 0 means + unspecified/known. + */ + int GetDepth() const; + + /** + Returns true if the object has been initialized + */ + bool IsOk() const; + + /** + The screen width in pixels (e.g. 640), 0 means unspecified. + */ + int w; + + /** + The screen height in pixels (e.g. 480), 0 means unspecified. + */ + int h; + + /** + Bits per pixel (e.g. 32), 1 is monochrome and 0 means + unspecified/known. + */ + int bpp; + + /** + Refresh frequency in Hz, 0 means unspecified/unknown. + */ + int refresh; +}; + +/** + A global wxVideoMode instance used by wxDisplay. +*/ +wxVideoMode wxDefaultVideoMode; + diff --git a/interface/wx/vlbox.h b/interface/wx/vlbox.h new file mode 100644 index 0000000000..d376222010 --- /dev/null +++ b/interface/wx/vlbox.h @@ -0,0 +1,328 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: vlbox.h +// Purpose: interface of wxVListBox +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxVListBox + @wxheader{vlbox.h} + + wxVListBox is a wxListBox-like control with the following two main + differences from a regular wxListBox: it can have an arbitrarily huge + number of items because it doesn't store them itself but uses the + OnDrawItem() callback to draw them (so it is a virtual listbox) and its + items can have variable height as determined by OnMeasureItem() (so it is + also a listbox with the lines of variable height). + + Also, as a consequence of its virtual nature, it doesn't have any methods + to append or insert items in it as it isn't necessary to do it: you just + have to call SetItemCount() to tell the control how many items it should + display. Of course, this also means that you will never use this class + directly because it has pure virtual functions, but will need to derive + your own class from it (for example, wxHtmlListBox). + + However it emits the same events as wxListBox and the same event macros may + be used with it. Since wxVListBox does not store its items itself, the + events will only contain the index, not any contents such as the string of + an item. + + @library{wxcore} + @category{ctrl} + + + @see wxSimpleHtmlListBox, wxHtmlListBox +*/ +class wxVListBox : public wxVScrolledWindow +{ +public: + /** + Default constructor, you must call Create() later. + */ + wxVListBox(); + /** + Normal constructor which calls Create() internally. + */ + wxVListBox(wxWindow* parent, wxWindowID id = wxID_ANY, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0, const wxString& name = wxVListBoxNameStr); + + /** + Destructor. + */ + virtual ~wxVListBox(); + + /** + Deletes all items from the control. + */ + void Clear(); + + /** + Creates the control. To finish creating it you also should call + SetItemCount() to let it know about the number of items it contains. + + The only special style which may be used with wxVListBox is + @c wxLB_MULTIPLE which indicates that the listbox should support + multiple selection. + + @return @true on success or @false if the control couldn't be created. + */ + bool Create(wxWindow* parent, wxWindowID id = wxID_ANY, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, long style = 0, + const wxString& name = wxVListBoxNameStr); + + /** + Deselects all the items in the listbox. This method is only valid for + multi selection listboxes. + + @return @true if any items were changed, i.e. if there had been any + selected items before, or @false if all the items were already + deselected. + + @see SelectAll(), Select() + */ + bool DeselectAll(); + + /** + Returns the index of the first selected item in the listbox or + @c wxNOT_FOUND if no items are currently selected. + + @a cookie is an opaque parameter which should be passed to the + subsequent calls to GetNextSelected(). It is needed in order to allow + parallel iterations over the selected items. + + Here is a typical example of using these functions: + + @code + unsigned long cookie; + int item = hlbox->GetFirstSelected(cookie); + while ( item != wxNOT_FOUND ) + { + // ... process item ... + item = hlbox->GetNextSelected(cookie); + } + @endcode + + This method is only valid for multi selection listboxes. + */ + int GetFirstSelected(unsigned long& cookie) const; + + /** + Get the number of items in the control. + + @see SetItemCount() + */ + size_t GetItemCount() const; + + /** + Returns the margins used by the control. The @c x field of the returned + point is the horizontal margin and the @c y field is the vertical one. + + @see SetMargins() + */ + wxPoint GetMargins() const; + + /** + Returns the index of the next selected item or @c wxNOT_FOUND if there + are no more. + + This method is only valid for multi selection listboxes. + + @see GetFirstSelected() + */ + int GetNextSelected(unsigned long& cookie) const; + + /** + Returns the number of the items currently selected. + + It is valid for both single and multi selection controls. In the former + case it may only return 0 or 1 however. + + @see IsSelected(), GetFirstSelected(), GetNextSelected() + */ + size_t GetSelectedCount() const; + + /** + Get the currently selected item or @c wxNOT_FOUND if there is no + selection. + */ + int GetSelection() const; + + /** + Returns the background colour used for the selected cells. By default + the standard system colour is used. + + @see wxSystemSettings::GetColour(), SetSelectionBackground() + */ + const wxColour& GetSelectionBackground() const; + + /** + Returns @true if the listbox was created with @c wxLB_MULTIPLE style + and so supports multiple selection or @false if it is a single + selection listbox. + */ + bool HasMultipleSelection() const; + + /** + Returns @true if this item is the current one, @false otherwise. + + The current item is always the same as selected one for the single + selection listbox and in this case this method is equivalent to + IsSelected() but they are different for multi selection listboxes where + many items may be selected but only one (at most) is current. + */ + bool IsCurrent(size_t item) const; + + /** + Returns @true if this item is selected, @false otherwise. + */ + bool IsSelected(size_t item) const; + + /** + 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. + + @todo Change this function signature to non-const. + */ + void OnDrawBackground(wxDC& dc, const wxRect& rect, size_t n) const; + + /** + The derived class must implement this function to actually draw the + item with the given index on the provided DC. + + @param dc + The device context to use for drawing. + @param rect + The bounding rectangle for the item being drawn (DC clipping + region is set to this rectangle before calling this function). + @param n + The index of the item to be drawn. + + @todo Change this function signature to non-const. + */ + virtual void OnDrawItem(wxDC& dc, const wxRect& rect, size_t n) const; + + /** + This method may be used to draw separators between the lines. The + rectangle passed to it may be modified, typically to deflate it a bit + before passing to OnDrawItem(). + + The base class version of this method doesn't do anything. + + @param dc + The device context to use for drawing. + @param rect + The bounding rectangle for the item. + @param n + The index of the item. + + @todo Change this function signature to non-const. + */ + virtual void OnDrawSeparator(wxDC& dc, wxRect& rect, size_t n) const; + + /** + The derived class must implement this method to return the height of + the specified item (in pixels). + */ + virtual wxCoord OnMeasureItem(size_t n) const; + + /** + Selects or deselects the specified item which must be valid (i.e. not + equal to @c wxNOT_FOUND). + + @return @true if the items selection status has changed or @false + otherwise. + + This function is only valid for the multiple selection listboxes, use + SetSelection() for the single selection ones. + */ + bool Select(size_t item, bool select = true); + + /** + Selects all the items in the listbox. + + @return @true if any items were changed, i.e. if there had been any + unselected items before, or @false if all the items were + already selected. + + This method is only valid for multi selection listboxes. + + @see DeselectAll(), Select() + */ + bool SelectAll(); + + /** + Selects all items in the specified range which may be given in any + order. + + @return @true if the items selection status has changed or @false + otherwise. + + This method is only valid for multi selection listboxes. + + @see SelectAll(), Select() + */ + bool SelectRange(size_t from, size_t to); + + /** + Set the number of items to be shown in the control. + + This is just a synonym for wxVScrolledWindow::SetRowCount(). + */ + void SetItemCount(size_t count); + + //@{ + /** + Set the margins: horizontal margin is the distance between the window + border and the item contents while vertical margin is half of the + distance between items. + + By default both margins are 0. + */ + void SetMargins(const wxPoint& pt); + void SetMargins(wxCoord x, wxCoord y); + //@} + + /** + Set the selection to the specified item, if it is -1 the selection is + unset. The selected item will be automatically scrolled into view if it + isn't currently visible. + + This method may be used both with single and multiple selection + listboxes. + */ + void SetSelection(int selection); + + /** + Sets the colour to be used for the selected cells background. The + background of the standard cells may be changed by simply calling + wxWindow::SetBackgroundColour(). + + @note Using a non-default background colour may result in control + having an appearance different from the similar native controls + and should be avoided in general. + + @see GetSelectionBackground() + */ + void SetSelectionBackground(const wxColour& col); + + /** + Toggles the state of the specified @a item, i.e. selects it if it was + unselected and deselects it if it was selected. + + This method is only valid for multi selection listboxes. + + @see Select() + */ + void Toggle(size_t item); +}; + diff --git a/interface/wx/vscroll.h b/interface/wx/vscroll.h new file mode 100644 index 0000000000..c5acde34e3 --- /dev/null +++ b/interface/wx/vscroll.h @@ -0,0 +1,882 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: vscroll.h +// Purpose: interface of wxVarHScrollHelper +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxVarScrollHelperBase + @wxheader{vscroll.h} + + This class provides all common base functionality for scroll calculations + shared among all variable scrolled window implementations as well as + automatic scrollbar functionality, saved scroll positions, controlling + target windows to be scrolled, as well as defining all required virtual + functions that need to be implemented for any orientation specific work. + + Documentation of this class is provided specifically for referencing use + of the functions provided by this class for use with the variable scrolled + windows that derive from here. You will likely want to derive your window + from one of the already implemented variable scrolled windows rather than + from wxVarScrollHelperBase directly. + + @library{wxcore} + @category{miscwnd} + + @see wxHScrolledWindow, wxHVScrolledWindow, wxVScrolledWindow +*/ +class wxVarScrollHelperBase +{ +public: + /** + Constructor taking the target window to be scrolled by this helper + class. This will attach scroll event handlers to the target window to + catch and handle scroll events appropriately. + */ + wxVarScrollHelperBase(wxWindow* winToScroll); + + /** + Virtual destructor for detaching scroll event handlers attached with + this helper class. + */ + virtual ~wxVarScrollHelperBase(); + + /** + Translates the logical coordinate given to the current device + coordinate. For example, if the window is scrolled 10 units and each + scroll unit represents 10 device units (which may not be the case since + this class allows for variable scroll unit sizes), a call to this + function with a coordinate of 15 will return -85. + + @see CalcUnscrolledPosition() + */ + int CalcScrolledPosition(int coord) const; + + /** + Translates the device coordinate given to the corresponding logical + coordinate. For example, if the window is scrolled 10 units and each + scroll unit represents 10 device units (which may not be the case since + this class allows for variable scroll unit sizes), a call to this + function with a coordinate of 15 will return 115. + + @see CalcScrolledPosition() + */ + int CalcUnscrolledPosition(int coord) const; + + /** + With physical scrolling on (when this is @true), the device origin is + changed properly when a wxPaintDC is prepared, children are actually + moved and laid out properly, and the contents of the window (pixels) + are actually moved. When this is @false, you are responsible for + repainting any invalidated areas of the window yourself to account for + the new scroll position. + */ + void EnablePhysicalScrolling(bool scrolling = true); + + /** + When the number of scroll units change, we try to estimate the total + size of all units when the full window size is needed (i.e. to + calculate the scrollbar thumb size). This is a rather expensive + operation in terms of unit access, so if the user code may estimate the + average size better or faster than we do, it should override this + function to implement its own logic. This function should return the + best guess for the total virtual window size. + + @note Although returning a totally wrong value would still work, it + risks resulting in very strange scrollbar behaviour so this + function should really try to make the best guess possible. + */ + virtual wxCoord EstimateTotalSize() const; + + /** + This function needs to be overridden in the in the derived class to + return the window size with respect to the opposing orientation. If + this is a vertical scrolled window, it should return the height. + + @see GetOrientationTargetSize() + */ + virtual int GetNonOrientationTargetSize() const; + + /** + This function need to be overridden to return the orientation that this + helper is working with, either @c wxHORIZONTAL or @c wxVERTICAL. + */ + virtual wxOrientation GetOrientation() const; + + /** + This function needs to be overridden in the in the derived class to + return the window size with respect to the orientation this helper is + working with. If this is a vertical scrolled window, it should return + the width. + + @see GetNonOrientationTargetSize() + */ + virtual int GetOrientationTargetSize() const; + + /** + This function will return the target window this helper class is + currently scrolling. + + @see SetTargetWindow() + */ + wxWindow* GetTargetWindow() const; + + /** + Returns the index of the first visible unit based on the scroll + position. + */ + size_t GetVisibleBegin() const; + + /** + Returns the index of the last visible unit based on the scroll + position. This includes the last unit even if it is only partially + visible. + */ + size_t GetVisibleEnd() const; + + /** + Returns @true if the given scroll unit is currently visible (even if + only partially visible) or @false otherwise. + */ + bool IsVisible(size_t unit) const; + + /** + This function must be overridden in the derived class, and should + return the size of the given unit in pixels. + */ + virtual wxCoord OnGetUnitSize(size_t unit) const; + + /** + This function doesn't have to be overridden but it may be useful to do + so if calculating the units' sizes is a relatively expensive operation + as it gives your code a chance to calculate several of them at once and + cache the result if necessary. + + OnGetUnitsSizeHint() is normally called just before OnGetUnitSize() but + you shouldn't rely on the latter being called for all units in the + interval specified here. It is also possible that OnGetUnitSize() will + be called for units outside of this interval, so this is really just a + hint, not a promise. + + Finally, note that @a unitMin is inclusive, while @a unitMax is + exclusive. + */ + virtual void OnGetUnitsSizeHint(size_t unitMin, size_t unitMax) const; + + /** + Recalculate all parameters and repaint all units. + */ + virtual void RefreshAll(); + + /** + Normally the window will scroll itself, but in some rare occasions you + might want it to scroll (part of) another window (e.g. a child of it in + order to scroll only a portion the area between the scrollbars like a + spreadsheet where only the cell area will move). + + @see GetTargetWindow() + */ + void SetTargetWindow(wxWindow* target); + + /** + Update the thumb size shown by the scrollbar. + */ + virtual void UpdateScrollbar(); + + /** + Returns the virtual scroll unit under the device unit given accounting + for scroll position or @c wxNOT_FOUND if none (i.e. if it is below the + last item). + */ + int VirtualHitTest(wxCoord coord) const; +}; + + + +/** + @class wxVarVScrollHelper + @wxheader{vscroll.h} + + This class provides functions wrapping the wxVarScrollHelperBase class, + targeted for vertical-specific scrolling. + + Like wxVarScrollHelperBase, this class is mostly only useful to those + classes built into wxWidgets deriving from here, and this documentation is + mostly only provided for referencing the functions provided by this class. + You will likely want to derive your window from wxVScrolledWindow rather + than from here directly. + + @library{wxcore} + @category{miscwnd} + + @see wxHScrolledWindow, wxHVScrolledWindow, wxVScrolledWindow +*/ +class wxVarVScrollHelper : public wxVarScrollHelperBase +{ +public: + /** + Constructor taking the target window to be scrolled by this helper + class. This will attach scroll event handlers to the target window to + catch and handle scroll events appropriately. + */ + wxVarVScrollHelper(wxWindow* winToScroll); + + /** + This class forwards calls from EstimateTotalSize() to this function so + derived classes can override either just the height or the width + estimation, or just estimate both differently if desired in any + wxHVScrolledWindow derived class. + + @note This function will not be called if EstimateTotalSize() is + overridden in your derived class. + */ + virtual wxCoord EstimateTotalHeight() const; + + /** + Returns the number of rows the target window contains. + + @see SetRowCount() + */ + size_t GetRowCount() const; + + /** + Returns the index of the first visible row based on the scroll + position. + */ + size_t GetVisibleRowsBegin() const; + + /** + Returns the index of the last visible row based on the scroll position. + This includes the last row even if it is only partially visible. + */ + size_t GetVisibleRowsEnd() const; + + /** + Returns @true if the given row is currently visible (even if only + partially visible) or @false otherwise. + */ + bool IsRowVisible(size_t row) const; + + /** + This function must be overridden in the derived class, and should + return the height of the given row in pixels. + */ + virtual wxCoord OnGetRowHeight(size_t row) const; + + /** + This function doesn't have to be overridden but it may be useful to do + so if calculating the rows' sizes is a relatively expensive operation + as it gives your code a chance to calculate several of them at once and + cache the result if necessary. + + OnGetRowsHeightHint() is normally called just before OnGetRowHeight() + but you shouldn't rely on the latter being called for all rows in the + interval specified here. It is also possible that OnGetRowHeight() will + be called for units outside of this interval, so this is really just a + hint, not a promise. + + Finally, note that @a rowMin is inclusive, while @a rowMax is + exclusive. + */ + virtual void OnGetRowsHeightHint(size_t rowMin, size_t rowMax) const; + + /** + Triggers a refresh for just the given row's area of the window if it's + visible. + */ + virtual void RefreshRow(size_t row); + + /** + Triggers a refresh for the area between the specified range of rows + given (inclusively). + */ + virtual void RefreshRows(size_t from, size_t to); + + /** + Scroll by the specified number of pages which may be positive (to + scroll down) or negative (to scroll up). + */ + virtual bool ScrollRowPages(int pages); + + /** + Scroll by the specified number of rows which may be positive (to scroll + down) or negative (to scroll up). + + @return @true if the window was scrolled, @false otherwise (for + example, if we're trying to scroll down but we are already + showing the last row). + */ + virtual bool ScrollRows(int rows); + + /** + Scroll to the specified row. It will become the first visible row in + the window. + + @return @true if we scrolled the window, @false if nothing was done. + */ + bool ScrollToRow(size_t row); + + /** + Set the number of rows the window contains. The derived class must + provide the heights for all rows with indices up to the one given here + in it's OnGetRowHeight() implementation. + + @see GetRowCount() + */ + void SetRowCount(size_t rowCount); +}; + + + +/** + @class wxVarHScrollHelper + @wxheader{vscroll.h} + + This class provides functions wrapping the wxVarScrollHelperBase class, + targeted for horizontal-specific scrolling. + + Like wxVarScrollHelperBase, this class is mostly only useful to those + classes built into wxWidgets deriving from here, and this documentation is + mostly only provided for referencing the functions provided by this class. + You will likely want to derive your window from wxHScrolledWindow rather + than from here directly. + + @library{wxcore} + @category{miscwnd} + + @see wxHScrolledWindow, wxHVScrolledWindow, wxVScrolledWindow +*/ +class wxVarHScrollHelper : public wxVarScrollHelperBase +{ +public: + /** + Constructor taking the target window to be scrolled by this helper + class. This will attach scroll event handlers to the target window to + catch and handle scroll events appropriately. + */ + wxVarHScrollHelper(wxWindow* winToScroll); + + /** + This class forwards calls from EstimateTotalSize() to this function so + derived classes can override either just the height or the width + estimation, or just estimate both differently if desired in any + wxHVScrolledWindow derived class. + + @note This function will not be called if EstimateTotalSize() is + overridden in your derived class. + */ + virtual wxCoord EstimateTotalWidth() const; + + /** + Returns the number of columns the target window contains. + + @see SetColumnCount() + */ + size_t GetColumnCount() const; + + /** + Returns the index of the first visible column based on the scroll + position. + */ + size_t GetVisibleColumnsBegin() const; + + /** + Returns the index of the last visible column based on the scroll + position. This includes the last column even if it is only partially + visible. + */ + size_t GetVisibleColumnsEnd() const; + + /** + Returns @true if the given column is currently visible (even if only + partially visible) or @false otherwise. + */ + bool IsColumnVisible(size_t column) const; + + /** + This function must be overridden in the derived class, and should + return the width of the given column in pixels. + */ + virtual wxCoord OnGetColumnWidth(size_t column) const; + + /** + This function doesn't have to be overridden but it may be useful to do + so if calculating the columns' sizes is a relatively expensive + operation as it gives your code a chance to calculate several of them + at once and cache the result if necessary. + + OnGetColumnsWidthHint() is normally called just before + OnGetColumnWidth() but you shouldn't rely on the latter being called + for all columns in the interval specified here. It is also possible + that OnGetColumnWidth() will be called for units outside of this + interval, so this is really just a hint, not a promise. + + Finally, note that @a columnMin is inclusive, while @a columnMax is + exclusive. + */ + virtual void OnGetColumnsWidthHint(size_t columnMin, + size_t columnMax) const; + + /** + Triggers a refresh for just the given column's area of the window if + it's visible. + */ + virtual void RefreshColumn(size_t column); + + /** + Triggers a refresh for the area between the specified range of columns + given (inclusively). + */ + virtual void RefreshColumns(size_t from, size_t to); + + /** + Scroll by the specified number of pages which may be positive (to + scroll right) or negative (to scroll left). + */ + virtual bool ScrollColumnPages(int pages); + + /** + Scroll by the specified number of columns which may be positive (to + scroll right) or negative (to scroll left). + + @return @true if the window was scrolled, @false otherwise (for + example, if we're trying to scroll right but we are already + showing the last column). + */ + virtual bool ScrollColumns(int columns); + + /** + Scroll to the specified column. It will become the first visible column + in the window. + + @return @true if we scrolled the window, @false if nothing was done. + */ + bool ScrollToColumn(size_t column); + + /** + Set the number of columns the window contains. The derived class must + provide the widths for all columns with indices up to the one given + here in it's OnGetColumnWidth() implementation. + + @see GetColumnCount() + */ + void SetColumnCount(size_t columnCount); +}; + + + +/** + @class wxVarHVScrollHelper + @wxheader{vscroll.h} + + This class provides functions wrapping the wxVarHScrollHelper and + wxVarVScrollHelper classes, targeted for scrolling a window in both axis. + Since this class is also the join class of the horizontal and vertical + scrolling functionality, it also addresses some wrappers that help avoid + the need to specify class scope in your wxHVScrolledWindow derived class + when using wxVarScrollHelperBase functionality. + + Like all three of it's scroll helper base classes, this class is mostly + only useful to those classes built into wxWidgets deriving from here, and + this documentation is mostly only provided for referencing the functions + provided by this class. You will likely want to derive your window from + wxHVScrolledWindow rather than from here directly. + + @library{wxcore} + @category{miscwnd} + + @see wxHScrolledWindow, wxHVScrolledWindow, wxVScrolledWindow +*/ +class wxVarHVScrollHelper : public wxVarVScrollHelper, + public wxVarHScrollHelper +{ +public: + /** + Constructor taking the target window to be scrolled by this helper + class. This will attach scroll event handlers to the target window to + catch and handle scroll events appropriately. + */ + wxVarHVScrollHelper(wxWindow* winToScroll); + + /** + With physical scrolling on (when this is @true), the device origin is + changed properly when a wxPaintDC is prepared, children are actually + moved and laid out properly, and the contents of the window (pixels) + are actually moved. When this is @false, you are responsible for + repainting any invalidated areas of the window yourself to account for + the new scroll position. + + @param vscrolling + Specifies if physical scrolling should be turned on when scrolling + vertically. + @param hscrolling + Specifies if physical scrolling should be turned on when scrolling + horizontally. + */ + void EnablePhysicalScrolling(bool vscrolling = true, + bool hscrolling = true); + + /** + Returns the number of columns and rows the target window contains. + + @see SetRowColumnCount() + */ + wxSize GetRowColumnCount() const; + + /** + Returns the index of the first visible column and row based on the + current scroll position. + */ + wxPosition GetVisibleBegin() const; + + /** + Returns the index of the last visible column and row based on the + scroll position. This includes any partially visible columns or rows. + */ + wxPosition GetVisibleEnd() const; + + //@{ + /** + Returns @true if both the given row and column are currently visible + (even if only partially visible) or @false otherwise. + */ + bool IsVisible(size_t row, size_t column) const; + bool IsVisible(const wxPosition& pos) const; + //@} + + //@{ + /** + Triggers a refresh for just the area shared between the given row and + column of the window if it is visible. + */ + virtual void RefreshRowColumn(size_t row, size_t column); + virtual void RefreshRowColumn(const wxPosition& pos); + //@} + + //@{ + /** + Triggers a refresh for the visible area shared between all given rows + and columns (inclusive) of the window. If the target window for both + orientations is the same, the rectangle of cells is refreshed; if the + target windows differ, the entire client size opposite the orientation + direction is refreshed between the specified limits. + */ + virtual void RefreshRowsColumns(size_t fromRow, size_t toRow, + size_t fromColumn, size_t toColumn); + virtual void RefreshRowsColumns(const wxPosition& from, + const wxPosition& to); + //@} + + //@{ + /** + Scroll to the specified row and column. It will become the first + visible row and column in the window. Returns @true if we scrolled the + window, @false if nothing was done. + */ + bool ScrollToRowColumn(size_t row, size_t column); + bool ScrollToRowColumn(const wxPosition& pos); + //@} + + /** + Set the number of rows and columns the target window will contain. The + derived class must provide the sizes for all rows and columns with + indices up to the ones given here in it's OnGetRowHeight() and + OnGetColumnWidth() implementations, respectively. + + @see GetRowColumnCount() + */ + void SetRowColumnCount(size_t rowCount, size_t columnCount); + + //@{ + /** + Returns the virtual scroll unit under the device unit given accounting + for scroll position or @c wxNOT_FOUND (for the row, column, or possibly + both values) if none. + */ + wxPosition VirtualHitTest(wxCoord x, wxCoord y) const; + wxPosition VirtualHitTest(const wxPoint& pos) const; + //@} +}; + + + +/** + @class wxVScrolledWindow + @wxheader{vscroll.h} + + In the name of this class, "V" may stand for "variable" because it can be + used for scrolling rows of variable heights; "virtual", because it is not + necessary to know the heights of all rows in advance -- only those which + are shown on the screen need to be measured; or even "vertical", because + this class only supports scrolling vertically. + + In any case, this is a generalization of wxScrolled which can be only used + when all rows have the same heights. It lacks some other wxScrolled + features however, notably it can't scroll specific pixel sizes of the + window or its exact client area size. + + To use this class, you need to derive from it and implement the + OnGetRowHeight() pure virtual method. You also must call SetRowCount() to + let the base class know how many rows it should display, but from that + moment on the scrolling is handled entirely by wxVScrolledWindow. You only + need to draw the visible part of contents in your @c OnPaint() method as + usual. You should use GetVisibleRowsBegin() and GetVisibleRowsEnd() to + select the lines to display. Note that the device context origin is not + shifted so the first visible row always appears at the point (0, 0) in + physical as well as logical coordinates. + + @section wxWidgets 2.8 Compatibility Functions + + The following functions provide backwards compatibility for applications + originally built using wxVScrolledWindow in 2.6 or 2.8. Originally, + wxVScrolledWindow referred to scrolling "lines". We now use "units" in + wxVarScrollHelperBase to avoid implying any orientation (since the + functions are used for both horizontal and vertical scrolling in derived + classes). And in the new wxVScrolledWindow and wxHScrolledWindow classes, + we refer to them as "rows" and "columns", respectively. This is to help + clear some confusion in not only those classes, but also in + wxHVScrolledWindow where functions are inherited from both. + + You are encouraged to update any existing code using these function to use + the new replacements mentioned below, and avoid using these functions for + any new code as they are deprecated. + + @beginTable + @row2col{ size_t %GetFirstVisibleLine() const, + Deprecated for GetVisibleRowsBegin(). } + @row2col{ size_t %GetLastVisibleLine() const, + Deprecated for GetVisibleRowsEnd(). This function originally had a + slight design flaw in that it was possible to return + (size_t)-1 (ie: a large positive number) if the scroll + position was 0 and the first line wasn't completely visible. } + @row2col{ size_t %GetLineCount() const, + Deprecated for GetRowCount(). } + @row2col{ int %HitTest(wxCoord x\, wxCoord y) const + @n int %HitTest(const wxPoint& pt) const, + Deprecated for VirtualHitTest(). } + @row2col{ virtual wxCoord %OnGetLineHeight(size_t line) const, + Deprecated for OnGetRowHeight(). } + @row2col{ virtual void %OnGetLinesHint(size_t lineMin\, size_t lineMax) const, + Deprecated for OnGetRowsHeightHint(). } + @row2col{ virtual void %RefreshLine(size_t line), + Deprecated for RefreshRow(). } + @row2col{ virtual void %RefreshLines(size_t from\, size_t to), + Deprecated for RefreshRows(). } + @row2col{ virtual bool %ScrollLines(int lines), + Deprecated for ScrollRows(). } + @row2col{ virtual bool %ScrollPages(int pages), + Deprecated for ScrollRowPages(). } + @row2col{ bool %ScrollToLine(size_t line), + Deprecated for ScrollToRow(). } + @row2col{ void %SetLineCount(size_t count), + Deprecated for SetRowCount(). } + @endTable + + @library{wxcore} + @category{miscwnd} + + @see wxHScrolledWindow, wxHVScrolledWindow +*/ +class wxVScrolledWindow : public wxPanel, public wxVarVScrollHelper +{ +public: + /** + Default constructor, you must call Create() later. + */ + wxVScrolledWindow(); + /** + This is the normal constructor, no need to call Create() after using + this constructor. + + @note @c wxVSCROLL is always automatically added to the style, there is + no need to specify it explicitly. + + @param parent + The parent window, must not be @NULL. + @param id + The identifier of this window, wxID_ANY by default. + @param pos + The initial window position. + @param size + The initial window size. + @param style + The window style. There are no special style bits defined for this + class. + @param name + The name for this window; usually not used. + */ + wxVScrolledWindow(wxWindow* parent, wxWindowID id = wxID_ANY, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, long style = 0, + const wxString& name = wxPanelNameStr); + + /** + Same as the non-default constuctor, but returns a status code: @true if + ok, @false if the window couldn't be created. + + Just as with the constructor, the @c wxVSCROLL style is always used, + there is no need to specify it explicitly. + */ + bool Create(wxWindow* parent, wxWindowID id = wxID_ANY, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, long style = 0, + const wxString& name = wxPanelNameStr); +}; + + + +/** + @class wxHScrolledWindow + @wxheader{vscroll.h} + + In the name of this class, "H" stands for "horizontal" because it can be + used for scrolling columns of variable widths. It is not necessary to know + the widths of all columns in advance -- only those which are shown on the + screen need to be measured. + + In any case, this is a generalization of wxScrolled which can be only used + when all columns have the same widths. It lacks some other wxScrolled + features however, notably it can't scroll specific pixel sizes of the + window or its exact client area size. + + To use this class, you need to derive from it and implement the + OnGetColumnWidth() pure virtual method. You also must call SetColumnCount() + to let the base class know how many columns it should display, but from + that moment on the scrolling is handled entirely by wxHScrolledWindow. You + only need to draw the visible part of contents in your @c OnPaint() method + as usual. You should use GetVisibleColumnsBegin() and + GetVisibleColumnsEnd() to select the lines to display. Note that the device + context origin is not shifted so the first visible column always appears at + the point (0, 0) in physical as well as logical coordinates. + + @library{wxcore} + @category{miscwnd} + + @see wxHVScrolledWindow, wxVScrolledWindow +*/ +class wxHScrolledWindow : public wxPanel, public wxVarHScrollHelper +{ +public: + /** + Default constructor, you must call Create() later. + */ + wxHScrolledWindow(); + /** + This is the normal constructor, no need to call Create() after using + this constructor. + + @note @c wxHSCROLL is always automatically added to the style, there is + no need to specify it explicitly. + + @param parent + The parent window, must not be @NULL. + @param id + The identifier of this window, wxID_ANY by default. + @param pos + The initial window position. + @param size + The initial window size. + @param style + The window style. There are no special style bits defined for this + class. + @param name + The name for this window; usually not used. + */ + wxHScrolledWindow(wxWindow* parent, wxWindowID id = wxID_ANY, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, long style = 0, + const wxString& name = wxPanelNameStr); + + /** + Same as the non-default constuctor, but returns a status code: @true if + ok, @false if the window couldn't be created. + + Just as with the constructor, the @c wxHSCROLL style is always used, + there is no need to specify it explicitly. + */ + bool Create(wxWindow* parent, wxWindowID id = wxID_ANY, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, long style = 0, + const wxString& name = wxPanelNameStr); +}; + + + +/** + @class wxHVScrolledWindow + @wxheader{vscroll.h} + + This window inherits all functionality of both vertical and horizontal, + variable scrolled windows. It automatically handles everything needed to + scroll both axis simultaneously with both variable row heights and variable + column widths. + + In any case, this is a generalization of wxScrolled which can be only used + when all rows and columns are the same size. It lacks some other wxScrolled + features however, notably it can't scroll specific pixel sizes of the + window or its exact client area size. + + To use this class, you must derive from it and implement both the + OnGetRowHeight() and OnGetColumnWidth() pure virtual methods to let the + base class know how many rows and columns it should display. You also need + to set the total rows and columns the window contains, but from that moment + on the scrolling is handled entirely by wxHVScrolledWindow. You only need + to draw the visible part of contents in your @c OnPaint() method as usual. + You should use GetVisibleBegin() and GetVisibleEnd() to select the lines to + display. Note that the device context origin is not shifted so the first + visible row and column always appear at the point (0, 0) in physical as + well as logical coordinates. + + @library{wxcore} + @category{miscwnd} + + @see wxHScrolledWindow, wxVScrolledWindow +*/ +class wxHVScrolledWindow : public wxPanel, public wxVarHVScrollHelper +{ +public: + /** + Default constructor, you must call Create() later. + */ + wxHVScrolledWindow(); + /** + This is the normal constructor, no need to call Create() after using + this constructor. + + @note @c wxHSCROLL and @c wxVSCROLL are always automatically added to + the style, there is no need to specify it explicitly. + + @param parent + The parent window, must not be @NULL. + @param id + The identifier of this window, wxID_ANY by default. + @param pos + The initial window position. + @param size + The initial window size. + @param style + The window style. There are no special style bits defined for this + class. + @param name + The name for this window; usually not used. + */ + wxHVScrolledWindow(wxWindow* parent, wxWindowID id = wxID_ANY, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, long style = 0, + const wxString& name = wxPanelNameStr); + + /** + Same as the non-default constuctor, but returns a status code: @true if + ok, @false if the window couldn't be created. + + Just as with the constructor, the @c wxHSCROLL and @c wxVSCROLL styles + are always used, there is no need to specify them explicitly. + */ + bool Create(wxWindow* parent, wxWindowID id = wxID_ANY, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, long style = 0, + const wxString& name = wxPanelNameStr); +}; + diff --git a/interface/wx/weakref.h b/interface/wx/weakref.h new file mode 100644 index 0000000000..f6522aa399 --- /dev/null +++ b/interface/wx/weakref.h @@ -0,0 +1,166 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: weakref.h +// Purpose: interface of wxWeakRefDynamic +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @wxheader{weakref.h} + + wxWeakRefDynamic is a template class for weak references that is used in + the same way as wxWeakRef. The only difference is that wxWeakRefDynamic + defaults to using @c dynamic_cast for establishing the object + reference (while wxWeakRef defaults to @c static_cast). + + So, wxWeakRef will detect a type mismatch during compile time and will + have a little better run-time performance. The role of wxWeakRefDynamic + is to handle objects which derived type one does not know. + + @note wxWeakRef selects an implementation based on the static type + of T. If T does not have wxTrackable statically, it defaults to to a mixed- + mode operation, where it uses @c dynamic_cast as the last measure (if + available from the compiler and enabled when building wxWidgets). + + For general cases, wxWeakRef is the better choice. + + For API documentation, see: wxWeakRef + + @library{wxcore} + @category{FIXME} +*/ +template +class wxWeakRefDynamic +{ +public: + +}; + + + +/** + @wxheader{weakref.h} + + wxWeakRef is a template class for weak references to wxWidgets objects, + such as wxEvtHandler, wxWindow and + wxObject. A weak reference behaves much like an ordinary + pointer, but when the object pointed is destroyed, the weak reference is + automatically reset to a @NULL pointer. + + wxWeakRef can be used whenever one must keep a pointer to an object + that one does not directly own, and that may be destroyed before the object + holding the reference. + + wxWeakRef is a small object and the mechanism behind it is fast + (@b O(1)). So the overall cost of using it is small. + + Example + + @code + wxWindow *wnd = new wxWindow( parent, wxID_ANY, "wxWindow" ); + wxWeakRef wr = wnd; + wxWindowRef wr2 = wnd; // Same as above, but using a typedef + // Do things with window + wnd->Show( true ); + // Weak ref is used like an ordinary pointer + wr->Show( false ); + wnd->Destroy(); + // Now the weak ref has been reset, so we don't risk accessing + // a dangling pointer: + wxASSERT( wr==NULL ); + @endcode + + wxWeakRef works for any objects that are derived from wxTrackable. By default, + wxEvtHandler and wxWindow derive from wxTrackable. However, wxObject does not, so + types like wxFont and wxColour are not trackable. The example below shows how to + create a wxObject derived class that is trackable: + + @code + class wxMyTrackableObject : public wxObject, public wxTrackable + { + // ... other members here + }; + @endcode + + The following types of weak references are predefined: + + @code + typedef wxWeakRef wxEvtHandlerRef; + typedef wxWeakRef wxWindowRef; + @endcode + + + @library{wxbase} + @category{FIXME} + + @see wxSharedPtr, wxScopedPtr +*/ +template +class wxWeakRef +{ +public: + /** + Constructor. The weak reference is initialized to @e pobj. + */ + wxWeakRef(T* pobj = NULL); + + /** + Copy constructor. + */ + wxWeakRef(const wxWeakRef& wr); + + /** + Destructor. + */ + ~wxWeakRef(); + + /** + Called when the tracked object is destroyed. Be default sets + internal pointer to @NULL. You need to call this method if + you override it. + */ + virtual void OnObjectDestroy(); + + /** + Release currently tracked object and rests object reference. + */ + void Release(); + + /** + Returns pointer to the tracked object or @NULL. + */ + T* get() const; + + /** + Release currently tracked object and start tracking the same object as + the wxWeakRef @e wr. + */ + T* operator =(wxWeakRef& wr); + + /** + Implicit conversion to T*. Returns pointer to the tracked + object or @NULL. + */ + T* operator*() const; + + /** + Returns a reference to the tracked object. If the internal pointer is @NULL + this method will cause an assert in debug mode. + */ + T operator*() const; + + /** + Smart pointer member access. Returns a pointer to the + tracked object. If the internal pointer is @NULL this + method will cause an assert in debug mode. + */ + T* operator-(); + + /** + Releases the currently tracked object and starts tracking @e pobj. + A weak reference may be reset by passing @e @NULL as @e pobj. + */ + T* operator=(T* pobj); +}; + diff --git a/interface/wx/wfstream.h b/interface/wx/wfstream.h new file mode 100644 index 0000000000..de501d0490 --- /dev/null +++ b/interface/wx/wfstream.h @@ -0,0 +1,269 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: wfstream.h +// Purpose: interface of wxTempFileOutputStream +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxTempFileOutputStream + @wxheader{wfstream.h} + + wxTempFileOutputStream is an output stream based on wxTempFile. It + provides a relatively safe way to replace the contents of the + existing file. + + @library{wxbase} + @category{streams} + + @see wxTempFile +*/ +class wxTempFileOutputStream : public wxOutputStream +{ +public: + /** + Associates wxTempFileOutputStream with the file to be replaced and opens it. + You should use + wxStreamBase::IsOk to verify if the constructor succeeded. + Call Commit() or wxOutputStream::Close to + replace the old file and close this one. Calling Discard() + (or allowing the destructor to do it) will discard the changes. + */ + wxTempFileOutputStream(const wxString& fileName); + + /** + Validate changes: deletes the old file of the given name and renames the new + file to the old name. Returns @true if both actions succeeded. If @false is + returned it may unfortunately mean two quite different things: either that + either the old file couldn't be deleted or that the new file couldn't be renamed + to the old name. + */ + bool Commit(); + + /** + Discard changes: the old file contents are not changed, the temporary file is + deleted. + */ + void Discard(); +}; + + + +/** + @class wxFFileOutputStream + @wxheader{wfstream.h} + + This class represents data written to a file. There are actually + two such groups of classes: this one is based on wxFFile + whereas wxFileInputStream is based in + the wxFile class. + + Note that wxOutputStream::SeekO + can seek beyond the end of the stream (file) and will thus not return + @e wxInvalidOffset for that. + + @library{wxbase} + @category{streams} + + @see wxBufferedOutputStream, wxFFileInputStream, wxFileInputStream +*/ +class wxFFileOutputStream : public wxOutputStream +{ +public: + //@{ + /** + Initializes a file stream in write-only mode using the file descriptor @e fp. + */ + wxFFileOutputStream(const wxString& filename, + const wxString& mode = "wb"); + wxFFileOutputStream(wxFFile& file); + wxFFileOutputStream(FILE* fp); + //@} + + /** + Destructor. + */ + ~wxFFileOutputStream(); + + /** + Returns @true if the stream is initialized and ready. + */ + bool IsOk() const; +}; + + + +/** + @class wxFileOutputStream + @wxheader{wfstream.h} + + This class represents data written to a file. There are actually + two such groups of classes: this one is based on wxFile + whereas wxFFileInputStream is based in + the wxFFile class. + + Note that wxOutputStream::SeekO + can seek beyond the end of the stream (file) and will thus not return + @e wxInvalidOffset for that. + + @library{wxbase} + @category{streams} + + @see wxBufferedOutputStream, wxFileInputStream, wxFFileInputStream +*/ +class wxFileOutputStream : public wxOutputStream +{ +public: + //@{ + /** + Initializes a file stream in write-only mode using the file descriptor @e fd. + */ + wxFileOutputStream(const wxString& ofileName); + wxFileOutputStream(wxFile& file); + wxFileOutputStream(int fd); + //@} + + /** + Destructor. + */ + ~wxFileOutputStream(); + + /** + Returns @true if the stream is initialized and ready. + */ + bool IsOk() const; +}; + + + +/** + @class wxFileInputStream + @wxheader{wfstream.h} + + This class represents data read in from a file. There are actually + two such groups of classes: this one is based on wxFile + whereas wxFFileInputStream is based in + the wxFFile class. + + Note that wxInputStream::SeekI + can seek beyond the end of the stream (file) and will thus not return + @e wxInvalidOffset for that. + + @library{wxbase} + @category{streams} + + @see wxBufferedInputStream, wxFileOutputStream, wxFFileOutputStream +*/ +class wxFileInputStream : public wxInputStream +{ +public: + //@{ + /** + Initializes a file stream in read-only mode using the specified file descriptor. + */ + wxFileInputStream(const wxString& ifileName); + wxFileInputStream(wxFile& file); + wxFileInputStream(int fd); + //@} + + /** + Destructor. + */ + ~wxFileInputStream(); + + /** + Returns @true if the stream is initialized and ready. + */ + bool IsOk() const; +}; + + + +/** + @class wxFFileInputStream + @wxheader{wfstream.h} + + This class represents data read in from a file. There are actually + two such groups of classes: this one is based on wxFFile + whereas wxFileInputStream is based in + the wxFile class. + + Note that wxInputStream::SeekI + can seek beyond the end of the stream (file) and will thus not return + @e wxInvalidOffset for that. + + @library{wxbase} + @category{streams} + + @see wxBufferedInputStream, wxFFileOutputStream, wxFileOutputStream +*/ +class wxFFileInputStream : public wxInputStream +{ +public: + //@{ + /** + Initializes a file stream in read-only mode using the specified file pointer @e + fp. + */ + wxFFileInputStream(const wxString& filename, + const wxString& mode = "rb"); + wxFFileInputStream(wxFFile& file); + wxFFileInputStream(FILE* fp); + //@} + + /** + Destructor. + */ + ~wxFFileInputStream(); + + /** + Returns @true if the stream is initialized and ready. + */ + bool IsOk() const; +}; + + + +/** + @class wxFFileStream + @wxheader{wfstream.h} + + + @library{wxbase} + @category{FIXME} + + @see wxStreamBuffer +*/ +class wxFFileStream : public wxFFileOutputStream +{ +public: + /** + Initializes a new file stream in read-write mode using the specified + @e iofilename name. + */ + wxFFileStream(const wxString& iofileName, const wxString& mode = "w+b"); +}; + + + +/** + @class wxFileStream + @wxheader{wfstream.h} + + + @library{wxbase} + @category{FIXME} + + @see wxStreamBuffer +*/ +class wxFileStream : public wxFileOutputStream +{ +public: + /** + Initializes a new file stream in read-write mode using the specified + @e iofilename name. + */ + wxFileStream(const wxString& iofileName); +}; + diff --git a/interface/wx/window.h b/interface/wx/window.h new file mode 100644 index 0000000000..2161f7dda8 --- /dev/null +++ b/interface/wx/window.h @@ -0,0 +1,2659 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: window.h +// Purpose: interface of wxWindow +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxWindow + @wxheader{window.h} + + wxWindow is the base class for all windows and represents any visible object on + screen. All controls, top level windows and so on are windows. Sizers and + device contexts are not, however, as they don't appear on screen themselves. + + Please note that all children of the window will be deleted automatically by + the destructor before the window itself is deleted which means that you don't + have to worry about deleting them manually. Please see the @ref + overview_windowdeletion "window deletion overview" for more information. + + Also note that in this, and many others, wxWidgets classes some + @c GetXXX() methods may be overloaded (as, for example, + wxWindow::GetSize or wxWindow::GetClientSize). In this case, the overloads + are non-virtual because having multiple virtual functions with the same name + results in a virtual function name hiding at the derived class level (in + English, this means that the derived class has to override all overloaded + variants if it overrides any of them). To allow overriding them in the derived + class, wxWidgets uses a unique protected virtual @c DoGetXXX() method + and all @c GetXXX() ones are forwarded to it, so overriding the former + changes the behaviour of the latter. + + @beginStyleTable + @style{wxBORDER_DEFAULT} + The window class will decide the kind of border to show, if any. + @style{wxBORDER_SIMPLE} + Displays a thin border around the window. wxSIMPLE_BORDER is the + old name for this style. + @style{wxBORDER_SUNKEN} + Displays a sunken border. wxSUNKEN_BORDER is the old name for this + style. + @style{wxBORDER_RAISED} + Displays a raised border. wxRAISED_BORDER is the old name for this + style. + @style{wxBORDER_STATIC} + Displays a border suitable for a static control. wxSTATIC_BORDER + is the old name for this style. Windows only. + @style{wxBORDER_THEME} + Displays a native border suitable for a control, on the current + platform. On Windows XP or Vista, this will be a themed border; on + most other platforms a sunken border will be used. For more + information for themed borders on Windows, please see Themed + borders on Windows. + @style{wxBORDER_NONE} + Displays no border, overriding the default border style for the + window. wxNO_BORDER is the old name for this style. + @style{wxBORDER_DOUBLE} + This style is obsolete and should not be used. + @style{wxTRANSPARENT_WINDOW} + The window is transparent, that is, it will not receive paint + events. Windows only. + @style{wxTAB_TRAVERSAL} + Use this to enable tab traversal for non-dialog windows. + @style{wxWANTS_CHARS} + Use this to indicate that the window wants to get all char/key + events for all keys - even for keys like TAB or ENTER which are + usually used for dialog navigation and which wouldn't be generated + without this style. If you need to use this style in order to get + the arrows or etc., but would still like to have normal keyboard + navigation take place, you should call Navigate in response to the + key events for Tab and Shift-Tab. + @style{wxNO_FULL_REPAINT_ON_RESIZE} + On Windows, this style used to disable repainting the window + completely when its size is changed. Since this behaviour is now + the default, the style is now obsolete and no longer has an effect. + @style{wxVSCROLL} + Use this style to enable a vertical scrollbar. Notice that this + style cannot be used with native controls which don't support + scrollbars nor with top-level windows in most ports. + @style{wxHSCROLL} + Use this style to enable a horizontal scrollbar. The same + limitations as for wxVSCROLL apply to this style. + @style{wxALWAYS_SHOW_SB} + If a window has scrollbars, disable them instead of hiding them + when they are not needed (i.e. when the size of the window is big + enough to not require the scrollbars to navigate it). This style is + currently implemented for wxMSW, wxGTK and wxUniversal and does + nothing on the other platforms. + @style{wxCLIP_CHILDREN} + Use this style to eliminate flicker caused by the background being + repainted, then children being painted over them. Windows only. + @style{wxFULL_REPAINT_ON_RESIZE} + Use this style to force a complete redraw of the window whenever it + is resized instead of redrawing just the part of the window + affected by resizing. Note that this was the behaviour by default + before 2.5.1 release and that if you experience redraw problems + with code which previously used to work you may want to try this. + Currently this style applies on GTK+ 2 and Windows only, and full + repainting is always done on other platforms. + @endStyleTable + + @beginExtraStyleTable + @style{wxWS_EX_VALIDATE_RECURSIVELY} + By default, Validate/TransferDataTo/FromWindow() only work on + direct children of the window (compatible behaviour). Set this flag + to make them recursively descend into all subwindows. + @style{wxWS_EX_BLOCK_EVENTS} + wxCommandEvents and the objects of the derived classes are + forwarded to the parent window and so on recursively by default. + Using this flag for the given window allows to block this + propagation at this window, i.e. prevent the events from being + propagated further upwards. Dialogs have this flag on by default. + @style{wxWS_EX_TRANSIENT} + Don't use this window as an implicit parent for the other windows: + this must be used with transient windows as otherwise there is the + risk of creating a dialog/frame with this window as a parent which + would lead to a crash if the parent is destroyed before the child. + @style{wxWS_EX_PROCESS_IDLE} + This window should always process idle events, even if the mode set + by wxIdleEvent::SetMode is wxIDLE_PROCESS_SPECIFIED. + @style{wxWS_EX_PROCESS_UI_UPDATES} + This window should always process UI update events, even if the + mode set by wxUpdateUIEvent::SetMode is + wxUPDATE_UI_PROCESS_SPECIFIED. + @endExtraStyleTable + + @library{wxcore} + @category{FIXME} + + @see @ref overview_eventhandling "Event handling overview", + @ref overview_windowsizing "Window sizing overview" +*/ +class wxWindow : public wxEvtHandler +{ +public: + /** + Default constructor + */ + wxWindow(); + + /** + Constructs a window, which can be a child of a frame, dialog or any other + non-control window. + + @param parent + Pointer to a parent window. + @param id + Window identifier. If wxID_ANY, will automatically create an identifier. + @param pos + Window position. wxDefaultPosition indicates that wxWidgets + should generate a default position for the window. If using the wxWindow + class directly, supply + an actual position. + @param size + Window size. wxDefaultSize indicates that wxWidgets + should generate a default size for the window. If no suitable size can be + found, the + window will be sized to 20x20 pixels so that the window is visible but + obviously not + correctly sized. + @param style + Window style. For generic window styles, please see wxWindow. + @param name + Window name. + */ + wxWindow(wxWindow* parent, wxWindowID id, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = 0, + const wxString& name = wxPanelNameStr); + + /** + Destructor. Deletes all sub-windows, then deletes itself. Instead of using + the @b delete operator explicitly, you should normally + use Destroy() so that wxWidgets + can delete a window only when it is safe to do so, in idle time. + + @see @ref overview_windowdeletion "Window Deletion Overview", + Destroy(), wxCloseEvent + */ + ~wxWindow(); + + /** + This method may be overridden in the derived classes to return @false to + indicate that this control doesn't accept input at all (i.e. behaves like e.g. + wxStaticText) and so doesn't need focus. + + @see AcceptsFocusFromKeyboard() + */ + virtual bool AcceptsFocus() const; + + /** + This method may be overridden in the derived classes to return @false to + indicate that while this control can, in principle, have focus if the user + clicks it with the mouse, it shouldn't be included in the TAB traversal chain + when using the keyboard. + */ + virtual bool AcceptsFocusFromKeyboard() const; + + /** + Overridden to indicate wehter this window or one of its children accepts + focus. Usually it's the same as AcceptsFocus() but is overridden for + container windows + */ + virtual bool AcceptsFocusRecursively() const; + + /** + Adds a child window. This is called automatically by window creation + functions so should not be required by the application programmer. + Notice that this function is mostly internal to wxWidgets and shouldn't be + called by the user code. + + @param child + Child window to add. + */ + virtual void AddChild(wxWindow* child); + + /** + Call this function to force one or both scrollbars to be always shown, even if + the window is big enough to show its entire contents without scrolling. + + @since 2.9.0 + + @param hflag + Whether the horizontal scroll bar should always be visible. + @param vflag + Whether the vertical scroll bar should always be visible. + + @remarks This function is currently only implemented under Mac/Carbon. + */ + void AlwaysShowScrollbars(bool hflag, bool vflag); + + /** + Sets the cached best size value. + */ + void CacheBestSize(const wxSize& size) const; + + /** + Returns @true if the system supports transparent windows and calling + SetTransparent() may succeed. If this function + returns @false, transparent windows are definitely not supported by the + current + system. + */ + bool CanSetTransparent(); + + /** + Directs all mouse input to this window. Call ReleaseMouse() to + release the capture. + Note that wxWidgets maintains the stack of windows having captured the mouse + and when the mouse is released the capture returns to the window which had had + captured it previously and it is only really released if there were no previous + window. In particular, this means that you must release the mouse as many times + as you capture it, unless the window receives + the wxMouseCaptureLostEvent event. + Any application which captures the mouse in the beginning of some operation + must handle wxMouseCaptureLostEvent + and cancel this operation when it receives the event. The event handler must + not recapture mouse. + + @see ReleaseMouse(), wxMouseCaptureLostEvent + */ + virtual void CaptureMouse(); + + /** + A synonym for Centre(). + */ + void Center(int direction); + + /** + A synonym for CentreOnParent(). + */ + void CenterOnParent(int direction); + + /** + Centres the window. + + @param direction + Specifies the direction for the centering. May be wxHORIZONTAL, wxVERTICAL + or wxBOTH. It may also include wxCENTRE_ON_SCREEN flag + if you want to center the window on the entire screen and not on its + parent window. + + @remarks If the window is a top level one (i.e. doesn't have a parent), + it will be centered relative to the screen anyhow. + + @see Center() + */ + void Centre(int direction = wxBOTH); + + /** + Centres the window on its parent. This is a more readable synonym for + Centre(). + + @param direction + Specifies the direction for the centering. May be wxHORIZONTAL, wxVERTICAL + or wxBOTH. + + @remarks This methods provides for a way to center top level windows over + their parents instead of the entire screen. If there + is no parent or if the window is not a top level + window, then behaviour is the same as Centre(). + + @see wxTopLevelWindow::CentreOnScreen + */ + void CentreOnParent(int direction = wxBOTH); + + /** + Clears the window by filling it with the current background colour. Does not + cause an erase background event to be generated. + */ + void ClearBackground(); + + //@{ + /** + Converts to screen coordinates from coordinates relative to this window. + + @param x + A pointer to a integer value for the x coordinate. Pass the client + coordinate in, and + a screen coordinate will be passed out. + @param y + A pointer to a integer value for the y coordinate. Pass the client + coordinate in, and + a screen coordinate will be passed out. + @param pt + The client position for the second form of the function. + */ + void ClientToScreen(int* x, int* y) const; + wxPoint ClientToScreen(const wxPoint& pt) const; + //@} + + /** + Converts client area size @a size to corresponding window size. In + other words, the returned value is what would GetSize() return if this + window had client area of given size. Components with wxDefaultCoord + value are left unchanged. Note that the conversion is not always + exact, it assumes that non-client area doesn't change and so doesn't + take into account things like menu bar (un)wrapping or (dis)appearance + of the scrollbars. + + @since 2.8.8 + + @see WindowToClientSize() + */ + virtual wxSize ClientToWindowSize(const wxSize& size); + + /** + Converts window size @a size to corresponding client area size. In + other words, the returned value is what would GetClientSize() return if + this window had given window size. Components with wxDefaultCoord value + are left unchanged. + + Note that the conversion is not always exact, it assumes that + non-client area doesn't change and so doesn't take into account things + like menu bar (un)wrapping or (dis)appearance of the scrollbars. + + @since 2.8.8 + + @see ClientToWindowSize() + */ + virtual wxSize WindowToClientSize(const wxSize& size); + + /** + This function simply generates a wxCloseEvent whose + handler usually tries to close the window. It doesn't close the window + itself, however. + + @param force + @false if the window's close handler should be able to veto the destruction + of this window, @true if it cannot. + + @remarks Close calls the close handler for the window, providing an + opportunity for the window to choose whether to destroy + the window. Usually it is only used with the top level + windows (wxFrame and wxDialog classes) as the others + are not supposed to have any special OnClose() logic. + + @see @ref overview_windowdeletion "Window Deletion Overview", + Destroy(), wxCloseEvent + */ + bool Close(bool force = false); + + //@{ + /** + Converts a point or size from dialog units to pixels. + For the x dimension, the dialog units are multiplied by the average character + width + and then divided by 4. + For the y dimension, the dialog units are multiplied by the average character + height + and then divided by 8. + + @remarks Dialog units are used for maintaining a dialog's proportions + even if the font changes. + + @see ConvertPixelsToDialog() + */ + wxPoint ConvertDialogToPixels(const wxPoint& pt); + wxSize ConvertDialogToPixels(const wxSize& sz); + //@} + + //@{ + /** + Converts a point or size from pixels to dialog units. + For the x dimension, the pixels are multiplied by 4 and then divided by the + average + character width. + For the y dimension, the pixels are multiplied by 8 and then divided by the + average + character height. + + @remarks Dialog units are used for maintaining a dialog's proportions + even if the font changes. + + @see ConvertDialogToPixels() + */ + wxPoint ConvertPixelsToDialog(const wxPoint& pt); + wxSize ConvertPixelsToDialog(const wxSize& sz); + //@} + + /** + Destroys the window safely. Use this function instead of the delete operator, + since + different window classes can be destroyed differently. Frames and dialogs + are not destroyed immediately when this function is called -- they are added + to a list of windows to be deleted on idle time, when all the window's events + have been processed. This prevents problems with events being sent to + non-existent + windows. + + @return @true if the window has either been successfully deleted, or it + has been added to the list of windows pending real + deletion. + */ + virtual bool Destroy(); + + /** + Destroys all children of a window. Called automatically by the destructor. + */ + virtual void DestroyChildren(); + + /** + Disables the window. Same as @ref Enable() Enable(@false). + + @return Returns @true if the window has been disabled, @false if it had + been already disabled before the call to this function. + */ + bool Disable(); + + /** + Gets the size which best suits the window: for a control, it would be + the minimal size which doesn't truncate the control, for a panel - the + same size as it would have after a call to Fit(). + + The default implementation of this function is designed for use in container + windows, such as wxPanel, and works something like this: + -# If the window has a sizer then it is used to calculate the best size. + -# Otherwise if the window has layout constraints then those are used to + calculate the best size. + -# Otherwise if the window has children then the best size is set to be large + enough to show all the children. + -# Otherwise if there are no children then the window's minimal size will be + used as its best size. + -# Otherwise if there is no minimal size set, then the current size is used + for the best size. + + @see @ref overview_windowsizing + */ + virtual wxSize DoGetBestSize() const; + + /** + Does the window-specific updating after processing the update event. + This function is called by UpdateWindowUI() in order to check return + values in the wxUpdateUIEvent and act appropriately. + */ + virtual void DoUpdateWindowUI(wxUpdateUIEvent& event); + + /** + Enables or disables eligibility for drop file events (OnDropFiles). + + @param accept + If @true, the window is eligible for drop file events. If @false, the window + will not accept drop file events. + + @remarks Windows only. + */ + virtual void DragAcceptFiles(bool accept); + + /** + Enable or disable the window for user input. Note that when a parent window is + disabled, all of its children are disabled as well and they are reenabled again + when the parent is. + + @param enable + If @true, enables the window for input. If @false, disables the window. + + @return Returns @true if the window has been enabled or disabled, @false + if nothing was done, i.e. if the window had already + been in the specified state. + + @see IsEnabled(), Disable(), wxRadioBox::Enable + */ + virtual bool Enable(bool enable = true); + + /** + Finds the window or control which currently has the keyboard focus. + + @remarks Note that this is a static function, so it can be called without + needing a wxWindow pointer. + + @see SetFocus(), HasFocus() + */ + static wxWindow* FindFocus(); + + /** + Find a child of this window, by @a id. May return @a this if + it matches itself. + */ + wxWindow* FindWindow(long id) const; + + + /** + Find a child of this window, by name. May return @a this if + it matches itself. + */ + wxWindow* FindWindow(const wxString& name) const; + + /** + Find the first window with the given @e id. + If @a parent is @NULL, the search will start from all top-level + frames and dialog boxes; if non-@NULL, the search will be limited to the given + window hierarchy. + The search is recursive in both cases. + + @see FindWindow() + */ + static wxWindow* FindWindowById(long id, wxWindow* parent = NULL); + + /** + Find a window by its label. Depending on the type of window, the label may be a + window title + or panel item label. If @a parent is @NULL, the search will start from all + top-level + frames and dialog boxes; if non-@NULL, the search will be limited to the given + window hierarchy. + The search is recursive in both cases. + + @see FindWindow() + */ + static wxWindow* FindWindowByLabel(const wxString& label, + wxWindow* parent = NULL); + + /** + Find a window by its name (as given in a window constructor or @b Create + function call). + If @a parent is @NULL, the search will start from all top-level + frames and dialog boxes; if non-@NULL, the search will be limited to the given + window hierarchy. + The search is recursive in both cases. + If no window with such name is found, + FindWindowByLabel() is called. + + @see FindWindow() + */ + static wxWindow* FindWindowByName(const wxString& name, + wxWindow* parent = NULL); + + /** + Sizes the window so that it fits around its subwindows. + + This function won't do anything if there are no subwindows and will only really + work correctly if sizers are used for the subwindows layout. + + Also, if the window has exactly one subwindow it is better (faster and the result + is more precise as Fit() adds some margin to account for fuzziness of its calculations) + to call: + + @code + window->SetClientSize(child->GetSize()); + @endcode + + instead of calling Fit(). + + @see @ref overview_windowsizing + */ + virtual void Fit(); + + /** + Similar to Fit(), but sizes the interior (virtual) size + of a window. Mainly useful with scrolled windows to reset scrollbars after + sizing changes that do not trigger a size event, and/or scrolled windows without + an interior sizer. This function similarly won't do anything if there are no + subwindows. + */ + virtual void FitInside(); + + /** + Freezes the window or, in other words, prevents any updates from taking + place on screen, the window is not redrawn at all. + + Thaw() must be called to reenable window redrawing. Calls to these two + functions may be nested but to ensure that the window is properly + repainted again, you must thaw it exactly as many times as you froze + it. + + If the window has any children, they are recursively frozen too. + + This method is useful for visual appearance optimization (for example, + it is a good idea to use it before doing many large text insertions in + a row into a wxTextCtrl under wxGTK) but is not implemented on all + platforms nor for all controls so it is mostly just a hint to wxWidgets + and not a mandatory directive. + + @see wxWindowUpdateLocker, Thaw(), IsFrozen() + */ + virtual void Freeze(); + + /** + Gets the accelerator table for this window. See wxAcceleratorTable. + */ + wxAcceleratorTable* GetAcceleratorTable() const; + + /** + Returns the accessible object for this window, if any. + See also wxAccessible. + */ + wxAccessible* GetAccessible(); + + /** + This method is deprecated, use GetEffectiveMinSize() instead. + */ + wxSize GetAdjustedBestSize() const; + + /** + Returns the background colour of the window. + + @see SetBackgroundColour(), SetForegroundColour(), + GetForegroundColour() + */ + wxColour GetBackgroundColour() const; + + /** + Returns the background style of the window. The background style can be one of: + + wxBG_STYLE_SYSTEM + + Use the default background, as determined by + the system or the current theme. + + wxBG_STYLE_COLOUR + + Use a solid colour for the background, this + style is set automatically if you call + SetBackgroundColour() so you only need to + set it explicitly if you had changed the background style to something else + before. + + wxBG_STYLE_CUSTOM + + Don't draw the background at all, it's + supposed that it is drawn by the user-defined erase background event handler. + This style should be used to avoid flicker when the background is entirely + custom-drawn. + + wxBG_STYLE_TRANSPARET + + The background is (partially) transparent, + this style is automatically set if you call + SetTransparent() which is used to set the + transparency level. + + @see SetBackgroundColour(), GetForegroundColour(), + SetBackgroundStyle(), SetTransparent() + */ + virtual wxBackgroundStyle GetBackgroundStyle() const; + + /** + This functions returns the best acceptable minimal size for the window. For + example, for a static control, it will be the minimal size such that the + control label is not truncated. For windows containing subwindows (typically + wxPanel), the size returned by this function will be the + same as the size the window would have had after calling + Fit(). + */ + wxSize GetBestSize() const; + + /** + Returns the currently captured window. + + @see HasCapture(), CaptureMouse(), ReleaseMouse(), + wxMouseCaptureLostEvent, wxMouseCaptureChangedEvent + */ + static wxWindow* GetCapture(); + + /** + Returns the caret() associated with the window. + */ + wxCaret* GetCaret() const; + + /** + Returns the character height for this window. + */ + virtual int GetCharHeight() const; + + /** + Returns the average character width for this window. + */ + virtual int GetCharWidth() const; + + //@{ + /** + Returns a reference to the list of the window's children. @c wxWindowList + is a type-safe wxList-like class whose elements are of type @c wxWindow*. + */ + wxWindowList& GetChildren(); + const wxWindowList& GetChildren() const; + //@} + + /** + Returns the default font and colours which are used by the control. This is + useful if you want to use the same font or colour in your own control as in a + standard control -- which is a much better idea than hard coding specific + colours or fonts which might look completely out of place on the users + system, especially if it uses themes. + The @a variant parameter is only relevant under Mac currently and is + ignore under other platforms. Under Mac, it will change the size of the + returned font. See SetWindowVariant() + for more about this. + This static method is "overridden" in many derived classes and so calling, + for example, wxButton::GetClassDefaultAttributes() will typically + return the values appropriate for a button which will be normally different + from those returned by, say, wxListCtrl::GetClassDefaultAttributes(). + The @c wxVisualAttributes structure has at least the fields + @c font, @c colFg and @c colBg. All of them may be invalid + if it was not possible to determine the default control appearance or, + especially for the background colour, if the field doesn't make sense as is + the case for @c colBg for the controls with themed background. + + @see InheritAttributes() + */ + static wxVisualAttributes GetClassDefaultAttributes(wxWindowVariant variant = wxWINDOW_VARIANT_NORMAL); + + //@{ + /** + Returns the size of the window 'client area' in pixels. The client area is the + area which may be drawn on by the programmer, excluding title bar, border, + scrollbars, etc. + Note that if this window is a top-level one and it is currently minimized, the + return size is empty (both width and height are 0). + + @param width + Receives the client width in pixels. + @param height + Receives the client height in pixels. + + @see GetSize(), GetVirtualSize() + */ + void GetClientSize(int* width, int* height) const; + wxSize GetClientSize() const; + //@} + + /** + Returns a pointer to the window's layout constraints, or @NULL if there are none. + */ + wxLayoutConstraints* GetConstraints() const; + + /** + Return the sizer that this window is a member of, if any, otherwise + @NULL. + */ + wxSizer* GetContainingSizer() const; + + /** + Return the cursor associated with this window. + + @see SetCursor() + */ + const wxCursor& GetCursor() const; + + /** + Currently this is the same as calling + wxWindow::GetClassDefaultAttributes(wxWindow::GetWindowVariant()). + One advantage of using this function compared to the static version is that + the call is automatically dispatched to the correct class (as usual with + virtual functions) and you don't have to specify the class name explicitly. + The other one is that in the future this function could return different + results, for example it might return a different font for an "Ok" button + than for a generic button if the users GUI is configured to show such buttons + in bold font. Of course, the down side is that it is impossible to call this + function without actually having an object to apply it to whereas the static + version can be used without having to create an object first. + */ + virtual wxVisualAttributes GetDefaultAttributes() const; + + /** + Returns the associated drop target, which may be @NULL. + + @see SetDropTarget(), @ref overview_dnd + */ + wxDropTarget* GetDropTarget() const; + + /** + Merges the window's best size into the min size and returns the result. + This is the value used by sizers to determine the appropriate + ammount of space to allocate for the widget. + + @see GetBestSize(), SetInitialSize(), @ref overview_windowsizing + */ + wxSize GetEffectiveMinSize() const; + + /** + Returns the event handler for this window. By default, the window is its + own event handler. + + @see SetEventHandler(), PushEventHandler(), + PopEventHandler(), wxEvtHandler::ProcessEvent, wxEvtHandler + */ + wxEvtHandler* GetEventHandler() const; + + /** + Returns the extra style bits for the window. + */ + long GetExtraStyle() const; + + /** + Returns the font for this window. + + @see SetFont() + */ + wxFont GetFont() const; + + /** + Returns the foreground colour of the window. + + @remarks The interpretation of foreground colour is open to + interpretation according to the window class; it may be + the text colour or other colour, or it may not be used + at all. + + @see SetForegroundColour(), SetBackgroundColour(), + GetBackgroundColour() + */ + wxColour GetForegroundColour(); + + /** + Returns the grandparent of a window, or @NULL if there isn't one. + */ + wxWindow* GetGrandParent() const; + + /** + Returns the platform-specific handle of the physical window. Cast it to an + appropriate + handle, such as @b HWND for Windows, @b Widget for Motif, @b GtkWidget for GTK + or @b WinHandle for PalmOS. + */ + void* GetHandle() const; + + /** + Gets the help text to be used as context-sensitive help for this window. + Note that the text is actually stored by the current wxHelpProvider + implementation, + and not in the window object itself. + + @see SetHelpText(), GetHelpTextAtPoint(), wxHelpProvider + */ + virtual wxString GetHelpText() const; + + /** + Gets the help text to be used as context-sensitive help for this window. This + method should be overridden if the help message depends on the position inside + the window, otherwise GetHelpText() can be used. + + @param point + Coordinates of the mouse at the moment of help event emission. + @param origin + Help event origin, see also wxHelpEvent::GetOrigin. + */ + virtual wxString GetHelpTextAtPoint(const wxPoint point, + wxHelpEvent::Origin origin) const; + + /** + Returns the identifier of the window. + + @remarks Each window has an integer identifier. If the application has + not provided one (or the default wxID_ANY) an unique + identifier with a negative value will be generated. + + @see SetId(), @ref overview_windowids "Window identifiers" + */ + int GetId() const; + + /** + Generic way of getting a label from any window, for + identification purposes. + + @remarks The interpretation of this function differs from class to class. + For frames and dialogs, the value returned is the + title. For buttons or static text controls, it is the + button text. This function can be useful for + meta-programs (such as testing tools or special-needs + access programs) which need to identify windows by name. + */ + virtual wxString GetLabel() const; + + /** + Returns the maximum size of window's client area. + This is an indication to the sizer layout mechanism that this is the maximum + possible size as well as the upper bound on window's size settable using + SetClientSize(). + + @see GetMaxSize() + */ + wxSize GetMaxClientSize() const; + + /** + Returns the maximum size of the window. This is an indication to the sizer + layout mechanism that this is the maximum possible size as well as the upper + bound on window's size settable using SetSize(). + + @see GetMaxClientSize() + */ + wxSize GetMaxSize() const; + + /** + Returns the minimum size of window's client area, an indication to the sizer + layout mechanism that this is the minimum required size of its client area. It + normally just returns the value set by + SetMinClientSize(), but it can be overridden + to do the calculation on demand. + + @see GetMinSize() + */ + virtual wxSize GetMinClientSize() const; + + /** + Returns the minimum size of the window, an indication to the sizer layout + mechanism that this is the minimum required size. + + This method normally just returns the value set by SetMinSize(), but it + can be overridden to do the calculation on demand. + + @see GetMinClientSize() + */ + virtual wxSize GetMinSize() const; + + /** + Returns the window's name. + + @remarks This name is not guaranteed to be unique; it is up to the + programmer to supply an appropriate name in the window + constructor or via SetName(). + + @see SetName() + */ + virtual wxString GetName() const; + + /** + Returns the next window after this one among the parent children or @NULL if + this window is the last child. + + @since 2.8.8 + + @see GetPrevSibling() + */ + wxWindow* GetNextSibling() const; + + /** + Returns the parent of the window, or @NULL if there is no parent. + */ + virtual wxWindow* GetParent() const; + + //@{ + /** + This function shows a popup menu at the given position in this window and + returns the selected id. It can be more convenient than the general purpose + PopupMenu() function for simple menus proposing a + choice in a list of strings to the user. + + @param menu + The menu to show + @param pos + The position at which to show the menu in client coordinates + @param x + The horizontal position of the menu + @param y + The vertical position of the menu + + @return The selected menu item id or wxID_NONE if none selected or an + error occurred. + */ + int GetPopupMenuSelectionFromUser(wxMenu& menu, + const wxPoint& pos); + int GetPopupMenuSelectionFromUser(wxMenu& menu, int x, int y); + //@} + + //@{ + /** + This gets the position of the window in pixels, relative to the parent window + for the child windows or relative to the display origin for the top level + windows. + + @param x + Receives the x position of the window if non-@NULL. + @param y + Receives the y position of the window if non-@NULL. + + @see GetScreenPosition() + */ + void GetPosition(int* x, int* y) const; + wxPoint GetPosition() const; + //@} + + /** + Returns the previous window before this one among the parent children or @c + @NULL if + this window is the first child. + + @since 2.8.8 + + @see GetNextSibling() + */ + wxWindow* GetPrevSibling() const; + + /** + Returns the position and size of the window as a wxRect object. + + @see GetScreenRect() + */ + wxRect GetRect() const; + + //@{ + /** + Returns the window position in screen coordinates, whether the window is a + child window or a top level one. + + @param x + Receives the x position of the window on the screen if non-@NULL. + @param y + Receives the y position of the window on the screen if non-@NULL. + + @see GetPosition() + */ + void GetScreenPosition(int* x, int* y) const; + wxPoint GetScreenPosition() const; + //@} + + /** + Returns the position and size of the window on the screen as a + wxRect object. + + @see GetRect() + */ + wxRect GetScreenRect() const; + + /** + Returns the built-in scrollbar position. + + @see See SetScrollbar() + */ + virtual int GetScrollPos(int orientation); + + /** + Returns the built-in scrollbar range. + + @see SetScrollbar() + */ + virtual int GetScrollRange(int orientation); + + /** + Returns the built-in scrollbar thumb size. + + @see SetScrollbar() + */ + virtual int GetScrollThumb(int orientation); + + //@{ + /** + Returns the size of the entire window in pixels, including title bar, border, + scrollbars, etc. + Note that if this window is a top-level one and it is currently minimized, the + returned size is the restored window size, not the size of the window icon. + + @param width + Receives the window width. + @param height + Receives the window height. + + @see GetClientSize(), GetVirtualSize() + */ + void GetSize(int* width, int* height) const; + const wxSize GetSize() const; + //@} + + /** + Return the sizer associated with the window by a previous call to + SetSizer() or @NULL. + */ + wxSizer* GetSizer() const; + + //@{ + /** + Gets the dimensions of the string as it would be drawn on the + window with the currently selected font. + The text extent is returned in @a w and @a h pointers (first form) or as a + wxSize object (second form). + + @param string + String whose extent is to be measured. + @param w + Return value for width. + @param h + Return value for height. + @param descent + Return value for descent (optional). + @param externalLeading + Return value for external leading (optional). + @param font + Font to use instead of the current window font (optional). + @param use16 + If @true, string contains 16-bit characters. The default is @false. + */ + virtual void GetTextExtent(const wxString& string, int* w, + int* h, + int* descent = NULL, + int* externalLeading = NULL, + const wxFont* font = NULL, + bool use16 = false) const; + const wxSize GetTextExtent(const wxString& string) const; + //@} + + /** + Get the associated tooltip or @NULL if none. + */ + wxToolTip* GetToolTip() const; + + /** + Returns the region specifying which parts of the window have been damaged. + Should + only be called within an wxPaintEvent handler. + + @see wxRegion, wxRegionIterator + */ + virtual wxRegion GetUpdateRegion() const; + + /** + Returns a pointer to the current validator for the window, or @NULL if there is + none. + */ + wxValidator* GetValidator() const; + + //@{ + /** + This gets the virtual size of the window in pixels. By default it + returns the client size of the window, but after a call to + SetVirtualSize() it will return + that size. + + @param width + Receives the window virtual width. + @param height + Receives the window virtual height. + */ + void GetVirtualSize(int* width, int* height) const; + const wxSize GetVirtualSize() const; + //@} + + /** + Returns the size of the left/right and top/bottom borders of this window in x + and y components of the result respectively. + */ + wxSize GetWindowBorderSize() const; + + /** + Gets the window style that was passed to the constructor or @b Create + method. @b GetWindowStyle() is another name for the same function. + */ + long GetWindowStyleFlag() const; + + /** + Returns the value previously passed to + SetWindowVariant(). + */ + wxWindowVariant GetWindowVariant() const; + + /** + This function will generate the appropriate call to + Navigate() if the key event is one normally used for + keyboard navigation and return @true in this case. + + @return Returns @true if the key pressed was for navigation and was + handled, @false otherwise. + + @see Navigate() + */ + bool HandleAsNavigationKey(const wxKeyEvent& event); + + /** + Shorthand for @c + wxWindow::GetEventHandler()-wxEvtHandler::SafelyProcessEvent(event). + */ + bool HandleWindowEvent(wxEvent& event); + + /** + Returns @true if this window has the current mouse capture. + + @see CaptureMouse(), ReleaseMouse(), wxMouseCaptureLostEvent, + wxMouseCaptureChangedEvent + */ + virtual bool HasCapture() const; + + /** + Returns @true if the window has the given @a exFlag bit set in its + extra styles. + + @see SetExtraStyle() + */ + bool HasExtraStyle(int exFlag) const; + + /** + Returns @true if the window has the given @a flag bit set. + */ + bool HasFlag(int flag) const; + + /** + Returns @true if the window (or in case of composite controls, its main + child window) has focus. + + @see FindFocus() + */ + virtual bool HasFocus() const; + + /** + This method should be overridden to return @true if this window has + multiple pages. All standard class with multiple pages such as + wxNotebook, wxListbook and + wxTreebook already override it to return @true + and user-defined classes with similar behaviour should do it as well to allow + the library to handle such windows appropriately. + */ + virtual bool HasMultiplePages() const; + + /** + Returns @true if this window has a scroll bar for this orientation. + + @param orient + Orientation to check, either wxHORIZONTAL or wxVERTICAL. + */ + virtual bool HasScrollbar(int orient) const; + + /** + Returns @true if this window background is transparent (as, for example, for + wxStaticText) and should show the parent window background. + This method is mostly used internally by the library itself and you normally + shouldn't have to call it. You may, however, have to override it in your + wxWindow-derived class to ensure that background is painted correctly. + */ + virtual bool HasTransparentBackground() const; + + /** + Equivalent to calling wxWindow::Show(@false). + */ + bool Hide(); + + /** + This function hides a window, like Hide(), but using a special visual + effect if possible. + + The parameters of this function are the same as for ShowWithEffect(), + please see their description there. + + @since 2.9.0 + */ + virtual bool HideWithEffect(wxShowEffect effect, + unsigned timeout = 0); + + /** + This function is (or should be, in case of custom controls) called during + window creation to intelligently set up the window visual attributes, that is + the font and the foreground and background colours. + By "intelligently" the following is meant: by default, all windows use their + own @ref GetClassDefaultAttributes() default attributes. However + if some of the parents attributes are explicitly (that is, using + SetFont() and not + wxWindow::SetOwnFont) changed and if the + corresponding attribute hadn't been explicitly set for this window itself, + then this window takes the same value as used by the parent. In addition, if + the window overrides ShouldInheritColours() + to return @false, the colours will not be changed no matter what and only the + font might. + This rather complicated logic is necessary in order to accommodate the + different usage scenarios. The most common one is when all default attributes + are used and in this case, nothing should be inherited as in modern GUIs + different controls use different fonts (and colours) than their siblings so + they can't inherit the same value from the parent. However it was also deemed + desirable to allow to simply change the attributes of all children at once by + just changing the font or colour of their common parent, hence in this case we + do inherit the parents attributes. + */ + void InheritAttributes(); + + /** + Sends an @c wxEVT_INIT_DIALOG event, whose handler usually transfers data + to the dialog via validators. + */ + void InitDialog(); + + /** + Resets the cached best size value so it will be recalculated the next time it + is needed. + */ + void InvalidateBestSize(); + + /** + Returns @true if the window contents is double-buffered by the system, i.e. if + any drawing done on the window is really done on a temporary backing surface + and transferred to the screen all at once later. + + @see wxBufferedDC + */ + virtual bool IsDoubleBuffered() const; + + /** + Returns @true if the window is enabled, i.e. if it accepts user input, @c + @false + otherwise. + Notice that this method can return @false even if this window itself hadn't + been explicitly disabled when one of its parent windows is disabled. To get the + intrinsic status of this window, use + IsThisEnabled() + + @see Enable() + */ + virtual bool IsEnabled() const; + + //@{ + /** + Returns @true if the given point or rectangle area has been exposed since the + last repaint. Call this in an paint event handler to optimize redrawing by + only redrawing those areas, which have been exposed. + */ + bool IsExposed(int x, int y) const; + const bool IsExposed(wxPoint amp;pt) const; + const bool IsExposed(int x, int y, int w, int h) const; + const bool IsExposed(wxRect amp;rect) const; + //@} + + /** + Returns @true if the window is currently frozen by a call to + Freeze(). + + @see Freeze(), Thaw() + */ + virtual bool IsFrozen() const; + + /** + Returns @true if the window is retained, @false otherwise. + + @remarks Retained windows are only available on X platforms. + */ + virtual bool IsRetained() const; + + /** + Return whether a scrollbar is always shown. + + @param orient + Orientation to check, either wxHORIZONTAL or wxVERTICAL. + + @see AlwaysShowScrollbars() + */ + bool IsScrollbarAlwaysShown(int orient); + + /** + Returns @true if the window is shown, @false if it has been hidden. + + @see IsShownOnScreen() + */ + virtual bool IsShown() const; + + /** + Returns @true if the window is physically visible on the screen, i.e. it + is shown and all its parents up to the toplevel window are shown as well. + + @see IsShown() + */ + virtual bool IsShownOnScreen() const; + + /** + Returns @true if this window is intrinsically enabled, @false otherwise, + i.e. + if @ref Enable() Enable(@false) had been called. This method is + mostly used for wxWidgets itself, user code should normally use + IsEnabled() instead. + */ + bool IsThisEnabled() const; + + /** + Returns @true if the given window is a top-level one. Currently all frames and + dialogs are considered to be top-level windows (even if they have a parent + window). + */ + bool IsTopLevel() const; + + /** + Invokes the constraint-based layout algorithm or the sizer-based algorithm + for this window. + + See SetAutoLayout(): when auto layout is on, this function gets called automatically + when the window is resized. + + @see @ref overview_windowsizing + */ + void Layout(); + + /** + Lowers the window to the bottom of the window hierarchy (Z-order). + + @see Raise() + */ + void Lower(); + + /** + Disables all other windows in the application so that + the user can only interact with this window. + + @param flag + If @true, this call disables all other windows in the application so that + the user can only interact with this window. If @false, the effect is + reversed. + */ + virtual void MakeModal(bool flag); + + //@{ + /** + Moves the window to the given position. + + @param x + Required x position. + @param y + Required y position. + @param pt + wxPoint object representing the position. + + @remarks Implementations of SetSize can also implicitly implement the + Move() function, which is defined in the base + wxWindow class as the call: + + @see SetSize() + */ + void Move(int x, int y); + void Move(const wxPoint& pt); + //@} + + /** + Moves this window in the tab navigation order after the specified @e win. + This means that when the user presses @c TAB key on that other window, + the focus switches to this window. + Default tab order is the same as creation order, this function and + MoveBeforeInTabOrder() allow to change + it after creating all the windows. + + @param win + A sibling of this window which should precede it in tab order, + must not be @NULL + */ + void MoveAfterInTabOrder(wxWindow* win); + + /** + Same as MoveAfterInTabOrder() except that + it inserts this window just before @a win instead of putting it right after + it. + */ + void MoveBeforeInTabOrder(wxWindow* win); + + /** + Performs a keyboard navigation action starting from this window. This method is + equivalent to calling NavigateIn() method on the + parent window. + + @param flags + A combination of wxNavigationKeyEvent::IsForward and + wxNavigationKeyEvent::WinChange. + + @return Returns @true if the focus was moved to another window or @false + if nothing changed. + + @remarks You may wish to call this from a text control custom keypress + handler to do the default navigation behaviour for the + tab key, since the standard default behaviour for a + multiline text control with the wxTE_PROCESS_TAB style + is to insert a tab and not navigate to the next + control. See also wxNavigationKeyEvent and + HandleAsNavigationKey. + */ + bool Navigate(int flags = wxNavigationKeyEvent::IsForward); + + /** + Performs a keyboard navigation action inside this window. + See Navigate() for more information. + */ + bool NavigateIn(int flags = wxNavigationKeyEvent::IsForward); + + /** + Create a new ID or range of IDs that are not currently in use. The + IDs will be reserved until assigned to a wxWindowIDRef() + or unreserved with UnreserveControlId(). + See @ref overview_windowids "Window IDs Overview" for more information. + + @param count + The number of sequential IDs to reserve. + + @return Returns the ID or the first ID of the range, or wxID_NONE if the + specified number of identifiers couldn't be allocated. + + @see UnreserveControlId(), wxIdManager, @ref overview_windowids + "Window IDs Overview" + */ + static wxWindowID NewControlId(int count = 1); + + /** + This virtual function is normally only used internally, but + sometimes an application may need it to implement functionality + that should not be disabled by an application defining an OnIdle + handler in a derived class. + This function may be used to do delayed painting, for example, + and most implementations call UpdateWindowUI() + in order to send update events to the window in idle time. + */ + virtual void OnInternalIdle(); + + /** + Same as #ScrollLines (-1). + */ + bool LineUp(); + + /** + Same as #ScrollLines (1). + */ + bool LineDown(); + + /** + Same as #ScrollPages (-1). + */ + bool PageUp(); + + /** + Same as #ScrollPages (1). + */ + bool PageDown(); + + + /** + Removes and returns the top-most event handler on the event handler stack. + + @param deleteHandler + If this is @true, the handler will be deleted after it is removed. The + default value is @false. + + @see SetEventHandler(), GetEventHandler(), + PushEventHandler(), wxEvtHandler::ProcessEvent, wxEvtHandler + */ + wxEvtHandler* PopEventHandler(bool deleteHandler = false) const; + + //@{ + /** + Pops up the given menu at the specified coordinates, relative to this + window, and returns control when the user has dismissed the menu. If a + menu item is selected, the corresponding menu event is generated and will be + processed as usually. If the coordinates are not specified, current mouse + cursor position is used. + + @param menu + Menu to pop up. + @param pos + The position where the menu will appear. + @param x + Required x position for the menu to appear. + @param y + Required y position for the menu to appear. + + @remarks Just before the menu is popped up, wxMenu::UpdateUI is called to + ensure that the menu items are in the correct state. + The menu does not get deleted by the window. + + @see wxMenu + */ + bool PopupMenu(wxMenu* menu, + const wxPoint& pos = wxDefaultPosition); + bool PopupMenu(wxMenu* menu, int x, int y); + //@} + + /** + Pushes this event handler onto the event stack for the window. + + @param handler + Specifies the handler to be pushed. + + @remarks An event handler is an object that is capable of processing the + events sent to a window. By default, the window is its + own event handler, but an application may wish to + substitute another, for example to allow central + implementation of event-handling for a variety of + different window classes. + + @see SetEventHandler(), GetEventHandler(), + PopEventHandler(), wxEvtHandler::ProcessEvent, wxEvtHandler + */ + void PushEventHandler(wxEvtHandler* handler); + + /** + Raises the window to the top of the window hierarchy (Z-order). + In current version of wxWidgets this works both for managed and child windows. + + @see Lower() + */ + void Raise(); + + /** + Causes this window, and all of its children recursively (except under wxGTK1 + where this is not implemented), to be repainted. Note that repainting doesn't + happen immediately but only during the next event loop iteration, if you need + to update the window immediately you should use Update() + instead. + + @param eraseBackground + If @true, the background will be + erased. + @param rect + If non-@NULL, only the given rectangle will + be treated as damaged. + + @see RefreshRect() + */ + virtual void Refresh(bool eraseBackground = true, + const wxRect* rect = NULL); + + /** + Redraws the contents of the given rectangle: only the area inside it will be + repainted. + This is the same as Refresh() but has a nicer syntax + as it can be called with a temporary wxRect object as argument like this + @c RefreshRect(wxRect(x, y, w, h)). + */ + void RefreshRect(const wxRect& rect, bool eraseBackground = true); + + /** + Registers a system wide hotkey. Every time the user presses the hotkey + registered here, this window + will receive a hotkey event. It will receive the event even if the application + is in the background + and does not have the input focus because the user is working with some other + application. + + @param hotkeyId + Numeric identifier of the hotkey. For applications this must be between 0 + and 0xBFFF. If + this function is called from a shared DLL, it must be a system wide unique + identifier between 0xC000 and 0xFFFF. + This is a MSW specific detail. + @param modifiers + A bitwise combination of wxMOD_SHIFT, wxMOD_CONTROL, wxMOD_ALT + or wxMOD_WIN specifying the modifier keys that have to be pressed along + with the key. + @param virtualKeyCode + The virtual key code of the hotkey. + + @return @true if the hotkey was registered successfully. @false if some + other application already registered a hotkey with this + modifier/virtualKeyCode combination. + + @remarks Use EVT_HOTKEY(hotkeyId, fnc) in the event table to capture the + event. This function is currently only implemented + under Windows. It is used in the Windows CE port for + detecting hardware button presses. + + @see UnregisterHotKey() + */ + bool RegisterHotKey(int hotkeyId, int modifiers, + int virtualKeyCode); + + /** + Releases mouse input captured with CaptureMouse(). + + @see CaptureMouse(), HasCapture(), ReleaseMouse(), + wxMouseCaptureLostEvent, wxMouseCaptureChangedEvent + */ + virtual void ReleaseMouse(); + + /** + Removes a child window. This is called automatically by window deletion + functions so should not be required by the application programmer. + Notice that this function is mostly internal to wxWidgets and shouldn't be + called by the user code. + + @param child + Child window to remove. + */ + virtual void RemoveChild(wxWindow* child); + + /** + Find the given @a handler in the windows event handler chain and remove (but + not delete) it from it. + + @param handler + The event handler to remove, must be non-@NULL and + must be present in this windows event handlers chain + + @return Returns @true if it was found and @false otherwise (this also + results in an assert failure so this function should + only be called when the handler is supposed to be + there). + + @see PushEventHandler(), PopEventHandler() + */ + bool RemoveEventHandler(wxEvtHandler* handler); + + /** + Reparents the window, i.e the window will be removed from its + current parent window (e.g. a non-standard toolbar in a wxFrame) + and then re-inserted into another. + + @param newParent + New parent. + */ + virtual bool Reparent(wxWindow* newParent); + + //@{ + /** + Converts from screen to client window coordinates. + + @param x + Stores the screen x coordinate and receives the client x coordinate. + @param y + Stores the screen x coordinate and receives the client x coordinate. + @param pt + The screen position for the second form of the function. + */ + virtual void ScreenToClient(int* x, int* y) const; + const virtual wxPoint ScreenToClient(const wxPoint& pt) const; + //@} + + /** + Scrolls the window by the given number of lines down (if @a lines is + positive) or up. + + @return Returns @true if the window was scrolled, @false if it was already + on top/bottom and nothing was done. + + @remarks This function is currently only implemented under MSW and + wxTextCtrl under wxGTK (it also works for wxScrolled classes + under all platforms). + + @see ScrollPages() + */ + virtual bool ScrollLines(int lines); + + /** + Scrolls the window by the given number of pages down (if @a pages is + positive) or up. + + @return Returns @true if the window was scrolled, @false if it was already + on top/bottom and nothing was done. + + @remarks This function is currently only implemented under MSW and wxGTK. + + @see ScrollLines() + */ + virtual bool ScrollPages(int pages); + + /** + Physically scrolls the pixels in the window and move child windows accordingly. + + @param dx + Amount to scroll horizontally. + @param dy + Amount to scroll vertically. + @param rect + Rectangle to scroll, if it is @NULL, the whole window is + scrolled (this is always the case under wxGTK which doesn't support this + parameter) + + @remarks Note that you can often use wxScrolled instead of using this + function directly. + */ + virtual void ScrollWindow(int dx, int dy, + const wxRect* rect = NULL); + + /** + Sets the accelerator table for this window. See wxAcceleratorTable. + */ + virtual void SetAcceleratorTable(const wxAcceleratorTable& accel); + + /** + Sets the accessible for this window. Any existing accessible for this window + will be deleted first, if not identical to @e accessible. + See also wxAccessible. + */ + void SetAccessible(wxAccessible* accessible); + + /** + Determines whether the Layout() function will + be called automatically when the window is resized. Please note that this only + happens for the windows usually used to contain children, namely + wxPanel and wxTopLevelWindow + (and the classes deriving from them). + This method is called implicitly by + SetSizer() but if you use + SetConstraints() you should call it + manually or otherwise the window layout won't be correctly updated when its + size changes. + + @param autoLayout + Set this to @true if you wish the Layout function to be + called automatically when the window is resized. + + @see SetConstraints() + */ + void SetAutoLayout(bool autoLayout); + + /** + Sets the background colour of the window. + Please see InheritAttributes() for + explanation of the difference between this method and + SetOwnBackgroundColour(). + + @param colour + The colour to be used as the background colour, pass + wxNullColour to reset to the default colour. + + @remarks The background colour is usually painted by the default + wxEraseEvent event handler function under Windows and + automatically under GTK. + + @see GetBackgroundColour(), SetForegroundColour(), + GetForegroundColour(), ClearBackground(), + Refresh(), wxEraseEvent + */ + virtual bool SetBackgroundColour(const wxColour& colour); + + /** + Sets the background style of the window. see + GetBackgroundStyle() for the description + of the possible style values. + + @see SetBackgroundColour(), GetForegroundColour(), + SetTransparent() + */ + virtual void SetBackgroundStyle(wxBackgroundStyle style); + + /** + This method is only implemented by ports which have support for + native TAB traversal (such as GTK+ 2.0). It is called by wxWidgets' + container control code to give the native system a hint when + doing TAB traversal. A call to this does not disable or change + the effect of programmatically calling + SetFocus(). + + @see wxFocusEvent, wxPanel::SetFocus, wxPanel::SetFocusIgnoringChildren + */ + virtual void SetCanFocus(bool canFocus); + + /** + Sets the caret() associated with the window. + */ + void SetCaret(wxCaret* caret) const; + + //@{ + /** + This sets the size of the window client area in pixels. Using this function to + size a window + tends to be more device-independent than SetSize(), since the application need + not + worry about what dimensions the border or title bar have when trying to fit the + window + around panel items, for example. + + @param width + The required client area width. + @param height + The required client area height. + @param size + The required client size. + */ + virtual void SetClientSize(int width, int height); + virtual void SetClientSize(const wxSize& size); + //@} + + /** + Sets the window to have the given layout constraints. The window + will then own the object, and will take care of its deletion. + If an existing layout constraints object is already owned by the + window, it will be deleted. + + @param constraints + The constraints to set. Pass @NULL to disassociate and delete the window's + constraints. + + @remarks You must call SetAutoLayout() to tell a window to use + the constraints automatically in OnSize; otherwise, you + must override OnSize and call Layout() explicitly. When + setting both a wxLayoutConstraints and a wxSizer, only + the sizer will have effect. + */ + void SetConstraints(wxLayoutConstraints* constraints); + + /** + This normally does not need to be called by user code. It is called + when a window is added to a sizer, and is used so the window can + remove itself from the sizer when it is destroyed. + */ + void SetContainingSizer(wxSizer* sizer); + + /** + Sets the window's cursor. Notice that the window cursor also sets it for the + children of the window implicitly. + The @a cursor may be @c wxNullCursor in which case the window cursor will + be reset back to default. + + @param cursor + Specifies the cursor that the window should normally display. + + @see ::wxSetCursor, wxCursor + */ + virtual void SetCursor(const wxCursor& cursor); + + /** + Associates a drop target with this window. + If the window already has a drop target, it is deleted. + + @see GetDropTarget(), @ref overview_dnd + */ + void SetDropTarget(wxDropTarget* target); + + /** + Sets the event handler for this window. + + @param handler + Specifies the handler to be set. + + @remarks An event handler is an object that is capable of processing the + events sent to a window. By default, the window is its + own event handler, but an application may wish to + substitute another, for example to allow central + implementation of event-handling for a variety of + different window classes. + + @see GetEventHandler(), PushEventHandler(), + PopEventHandler(), wxEvtHandler::ProcessEvent, wxEvtHandler + */ + void SetEventHandler(wxEvtHandler* handler); + + /** + Sets the extra style bits for the window. The currently defined extra style + bits are: + + @b wxWS_EX_VALIDATE_RECURSIVELY + + TransferDataTo/FromWindow() + and Validate() methods will recursively descend into all children of the + window if it has this style flag set. + + @b wxWS_EX_BLOCK_EVENTS + + Normally, the command + events are propagated upwards to the window parent recursively until a handler + for them is found. Using this style allows to prevent them from being + propagated beyond this window. Notice that wxDialog has this style on by + default for the reasons explained in the + @ref overview_eventhandling "Event Handling Overview". + + @b wxWS_EX_TRANSIENT + + This can be used to prevent a + window from being used as an implicit parent for the dialogs which were + created without a parent. It is useful for the windows which can disappear at + any moment as creating children of such windows results in fatal problems. + + @b wxWS_EX_CONTEXTHELP + + Under Windows, puts a query + button on the caption. When pressed, Windows will go into a context-sensitive + help mode and wxWidgets will send a wxEVT_HELP event if the user clicked on an + application window. + This style cannot be used together with wxMAXIMIZE_BOX or wxMINIMIZE_BOX, so + these two styles are automatically turned of if this one is used. + + @b wxWS_EX_PROCESS_IDLE + + This window should always process idle events, even + if the mode set by wxIdleEvent::SetMode is wxIDLE_PROCESS_SPECIFIED. + + @b wxWS_EX_PROCESS_UI_UPDATES + + This window should always process UI update events, + even if the mode set by wxUpdateUIEvent::SetMode is + wxUPDATE_UI_PROCESS_SPECIFIED. + */ + void SetExtraStyle(long exStyle); + + /** + This sets the window to receive keyboard input. + + @see HasFocus(), wxFocusEvent, wxPanel::SetFocus, + wxPanel::SetFocusIgnoringChildren + */ + virtual void SetFocus(); + + /** + This function is called by wxWidgets keyboard navigation code when the user + gives the focus to this window from keyboard (e.g. using @c TAB key). + By default this method simply calls SetFocus() but + can be overridden to do something in addition to this in the derived classes. + */ + virtual void SetFocusFromKbd(); + + /** + Sets the font for this window. This function should not be called for the + parent window if you don't want its font to be inherited by its children, + use SetOwnFont() instead in this case and + see InheritAttributes() for more + explanations. + Please notice that the given font is not automatically used for + wxPaintDC objects associated with this window, you need to + call wxDC::SetFont too. However this font is used by + any standard controls for drawing their text as well as by + GetTextExtent(). + + @param font + Font to associate with this window, pass + wxNullFont to reset to the default font. + + @return @true if the want was really changed, @false if it was already set + to this font and so nothing was done. + + @see GetFont(), InheritAttributes() + */ + bool SetFont(const wxFont& font); + + /** + Sets the foreground colour of the window. + Please see InheritAttributes() for + explanation of the difference between this method and + SetOwnForegroundColour(). + + @param colour + The colour to be used as the foreground colour, pass + wxNullColour to reset to the default colour. + + @remarks The interpretation of foreground colour is open to + interpretation according to the window class; it may be + the text colour or other colour, or it may not be used + at all. + + @see GetForegroundColour(), SetBackgroundColour(), + GetBackgroundColour(), ShouldInheritColours() + */ + virtual void SetForegroundColour(const wxColour& colour); + + /** + Sets the help text to be used as context-sensitive help for this window. + Note that the text is actually stored by the current wxHelpProvider + implementation, + and not in the window object itself. + + @see GetHelpText(), wxHelpProvider::AddHelp() + */ + virtual void SetHelpText(const wxString& helpText); + + /** + Sets the identifier of the window. + + @remarks Each window has an integer identifier. If the application has + not provided one, an identifier will be generated. + Normally, the identifier should be provided on creation + and should not be modified subsequently. + + @see GetId(), @ref overview_windowids "Window identifiers" + */ + void SetId(int id); + + /** + Sets the initial window size if none is given (i.e. at least one of the + components of the size passed to ctor/Create() is wxDefaultCoord). + */ + virtual void SetInitialBestSize(const wxSize& size); + + /** + A @e smart SetSize that will fill in default size components with the + window's @e best size values. + + Also sets the window's minsize to the value passed in for use with sizers. + This means that if a full or partial size is passed to this function then + the sizers will use that size instead of the results of GetBestSize() to + determine the minimum needs of the window for layout. + + Most controls will use this to set their initial size, and their min + size to the passed in value (if any.) + + @see SetSize(), GetBestSize(), GetEffectiveMinSize(), + @ref overview_windowsizing + */ + void SetInitialSize(const wxSize& size = wxDefaultSize); + + /** + Sets the window's label. + + @param label + The window label. + + @see GetLabel() + */ + virtual void SetLabel(const wxString& label); + + /** + Sets the maximum client size of the window, to indicate to the sizer + layout mechanism that this is the maximum possible size of its client area. + + @see SetMaxSize() + */ + void SetMaxClientSize(const wxSize& size); + + /** + Sets the maximum size of the window, to indicate to the sizer layout mechanism + that this is the maximum possible size. + + @see SetMaxClientSize() + */ + void SetMaxSize(const wxSize& size); + + /** + Sets the minimum client size of the window, to indicate to the sizer + layout mechanism that this is the minimum required size of window's client + area. + + You may need to call this if you change the window size after + construction and before adding to its parent sizer. + + Note, that just as with SetMinSize(), calling this method doesn't + prevent the program from explicitly making the window smaller than the + specified size. + + @see SetMinSize() + */ + void SetMinClientSize(const wxSize& size); + + /** + Sets the minimum size of the window, to indicate to the sizer layout + mechanism that this is the minimum required size. + + You may need to call this if you change the window size after + construction and before adding to its parent sizer. + + Notice that calling this method doesn't prevent the program from making + the window explicitly smaller than the specified size by calling + SetSize(), it just ensures that it won't become smaller than this size + during the automatic layout. + + @see SetMinClientSize() + */ + void SetMinSize(const wxSize& size); + + /** + Sets the window's name. + + @param name + A name to set for the window. + + @see GetName() + */ + virtual void SetName(const wxString& name); + + /** + Sets the background colour of the window but prevents it from being inherited + by the children of this window. + + @see SetBackgroundColour(), InheritAttributes() + */ + void SetOwnBackgroundColour(const wxColour& colour); + + /** + Sets the font of the window but prevents it from being inherited by the + children of this window. + + @see SetFont(), InheritAttributes() + */ + void SetOwnFont(const wxFont& font); + + /** + Sets the foreground colour of the window but prevents it from being inherited + by the children of this window. + + @see SetForegroundColour(), InheritAttributes() + */ + void SetOwnForegroundColour(const wxColour& colour); + + /** + Obsolete - use wxDC::SetPalette instead. + */ + virtual void SetPalette(wxPalette* palette); + + /** + Sets the position of one of the built-in scrollbars. + + @param orientation + Determines the scrollbar whose position is to be set. May be wxHORIZONTAL + or wxVERTICAL. + @param pos + Position in scroll units. + @param refresh + @true to redraw the scrollbar, @false otherwise. + + @remarks This function does not directly affect the contents of the + window: it is up to the application to take note of + scrollbar attributes and redraw contents accordingly. + + @see SetScrollbar(), GetScrollPos(), GetScrollThumb(), wxScrollBar, + wxScrolled + */ + virtual void SetScrollPos(int orientation, int pos, + bool refresh = true); + + /** + Sets the scrollbar properties of a built-in scrollbar. + + @param orientation + Determines the scrollbar whose page size is to be set. May be wxHORIZONTAL + or wxVERTICAL. + @param position + The position of the scrollbar in scroll units. + @param thumbSize + The size of the thumb, or visible portion of the scrollbar, in scroll units. + @param range + The maximum position of the scrollbar. + @param refresh + @true to redraw the scrollbar, @false otherwise. + + @remarks Let's say you wish to display 50 lines of text, using the same + font. The window is sized so that you can only see 16 + lines at a time. + + @see @ref overview_scrolling, wxScrollBar, wxScrolled, wxScrollWinEvent + */ + virtual void SetScrollbar(int orientation, int position, + int thumbSize, + int range, + bool refresh = true); + + //@{ + /** + Sets the size of the window in pixels. + + @param x + Required x position in pixels, or wxDefaultCoord to indicate that the + existing + value should be used. + @param y + Required y position in pixels, or wxDefaultCoord to indicate that the + existing + value should be used. + @param width + Required width in pixels, or wxDefaultCoord to indicate that the existing + value should be used. + @param height + Required height position in pixels, or wxDefaultCoord to indicate that the + existing + value should be used. + @param size + wxSize object for setting the size. + @param rect + wxRect object for setting the position and size. + @param sizeFlags + Indicates the interpretation of other parameters. It is a bit list of the + following: + wxSIZE_AUTO_WIDTH: a wxDefaultCoord width value is taken to indicate + a wxWidgets-supplied default width. + + wxSIZE_AUTO_HEIGHT: a wxDefaultCoord height value is taken to indicate + a wxWidgets-supplied default height. + + wxSIZE_AUTO: wxDefaultCoord size values are taken to indicate + a wxWidgets-supplied default size. + + wxSIZE_USE_EXISTING: existing dimensions should be used + if wxDefaultCoord values are supplied. + + wxSIZE_ALLOW_MINUS_ONE: allow negative dimensions (i.e. value of + wxDefaultCoord) to be interpreted + as real dimensions, not default values. + wxSIZE_FORCE: normally, if the position and the size of the window are + already the same as the parameters of this function, nothing is done. but + with + this flag a window resize may be forced even in this case (supported in wx + 2.6.2 and later and only implemented for MSW and ignored elsewhere + currently) + + @remarks The second form is a convenience for calling the first form with + default x and y parameters, and must be used with + non-default width and height values. + + @see Move() + */ + virtual void SetSize(int x, int y, int width, int height, + int sizeFlags = wxSIZE_AUTO); + virtual void SetSize(const wxRect& rect); + virtual void SetSize(int width, int height); + virtual void SetSize(const wxSize& size); + //@} + + /** + Sets the window to have the given layout sizer. The window + will then own the object, and will take care of its deletion. + If an existing layout constraints object is already owned by the + window, it will be deleted if the deleteOld parameter is @true. + Note that this function will also call + SetAutoLayout() implicitly with @true + parameter if the @a sizer is non-@NULL and @false otherwise. + + @param sizer + The sizer to set. Pass @NULL to disassociate and conditionally delete + the window's sizer. See below. + @param deleteOld + If @true (the default), this will delete any pre-existing sizer. + Pass @false if you wish to handle deleting the old sizer yourself. + @remarks SetSizer enables and disables Layout automatically. + */ + void SetSizer(wxSizer* sizer, bool deleteOld = true); + + /** + This method calls SetSizer() and then + wxSizer::SetSizeHints which sets the initial + window size to the size needed to accommodate all sizer elements and sets the + size hints which, if this window is a top level one, prevent the user from + resizing it to be less than this minimial size. + */ + void SetSizerAndFit(wxSizer* sizer, bool deleteOld = true); + + /** + This function tells a window if it should use the system's "theme" code + to draw the windows' background instead if its own background drawing + code. This does not always have any effect since the underlying platform + obviously needs to support the notion of themes in user defined windows. + One such platform is GTK+ where windows can have (very colourful) backgrounds + defined by a user's selected theme. + Dialogs, notebook pages and the status bar have this flag set to @true + by default so that the default look and feel is simulated best. + */ + virtual void SetThemeEnabled(bool enable); + + //@{ + /** + Attach a tooltip to the window. + See also: GetToolTip(), + wxToolTip + */ + void SetToolTip(const wxString& tip); + void SetToolTip(wxToolTip* tip); + //@} + + /** + Set the transparency of the window. If the system supports transparent windows, + returns @true, otherwise returns @false and the window remains fully opaque. + See also CanSetTransparent(). + The parameter @a alpha is in the range 0..255 where 0 corresponds to a + fully transparent window and 255 to the fully opaque one. The constants + @c wxIMAGE_ALPHA_TRANSPARENT and @c wxIMAGE_ALPHA_OPAQUE can be + used. + */ + bool SetTransparent(wxByte alpha); + + /** + Deletes the current validator (if any) and sets the window validator, having + called wxValidator::Clone to + create a new validator of this type. + */ + virtual void SetValidator(const wxValidator& validator); + + //@{ + /** + Sets the virtual size of the window in pixels. + */ + void SetVirtualSize(int width, int height); + void SetVirtualSize(const wxSize& size); + //@} + + /** + Identical to SetWindowStyleFlag(). + */ + void SetWindowStyle(long style); + + /** + Sets the style of the window. Please note that some styles cannot be changed + after the window creation and that Refresh() might + need to be be called after changing the others for the change to take place + immediately. + See @ref overview_windowstyles "Window styles" for more information about flags. + + @see GetWindowStyleFlag() + */ + virtual void SetWindowStyleFlag(long style); + + /** + This function can be called under all platforms but only does anything under + Mac OS X 10.3+ currently. Under this system, each of the standard control can + exist in several sizes which correspond to the elements of wxWindowVariant + enum: + + By default the controls use the normal size, of course, but this function can + be used to change this. + */ + void SetWindowVariant(wxWindowVariant variant); + + /** + Return @true from here to allow the colours of this window to be changed by + InheritAttributes(), returning @false + forbids inheriting them from the parent window. + The base class version returns @false, but this method is overridden in + wxControl where it returns @true. + */ + virtual bool ShouldInheritColours(); + + /** + Shows or hides the window. You may need to call Raise() + for a top level window if you want to bring it to top, although this is not + needed if Show() is called immediately after the frame creation. + + @param show + If @true displays the window. Otherwise, hides it. + + @return @true if the window has been shown or hidden or @false if nothing + was done because it already was in the requested state. + + @see IsShown(), Hide(), wxRadioBox::Show, wxShowEvent. + */ + virtual bool Show(bool show = true); + + /** + This function shows a window, like Show(), but using a special visual + effect if possible. + + @param effect + The effect to use. + + @param timeout + The @a timeout parameter specifies the time of the animation, in + milliseconds. If the default value of 0 is used, the default + animation time for the current platform is used. + + @note Currently this function is only implemented in wxMSW and does the + same thing as Show() in the other ports. + + @since 2.9.0 + + @see HideWithEffect() + */ + virtual bool ShowWithEffect(wxShowEffect effect, + unsigned timeout = 0); + + /** + Reenables window updating after a previous call to Freeze(). + + To really thaw the control, it must be called exactly the same number + of times as Freeze(). + + If the window has any children, they are recursively thawn too. + + @see wxWindowUpdateLocker, Freeze(), IsFrozen() + */ + virtual void Thaw(); + + /** + Turns the given @a flag on if it's currently turned off and vice versa. + This function cannot be used if the value of the flag is 0 (which is often + the case for default flags). + Also, please notice that not all styles can be changed after the control + creation. + + @return Returns @true if the style was turned on by this function, @false + if it was switched off. + + @see SetWindowStyleFlag(), HasFlag() + */ + bool ToggleWindowStyle(int flag); + + /** + Transfers values from child controls to data areas specified by their + validators. Returns + @false if a transfer failed. + If the window has @c wxWS_EX_VALIDATE_RECURSIVELY extra style flag set, + the method will also call TransferDataFromWindow() of all child windows. + + @see TransferDataToWindow(), wxValidator, Validate() + */ + virtual bool TransferDataFromWindow(); + + /** + Transfers values to child controls from data areas specified by their + validators. + If the window has @c wxWS_EX_VALIDATE_RECURSIVELY extra style flag set, + the method will also call TransferDataToWindow() of all child windows. + + @return Returns @false if a transfer failed. + + @see TransferDataFromWindow(), wxValidator, Validate() + */ + virtual bool TransferDataToWindow(); + + /** + Unregisters a system wide hotkey. + + @param hotkeyId + Numeric identifier of the hotkey. Must be the same id that was passed to + RegisterHotKey. + + @return @true if the hotkey was unregistered successfully, @false if the + id was invalid. + + @remarks This function is currently only implemented under MSW. + + @see RegisterHotKey() + */ + bool UnregisterHotKey(int hotkeyId); + + /** + Unreserve an ID or range of IDs that was reserved by NewControlId(). + See @ref overview_windowids "Window IDs Overview" for more information. + + @param id + The starting ID of the range of IDs to unreserve. + @param count + The number of sequential IDs to unreserve. + + @see NewControlId(), wxIdManager, @ref overview_windowids + "Window IDs Overview" + */ + static void UnreserveControlId(wxWindowID id, int count = 1); + + /** + Calling this method immediately repaints the invalidated area of the window and + all of its children recursively while this would usually only happen when the + flow of control returns to the event loop. + Notice that this function doesn't invalidate any area of the window so + nothing happens if nothing has been invalidated (i.e. marked as requiring + a redraw). Use Refresh() first if you want to + immediately redraw the window unconditionally. + */ + virtual void Update(); + + /** + This function sends wxUpdateUIEvents() to + the window. The particular implementation depends on the window; for + example a wxToolBar will send an update UI event for each toolbar button, + and a wxFrame will send an update UI event for each menubar menu item. + You can call this function from your application to ensure that your + UI is up-to-date at this point (as far as your wxUpdateUIEvent handlers + are concerned). This may be necessary if you have called + wxUpdateUIEvent::SetMode or + wxUpdateUIEvent::SetUpdateInterval to + limit the overhead that wxWidgets incurs by sending update UI events in idle + time. + @a flags should be a bitlist of one or more of the following values. + + If you are calling this function from an OnInternalIdle or OnIdle + function, make sure you pass the wxUPDATE_UI_FROMIDLE flag, since + this tells the window to only update the UI elements that need + to be updated in idle time. Some windows update their elements + only when necessary, for example when a menu is about to be shown. + The following is an example of how to call UpdateWindowUI from + an idle function. + + @see wxUpdateUIEvent, DoUpdateWindowUI(), OnInternalIdle() + */ + virtual void UpdateWindowUI(long flags = wxUPDATE_UI_NONE); + + /** + Validates the current values of the child controls using their validators. + If the window has @c wxWS_EX_VALIDATE_RECURSIVELY extra style flag set, + the method will also call Validate() of all child windows. + + @return Returns @false if any of the validations failed. + + @see TransferDataFromWindow(), TransferDataToWindow(), + wxValidator + */ + virtual bool Validate(); + + /** + Moves the pointer to the given position on the window. + @note This function is not supported under Mac because Apple Human + Interface Guidelines forbid moving the mouse cursor programmatically. + + @param x + The new x position for the cursor. + @param y + The new y position for the cursor. + */ + void WarpPointer(int x, int y); +}; + + +/// Valid values for wxWindow::ShowWithEffect() and wxWindow::HideWithEffect(). +enum wxShowEffect +{ + /// Roll window to the left + wxSHOW_EFFECT_ROLL_TO_LEFT, + /// Roll window to the right + wxSHOW_EFFECT_ROLL_TO_RIGHT, + /// Roll window to the top + wxSHOW_EFFECT_ROLL_TO_TOP, + /// Roll window to the bottom + wxSHOW_EFFECT_ROLL_TO_BOTTOM, + /// Slide window to the left + wxSHOW_EFFECT_SLIDE_TO_LEFT, + /// Slide window to the right + wxSHOW_EFFECT_SLIDE_TO_RIGHT, + /// Slide window to the top + wxSHOW_EFFECT_SLIDE_TO_TOP, + /// Slide window to the bottom + wxSHOW_EFFECT_SLIDE_TO_BOTTOM, + /// Fade in or out effect + wxSHOW_EFFECT_BLEND, + /// Expanding or collapsing effect + wxSHOW_EFFECT_EXPAND +}; + + + +// ============================================================================ +// Global functions/macros +// ============================================================================ + +/** @ingroup group_funcmacro_misc */ +//@{ + +/** + Find the deepest window at the mouse pointer position, returning the window + and current pointer position in screen coordinates. + + @header{wx/window.h} +*/ +wxWindow* wxFindWindowAtPointer(wxPoint& pt); + +/** + Gets the currently active window (implemented for MSW and GTK only + currently, always returns @NULL in the other ports). + + @header{wx/window.h} +*/ +wxWindow* wxGetActiveWindow(); + +/** + Returns the first top level parent of the given window, or in other words, + the frame or dialog containing it, or @NULL. + + @header{wx/window.h} +*/ +wxWindow* wxGetTopLevelParent(wxWindow* window); + +//@} + diff --git a/interface/wx/windowid.h b/interface/wx/windowid.h new file mode 100644 index 0000000000..7b14cce3ed --- /dev/null +++ b/interface/wx/windowid.h @@ -0,0 +1,42 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: windowid.h +// Purpose: interface of wxIdManager +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxIdManager + @wxheader{windowid.h} + + wxIdManager is responsible for allocating and releasing window IDs. It + is used by wxWindow::NewControlId and + wxWindow::UnreserveControlId, and can also + be used be used directly. + + @library{wxcore} + @category{FIXME} + + @see wxWindow::NewControlId, wxWindow::UnreserveControlId, @ref + overview_windowidsoverview "Window IDs overview" +*/ +class wxIdManager +{ +public: + /** + Called directly by wxWindow::NewControlId, + this function will create a new ID or range of IDs. The IDs will be + reserved until assigned to a wxWindowIDRef() + or unreserved with UnreserveControlId(). + Only ID values that are not assigned to a wxWindowIDRef() + need to be unreserved. + + @param count + The number of sequential IDs to reserve. + + @return The value of the first ID in the sequence, or wxID_NONE. + */ + static wxWindowID ReserveControlId(int count = 1); +}; + diff --git a/interface/wx/wizard.h b/interface/wx/wizard.h new file mode 100644 index 0000000000..8225b2f6d9 --- /dev/null +++ b/interface/wx/wizard.h @@ -0,0 +1,473 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: wizard.h +// Purpose: interface of wxWizardPage +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxWizardPage + @wxheader{wizard.h} + + wxWizardPage is one of the screens in wxWizard: it must + know what are the following and preceding pages (which may be @NULL for the + first/last page). Except for this extra knowledge, wxWizardPage is just a + panel, so the controls may be placed directly on it in the usual way. + + This class allows the programmer to decide the order of pages in the wizard + dynamically (during run-time) and so provides maximal flexibility. Usually, + however, the order of pages is known in advance in which case + wxWizardPageSimple class is enough and it is simpler + to use. + + @library{wxadv} + @category{miscwnd} + + @see wxWizard, @ref overview_samplewizard "wxWizard sample" +*/ +class wxWizardPage : public wxPanel +{ +public: + /** + Constructor accepts an optional bitmap which will be used for this page + instead of the default one for this wizard (note that all bitmaps used should + be of the same size). Notice that no other parameters are needed because the + wizard will resize and reposition the page anyhow. + + @param parent + The parent wizard + @param bitmap + The page-specific bitmap if different from the global one + */ + wxWizardPage(wxWizard* parent, + const wxBitmap& bitmap = wxNullBitmap); + + /** + This method is called by wxWizard to get the bitmap to display alongside the + page. By default, @c m_bitmap member variable which was set in the + @ref wxwizardpage() constructor. + If the bitmap was not explicitly set (i.e. if @c wxNullBitmap is returned), + the default bitmap for the wizard should be used. + The only cases when you would want to override this function is if the page + bitmap depends dynamically on the user choices, i.e. almost never. + */ + wxBitmap GetBitmap() const; + + /** + Get the page which should be shown when the user chooses the @c "Next" + button: if @NULL is returned, this button will be disabled. The last + page of the wizard will usually return @NULL from here, but the others + will not. + + @see GetPrev() + */ + wxWizardPage* GetNext() const; + + /** + Get the page which should be shown when the user chooses the @c "Back" + button: if @NULL is returned, this button will be disabled. The first + page of the wizard will usually return @NULL from here, but the others + will not. + + @see GetNext() + */ + wxWizardPage* GetPrev() const; +}; + + + +/** + @class wxWizardEvent + @wxheader{wizard.h} + + wxWizardEvent class represents an event generated by the + wizard(): this event is first sent to the page itself and, + if not processed there, goes up the window hierarchy as usual. + + @library{wxadv} + @category{events} + + @see wxWizard, @ref overview_samplewizard "wxWizard sample" +*/ +class wxWizardEvent : public wxNotifyEvent +{ +public: + /** + Constructor. It is not normally used by the user code as the objects of this + type are constructed by wxWizard. + */ + wxWizardEvent(wxEventType type = wxEVT_NULL, int id = -1, + bool direction = true); + + /** + Return the direction in which the page is changing: for @c + EVT_WIZARD_PAGE_CHANGING, return @true if we're going forward or + @false otherwise and for @c EVT_WIZARD_PAGE_CHANGED return @true if + we came from the previous page and @false if we returned from the next + one. + */ + bool GetDirection() const; + + /** + Returns the wxWizardPage which was active when this + event was generated. + */ + wxWizardPage* GetPage() const; +}; + + + +/** + @class wxWizardPageSimple + @wxheader{wizard.h} + + wxWizardPageSimple is the simplest possible + wxWizardPage implementation: it just returns the + pointers given to its constructor from GetNext() and GetPrev() functions. + + This makes it very easy to use the objects of this class in the wizards where + the pages order is known statically - on the other hand, if this is not the + case you must derive your own class from wxWizardPage + instead. + + @library{wxadv} + @category{miscwnd} + + @see wxWizard, @ref overview_samplewizard "wxWizard sample" +*/ +class wxWizardPageSimple : public wxWizardPage +{ +public: + /** + Constructor takes the previous and next pages. They may be modified later by + SetPrev() or + SetNext(). + */ + wxWizardPageSimple(wxWizard* parent = NULL, + wxWizardPage* prev = NULL, + wxWizardPage* next = NULL, + const wxBitmap& bitmap = wxNullBitmap); + + /** + A convenience function to make the pages follow each other. + Example: + */ + static void Chain(wxWizardPageSimple* first, + wxWizardPageSimple* second); + + /** + Sets the next page. + */ + void SetNext(wxWizardPage* next); + + /** + Sets the previous page. + */ + void SetPrev(wxWizardPage* prev); +}; + + + +/** + @class wxWizard + @wxheader{wizard.h} + + wxWizard is the central class for implementing 'wizard-like' dialogs. These + dialogs are mostly familiar to Windows users and are nothing other than a + sequence of 'pages', each displayed inside a dialog which has the + buttons to navigate to the next (and previous) pages. + + The wizards are typically used to decompose a complex dialog into several + simple steps and are mainly useful to the novice users, hence it is important + to keep them as simple as possible. + + To show a wizard dialog, you must first create an instance of the wxWizard class + using either the non-default constructor or a default one followed by call to + the + wxWizard::Create function. Then you should add all pages you + want the wizard to show and call wxWizard::RunWizard. + Finally, don't forget to call @c wizard-Destroy(), otherwise your application + will hang on exit due to an undestroyed window. + + You can supply a bitmap to display on the left of the wizard, either for all + pages + or for individual pages. If you need to have the bitmap resize to the height of + the wizard, + call wxWizard::SetBitmapPlacement and if necessary, + wxWizard::SetBitmapBackgroundColour and wxWizard::SetMinimumBitmapWidth. + + To make wizard pages scroll when the display is too small to fit the whole + dialog, you can switch + layout adaptation on globally with wxDialog::EnableLayoutAdaptation or + per dialog with wxDialog::SetLayoutAdaptationMode. For more + about layout adaptation, see @ref overview_autoscrollingdialogs "Automatic + scrolling dialogs". + + @library{wxadv} + @category{cmndlg} + + @see wxWizardEvent, wxWizardPage, @ref overview_samplewizard "wxWizard sample" +*/ +class wxWizard : public wxDialog +{ +public: + //@{ + /** + Constructor which really creates the wizard -- if you use this constructor, you + shouldn't call Create(). + Notice that unlike almost all other wxWidgets classes, there is no @e size + parameter in the wxWizard constructor because the wizard will have a predefined + default size by default. If you want to change this, you should use the + GetPageAreaSizer() function. + + @param parent + The parent window, may be @NULL. + @param id + The id of the dialog, will usually be just -1. + @param title + The title of the dialog. + @param bitmap + The default bitmap used in the left side of the wizard. See + also GetBitmap. + @param pos + The position of the dialog, it will be centered on the screen + by default. + @param style + Window style is passed to wxDialog. + */ + wxWizard(); + wxWizard(wxWindow* parent, int id = -1, + const wxString& title = wxEmptyString, + const wxBitmap& bitmap = wxNullBitmap, + const wxPoint& pos = wxDefaultPosition, + long style = wxDEFAULT_DIALOG_STYLE); + //@} + + /** + Creates the wizard dialog. Must be called if the default constructor had been + used to create the object. + Notice that unlike almost all other wxWidgets classes, there is no @e size + parameter in the wxWizard constructor because the wizard will have a predefined + default size by default. If you want to change this, you should use the + GetPageAreaSizer() function. + + @param parent + The parent window, may be @NULL. + @param id + The id of the dialog, will usually be just -1. + @param title + The title of the dialog. + @param bitmap + The default bitmap used in the left side of the wizard. See + also GetBitmap. + @param pos + The position of the dialog, it will be centered on the screen + by default. + @param style + Window style is passed to wxDialog. + */ + bool Create(wxWindow* parent, int id = -1, + const wxString& title = wxEmptyString, + const wxBitmap& bitmap = wxNullBitmap, + const wxPoint& pos = wxDefaultPosition, + long style = wxDEFAULT_DIALOG_STYLE); + + /** + This method is obsolete, use + GetPageAreaSizer() instead. + Sets the page size to be big enough for all the pages accessible via the + given @e firstPage, i.e. this page, its next page and so on. + This method may be called more than once and it will only change the page size + if the size required by the new page is bigger than the previously set one. + This is useful if the decision about which pages to show is taken during + run-time, as in this case, the wizard won't be able to get to all pages starting + from a single one and you should call @e Fit separately for the others. + */ + void FitToPage(const wxWizardPage* firstPage); + + /** + Returns the bitmap used for the wizard. + */ + const wxBitmap GetBitmap() const; + + /** + Returns the colour that should be used to fill the area not taken up by the + wizard or page bitmap, + if a non-zero bitmap placement flag has been set. + See also SetBitmapPlacement(). + */ + const wxColour GetBitmapBackgroundColour() const; + + /** + Returns the flags indicating how the wizard or page bitmap should be expanded + and positioned to fit the + page height. By default, placement is 0 (no expansion is done). + See also SetBitmapPlacement() for the possible values. + */ + int GetBitmapPlacement(); + + /** + Get the current page while the wizard is running. @NULL is returned if + RunWizard() is not being executed now. + */ + wxWizardPage* GetCurrentPage() const; + + /** + Returns the minimum width for the bitmap that will be constructed to contain + the actual wizard or page bitmap + if a non-zero bitmap placement flag has been set. + See also SetBitmapPlacement(). + */ + int GetMinimumBitmapWidth() const; + + /** + Returns pointer to page area sizer. The wizard is laid out using sizers and + the page area sizer is the place-holder for the pages. All pages are resized + before + being shown to match the wizard page area. + Page area sizer has a minimal size that is the maximum of several values. First, + all pages (or other objects) added to the sizer. Second, all pages reachable + by repeatedly applying + wxWizardPage::GetNext to + any page inserted into the sizer. Third, + the minimal size specified using SetPageSize() and + FitToPage(). Fourth, the total wizard height may + be increased to accommodate the bitmap height. Fifth and finally, wizards are + never smaller than some built-in minimal size to avoid wizards that are too + small. + The caller can use wxSizer::SetMinSize to enlarge it + beyond the minimal size. If @c wxRESIZE_BORDER was passed to constructor, user + can resize wizard and consequently the page area (but not make it smaller than + the + minimal size). + It is recommended to add the first page to the page area sizer. For simple + wizards, + this will enlarge the wizard to fit the biggest page. For non-linear wizards, + the first page of every separate chain should be added. Caller-specified size + can be accomplished using wxSizer::SetMinSize. + Adding pages to the page area sizer affects the default border width around page + area that can be altered with SetBorder(). + */ + virtual wxSizer* GetPageAreaSizer() const; + + /** + Returns the size available for the pages. + */ + wxSize GetPageSize() const; + + /** + Return @true if this page is not the last one in the wizard. The base + class version implements this by calling + @ref wxWizardPage::getnext page-GetNext but this could be undesirable if, + for example, the pages are created on demand only. + + @see HasPrevPage() + */ + virtual bool HasNextPage(wxWizardPage* page); + + /** + Returns @true if this page is not the last one in the wizard. The base + class version implements this by calling + @ref wxWizardPage::getprev page-GetPrev but this could be undesirable if, + for example, the pages are created on demand only. + + @see HasNextPage() + */ + virtual bool HasPrevPage(wxWizardPage* page); + + /** + Executes the wizard starting from the given page, returning @true if it was + successfully finished or @false if user cancelled it. The @a firstPage + can not be @NULL. + */ + bool RunWizard(wxWizardPage* firstPage); + + /** + Sets the bitmap used for the wizard. + */ + void SetBitmap(const wxBitmap& bitmap); + + /** + Sets the colour that should be used to fill the area not taken up by the wizard + or page bitmap, + if a non-zero bitmap placement flag has been set. + See also SetBitmapPlacement(). + */ + void SetBitmapBackgroundColour(const wxColour& colour); + + /** + Sets the flags indicating how the wizard or page bitmap should be expanded and + positioned to fit the + page height. By default, placement is 0 (no expansion is done). @a placement is + a bitlist with the + following possible values: + + @b wxWIZARD_VALIGN_TOP + + Aligns the bitmap at the top. + + @b wxWIZARD_VALIGN_CENTRE + + Centres the bitmap vertically. + + @b wxWIZARD_VALIGN_BOTTOM + + Aligns the bitmap at the bottom. + + @b wxWIZARD_HALIGN_LEFT + + Left-aligns the bitmap. + + @b wxWIZARD_HALIGN_CENTRE + + Centres the bitmap horizontally. + + @b wxWIZARD_HALIGN_RIGHT + + Right-aligns the bitmap. + + @b wxWIZARD_TILE + + + See also SetMinimumBitmapWidth(). + */ + void SetBitmapPlacement(int placement); + + /** + Sets width of border around page area. Default is zero. For backward + compatibility, if there are no pages in + GetPageAreaSizer(), the default is 5 pixels. + If there is a five point border around all controls in a page and the border + around + page area is left as zero, a five point white space along all dialog borders + will be added to the control border in order to space page controls ten points + from the dialog + border and non-page controls. + */ + void SetBorder(int border); + + /** + Sets the minimum width for the bitmap that will be constructed to contain the + actual wizard or page bitmap + if a non-zero bitmap placement flag has been set. If this is not set when using + bitmap placement, the initial + layout may be incorrect. + See also SetBitmapPlacement(). + */ + void SetMinimumBitmapWidth(int width); + + /** + This method is obsolete, use + GetPageAreaSizer() instead. + Sets the minimal size to be made available for the wizard pages. The wizard + will take into account the size of the bitmap (if any) itself. Also, the + wizard will never be smaller than the default size. + The recommended way to use this function is to lay out all wizard pages using + the sizers (even though the wizard is not resizeable) and then use + wxSizer::CalcMin in a loop to calculate the maximum + of minimal sizes of the pages and pass it to SetPageSize(). + */ + void SetPageSize(const wxSize& sizePage); +}; + diff --git a/interface/wx/wrapsizer.h b/interface/wx/wrapsizer.h new file mode 100644 index 0000000000..9a186de2fc --- /dev/null +++ b/interface/wx/wrapsizer.h @@ -0,0 +1,63 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: wrapsizer.h +// Purpose: interface of wxWrapSizer +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxWrapSizer + @wxheader{wrapsizer.h} + + A wrap sizer lays out its items in a single line, like a box sizer -- as long + as there is space available in that direction. Once all available space in + the primary direction has been used, a new line is added and items are added + there. + + So a wrap sizer has a primary orientation for adding items, and adds lines + as needed in the secondary direction. + + @library{wxcore} + @category{winlayout} + + @see wxBoxSizer, wxSizer, @ref overview_sizeroverview "Sizer overview" +*/ +class wxWrapSizer : public wxBoxSizer +{ +public: + /** + Constructor for a wxWrapSizer. @a orient determines the primary direction of + the sizer (the most common case being @c wxHORIZONTAL). The flags + parameter can be a combination of the values @c + wxEXTEND_LAST_ON_EACH_LINE which will cause the last item on each line + to use any remaining space on that line and @c wxREMOVE_LEADING_SPACES + which removes any spacer elements from the beginning of a row. Both of + these flags are on by default. + */ + wxWrapSizer(int orient = wxHORIZONTAL, + int flags = wxEXTEND_LAST_ON_EACH_LINE | + wxREMOVE_LEADING_SPACES); + + /** + Not used by an application. This is the mechanism by which sizers can inform + sub-items of the first determined size component. The sub-item can then better + determine its size requirements. + Returns @true if the information was used (and the sub-item min size was + updated). + */ + bool InformFirstDirection(int direction, int size, + int availableOtherDir); + +protected: + /** + Can be overridden in the derived classes to treat some normal items as + spacers. + + This method is used to determine whether the given @a item should be + considered to be a spacer for the purposes of @c wxREMOVE_LEADING_SPACES + implementation. By default only returns @true for the real spacers. + */ + virtual bool IsSpaceItem(wxSizerItem *item) const; +}; + diff --git a/interface/wx/wupdlock.h b/interface/wx/wupdlock.h new file mode 100644 index 0000000000..525a9a09f6 --- /dev/null +++ b/interface/wx/wupdlock.h @@ -0,0 +1,53 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: wupdlock.h +// Purpose: interface of wxWindowUpdateLocker +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxWindowUpdateLocker + @wxheader{wupdlock.h} + + This tiny class prevents redrawing of a wxWindow during its + lifetime by using wxWindow::Freeze and + wxWindow::Thaw methods. It is typically used for creating + automatic objects to temporarily suppress window updates before a batch of + operations is performed: + + @code + void MyFrame::Foo() + { + m_text = new wxTextCtrl(this, ...); + + wxWindowUpdateLocker noUpdates(m_text); + m_text-AppendText(); + ... many other operations with m_text... + m_text-WriteText(); + } + @endcode + + Using this class is easier and safer than calling + wxWindow::Freeze and wxWindow::Thaw because you + don't risk to forget calling the latter. + + @library{wxbase} + @category{FIXME} +*/ +class wxWindowUpdateLocker +{ +public: + /** + Creates an object preventing the updates of the specified @e win. The + parameter must be non-@NULL and the window must exist for longer than + wxWindowUpdateLocker object itself. + */ + wxWindowUpdateLocker(wxWindow* win); + + /** + Destructor reenables updates for the window this object is associated with. + */ + ~wxWindowUpdateLocker(); +}; + diff --git a/interface/wx/wxcrt.h b/interface/wx/wxcrt.h new file mode 100644 index 0000000000..f30ed8982c --- /dev/null +++ b/interface/wx/wxcrt.h @@ -0,0 +1,123 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: wxcrt.h +// Purpose: interface of global functions +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** @ingroup group_funcmacro_string */ +//@{ + +/** + @return @true if the pointer is either @NULL or points to an empty string, + @false otherwise. + + @header{wx/wxcrt.h} +*/ +bool wxIsEmpty(const char* p); + +/** + This is a safe version of standard function @e strlen(): it does exactly + the same thing (i.e. returns the length of the string) except that it + returns 0 if @a p is the @NULL pointer. + + @header{wx/wxcrt.h} +*/ +size_t wxStrlen(const char* p); + +/** + This function complements the standard C function @e stricmp() which + performs case-insensitive comparison. + + @return A negative value, 0, or positive value if @a p1 is less than, + equal to or greater than @a p2. The comparison is case-sensitive. + + @header{wx/wxcrt.h} +*/ +int wxStrcmp(const char* p1, const char* p2); + +/** + This function complements the standard C function @e strcmp() which performs + case-sensitive comparison. + + @return A negative value, 0, or positive value if @a p1 is less than, + equal to or greater than @e p2. The comparison is case-insensitive. + + @header{wx/wxcrt.h} +*/ +int wxStricmp(const char* p1, const char* p2); + +/** + @deprecated Use wxString instead. + + This macro is defined as: + + @code + #define wxStringEq(s1, s2) (s1 && s2 && (strcmp(s1, s2) == 0)) + @endcode + + @header{wx/wxcrt.h} +*/ +bool wxStringEq(const wxString& s1, const wxString& s2); + +/** + @deprecated Use wxString::Find() instead. + + Returns @true if the substring @a s1 is found within @a s2, ignoring case + if @a exact is @false. If @a subString is @false, no substring matching is + done. + + @header{wx/wxcrt.h} +*/ +bool wxStringMatch(const wxString& s1, const wxString& s2, + bool subString = true, bool exact = false); + +/** + This is a convenience function wrapping wxStringTokenizer which simply + returns all tokens found in the given @a string in an array. + + Please see wxStringTokenizer::wxStringTokenizer() for a description of the + other parameters. + + @header{wx/wxcrt.h} +*/ +wxArrayString wxStringTokenize(const wxString& string, + const wxString& delims = wxDEFAULT_DELIMITERS, + wxStringTokenizerMode mode = wxTOKEN_DEFAULT); + +/** + This function replaces the dangerous standard function @e sprintf() and is + like @e snprintf() available on some platforms. The only difference with + @e sprintf() is that an additional argument - buffer size - is taken and + the buffer is never overflowed. + + Returns the number of characters copied to the buffer or -1 if there is not + enough space. + + @see wxVsnprintf(), wxString::Printf() + + @header{wx/wxcrt.h} +*/ +int wxSnprintf(wxChar* buf, size_t len, const wxChar* format, ...); + +/** + The same as wxSnprintf() but takes a @c va_list argument instead of an + arbitrary number of parameters. + + @note If @c wxUSE_PRINTF_POS_PARAMS is set to 1, then this function + supports positional arguments (see wxString::Printf() for more + information). However other functions of the same family (wxPrintf(), + wxSprintf(), wxFprintf(), wxVfprintf(), wxVfprintf(), wxVprintf(), + wxVsprintf()) currently do not to support positional parameters even + when @c wxUSE_PRINTF_POS_PARAMS is 1. + + @see wxSnprintf(), wxString::PrintfV() + + @header{wx/wxcrt.h} +*/ +int wxVsnprintf(wxChar* buf, size_t len, + const wxChar* format, va_list argPtr); + +//@} + diff --git a/interface/wx/xml/xml.h b/interface/wx/xml/xml.h new file mode 100644 index 0000000000..bbc63c62ed --- /dev/null +++ b/interface/wx/xml/xml.h @@ -0,0 +1,518 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: xml/xml.h +// Purpose: interface of wxXmlNode +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxXmlNode + @headerfile xml.h wx/xml/xml.h + + Represents a node in an XML document. See wxXmlDocument. + + Node has a name and may have content and attributes. Most common node types are + @c wxXML_TEXT_NODE (name and attributes are irrelevant) and + @c wxXML_ELEMENT_NODE (e.g. in @c titlehi/title there is an element + with name="title", irrelevant content and one child (@c wxXML_TEXT_NODE + with content="hi"). + + If @c wxUSE_UNICODE is 0, all strings are encoded in the encoding given to + wxXmlDocument::Load (default is UTF-8). + + @library{wxxml} + @category{xml} + + @see wxXmlDocument, wxXmlAttribute +*/ +class wxXmlNode +{ +public: + //@{ + /** + A simplified version of the first constructor form, assuming a @NULL parent. + */ + wxXmlNode(wxXmlNode* parent, wxXmlNodeType type, + const wxString& name, + const wxString& content = wxEmptyString, + wxXmlAttribute* attrs = NULL, + wxXmlNode* next = NULL, int lineNo = -1); + wxXmlNode(const wxXmlNode& node); + wxXmlNode(wxXmlNodeType type, const wxString& name, + const wxString& content = wxEmptyString, + int lineNo = -1); + //@} + + /** + The virtual destructor. Deletes attached children and attributes. + */ + ~wxXmlNode(); + + //@{ + /** + Appends given attribute to the list of attributes for this node. + */ + void AddAttribute(const wxString& name, const wxString& value); + void AddAttribute(wxXmlAttribute* attr); + //@} + + /** + Adds node @a child as the last child of this node. + + @note + Note that this function works in O(n) time where @e n is the number + of existing children. Consequently, adding large number of child + nodes using this method can be expensive, because it has O(n^2) time + complexity in number of nodes to be added. Use InsertChildAfter() to + populate XML tree in linear time. + + @see InsertChild(), InsertChildAfter() + */ + void AddChild(wxXmlNode* child); + + /** + Removes the first attributes which has the given @a name from the list of + attributes for this node. + */ + bool DeleteAttribute(const wxString& name); + + //@{ + /** + Returns the value of the attribute named @a attrName if it does exist. + If it does not exist, the @a defaultVal is returned. + */ + bool GetAttribute(const wxString& attrName, wxString* value) const; + const wxString GetAttribute(const wxString& attrName, + const wxString& defaultVal = wxEmptyString) const; + //@} + + /** + Return a pointer to the first attribute of this node. + */ + wxXmlAttribute* GetAttributes() const; + + /** + Returns the first child of this node. + To get a pointer to the second child of this node (if it does exist), use the + GetNext() function on the returned value. + */ + wxXmlNode* GetChildren() const; + + /** + Returns the content of this node. Can be an empty string. + Be aware that for nodes of type @c wxXML_ELEMENT_NODE (the most used node type) + the + content is an empty string. See GetNodeContent() for more details. + */ + wxString GetContent() const; + + /** + Returns the number of nodes which separe this node from @c grandparent. + This function searches only the parents of this node until it finds @c + grandparent + or the @NULL node (which is the parent of non-linked nodes or the parent of a + wxXmlDocument's root node). + */ + int GetDepth(wxXmlNode* grandparent = NULL) const; + + /** + Returns line number of the node in the input XML file or -1 if it is unknown. + */ + int GetLineNumber() const; + + /** + Returns the name of this node. Can be an empty string (e.g. for nodes of type + @c wxXML_TEXT_NODE or @c wxXML_CDATA_SECTION_NODE). + */ + wxString GetName() const; + + /** + Returns a pointer to the sibling of this node or @NULL if there are no + siblings. + */ + wxXmlNode* GetNext() const; + + /** + Returns the content of the first child node of type @c wxXML_TEXT_NODE or @c + wxXML_CDATA_SECTION_NODE. + This function is very useful since the XML snippet @c + "tagnametagcontent/tagname" is represented by + expat with the following tag tree: + + or eventually: + + An empty string is returned if the node has no children of type @c + wxXML_TEXT_NODE or @c wxXML_CDATA_SECTION_NODE, or if the content of the first child of such types is empty. + */ + wxString GetNodeContent() const; + + /** + Returns a pointer to the parent of this node or @NULL if this node has no + parent. + */ + wxXmlNode* GetParent() const; + + /** + Returns the type of this node. + */ + wxXmlNodeType GetType() const; + + /** + Returns @true if this node has a attribute named @e attrName. + */ + bool HasAttribute(const wxString& attrName) const; + + /** + Inserts the @a child node immediately before @a followingNode in the + children list. + + @return @true if @a followingNode has been found and the @a child + node has been inserted. + + @note + For historical reasons, @a followingNode may be @NULL. In that case, + then @a child is prepended to the list of children and becomes the + first child of this node, i.e. it behaves identically to using the + first children (as returned by GetChildren()) for @a followingNode). + + @see AddChild(), InsertChildAfter() + */ + bool InsertChild(wxXmlNode* child, wxXmlNode* followingNode); + + /** + Inserts the @a child node immediately after @a precedingNode in the + children list. + + @return @true if @a precedingNode has been found and the @a child + node has been inserted. + + @param precedingNode + The node to insert @a child after. As a special case, this can be + @NULL if this node has no children yet -- in that case, @a child + will become this node's only child node. + + @since 2.8.8 + + @see InsertChild(), AddChild() + */ + bool InsertChildAfter(wxXmlNode* child, wxXmlNode* precedingNode); + + /** + Returns @true if the content of this node is a string containing only + whitespaces (spaces, + tabs, new lines, etc). Note that this function is locale-independent since the + parsing of XML + documents must always produce the exact same tree regardless of the locale it + runs under. + */ + bool IsWhitespaceOnly() const; + + /** + Removes the given node from the children list. Returns @true if the node was + found and removed + or @false if the node could not be found. + Note that the caller is reponsible for deleting the removed node in order to + avoid memory leaks. + */ + bool RemoveChild(wxXmlNode* child); + + /** + Sets as first attribute the given wxXmlAttribute object. + The caller is responsible to delete any previously present attributes attached + to this node. + */ + void SetAttributes(wxXmlAttribute* attr); + + /** + Sets as first child the given node. The caller is responsible to delete any + previously present + children node. + */ + void SetChildren(wxXmlNode* child); + + /** + Sets the content of this node. + */ + void SetContent(const wxString& con); + + /** + Sets the name of this node. + */ + void SetName(const wxString& name); + + /** + Sets as sibling the given node. The caller is responsible to delete any + previously present + sibling node. + */ + void SetNext(wxXmlNode* next); + + /** + Sets as parent the given node. The caller is responsible to delete any + previously present + parent node. + */ + void SetParent(wxXmlNode* parent); + + /** + Sets the type of this node. + */ + void SetType(wxXmlNodeType type); + + /** + See the copy constructor for more info. + */ + wxXmlNode operator=(const wxXmlNode& node); +}; + + + +/** + @class wxXmlAttribute + @headerfile xml.h wx/xml/xml.h + + Represents a node attribute. + + Example: in @c img src="hello.gif" id="3"/, @c "src" is attribute with value + @c "hello.gif" and @c "id" is a attribute with value @c "3". + + @library{wxxml} + @category{xml} + + @see wxXmlDocument, wxXmlNode +*/ +class wxXmlAttribute +{ +public: + //@{ + /** + Creates the attribute with given @a name and @e value. + If @a next is not @NULL, then sets it as sibling of this attribute. + */ + wxXmlAttribute(); + wxXmlAttribute(const wxString& name, const wxString& value, + wxXmlAttribute* next = NULL); + //@} + + /** + The virtual destructor. + */ + ~wxXmlAttribute(); + + /** + Returns the name of this attribute. + */ + wxString GetName() const; + + /** + Returns the sibling of this attribute or @NULL if there are no siblings. + */ + wxXmlAttribute* GetNext() const; + + /** + Returns the value of this attribute. + */ + wxString GetValue() const; + + /** + Sets the name of this attribute. + */ + void SetName(const wxString& name); + + /** + Sets the sibling of this attribute. + */ + void SetNext(wxXmlAttribute* next); + + /** + Sets the value of this attribute. + */ + void SetValue(const wxString& value); +}; + + + +/** + @class wxXmlDocument + @headerfile xml.h wx/xml/xml.h + + This class holds XML data/document as parsed by XML parser in the root node. + + wxXmlDocument internally uses the expat library which comes with wxWidgets to + parse the given stream. + + A simple example of using XML classes is: + + @code + wxXmlDocument doc; + if (!doc.Load(wxT("myfile.xml"))) + return @false; + + // start processing the XML file + if (doc.GetRoot()-GetName() != wxT("myroot-node")) + return @false; + + wxXmlNode *child = doc.GetRoot()-GetChildren(); + while (child) { + + if (child-GetName() == wxT("tag1")) { + + // process text enclosed by tag1/tag1 + wxString content = child-GetNodeContent(); + + ... + + // process attributes of tag1 + wxString attrvalue1 = + child-GetAttribute(wxT("attr1"), + wxT("default-value")); + wxString attrvalue2 = + child-GetAttribute(wxT("attr2"), + wxT("default-value")); + + ... + + } else if (child-GetName() == wxT("tag2")) { + + // process tag2 ... + } + + child = child-GetNext(); + } + @endcode + + @note if you want to preserve the original formatting of the loaded file + including whitespaces + and indentation, you need to turn off whitespace-only textnode removal and + automatic indentation: + + @code + wxXmlDocument doc; + doc.Load(wxT("myfile.xml"), wxT("UTF-8"), wxXMLDOC_KEEP_WHITESPACE_NODES); + + // myfile2.xml will be indentic to myfile.xml saving it this way: + doc.Save(wxT("myfile2.xml"), wxXML_NO_INDENTATION); + @endcode + + Using default parameters, you will get a reformatted document which in general + is different from + the original loaded content: + + @code + wxXmlDocument doc; + doc.Load(wxT("myfile.xml")); + doc.Save(wxT("myfile2.xml")); // myfile2.xml != myfile.xml + @endcode + + @library{wxxml} + @category{xml} + + @see wxXmlNode, wxXmlAttribute +*/ +class wxXmlDocument : public wxObject +{ +public: + //@{ + /** + Copy constructor. Deep copies all the XML tree of the given document. + */ + wxXmlDocument(); + wxXmlDocument(const wxString& filename); + wxXmlDocument(wxInputStream& stream); + wxXmlDocument(const wxXmlDocument& doc); + //@} + + /** + Virtual destructor. Frees the document root node. + */ + ~wxXmlDocument(); + + /** + Detaches the document root node and returns it. The document root node will be + set to @NULL + and thus IsOk() will return @false after calling this function. + Note that the caller is reponsible for deleting the returned node in order to + avoid memory leaks. + */ + wxXmlNode* DetachRoot(); + + /** + Returns encoding of in-memory representation of the document + (same as passed to Load() or constructor, defaults to UTF-8). + @note this is meaningless in Unicode build where data are stored as @c wchar_t*. + */ + wxString GetEncoding() const; + + /** + Returns encoding of document (may be empty). + Note: this is the encoding original file was saved in, @b not the + encoding of in-memory representation! + */ + wxString GetFileEncoding() const; + + /** + Returns the root node of the document. + */ + wxXmlNode* GetRoot() const; + + /** + Returns the version of document. + This is the value in the @c ?xml version="1.0"? header of the XML document. + If the version attribute was not explicitely given in the header, this function + returns an empty string. + */ + wxString GetVersion() const; + + /** + Returns @true if the document has been loaded successfully. + */ + bool IsOk() const; + + //@{ + /** + , @b int@e flags = wxXMLDOC_NONE) + Like above but takes the data from given input stream. + */ + bool Load(const wxString& filename); + int bool Load(wxInputStream& stream); + //@} + + //@{ + /** + Saves XML tree in the given output stream. See other overload for a description + of @c indentstep. + */ + bool Save(const wxString& filename, int indentstep = 1) const; + const bool Save(wxOutputStream& stream, int indentstep = 1) const; + //@} + + /** + Sets the enconding of the document. + */ + void SetEncoding(const wxString& enc); + + /** + Sets the enconding of the file which will be used to save the document. + */ + void SetFileEncoding(const wxString& encoding); + + /** + Sets the root node of this document. Deletes previous root node. + Use DetachRoot() and then + SetRoot() if you want + to replace the root node without deleting the old document tree. + */ + void SetRoot(wxXmlNode* node); + + /** + Sets the version of the XML file which will be used to save the document. + */ + void SetVersion(const wxString& version); + + /** + Deep copies the given document. + */ + wxXmlDocument& operator operator=(const wxXmlDocument& doc); +}; + diff --git a/interface/wx/xrc/xmlres.h b/interface/wx/xrc/xmlres.h new file mode 100644 index 0000000000..d1d2765684 --- /dev/null +++ b/interface/wx/xrc/xmlres.h @@ -0,0 +1,436 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: xrc/xmlres.h +// Purpose: interface of wxXmlResource +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxXmlResource + @headerfile xmlres.h wx/xrc/xmlres.h + + This is the main class for interacting with the XML-based resource system. + + The class holds XML resources from one or more .xml files, binary files or zip + archive files. + + See @ref overview_xrcoverview "XML-based resource system overview" for details. + + @library{wxxrc} + @category{xrc} +*/ +class wxXmlResource : public wxObject +{ +public: + //@{ + /** + Constructor. + + @param flags + wxXRC_USE_LOCALE: translatable strings will be translated via _(). + wxXRC_NO_SUBCLASSING: subclass property of object nodes will be ignored + (useful for previews in XRC editors). wxXRC_NO_RELOADING will prevent the + XRC files from being reloaded from disk in case they have been modified + there + since being last loaded (may slightly speed up loading them). + @param domain + The name of the gettext catalog to search for + translatable strings. By default all loaded catalogs will be + searched. This provides a way to allow the strings to only come + from a specific catalog. + */ + wxXmlResource(const wxString& filemask, + int flags = wxXRC_USE_LOCALE, + const wxString domain = wxEmptyString); + wxXmlResource(int flags = wxXRC_USE_LOCALE, + const wxString domain = wxEmptyString); + //@} + + /** + Destructor. + */ + ~wxXmlResource(); + + /** + Initializes only a specific handler (or custom handler). Convention says + that the handler name is equal to the control's name plus 'XmlHandler', for + example + wxTextCtrlXmlHandler, wxHtmlWindowXmlHandler. The XML resource compiler + (wxxrc) can create include file that contains initialization code for + all controls used within the resource. Note that this handler should be + allocated on the heap, since it will be delete by + ClearHandlers() later. + */ + void AddHandler(wxXmlResourceHandler* handler); + + /** + Attaches an unknown control to the given panel/window/dialog. + Unknown controls are used in conjunction with object class="unknown". + */ + bool AttachUnknownControl(const wxString& name, + wxWindow* control, + wxWindow* parent = NULL); + + /** + Removes all handlers and deletes them (this means that any handlers added using + AddHandler() must be allocated on the heap). + */ + void ClearHandlers(); + + /** + Compares the XRC version to the argument. Returns -1 if the XRC version + is less than the argument, +1 if greater, and 0 if they equal. + */ + int CompareVersion(int major, int minor, int release, + int revision) const; + + /** + Gets the global resources object or creates one if none exists. + */ + wxXmlResource* Get(); + + /** + Returns the domain (message catalog) that will be used to load + translatable strings in the XRC. + */ + wxChar* GetDomain(); + + /** + Returns flags, which may be a bitlist of wxXRC_USE_LOCALE and + wxXRC_NO_SUBCLASSING. + */ + int GetFlags(); + + /** + Returns version information (a.b.c.d = d+ 256*c + 256@c 2*b + 256@c 3*a). + */ + long GetVersion() const; + + /** + Returns a numeric ID that is equivalent to the string ID used in an XML + resource. If an unknown @a str_id is requested (i.e. other than wxID_XXX + or integer), a new record is created which associates the given string with + a number. If @a value_if_not_found is @c wxID_NONE, the number is obtained via + wxNewId(). Otherwise @a value_if_not_found is used. + Macro @c XRCID(name) is provided for convenient use in event tables. + */ +#define int GetXRCID(const wxString& str_id, int value_if_not_found = -2) /* implementation is private */ + + /** + Initializes handlers for all supported controls/windows. This will + make the executable quite big because it forces linking against + most of the wxWidgets library. + */ + void InitAllHandlers(); + + /** + Loads resources from XML files that match given filemask. + This method understands VFS (see filesys.h). + */ + bool Load(const wxString& filemask); + + /** + Loads a bitmap resource from a file. + */ + wxBitmap LoadBitmap(const wxString& name); + + //@{ + /** + Loads a dialog. @a dlg points to parent window (if any). + This form is used to finish creation of an already existing instance (the main + reason + for this is that you may want to use derived class with a new event table). + Example: + */ + wxDialog* LoadDialog(wxWindow* parent, const wxString& name); + bool LoadDialog(wxDialog* dlg, wxWindow* parent, + const wxString& name); + //@} + + /** + Loads a frame. + */ + bool LoadFrame(wxFrame* frame, wxWindow* parent, + const wxString& name); + + /** + Loads an icon resource from a file. + */ + wxIcon LoadIcon(const wxString& name); + + /** + Loads menu from resource. Returns @NULL on failure. + */ + wxMenu* LoadMenu(const wxString& name); + + //@{ + /** + Loads a menubar from resource. Returns @NULL on failure. + */ + wxMenuBar* LoadMenuBar(wxWindow* parent, const wxString& name); + wxMenuBar* LoadMenuBar(const wxString& name); + //@} + + //@{ + /** + Load an object from the resource specifying both the resource name and the + class name. + The first overload lets you load nonstandard container windows and returns @c + @NULL + on failure. The second one lets you finish the creation of an existing + instance and returns @false on failure. + */ + wxObject* LoadObject(wxWindow* parent, const wxString& name, + const wxString& classname); + bool LoadObject(wxObject* instance, wxWindow* parent, + const wxString& name, + const wxString& classname); + //@} + + //@{ + /** + Loads a panel. @a panel points to parent window (if any). This form + is used to finish creation of an already existing instance. + */ + wxPanel* LoadPanel(wxWindow* parent, const wxString& name); + bool LoadPanel(wxPanel* panel, wxWindow* parent, + const wxString& name); + //@} + + /** + Loads a toolbar. + */ + wxToolBar* LoadToolBar(wxWindow* parent, const wxString& name); + + /** + Sets the global resources object and returns a pointer to the previous one (may + be @NULL). + */ + wxXmlResource* Set(wxXmlResource* res); + + /** + Sets the domain (message catalog) that will be used to load + translatable strings in the XRC. + */ + wxChar* SetDomain(const wxChar* domain); + + /** + Sets flags (bitlist of wxXRC_USE_LOCALE and wxXRC_NO_SUBCLASSING). + */ + void SetFlags(int flags); + + /** + This function unloads a resource previously loaded by + Load(). + Returns @true if the resource was successfully unloaded and @false if it + hasn't + been found in the list of loaded resources. + */ + bool Unload(const wxString& filename); +}; + + + +/** + @class wxXmlResourceHandler + @headerfile xmlres.h wx/xrc/xmlres.h + + wxXmlResourceHandler is an abstract base class for resource handlers + capable of creating a control from an XML node. + + See @ref overview_xrcoverview "XML-based resource system overview" for details. + + @library{wxxrc} + @category{xrc} +*/ +class wxXmlResourceHandler : public wxObject +{ +public: + /** + Default constructor. + */ + wxXmlResourceHandler(); + + /** + Destructor. + */ + ~wxXmlResourceHandler(); + + /** + Add a style flag (e.g. wxMB_DOCKABLE) to the list of flags + understood by this handler. + */ + void AddStyle(const wxString& name, int value); + + /** + Add styles common to all wxWindow-derived classes. + */ + void AddWindowStyles(); + + /** + Returns @true if it understands this node and can create + a resource from it, @false otherwise. + */ + bool CanHandle(wxXmlNode* node); + + /** + Creates children. + */ + void CreateChildren(wxObject* parent, bool this_hnd_only = false); + + /** + Helper function. + */ + void CreateChildrenPrivately(wxObject* parent, + wxXmlNode* rootnode = NULL); + + /** + Creates a resource from a node. + */ + wxObject* CreateResFromNode(wxXmlNode* node, wxObject* parent, + wxObject* instance = NULL); + + /** + Creates an object (menu, dialog, control, ...) from an XML node. + Should check for validity. @a parent is a higher-level object (usually window, + dialog or panel) + that is often necessary to create the resource. + If @b instance is non-@NULL it should not create a new instance via 'new' but + should rather use this one, and call its Create method. + */ + wxObject* CreateResource(wxXmlNode* node, wxObject* parent, + wxObject* instance); + + /** + Called from CreateResource after variables + were filled. + */ + wxObject* DoCreateResource(); + + /** + ) + Creates a animation() from the filename specified in @e param. + */ + wxAnimation GetAnimation(); + + /** + , @b wxSize@e size = wxDefaultSize) + Gets a bitmap. + */ + wxBitmap GetBitmap(); + + /** + Gets a bool flag (1, t, yes, on, @true are @true, everything else is @false). + */ + bool GetBool(const wxString& param, bool defaultv = false); + + /** + Gets colour in HTML syntax (#RRGGBB). + */ + wxColour GetColour(const wxString& param, + const wxColour& default = wxNullColour); + + /** + Returns the current file system. + */ + wxFileSystem GetCurFileSystem(); + + /** + Gets a dimension (may be in dialog units). + */ + wxCoord GetDimension(const wxString& param, wxCoord defaultv = 0); + + /** + ) + Gets a font. + */ + wxFont GetFont(); + + /** + Returns the XRCID. + */ + int GetID(); + + /** + , @b wxSize@e size = wxDefaultSize) + Returns an icon. + */ + wxIcon GetIcon(); + + /** + Gets the integer value from the parameter. + */ + long GetLong(const wxString& param, long defaultv = 0); + + /** + Returns the resource name. + */ + wxString GetName(); + + /** + Gets node content from wxXML_ENTITY_NODE. + */ + wxString GetNodeContent(wxXmlNode* node); + + /** + Finds the node or returns @NULL. + */ + wxXmlNode* GetParamNode(const wxString& param); + + /** + Finds the parameter value or returns the empty string. + */ + wxString GetParamValue(const wxString& param); + + /** + ) + Gets the position (may be in dialog units). + */ + wxPoint GetPosition(); + + /** + ) + Gets the size (may be in dialog units). + */ + wxSize GetSize(); + + /** + , @b int@e defaults = 0) + Gets style flags from text in form "flag | flag2| flag3 |..." + Only understands flags added with AddStyle. + */ + int GetStyle(); + + /** + Gets text from param and does some conversions: + replaces \n, \r, \t by respective characters (according to C syntax) + replaces @c $ by @c and @c $$ by @c $ (needed for @c _File to @c File + translation because of XML syntax) + calls wxGetTranslations (unless disabled in wxXmlResource) + */ + wxString GetText(const wxString& param); + + /** + Check to see if a parameter exists. + */ + bool HasParam(const wxString& param); + + /** + Convenience function. Returns @true if the node has a property class equal to + classname, + e.g. object class="wxDialog". + */ + bool IsOfClass(wxXmlNode* node, const wxString& classname); + + /** + Sets the parent resource. + */ + void SetParentResource(wxXmlResource* res); + + /** + Sets common window options. + */ + void SetupWindow(wxWindow* wnd); +}; + diff --git a/interface/wx/zipstrm.h b/interface/wx/zipstrm.h new file mode 100644 index 0000000000..ba285cd4ab --- /dev/null +++ b/interface/wx/zipstrm.h @@ -0,0 +1,442 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: zipstrm.h +// Purpose: interface of wxZipNotifier +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxZipNotifier + @wxheader{zipstrm.h} + + If you need to know when a wxZipInputStream + updates a wxZipEntry, + you can create a notifier by deriving from this abstract base class, + overriding wxZipNotifier::OnEntryUpdated. + An instance of your notifier class can then be assigned to wxZipEntry + objects, using wxZipEntry::SetNotifier. + + Setting a notifier is not usually necessary. It is used to handle + certain cases when modifying an zip in a pipeline (i.e. between + non-seekable streams). + See '@ref overview_wxarcnoseek "Archives on non-seekable streams"'. + + @library{wxbase} + @category{FIXME} + + @see @ref overview_wxarcnoseek "Archives on non-seekable streams", wxZipEntry, + wxZipInputStream, wxZipOutputStream +*/ +class wxZipNotifier +{ +public: + /** + Override this to receive notifications when + an wxZipEntry object changes. + */ + void OnEntryUpdated(wxZipEntry& entry); +}; + + + +/** + @class wxZipEntry + @wxheader{zipstrm.h} + + Holds the meta-data for an entry in a zip. + + @library{wxbase} + @category{FIXME} + + @see @ref overview_wxarc "Archive formats such as zip", wxZipInputStream, + wxZipOutputStream, wxZipNotifier +*/ +class wxZipEntry : public wxArchiveEntry +{ +public: + //@{ + /** + Copy constructor. + */ + wxZipEntry(const wxString& name = wxEmptyString); + wxZipEntry(const wxZipEntry& entry); + //@} + + /** + Make a copy of this entry. + */ + wxZipEntry* Clone() const; + + //@{ + /** + A short comment for this entry. + */ + wxString GetComment(); + const void SetComment(const wxString& comment); + //@} + + //@{ + /** + The low 8 bits are always the DOS/Windows file attributes for this entry. + The values of these attributes are given in the + enumeration @c wxZipAttributes. + The remaining bits can store platform specific permission bits or + attributes, and their meaning depends on the value + of @ref systemmadeby() SetSystemMadeBy. + If IsMadeByUnix() is @true then the + high 16 bits are unix mode bits. + The following other accessors access these bits: + @ref wxArchiveEntry::isreadonly IsReadOnly/SetIsReadOnly + + @ref wxArchiveEntry::isdir IsDir/SetIsDir + + @ref mode() Get/SetMode + */ + wxUint32 GetExternalAttributes(); + const void SetExternalAttributes(wxUint32 attr); + //@} + + //@{ + /** + The extra field from the entry's central directory record. + The extra field is used to store platform or application specific + data. See Pkware's document 'appnote.txt' for information on its format. + */ + const char* GetExtra(); + const size_t GetExtraLen(); + const void SetExtra(const char* extra, size_t len); + //@} + + //@{ + /** + The extra field from the entry's local record. + The extra field is used to store platform or application specific + data. See Pkware's document 'appnote.txt' for information on its format. + */ + const char* GetLocalExtra(); + const size_t GetLocalExtraLen(); + const void SetLocalExtra(const char* extra, size_t len); + //@} + + //@{ + /** + The compression method. The enumeration @c wxZipMethod lists the + possible values. + The default constructor sets this to wxZIP_METHOD_DEFAULT, + which allows wxZipOutputStream to + choose the method when writing the entry. + */ + int GetMethod(); + const void SetMethod(int method); + //@} + + //@{ + /** + Sets the DOS attributes + in @ref externalattributes() GetExternalAttributes + to be consistent with the @c mode given. + If IsMadeByUnix() is @true then also + stores @c mode in GetExternalAttributes(). + Note that the default constructor + sets @ref systemmadeby() GetSystemMadeBy to + wxZIP_SYSTEM_MSDOS by default. So to be able to store unix + permissions when creating zips, call SetSystemMadeBy(wxZIP_SYSTEM_UNIX). + */ + int GetMode(); + const void SetMode(int mode); + //@} + + //@{ + /** + The originating file-system. The default constructor sets this to + wxZIP_SYSTEM_MSDOS. Set it to wxZIP_SYSTEM_UNIX in order to be + able to store unix permissions using @ref mode() SetMode. + */ + int GetSystemMadeBy(); + const void SetSystemMadeBy(int system); + //@} + + /** + The compressed size of this entry in bytes. + */ + off_t GetCompressedSize() const; + + /** + CRC32 for this entry's data. + */ + wxUint32 GetCrc() const; + + /** + Returns a combination of the bits flags in the enumeration @c wxZipFlags. + */ + int GetFlags() const; + + //@{ + /** + A static member that translates a filename into the internal format used + within the archive. If the third parameter is provided, the bool pointed + to is set to indicate whether the name looks like a directory name + (i.e. has a trailing path separator). + + @see @ref overview_wxarcbyname "Looking up an archive entry by name" + */ + wxString GetInternalName(); + const wxString GetInternalName(const wxString& name, + wxPathFormat format = wxPATH_NATIVE, + bool* pIsDir = NULL); + //@} + + /** + Returns @true if @ref systemmadeby() GetSystemMadeBy + is a flavour of unix. + */ + bool IsMadeByUnix() const; + + //@{ + /** + Indicates that this entry's data is text in an 8-bit encoding. + */ + bool IsText(); + const void SetIsText(bool isText = true); + //@} + + //@{ + /** + Sets the notifier() for this entry. + Whenever the wxZipInputStream updates + this entry, it will then invoke the associated + notifier's wxZipNotifier::OnEntryUpdated + method. + Setting a notifier is not usually necessary. It is used to handle + certain cases when modifying an zip in a pipeline (i.e. between + non-seekable streams). + + @see @ref overview_wxarcnoseek "Archives on non-seekable streams", wxZipNotifier + */ + void SetNotifier(wxZipNotifier& notifier); + void UnsetNotifier(); + //@} + + /** + Assignment operator. + */ + wxZipEntry& operator operator=(const wxZipEntry& entry); +}; + + + +/** + @class wxZipInputStream + @wxheader{zipstrm.h} + + Input stream for reading zip files. + + wxZipInputStream::GetNextEntry returns an + wxZipEntry object containing the meta-data + for the next entry in the zip (and gives away ownership). Reading from + the wxZipInputStream then returns the entry's data. Eof() becomes @true + after an attempt has been made to read past the end of the entry's data. + When there are no more entries, GetNextEntry() returns @NULL and sets Eof(). + + Note that in general zip entries are not seekable, and + wxZipInputStream::SeekI() always returns wxInvalidOffset. + + @library{wxbase} + @category{streams} + + @see @ref overview_wxarc "Archive formats such as zip", wxZipEntry, + wxZipOutputStream +*/ +class wxZipInputStream : public wxArchiveInputStream +{ +public: + //@{ + /** + Compatibility constructor (requires WXWIN_COMPATIBILITY_2_6). + When this constructor is used, an emulation of seeking is + switched on for compatibility with previous versions. Note however, + that it is deprecated. + */ + wxZipInputStream(wxInputStream& stream, + wxMBConv& conv = wxConvLocal); + wxZipInputStream(wxInputStream* stream, + wxMBConv& conv = wxConvLocal); + wxZipInputStream(const wxString& archive, + const wxString& file); + //@} + + /** + Closes the current entry. On a non-seekable stream reads to the end of + the current entry first. + */ + bool CloseEntry(); + + /** + Returns the zip comment. + This is stored at the end of the zip, therefore when reading a zip + from a non-seekable stream, it returns the empty string until the + end of the zip has been reached, i.e. when GetNextEntry() returns + @NULL. + */ + wxString GetComment(); + + /** + Closes the current entry if one is open, then reads the meta-data for + the next entry and returns it in a wxZipEntry + object, giving away ownership. The stream is then open and can be read. + */ + wxZipEntry* GetNextEntry(); + + /** + For a zip on a seekable stream returns the total number of entries in + the zip. For zips on non-seekable streams returns the number of entries + returned so far by GetNextEntry(). + */ + int GetTotalEntries(); + + /** + Closes the current entry if one is open, then opens the entry specified + by the @a entry object. + @a entry should be from the same zip file, and the zip should + be on a seekable stream. + */ + bool OpenEntry(wxZipEntry& entry); +}; + + + +/** + @class wxZipClassFactory + @wxheader{zipstrm.h} + + Class factory for the zip archive format. See the base class + for details. + + @library{wxbase} + @category{FIXME} + + @see @ref overview_wxarc "Archive formats such as zip", @ref + overview_wxarcgeneric "Generic archive programming", wxZipEntry, wxZipInputStream, wxZipOutputStream +*/ +class wxZipClassFactory : public wxArchiveClassFactory +{ +public: + +}; + + + +/** + @class wxZipOutputStream + @wxheader{zipstrm.h} + + Output stream for writing zip files. + + wxZipOutputStream::PutNextEntry is used to create + a new entry in the output zip, then the entry's data is written to the + wxZipOutputStream. Another call to PutNextEntry() closes the current + entry and begins the next. + + @library{wxbase} + @category{streams} + + @see @ref overview_wxarc "Archive formats such as zip", wxZipEntry, + wxZipInputStream +*/ +class wxZipOutputStream : public wxArchiveOutputStream +{ +public: + //@{ + /** + Constructor. @c level is the compression level to use. + It can be a value between 0 and 9 or -1 to use the default value + which currently is equivalent to 6. + If the parent stream is passed as a pointer then the new filter stream + takes ownership of it. If it is passed by reference then it does not. + In a Unicode build the third parameter @c conv is used to translate + the filename and comment fields to an 8-bit encoding. It has no effect on the + stream's data. + */ + wxZipOutputStream(wxOutputStream& stream, int level = -1, + wxMBConv& conv = wxConvLocal); + wxZipOutputStream(wxOutputStream* stream, int level = -1, + wxMBConv& conv = wxConvLocal); + //@} + + /** + The destructor calls Close() to finish + writing the zip if it has not been called already. + */ + ~wxZipOutputStream(); + + /** + Finishes writing the zip, returning @true if successful. + Called by the destructor if not called explicitly. + */ + bool Close(); + + /** + Close the current entry. It is called implicitly whenever another new + entry is created with CopyEntry() + or PutNextEntry(), or + when the zip is closed. + */ + bool CloseEntry(); + + /** + Transfers the zip comment from the wxZipInputStream + to this output stream. + */ + bool CopyArchiveMetaData(wxZipInputStream& inputStream); + + /** + Takes ownership of @c entry and uses it to create a new entry + in the zip. @c entry is then opened in @c inputStream and its contents + copied to this stream. + CopyEntry() is much more efficient than transferring the data using + Read() and Write() since it will copy them without decompressing and + recompressing them. + For zips on seekable streams, @c entry must be from the same zip file + as @c stream. For non-seekable streams, @c entry must also be the + last thing read from @c inputStream. + */ + bool CopyEntry(wxZipEntry* entry, wxZipInputStream& inputStream); + + //@{ + /** + Set the compression level that will be used the next time an entry is + created. It can be a value between 0 and 9 or -1 to use the default value + which currently is equivalent to 6. + */ + int GetLevel(); + const void SetLevel(int level); + //@} + + /** + ) + Create a new directory entry + (see wxArchiveEntry::IsDir) + with the given name and timestamp. + PutNextEntry() can + also be used to create directory entries, by supplying a name with + a trailing path separator. + */ + bool PutNextDirEntry(const wxString& name); + + //@{ + /** + , @b off_t@e size = wxInvalidOffset) + Create a new entry with the given name, timestamp and size. + */ + bool PutNextEntry(wxZipEntry* entry); + bool PutNextEntry(const wxString& name); + //@} + + /** + Sets a comment for the zip as a whole. It is written at the end of the + zip. + */ + void SetComment(const wxString& comment); +}; + diff --git a/interface/wx/zstream.h b/interface/wx/zstream.h new file mode 100644 index 0000000000..205c6bcc14 --- /dev/null +++ b/interface/wx/zstream.h @@ -0,0 +1,107 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: zstream.h +// Purpose: interface of wxZlibOutputStream +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + @class wxZlibOutputStream + @wxheader{zstream.h} + + This stream compresses all data written to it. The compressed output can be + in zlib or gzip format. + Note that writing the gzip format requires zlib version 1.2.1 or greater + (the builtin version does support gzip format). + + The stream is not seekable, wxOutputStream::SeekO returns + @e wxInvalidOffset. + + @library{wxbase} + @category{streams} + + @see wxOutputStream, wxZlibInputStream +*/ +class wxZlibOutputStream : public wxFilterOutputStream +{ +public: + //@{ + /** + Creates a new write-only compressed stream. @a level means level of + compression. It is number between 0 and 9 (including these values) where + 0 means no compression and 9 best but slowest compression. -1 is default + value (currently equivalent to 6). + If the parent stream is passed as a pointer then the new filter stream + takes ownership of it. If it is passed by reference then it does not. + The @a flags wxZLIB_ZLIB and wxZLIB_GZIP specify whether the output data + will be in zlib or gzip format. wxZLIB_ZLIB is the default. + If @a flags is wxZLIB_NO_HEADER, then a raw deflate stream is output + without either zlib or gzip headers. This is a lower level + mode, which is not usually used directly. It can be used to embed a raw + deflate stream in a higher level protocol. + The following symbols can be use for the compression level and flags: + */ + wxZlibOutputStream(wxOutputStream& stream, int level = -1, + int flags = wxZLIB_ZLIB); + wxZlibOutputStream(wxOutputStream* stream, int level = -1, + int flags = wxZLIB_ZLIB); + //@} + + /** + Returns @true if zlib library in use can handle gzip compressed data. + */ + static bool CanHandleGZip(); +}; + + + +/** + @class wxZlibInputStream + @wxheader{zstream.h} + + This filter stream decompresses a stream that is in zlib or gzip format. + Note that reading the gzip format requires zlib version 1.2.1 or greater, + (the builtin version does support gzip format). + + The stream is not seekable, wxInputStream::SeekI returns + @e wxInvalidOffset. Also wxStreamBase::GetSize is + not supported, it always returns 0. + + @library{wxbase} + @category{streams} + + @see wxInputStream, wxZlibOutputStream. +*/ +class wxZlibInputStream : public wxFilterInputStream +{ +public: + //@{ + /** + If the parent stream is passed as a pointer then the new filter stream + takes ownership of it. If it is passed by reference then it does not. + The @a flags wxZLIB_ZLIB and wxZLIB_GZIP specify whether the input data + is in zlib or gzip format. If wxZLIB_AUTO is used, then zlib will + autodetect the stream type, this is the default. + If @a flags is wxZLIB_NO_HEADER, then the data is assumed to be a raw + deflate stream without either zlib or gzip headers. This is a lower level + mode, which is not usually used directly. It can be used to read a raw + deflate stream embedded in a higher level protocol. + This version is not by default compatible with the output produced by + the version of @e wxZlibOutputStream in wxWidgets 2.4.x. However, + there is a compatibility mode, which is switched on by passing + wxZLIB_24COMPATIBLE for flags. Note that in when operating in compatibility + mode error checking is very much reduced. + The following symbols can be use for the flags: + */ + wxZlibInputStream(wxInputStream& stream, int flags = wxZLIB_AUTO); + wxZlibInputStream(wxInputStream* stream, + int flags = wxZLIB_AUTO); + //@} + + /** + Returns @true if zlib library in use can handle gzip compressed data. + */ + static bool CanHandleGZip(); +}; + diff --git a/interface/wxcrt.h b/interface/wxcrt.h deleted file mode 100644 index f30ed8982c..0000000000 --- a/interface/wxcrt.h +++ /dev/null @@ -1,123 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: wxcrt.h -// Purpose: interface of global functions -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** @ingroup group_funcmacro_string */ -//@{ - -/** - @return @true if the pointer is either @NULL or points to an empty string, - @false otherwise. - - @header{wx/wxcrt.h} -*/ -bool wxIsEmpty(const char* p); - -/** - This is a safe version of standard function @e strlen(): it does exactly - the same thing (i.e. returns the length of the string) except that it - returns 0 if @a p is the @NULL pointer. - - @header{wx/wxcrt.h} -*/ -size_t wxStrlen(const char* p); - -/** - This function complements the standard C function @e stricmp() which - performs case-insensitive comparison. - - @return A negative value, 0, or positive value if @a p1 is less than, - equal to or greater than @a p2. The comparison is case-sensitive. - - @header{wx/wxcrt.h} -*/ -int wxStrcmp(const char* p1, const char* p2); - -/** - This function complements the standard C function @e strcmp() which performs - case-sensitive comparison. - - @return A negative value, 0, or positive value if @a p1 is less than, - equal to or greater than @e p2. The comparison is case-insensitive. - - @header{wx/wxcrt.h} -*/ -int wxStricmp(const char* p1, const char* p2); - -/** - @deprecated Use wxString instead. - - This macro is defined as: - - @code - #define wxStringEq(s1, s2) (s1 && s2 && (strcmp(s1, s2) == 0)) - @endcode - - @header{wx/wxcrt.h} -*/ -bool wxStringEq(const wxString& s1, const wxString& s2); - -/** - @deprecated Use wxString::Find() instead. - - Returns @true if the substring @a s1 is found within @a s2, ignoring case - if @a exact is @false. If @a subString is @false, no substring matching is - done. - - @header{wx/wxcrt.h} -*/ -bool wxStringMatch(const wxString& s1, const wxString& s2, - bool subString = true, bool exact = false); - -/** - This is a convenience function wrapping wxStringTokenizer which simply - returns all tokens found in the given @a string in an array. - - Please see wxStringTokenizer::wxStringTokenizer() for a description of the - other parameters. - - @header{wx/wxcrt.h} -*/ -wxArrayString wxStringTokenize(const wxString& string, - const wxString& delims = wxDEFAULT_DELIMITERS, - wxStringTokenizerMode mode = wxTOKEN_DEFAULT); - -/** - This function replaces the dangerous standard function @e sprintf() and is - like @e snprintf() available on some platforms. The only difference with - @e sprintf() is that an additional argument - buffer size - is taken and - the buffer is never overflowed. - - Returns the number of characters copied to the buffer or -1 if there is not - enough space. - - @see wxVsnprintf(), wxString::Printf() - - @header{wx/wxcrt.h} -*/ -int wxSnprintf(wxChar* buf, size_t len, const wxChar* format, ...); - -/** - The same as wxSnprintf() but takes a @c va_list argument instead of an - arbitrary number of parameters. - - @note If @c wxUSE_PRINTF_POS_PARAMS is set to 1, then this function - supports positional arguments (see wxString::Printf() for more - information). However other functions of the same family (wxPrintf(), - wxSprintf(), wxFprintf(), wxVfprintf(), wxVfprintf(), wxVprintf(), - wxVsprintf()) currently do not to support positional parameters even - when @c wxUSE_PRINTF_POS_PARAMS is 1. - - @see wxSnprintf(), wxString::PrintfV() - - @header{wx/wxcrt.h} -*/ -int wxVsnprintf(wxChar* buf, size_t len, - const wxChar* format, va_list argPtr); - -//@} - diff --git a/interface/xml/xml.h b/interface/xml/xml.h deleted file mode 100644 index bbc63c62ed..0000000000 --- a/interface/xml/xml.h +++ /dev/null @@ -1,518 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: xml/xml.h -// Purpose: interface of wxXmlNode -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxXmlNode - @headerfile xml.h wx/xml/xml.h - - Represents a node in an XML document. See wxXmlDocument. - - Node has a name and may have content and attributes. Most common node types are - @c wxXML_TEXT_NODE (name and attributes are irrelevant) and - @c wxXML_ELEMENT_NODE (e.g. in @c titlehi/title there is an element - with name="title", irrelevant content and one child (@c wxXML_TEXT_NODE - with content="hi"). - - If @c wxUSE_UNICODE is 0, all strings are encoded in the encoding given to - wxXmlDocument::Load (default is UTF-8). - - @library{wxxml} - @category{xml} - - @see wxXmlDocument, wxXmlAttribute -*/ -class wxXmlNode -{ -public: - //@{ - /** - A simplified version of the first constructor form, assuming a @NULL parent. - */ - wxXmlNode(wxXmlNode* parent, wxXmlNodeType type, - const wxString& name, - const wxString& content = wxEmptyString, - wxXmlAttribute* attrs = NULL, - wxXmlNode* next = NULL, int lineNo = -1); - wxXmlNode(const wxXmlNode& node); - wxXmlNode(wxXmlNodeType type, const wxString& name, - const wxString& content = wxEmptyString, - int lineNo = -1); - //@} - - /** - The virtual destructor. Deletes attached children and attributes. - */ - ~wxXmlNode(); - - //@{ - /** - Appends given attribute to the list of attributes for this node. - */ - void AddAttribute(const wxString& name, const wxString& value); - void AddAttribute(wxXmlAttribute* attr); - //@} - - /** - Adds node @a child as the last child of this node. - - @note - Note that this function works in O(n) time where @e n is the number - of existing children. Consequently, adding large number of child - nodes using this method can be expensive, because it has O(n^2) time - complexity in number of nodes to be added. Use InsertChildAfter() to - populate XML tree in linear time. - - @see InsertChild(), InsertChildAfter() - */ - void AddChild(wxXmlNode* child); - - /** - Removes the first attributes which has the given @a name from the list of - attributes for this node. - */ - bool DeleteAttribute(const wxString& name); - - //@{ - /** - Returns the value of the attribute named @a attrName if it does exist. - If it does not exist, the @a defaultVal is returned. - */ - bool GetAttribute(const wxString& attrName, wxString* value) const; - const wxString GetAttribute(const wxString& attrName, - const wxString& defaultVal = wxEmptyString) const; - //@} - - /** - Return a pointer to the first attribute of this node. - */ - wxXmlAttribute* GetAttributes() const; - - /** - Returns the first child of this node. - To get a pointer to the second child of this node (if it does exist), use the - GetNext() function on the returned value. - */ - wxXmlNode* GetChildren() const; - - /** - Returns the content of this node. Can be an empty string. - Be aware that for nodes of type @c wxXML_ELEMENT_NODE (the most used node type) - the - content is an empty string. See GetNodeContent() for more details. - */ - wxString GetContent() const; - - /** - Returns the number of nodes which separe this node from @c grandparent. - This function searches only the parents of this node until it finds @c - grandparent - or the @NULL node (which is the parent of non-linked nodes or the parent of a - wxXmlDocument's root node). - */ - int GetDepth(wxXmlNode* grandparent = NULL) const; - - /** - Returns line number of the node in the input XML file or -1 if it is unknown. - */ - int GetLineNumber() const; - - /** - Returns the name of this node. Can be an empty string (e.g. for nodes of type - @c wxXML_TEXT_NODE or @c wxXML_CDATA_SECTION_NODE). - */ - wxString GetName() const; - - /** - Returns a pointer to the sibling of this node or @NULL if there are no - siblings. - */ - wxXmlNode* GetNext() const; - - /** - Returns the content of the first child node of type @c wxXML_TEXT_NODE or @c - wxXML_CDATA_SECTION_NODE. - This function is very useful since the XML snippet @c - "tagnametagcontent/tagname" is represented by - expat with the following tag tree: - - or eventually: - - An empty string is returned if the node has no children of type @c - wxXML_TEXT_NODE or @c wxXML_CDATA_SECTION_NODE, or if the content of the first child of such types is empty. - */ - wxString GetNodeContent() const; - - /** - Returns a pointer to the parent of this node or @NULL if this node has no - parent. - */ - wxXmlNode* GetParent() const; - - /** - Returns the type of this node. - */ - wxXmlNodeType GetType() const; - - /** - Returns @true if this node has a attribute named @e attrName. - */ - bool HasAttribute(const wxString& attrName) const; - - /** - Inserts the @a child node immediately before @a followingNode in the - children list. - - @return @true if @a followingNode has been found and the @a child - node has been inserted. - - @note - For historical reasons, @a followingNode may be @NULL. In that case, - then @a child is prepended to the list of children and becomes the - first child of this node, i.e. it behaves identically to using the - first children (as returned by GetChildren()) for @a followingNode). - - @see AddChild(), InsertChildAfter() - */ - bool InsertChild(wxXmlNode* child, wxXmlNode* followingNode); - - /** - Inserts the @a child node immediately after @a precedingNode in the - children list. - - @return @true if @a precedingNode has been found and the @a child - node has been inserted. - - @param precedingNode - The node to insert @a child after. As a special case, this can be - @NULL if this node has no children yet -- in that case, @a child - will become this node's only child node. - - @since 2.8.8 - - @see InsertChild(), AddChild() - */ - bool InsertChildAfter(wxXmlNode* child, wxXmlNode* precedingNode); - - /** - Returns @true if the content of this node is a string containing only - whitespaces (spaces, - tabs, new lines, etc). Note that this function is locale-independent since the - parsing of XML - documents must always produce the exact same tree regardless of the locale it - runs under. - */ - bool IsWhitespaceOnly() const; - - /** - Removes the given node from the children list. Returns @true if the node was - found and removed - or @false if the node could not be found. - Note that the caller is reponsible for deleting the removed node in order to - avoid memory leaks. - */ - bool RemoveChild(wxXmlNode* child); - - /** - Sets as first attribute the given wxXmlAttribute object. - The caller is responsible to delete any previously present attributes attached - to this node. - */ - void SetAttributes(wxXmlAttribute* attr); - - /** - Sets as first child the given node. The caller is responsible to delete any - previously present - children node. - */ - void SetChildren(wxXmlNode* child); - - /** - Sets the content of this node. - */ - void SetContent(const wxString& con); - - /** - Sets the name of this node. - */ - void SetName(const wxString& name); - - /** - Sets as sibling the given node. The caller is responsible to delete any - previously present - sibling node. - */ - void SetNext(wxXmlNode* next); - - /** - Sets as parent the given node. The caller is responsible to delete any - previously present - parent node. - */ - void SetParent(wxXmlNode* parent); - - /** - Sets the type of this node. - */ - void SetType(wxXmlNodeType type); - - /** - See the copy constructor for more info. - */ - wxXmlNode operator=(const wxXmlNode& node); -}; - - - -/** - @class wxXmlAttribute - @headerfile xml.h wx/xml/xml.h - - Represents a node attribute. - - Example: in @c img src="hello.gif" id="3"/, @c "src" is attribute with value - @c "hello.gif" and @c "id" is a attribute with value @c "3". - - @library{wxxml} - @category{xml} - - @see wxXmlDocument, wxXmlNode -*/ -class wxXmlAttribute -{ -public: - //@{ - /** - Creates the attribute with given @a name and @e value. - If @a next is not @NULL, then sets it as sibling of this attribute. - */ - wxXmlAttribute(); - wxXmlAttribute(const wxString& name, const wxString& value, - wxXmlAttribute* next = NULL); - //@} - - /** - The virtual destructor. - */ - ~wxXmlAttribute(); - - /** - Returns the name of this attribute. - */ - wxString GetName() const; - - /** - Returns the sibling of this attribute or @NULL if there are no siblings. - */ - wxXmlAttribute* GetNext() const; - - /** - Returns the value of this attribute. - */ - wxString GetValue() const; - - /** - Sets the name of this attribute. - */ - void SetName(const wxString& name); - - /** - Sets the sibling of this attribute. - */ - void SetNext(wxXmlAttribute* next); - - /** - Sets the value of this attribute. - */ - void SetValue(const wxString& value); -}; - - - -/** - @class wxXmlDocument - @headerfile xml.h wx/xml/xml.h - - This class holds XML data/document as parsed by XML parser in the root node. - - wxXmlDocument internally uses the expat library which comes with wxWidgets to - parse the given stream. - - A simple example of using XML classes is: - - @code - wxXmlDocument doc; - if (!doc.Load(wxT("myfile.xml"))) - return @false; - - // start processing the XML file - if (doc.GetRoot()-GetName() != wxT("myroot-node")) - return @false; - - wxXmlNode *child = doc.GetRoot()-GetChildren(); - while (child) { - - if (child-GetName() == wxT("tag1")) { - - // process text enclosed by tag1/tag1 - wxString content = child-GetNodeContent(); - - ... - - // process attributes of tag1 - wxString attrvalue1 = - child-GetAttribute(wxT("attr1"), - wxT("default-value")); - wxString attrvalue2 = - child-GetAttribute(wxT("attr2"), - wxT("default-value")); - - ... - - } else if (child-GetName() == wxT("tag2")) { - - // process tag2 ... - } - - child = child-GetNext(); - } - @endcode - - @note if you want to preserve the original formatting of the loaded file - including whitespaces - and indentation, you need to turn off whitespace-only textnode removal and - automatic indentation: - - @code - wxXmlDocument doc; - doc.Load(wxT("myfile.xml"), wxT("UTF-8"), wxXMLDOC_KEEP_WHITESPACE_NODES); - - // myfile2.xml will be indentic to myfile.xml saving it this way: - doc.Save(wxT("myfile2.xml"), wxXML_NO_INDENTATION); - @endcode - - Using default parameters, you will get a reformatted document which in general - is different from - the original loaded content: - - @code - wxXmlDocument doc; - doc.Load(wxT("myfile.xml")); - doc.Save(wxT("myfile2.xml")); // myfile2.xml != myfile.xml - @endcode - - @library{wxxml} - @category{xml} - - @see wxXmlNode, wxXmlAttribute -*/ -class wxXmlDocument : public wxObject -{ -public: - //@{ - /** - Copy constructor. Deep copies all the XML tree of the given document. - */ - wxXmlDocument(); - wxXmlDocument(const wxString& filename); - wxXmlDocument(wxInputStream& stream); - wxXmlDocument(const wxXmlDocument& doc); - //@} - - /** - Virtual destructor. Frees the document root node. - */ - ~wxXmlDocument(); - - /** - Detaches the document root node and returns it. The document root node will be - set to @NULL - and thus IsOk() will return @false after calling this function. - Note that the caller is reponsible for deleting the returned node in order to - avoid memory leaks. - */ - wxXmlNode* DetachRoot(); - - /** - Returns encoding of in-memory representation of the document - (same as passed to Load() or constructor, defaults to UTF-8). - @note this is meaningless in Unicode build where data are stored as @c wchar_t*. - */ - wxString GetEncoding() const; - - /** - Returns encoding of document (may be empty). - Note: this is the encoding original file was saved in, @b not the - encoding of in-memory representation! - */ - wxString GetFileEncoding() const; - - /** - Returns the root node of the document. - */ - wxXmlNode* GetRoot() const; - - /** - Returns the version of document. - This is the value in the @c ?xml version="1.0"? header of the XML document. - If the version attribute was not explicitely given in the header, this function - returns an empty string. - */ - wxString GetVersion() const; - - /** - Returns @true if the document has been loaded successfully. - */ - bool IsOk() const; - - //@{ - /** - , @b int@e flags = wxXMLDOC_NONE) - Like above but takes the data from given input stream. - */ - bool Load(const wxString& filename); - int bool Load(wxInputStream& stream); - //@} - - //@{ - /** - Saves XML tree in the given output stream. See other overload for a description - of @c indentstep. - */ - bool Save(const wxString& filename, int indentstep = 1) const; - const bool Save(wxOutputStream& stream, int indentstep = 1) const; - //@} - - /** - Sets the enconding of the document. - */ - void SetEncoding(const wxString& enc); - - /** - Sets the enconding of the file which will be used to save the document. - */ - void SetFileEncoding(const wxString& encoding); - - /** - Sets the root node of this document. Deletes previous root node. - Use DetachRoot() and then - SetRoot() if you want - to replace the root node without deleting the old document tree. - */ - void SetRoot(wxXmlNode* node); - - /** - Sets the version of the XML file which will be used to save the document. - */ - void SetVersion(const wxString& version); - - /** - Deep copies the given document. - */ - wxXmlDocument& operator operator=(const wxXmlDocument& doc); -}; - diff --git a/interface/xrc/xmlres.h b/interface/xrc/xmlres.h deleted file mode 100644 index d1d2765684..0000000000 --- a/interface/xrc/xmlres.h +++ /dev/null @@ -1,436 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: xrc/xmlres.h -// Purpose: interface of wxXmlResource -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxXmlResource - @headerfile xmlres.h wx/xrc/xmlres.h - - This is the main class for interacting with the XML-based resource system. - - The class holds XML resources from one or more .xml files, binary files or zip - archive files. - - See @ref overview_xrcoverview "XML-based resource system overview" for details. - - @library{wxxrc} - @category{xrc} -*/ -class wxXmlResource : public wxObject -{ -public: - //@{ - /** - Constructor. - - @param flags - wxXRC_USE_LOCALE: translatable strings will be translated via _(). - wxXRC_NO_SUBCLASSING: subclass property of object nodes will be ignored - (useful for previews in XRC editors). wxXRC_NO_RELOADING will prevent the - XRC files from being reloaded from disk in case they have been modified - there - since being last loaded (may slightly speed up loading them). - @param domain - The name of the gettext catalog to search for - translatable strings. By default all loaded catalogs will be - searched. This provides a way to allow the strings to only come - from a specific catalog. - */ - wxXmlResource(const wxString& filemask, - int flags = wxXRC_USE_LOCALE, - const wxString domain = wxEmptyString); - wxXmlResource(int flags = wxXRC_USE_LOCALE, - const wxString domain = wxEmptyString); - //@} - - /** - Destructor. - */ - ~wxXmlResource(); - - /** - Initializes only a specific handler (or custom handler). Convention says - that the handler name is equal to the control's name plus 'XmlHandler', for - example - wxTextCtrlXmlHandler, wxHtmlWindowXmlHandler. The XML resource compiler - (wxxrc) can create include file that contains initialization code for - all controls used within the resource. Note that this handler should be - allocated on the heap, since it will be delete by - ClearHandlers() later. - */ - void AddHandler(wxXmlResourceHandler* handler); - - /** - Attaches an unknown control to the given panel/window/dialog. - Unknown controls are used in conjunction with object class="unknown". - */ - bool AttachUnknownControl(const wxString& name, - wxWindow* control, - wxWindow* parent = NULL); - - /** - Removes all handlers and deletes them (this means that any handlers added using - AddHandler() must be allocated on the heap). - */ - void ClearHandlers(); - - /** - Compares the XRC version to the argument. Returns -1 if the XRC version - is less than the argument, +1 if greater, and 0 if they equal. - */ - int CompareVersion(int major, int minor, int release, - int revision) const; - - /** - Gets the global resources object or creates one if none exists. - */ - wxXmlResource* Get(); - - /** - Returns the domain (message catalog) that will be used to load - translatable strings in the XRC. - */ - wxChar* GetDomain(); - - /** - Returns flags, which may be a bitlist of wxXRC_USE_LOCALE and - wxXRC_NO_SUBCLASSING. - */ - int GetFlags(); - - /** - Returns version information (a.b.c.d = d+ 256*c + 256@c 2*b + 256@c 3*a). - */ - long GetVersion() const; - - /** - Returns a numeric ID that is equivalent to the string ID used in an XML - resource. If an unknown @a str_id is requested (i.e. other than wxID_XXX - or integer), a new record is created which associates the given string with - a number. If @a value_if_not_found is @c wxID_NONE, the number is obtained via - wxNewId(). Otherwise @a value_if_not_found is used. - Macro @c XRCID(name) is provided for convenient use in event tables. - */ -#define int GetXRCID(const wxString& str_id, int value_if_not_found = -2) /* implementation is private */ - - /** - Initializes handlers for all supported controls/windows. This will - make the executable quite big because it forces linking against - most of the wxWidgets library. - */ - void InitAllHandlers(); - - /** - Loads resources from XML files that match given filemask. - This method understands VFS (see filesys.h). - */ - bool Load(const wxString& filemask); - - /** - Loads a bitmap resource from a file. - */ - wxBitmap LoadBitmap(const wxString& name); - - //@{ - /** - Loads a dialog. @a dlg points to parent window (if any). - This form is used to finish creation of an already existing instance (the main - reason - for this is that you may want to use derived class with a new event table). - Example: - */ - wxDialog* LoadDialog(wxWindow* parent, const wxString& name); - bool LoadDialog(wxDialog* dlg, wxWindow* parent, - const wxString& name); - //@} - - /** - Loads a frame. - */ - bool LoadFrame(wxFrame* frame, wxWindow* parent, - const wxString& name); - - /** - Loads an icon resource from a file. - */ - wxIcon LoadIcon(const wxString& name); - - /** - Loads menu from resource. Returns @NULL on failure. - */ - wxMenu* LoadMenu(const wxString& name); - - //@{ - /** - Loads a menubar from resource. Returns @NULL on failure. - */ - wxMenuBar* LoadMenuBar(wxWindow* parent, const wxString& name); - wxMenuBar* LoadMenuBar(const wxString& name); - //@} - - //@{ - /** - Load an object from the resource specifying both the resource name and the - class name. - The first overload lets you load nonstandard container windows and returns @c - @NULL - on failure. The second one lets you finish the creation of an existing - instance and returns @false on failure. - */ - wxObject* LoadObject(wxWindow* parent, const wxString& name, - const wxString& classname); - bool LoadObject(wxObject* instance, wxWindow* parent, - const wxString& name, - const wxString& classname); - //@} - - //@{ - /** - Loads a panel. @a panel points to parent window (if any). This form - is used to finish creation of an already existing instance. - */ - wxPanel* LoadPanel(wxWindow* parent, const wxString& name); - bool LoadPanel(wxPanel* panel, wxWindow* parent, - const wxString& name); - //@} - - /** - Loads a toolbar. - */ - wxToolBar* LoadToolBar(wxWindow* parent, const wxString& name); - - /** - Sets the global resources object and returns a pointer to the previous one (may - be @NULL). - */ - wxXmlResource* Set(wxXmlResource* res); - - /** - Sets the domain (message catalog) that will be used to load - translatable strings in the XRC. - */ - wxChar* SetDomain(const wxChar* domain); - - /** - Sets flags (bitlist of wxXRC_USE_LOCALE and wxXRC_NO_SUBCLASSING). - */ - void SetFlags(int flags); - - /** - This function unloads a resource previously loaded by - Load(). - Returns @true if the resource was successfully unloaded and @false if it - hasn't - been found in the list of loaded resources. - */ - bool Unload(const wxString& filename); -}; - - - -/** - @class wxXmlResourceHandler - @headerfile xmlres.h wx/xrc/xmlres.h - - wxXmlResourceHandler is an abstract base class for resource handlers - capable of creating a control from an XML node. - - See @ref overview_xrcoverview "XML-based resource system overview" for details. - - @library{wxxrc} - @category{xrc} -*/ -class wxXmlResourceHandler : public wxObject -{ -public: - /** - Default constructor. - */ - wxXmlResourceHandler(); - - /** - Destructor. - */ - ~wxXmlResourceHandler(); - - /** - Add a style flag (e.g. wxMB_DOCKABLE) to the list of flags - understood by this handler. - */ - void AddStyle(const wxString& name, int value); - - /** - Add styles common to all wxWindow-derived classes. - */ - void AddWindowStyles(); - - /** - Returns @true if it understands this node and can create - a resource from it, @false otherwise. - */ - bool CanHandle(wxXmlNode* node); - - /** - Creates children. - */ - void CreateChildren(wxObject* parent, bool this_hnd_only = false); - - /** - Helper function. - */ - void CreateChildrenPrivately(wxObject* parent, - wxXmlNode* rootnode = NULL); - - /** - Creates a resource from a node. - */ - wxObject* CreateResFromNode(wxXmlNode* node, wxObject* parent, - wxObject* instance = NULL); - - /** - Creates an object (menu, dialog, control, ...) from an XML node. - Should check for validity. @a parent is a higher-level object (usually window, - dialog or panel) - that is often necessary to create the resource. - If @b instance is non-@NULL it should not create a new instance via 'new' but - should rather use this one, and call its Create method. - */ - wxObject* CreateResource(wxXmlNode* node, wxObject* parent, - wxObject* instance); - - /** - Called from CreateResource after variables - were filled. - */ - wxObject* DoCreateResource(); - - /** - ) - Creates a animation() from the filename specified in @e param. - */ - wxAnimation GetAnimation(); - - /** - , @b wxSize@e size = wxDefaultSize) - Gets a bitmap. - */ - wxBitmap GetBitmap(); - - /** - Gets a bool flag (1, t, yes, on, @true are @true, everything else is @false). - */ - bool GetBool(const wxString& param, bool defaultv = false); - - /** - Gets colour in HTML syntax (#RRGGBB). - */ - wxColour GetColour(const wxString& param, - const wxColour& default = wxNullColour); - - /** - Returns the current file system. - */ - wxFileSystem GetCurFileSystem(); - - /** - Gets a dimension (may be in dialog units). - */ - wxCoord GetDimension(const wxString& param, wxCoord defaultv = 0); - - /** - ) - Gets a font. - */ - wxFont GetFont(); - - /** - Returns the XRCID. - */ - int GetID(); - - /** - , @b wxSize@e size = wxDefaultSize) - Returns an icon. - */ - wxIcon GetIcon(); - - /** - Gets the integer value from the parameter. - */ - long GetLong(const wxString& param, long defaultv = 0); - - /** - Returns the resource name. - */ - wxString GetName(); - - /** - Gets node content from wxXML_ENTITY_NODE. - */ - wxString GetNodeContent(wxXmlNode* node); - - /** - Finds the node or returns @NULL. - */ - wxXmlNode* GetParamNode(const wxString& param); - - /** - Finds the parameter value or returns the empty string. - */ - wxString GetParamValue(const wxString& param); - - /** - ) - Gets the position (may be in dialog units). - */ - wxPoint GetPosition(); - - /** - ) - Gets the size (may be in dialog units). - */ - wxSize GetSize(); - - /** - , @b int@e defaults = 0) - Gets style flags from text in form "flag | flag2| flag3 |..." - Only understands flags added with AddStyle. - */ - int GetStyle(); - - /** - Gets text from param and does some conversions: - replaces \n, \r, \t by respective characters (according to C syntax) - replaces @c $ by @c and @c $$ by @c $ (needed for @c _File to @c File - translation because of XML syntax) - calls wxGetTranslations (unless disabled in wxXmlResource) - */ - wxString GetText(const wxString& param); - - /** - Check to see if a parameter exists. - */ - bool HasParam(const wxString& param); - - /** - Convenience function. Returns @true if the node has a property class equal to - classname, - e.g. object class="wxDialog". - */ - bool IsOfClass(wxXmlNode* node, const wxString& classname); - - /** - Sets the parent resource. - */ - void SetParentResource(wxXmlResource* res); - - /** - Sets common window options. - */ - void SetupWindow(wxWindow* wnd); -}; - diff --git a/interface/zipstrm.h b/interface/zipstrm.h deleted file mode 100644 index ba285cd4ab..0000000000 --- a/interface/zipstrm.h +++ /dev/null @@ -1,442 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: zipstrm.h -// Purpose: interface of wxZipNotifier -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxZipNotifier - @wxheader{zipstrm.h} - - If you need to know when a wxZipInputStream - updates a wxZipEntry, - you can create a notifier by deriving from this abstract base class, - overriding wxZipNotifier::OnEntryUpdated. - An instance of your notifier class can then be assigned to wxZipEntry - objects, using wxZipEntry::SetNotifier. - - Setting a notifier is not usually necessary. It is used to handle - certain cases when modifying an zip in a pipeline (i.e. between - non-seekable streams). - See '@ref overview_wxarcnoseek "Archives on non-seekable streams"'. - - @library{wxbase} - @category{FIXME} - - @see @ref overview_wxarcnoseek "Archives on non-seekable streams", wxZipEntry, - wxZipInputStream, wxZipOutputStream -*/ -class wxZipNotifier -{ -public: - /** - Override this to receive notifications when - an wxZipEntry object changes. - */ - void OnEntryUpdated(wxZipEntry& entry); -}; - - - -/** - @class wxZipEntry - @wxheader{zipstrm.h} - - Holds the meta-data for an entry in a zip. - - @library{wxbase} - @category{FIXME} - - @see @ref overview_wxarc "Archive formats such as zip", wxZipInputStream, - wxZipOutputStream, wxZipNotifier -*/ -class wxZipEntry : public wxArchiveEntry -{ -public: - //@{ - /** - Copy constructor. - */ - wxZipEntry(const wxString& name = wxEmptyString); - wxZipEntry(const wxZipEntry& entry); - //@} - - /** - Make a copy of this entry. - */ - wxZipEntry* Clone() const; - - //@{ - /** - A short comment for this entry. - */ - wxString GetComment(); - const void SetComment(const wxString& comment); - //@} - - //@{ - /** - The low 8 bits are always the DOS/Windows file attributes for this entry. - The values of these attributes are given in the - enumeration @c wxZipAttributes. - The remaining bits can store platform specific permission bits or - attributes, and their meaning depends on the value - of @ref systemmadeby() SetSystemMadeBy. - If IsMadeByUnix() is @true then the - high 16 bits are unix mode bits. - The following other accessors access these bits: - @ref wxArchiveEntry::isreadonly IsReadOnly/SetIsReadOnly - - @ref wxArchiveEntry::isdir IsDir/SetIsDir - - @ref mode() Get/SetMode - */ - wxUint32 GetExternalAttributes(); - const void SetExternalAttributes(wxUint32 attr); - //@} - - //@{ - /** - The extra field from the entry's central directory record. - The extra field is used to store platform or application specific - data. See Pkware's document 'appnote.txt' for information on its format. - */ - const char* GetExtra(); - const size_t GetExtraLen(); - const void SetExtra(const char* extra, size_t len); - //@} - - //@{ - /** - The extra field from the entry's local record. - The extra field is used to store platform or application specific - data. See Pkware's document 'appnote.txt' for information on its format. - */ - const char* GetLocalExtra(); - const size_t GetLocalExtraLen(); - const void SetLocalExtra(const char* extra, size_t len); - //@} - - //@{ - /** - The compression method. The enumeration @c wxZipMethod lists the - possible values. - The default constructor sets this to wxZIP_METHOD_DEFAULT, - which allows wxZipOutputStream to - choose the method when writing the entry. - */ - int GetMethod(); - const void SetMethod(int method); - //@} - - //@{ - /** - Sets the DOS attributes - in @ref externalattributes() GetExternalAttributes - to be consistent with the @c mode given. - If IsMadeByUnix() is @true then also - stores @c mode in GetExternalAttributes(). - Note that the default constructor - sets @ref systemmadeby() GetSystemMadeBy to - wxZIP_SYSTEM_MSDOS by default. So to be able to store unix - permissions when creating zips, call SetSystemMadeBy(wxZIP_SYSTEM_UNIX). - */ - int GetMode(); - const void SetMode(int mode); - //@} - - //@{ - /** - The originating file-system. The default constructor sets this to - wxZIP_SYSTEM_MSDOS. Set it to wxZIP_SYSTEM_UNIX in order to be - able to store unix permissions using @ref mode() SetMode. - */ - int GetSystemMadeBy(); - const void SetSystemMadeBy(int system); - //@} - - /** - The compressed size of this entry in bytes. - */ - off_t GetCompressedSize() const; - - /** - CRC32 for this entry's data. - */ - wxUint32 GetCrc() const; - - /** - Returns a combination of the bits flags in the enumeration @c wxZipFlags. - */ - int GetFlags() const; - - //@{ - /** - A static member that translates a filename into the internal format used - within the archive. If the third parameter is provided, the bool pointed - to is set to indicate whether the name looks like a directory name - (i.e. has a trailing path separator). - - @see @ref overview_wxarcbyname "Looking up an archive entry by name" - */ - wxString GetInternalName(); - const wxString GetInternalName(const wxString& name, - wxPathFormat format = wxPATH_NATIVE, - bool* pIsDir = NULL); - //@} - - /** - Returns @true if @ref systemmadeby() GetSystemMadeBy - is a flavour of unix. - */ - bool IsMadeByUnix() const; - - //@{ - /** - Indicates that this entry's data is text in an 8-bit encoding. - */ - bool IsText(); - const void SetIsText(bool isText = true); - //@} - - //@{ - /** - Sets the notifier() for this entry. - Whenever the wxZipInputStream updates - this entry, it will then invoke the associated - notifier's wxZipNotifier::OnEntryUpdated - method. - Setting a notifier is not usually necessary. It is used to handle - certain cases when modifying an zip in a pipeline (i.e. between - non-seekable streams). - - @see @ref overview_wxarcnoseek "Archives on non-seekable streams", wxZipNotifier - */ - void SetNotifier(wxZipNotifier& notifier); - void UnsetNotifier(); - //@} - - /** - Assignment operator. - */ - wxZipEntry& operator operator=(const wxZipEntry& entry); -}; - - - -/** - @class wxZipInputStream - @wxheader{zipstrm.h} - - Input stream for reading zip files. - - wxZipInputStream::GetNextEntry returns an - wxZipEntry object containing the meta-data - for the next entry in the zip (and gives away ownership). Reading from - the wxZipInputStream then returns the entry's data. Eof() becomes @true - after an attempt has been made to read past the end of the entry's data. - When there are no more entries, GetNextEntry() returns @NULL and sets Eof(). - - Note that in general zip entries are not seekable, and - wxZipInputStream::SeekI() always returns wxInvalidOffset. - - @library{wxbase} - @category{streams} - - @see @ref overview_wxarc "Archive formats such as zip", wxZipEntry, - wxZipOutputStream -*/ -class wxZipInputStream : public wxArchiveInputStream -{ -public: - //@{ - /** - Compatibility constructor (requires WXWIN_COMPATIBILITY_2_6). - When this constructor is used, an emulation of seeking is - switched on for compatibility with previous versions. Note however, - that it is deprecated. - */ - wxZipInputStream(wxInputStream& stream, - wxMBConv& conv = wxConvLocal); - wxZipInputStream(wxInputStream* stream, - wxMBConv& conv = wxConvLocal); - wxZipInputStream(const wxString& archive, - const wxString& file); - //@} - - /** - Closes the current entry. On a non-seekable stream reads to the end of - the current entry first. - */ - bool CloseEntry(); - - /** - Returns the zip comment. - This is stored at the end of the zip, therefore when reading a zip - from a non-seekable stream, it returns the empty string until the - end of the zip has been reached, i.e. when GetNextEntry() returns - @NULL. - */ - wxString GetComment(); - - /** - Closes the current entry if one is open, then reads the meta-data for - the next entry and returns it in a wxZipEntry - object, giving away ownership. The stream is then open and can be read. - */ - wxZipEntry* GetNextEntry(); - - /** - For a zip on a seekable stream returns the total number of entries in - the zip. For zips on non-seekable streams returns the number of entries - returned so far by GetNextEntry(). - */ - int GetTotalEntries(); - - /** - Closes the current entry if one is open, then opens the entry specified - by the @a entry object. - @a entry should be from the same zip file, and the zip should - be on a seekable stream. - */ - bool OpenEntry(wxZipEntry& entry); -}; - - - -/** - @class wxZipClassFactory - @wxheader{zipstrm.h} - - Class factory for the zip archive format. See the base class - for details. - - @library{wxbase} - @category{FIXME} - - @see @ref overview_wxarc "Archive formats such as zip", @ref - overview_wxarcgeneric "Generic archive programming", wxZipEntry, wxZipInputStream, wxZipOutputStream -*/ -class wxZipClassFactory : public wxArchiveClassFactory -{ -public: - -}; - - - -/** - @class wxZipOutputStream - @wxheader{zipstrm.h} - - Output stream for writing zip files. - - wxZipOutputStream::PutNextEntry is used to create - a new entry in the output zip, then the entry's data is written to the - wxZipOutputStream. Another call to PutNextEntry() closes the current - entry and begins the next. - - @library{wxbase} - @category{streams} - - @see @ref overview_wxarc "Archive formats such as zip", wxZipEntry, - wxZipInputStream -*/ -class wxZipOutputStream : public wxArchiveOutputStream -{ -public: - //@{ - /** - Constructor. @c level is the compression level to use. - It can be a value between 0 and 9 or -1 to use the default value - which currently is equivalent to 6. - If the parent stream is passed as a pointer then the new filter stream - takes ownership of it. If it is passed by reference then it does not. - In a Unicode build the third parameter @c conv is used to translate - the filename and comment fields to an 8-bit encoding. It has no effect on the - stream's data. - */ - wxZipOutputStream(wxOutputStream& stream, int level = -1, - wxMBConv& conv = wxConvLocal); - wxZipOutputStream(wxOutputStream* stream, int level = -1, - wxMBConv& conv = wxConvLocal); - //@} - - /** - The destructor calls Close() to finish - writing the zip if it has not been called already. - */ - ~wxZipOutputStream(); - - /** - Finishes writing the zip, returning @true if successful. - Called by the destructor if not called explicitly. - */ - bool Close(); - - /** - Close the current entry. It is called implicitly whenever another new - entry is created with CopyEntry() - or PutNextEntry(), or - when the zip is closed. - */ - bool CloseEntry(); - - /** - Transfers the zip comment from the wxZipInputStream - to this output stream. - */ - bool CopyArchiveMetaData(wxZipInputStream& inputStream); - - /** - Takes ownership of @c entry and uses it to create a new entry - in the zip. @c entry is then opened in @c inputStream and its contents - copied to this stream. - CopyEntry() is much more efficient than transferring the data using - Read() and Write() since it will copy them without decompressing and - recompressing them. - For zips on seekable streams, @c entry must be from the same zip file - as @c stream. For non-seekable streams, @c entry must also be the - last thing read from @c inputStream. - */ - bool CopyEntry(wxZipEntry* entry, wxZipInputStream& inputStream); - - //@{ - /** - Set the compression level that will be used the next time an entry is - created. It can be a value between 0 and 9 or -1 to use the default value - which currently is equivalent to 6. - */ - int GetLevel(); - const void SetLevel(int level); - //@} - - /** - ) - Create a new directory entry - (see wxArchiveEntry::IsDir) - with the given name and timestamp. - PutNextEntry() can - also be used to create directory entries, by supplying a name with - a trailing path separator. - */ - bool PutNextDirEntry(const wxString& name); - - //@{ - /** - , @b off_t@e size = wxInvalidOffset) - Create a new entry with the given name, timestamp and size. - */ - bool PutNextEntry(wxZipEntry* entry); - bool PutNextEntry(const wxString& name); - //@} - - /** - Sets a comment for the zip as a whole. It is written at the end of the - zip. - */ - void SetComment(const wxString& comment); -}; - diff --git a/interface/zstream.h b/interface/zstream.h deleted file mode 100644 index 205c6bcc14..0000000000 --- a/interface/zstream.h +++ /dev/null @@ -1,107 +0,0 @@ -///////////////////////////////////////////////////////////////////////////// -// Name: zstream.h -// Purpose: interface of wxZlibOutputStream -// Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license -///////////////////////////////////////////////////////////////////////////// - -/** - @class wxZlibOutputStream - @wxheader{zstream.h} - - This stream compresses all data written to it. The compressed output can be - in zlib or gzip format. - Note that writing the gzip format requires zlib version 1.2.1 or greater - (the builtin version does support gzip format). - - The stream is not seekable, wxOutputStream::SeekO returns - @e wxInvalidOffset. - - @library{wxbase} - @category{streams} - - @see wxOutputStream, wxZlibInputStream -*/ -class wxZlibOutputStream : public wxFilterOutputStream -{ -public: - //@{ - /** - Creates a new write-only compressed stream. @a level means level of - compression. It is number between 0 and 9 (including these values) where - 0 means no compression and 9 best but slowest compression. -1 is default - value (currently equivalent to 6). - If the parent stream is passed as a pointer then the new filter stream - takes ownership of it. If it is passed by reference then it does not. - The @a flags wxZLIB_ZLIB and wxZLIB_GZIP specify whether the output data - will be in zlib or gzip format. wxZLIB_ZLIB is the default. - If @a flags is wxZLIB_NO_HEADER, then a raw deflate stream is output - without either zlib or gzip headers. This is a lower level - mode, which is not usually used directly. It can be used to embed a raw - deflate stream in a higher level protocol. - The following symbols can be use for the compression level and flags: - */ - wxZlibOutputStream(wxOutputStream& stream, int level = -1, - int flags = wxZLIB_ZLIB); - wxZlibOutputStream(wxOutputStream* stream, int level = -1, - int flags = wxZLIB_ZLIB); - //@} - - /** - Returns @true if zlib library in use can handle gzip compressed data. - */ - static bool CanHandleGZip(); -}; - - - -/** - @class wxZlibInputStream - @wxheader{zstream.h} - - This filter stream decompresses a stream that is in zlib or gzip format. - Note that reading the gzip format requires zlib version 1.2.1 or greater, - (the builtin version does support gzip format). - - The stream is not seekable, wxInputStream::SeekI returns - @e wxInvalidOffset. Also wxStreamBase::GetSize is - not supported, it always returns 0. - - @library{wxbase} - @category{streams} - - @see wxInputStream, wxZlibOutputStream. -*/ -class wxZlibInputStream : public wxFilterInputStream -{ -public: - //@{ - /** - If the parent stream is passed as a pointer then the new filter stream - takes ownership of it. If it is passed by reference then it does not. - The @a flags wxZLIB_ZLIB and wxZLIB_GZIP specify whether the input data - is in zlib or gzip format. If wxZLIB_AUTO is used, then zlib will - autodetect the stream type, this is the default. - If @a flags is wxZLIB_NO_HEADER, then the data is assumed to be a raw - deflate stream without either zlib or gzip headers. This is a lower level - mode, which is not usually used directly. It can be used to read a raw - deflate stream embedded in a higher level protocol. - This version is not by default compatible with the output produced by - the version of @e wxZlibOutputStream in wxWidgets 2.4.x. However, - there is a compatibility mode, which is switched on by passing - wxZLIB_24COMPATIBLE for flags. Note that in when operating in compatibility - mode error checking is very much reduced. - The following symbols can be use for the flags: - */ - wxZlibInputStream(wxInputStream& stream, int flags = wxZLIB_AUTO); - wxZlibInputStream(wxInputStream* stream, - int flags = wxZLIB_AUTO); - //@} - - /** - Returns @true if zlib library in use can handle gzip compressed data. - */ - static bool CanHandleGZip(); -}; -