An object used by an application wishing to create an accelerator table .
Default constructor.
Constructor.
Returns the command identifier for the accelerator table entry.
Returns the flags for the accelerator table entry.
Returns the keycode for the accelerator table entry.
Sets the accelerator entry parameters.
An accelerator table allows the application to specify a table of keyboard shortcuts for menus or other commands. On Windows, menu or button commands are supported; on GTK, only menu commands are supported.
The object wxNullAcceleratorTable is defined to be a table with no data, and is the initial accelerator table for a window.
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);
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' (but not in GTK+ at present).
Default constructor.
Copy constructor.
Creates from an array of wxAcceleratorEntry objects.
Loads the accelerator table from a Windows resource (Windows only).
Destroys the wxAcceleratorTable object.
Returns true if the accelerator table is valid.
Assignment operator. This operator does not copy any data, but instead passes a pointer to the data in accel and increments a reference counter. It is a fast operation.
Equality operator. This operator tests whether the internal data pointers are equal (a fast test).
Inequality operator. This operator tests whether the internal data pointers are unequal (a fast test).
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 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 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.
Functions return a wxAccStatus error code, which may be one of the following:
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 the following:
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 following type:
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 the following type:
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 this type:
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
States are represented by the following:
#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
Event identifiers that can be sent via wxAccessible::NotifyEvent are as follows:
#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
Constructor, taking an optional window. The object can be associated with a window later.
Destructor.
Performs the default action for the object. 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).
Gets the specified child (starting from 1). If child is NULL and the return value is wxACC_OK, this means that the child is a simple element and not an accessible object.
Returns the number of children in childCount .
Gets the default action for this object (0) or a child (greater than 0). Return wxACC_OK even if there is no action. 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."
Returns the description for this object or a child.
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'.
Returns help text for this object or a child, similar to tooltip text.
Returns the keyboard shortcut for this object or child. Return e.g. ALT+K.
Returns the rectangle for this object (id is 0) or a child element (id is greater than 0). rect is in screen coordinates.
Gets the name of the specified object.
Returns the parent of this object, or NULL.
Returns a role constant describing this object. See wxAccessible for a list of these roles.
Gets a variant representing the selected children of this object.
Acceptable values are:
Returns a state constant. See wxAccessible for a list of these states.
Returns a localized string representing the value for the object or child.
Returns the window associated with this object.
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.
pt is in screen coordinates.
Navigates from fromId to toId / toObject .
Allows the application to send an event when something changes in an accessible object.
Selects the object or child. See wxAccessible for a list of the selection actions.
Sets the window associated with this object.
An activate event is sent when a window or application is being activated or deactivated.
A top-level window (a dialog or frame) receives an activate event when it is being activated or deactivated. This is indicated visually by the title bar changing colour, and a subwindow gaining the keyboard focus.
An application is activated or deactivated when one of its frames becomes activated, or a frame becomes inactivated resulting in all application frames being inactive. (Windows only)
Please note that usually you should call event.Skip() in your handlers for these events as not doing so can result in strange effects.
Constructor.
Returns true if the application or window is being activated, false otherwise.
The wxApp class represents the application itself. It is used to:
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.
Constructor. Called implicitly with a definition of a wxApp object.
Destructor. Will be called implicitly on program exit if the wxApp object is created on the stack.
Creates a wxLog class for the application to use for logging errors. The default implementation returns a new wxLogGui class.
Dispatches the next event in the windowing system event queue.
This can be used for programming event loops, e.g.
while (app.Pending())
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.
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).
wxWidgets sets this to a reasonable default before calling wxApp::OnInit , but the application can reset it at will.
Returns the application name.
Gets the class name of the application. The class name may be used in a platform specific manner to refer to the application.
Returns true if the application will exit when the top-level window is deleted, false otherwise.
Returns the one and only global application object. Usually wxTheApp is usead instead.
If the top window hasn't been set using wxApp::SetTopWindow , this function will find the first top-level window (frame or dialog) and return that.
Returns a pointer to the top window.
Returns true if the application will use the best visual on systems that support different visuals, false otherwise.
Returns the application's vendor name.
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.
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 the 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.
Called by wxWidgets on creation of the application. Override this if you wish to provide your own (environment-dependent) main loop.
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 __WXDEBUG__ is defined) as asserts are not left in the release code at all.
The base class version show the default assert failure dialog box proposing to the user to stop the program, continue or ignore all subsequent asserts.
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.
Called when the help option ( --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.
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.
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++ 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 .
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.
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.
This must be provided by the application, and will usually create the application's main window, optionally calling wxApp::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.
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.
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.
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). Note that the exception type is lost by now, so if you want to really handle the exception you should override OnRun() and put a try/catch clause around the call to the base class version there.
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:
// Provide wxWidgets message loop compatibility
BOOL CTheApp::PreTranslateMessage(MSG *msg)
{
if (wxTheApp && wxTheApp->ProcessMessage((WXMSW *)msg))
return true;
else
return CWinApp::PreTranslateMessage(msg);
}
Returns true if unprocessed events are in the window system event queue.
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.
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.
Sets the name of the application. The name may be used in dialogs (for example by the document/view framework). A default name is set by wxWidgets.
Sets the class name of the application. This may be used in a platform specific manner to refer to the application.
Allows the programmer to specify whether the application will exit when the top-level frame is deleted.
Allows external code to modify global wxTheApp , but you should really know what you're doing if you call it.
Sets the name of application's vendor. The name will be used in registry access. A default name is set by wxWidgets.
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.
This function simply invokes the given method func of the specified event handler handler with the 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.
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 onlyIfNeeded parameter is true , the method will just silently return false instead.
An abstract base class which serves as a common interface to archive class factories such as wxZipClassFactory .
For each supported archive type (such as zip) there is a class factory derived from wxArchiveClassFactory, which allows archive objects to be created in a generic way, without knowing the particular type of archive being used.
The wxMBConv object that the created streams will use when translating meta-data. The initial default, set by the constructor, is wxConvLocal.
Calls the static GetInternalName() function for the archive entry type, for example wxZipEntry::GetInternalName() .
Create a new wxArchiveEntry object of the appropriate type.
Create a new wxArchiveInputStream or wxArchiveOutputStream of the appropriate type.
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.
This information applies only when reading archives from non-seekable streams. When the stream is seekable GetNextEntry() returns a fully populated wxArchiveEntry . See ' Archives on non-seekable streams ' 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 GetNextEntry() returns, with the the following exceptions:
| GetSize() | Guaranteed to be available after the entry has been read to Eof() , or CloseEntry() has been called |
| IsReadOnly() | Guaranteed to be available after the end of the archive has been reached, i.e. after GetNextEntry() returns NULL and Eof() is true |
Returns a copy of this entry object.
The entry's timestamp.
Returns the path format used internally within the archive to store filenames.
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.
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 GetName() returns the name with a trailing path separator.
Similarly, setting a name with a trailing path separator sets IsDir().
Returns a numeric value unique to the entry within the archive.
The size of the entry's data in bytes.
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.
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.
True if the entry is a read-only file.
Sets the notifier for this entry. Whenever the wxArchiveInputStream updates this entry, it will then invoke the associated notifier's 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).
An abstract base class which serves as a common interface to archive input streams such as wxZipInputStream .
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().
typedef wxArchiveEntry entry_type
Closes the current entry. On a non-seekable stream reads to the end of the current entry first.
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.
Closes the current entry if one is open, then opens the entry specified by the wxArchiveEntry object.
entry must be from the same archive file that this wxArchiveInputStream is reading, and it must be reading it from a seekable stream.
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.
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) {
/* ... */
};
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::pair<wxString, wxArchiveEntry*>).
The <wx/archive.h> header defines the following typedefs:
typedef wxArchiveIterator<wxArchiveInputStream> wxArchiveIter;
typedef wxArchiveIterator<wxArchiveInputStream,
std::pair<wxString, wxArchiveEntry*> > wxArchivePairIter;
The header for any implementation of this interface should define similar typedefs for its types, for example in <wx/zipstrm.h> there is:
typedef wxArchiveIterator<wxZipInputStream> wxZipIter;
typedef wxArchiveIterator<wxZipInputStream,
std::pair<wxString, wxZipEntry*> > wxZipPairIter;
Transferring the catalogue of an archive arc to a vector cat , can then be done something like this:
std::vector<wxArchiveEntry*> cat((wxArchiveIter)arc, wxArchiveIter());
When the iterator is dereferenced, it gives away ownership of an entry object. So in the above example, when you have finished with 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 ZipEntryPtr :
typedef std::vector<ZipEntryPtr> ZipCatalog;
typedef wxArchiveIterator<wxZipInputStream, ZipEntryPtr> ZipIter;
ZipCatalog cat((ZipIter)zip, ZipIter());
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 GetInternalName() function.
typedef std::multimap<wxString, wxZipEntry*> ZipCatalog;
ZipCatalog cat((wxZipPairIter)zip, wxZipPairIter());
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 cat you must delete the pointers it contains.
Or if you have them, a pair containing a smart pointer can be used (again ZipEntryPtr ), no worries about ownership:
typedef std::multimap<wxString, ZipEntryPtr> ZipCatalog;
typedef wxArchiveIterator<wxZipInputStream,
std::pair<wxString, ZipEntryPtr> > ZipPairIter;
ZipCatalog cat((ZipPairIter)zip, ZipPairIter());
typedef std::input_iterator_tag iterator_category typedef T value_type typedef ptrdiff_t difference_type typedef T* pointer typedef T& reference
Construct an 'end of sequence' instance.
Construct iterator that returns all the entries in the archive input stream arc .
Returns an entry object from the archive input stream, giving away ownership.
Position the input iterator at the next entry in the archive input stream.
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 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 Archives on non-seekable streams .
This method must be overridden in your derived class.
An abstract base class which serves as a common interface to archive output streams such as wxZipOutputStream .
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.
Calls Close() if it has not already been called.
Closes the archive, returning true if it was successfully written. Called by the destructor if not called explicitly.
Close the current entry. It is called implicitly whenever another new entry is created with CopyEntry() or PutNextEntry() , or when the archive is closed.
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.
Takes ownership of entry and uses it to create a new entry in the archive. entry is then opened in the input stream 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.
entry must be from the same archive file that stream is accessing. For non-seekable streams, entry must also be the last thing read from stream .
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.
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.
Create a new entry with the given name, timestamp and size. The entry's data can then be written by writing to this wxArchiveOutputStream.
This section describes the so called dynamic arrays . This is a C array-like 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 debugging overview 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 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 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 WX_DEFINE_XXXARRAY macro 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 sizeof() greater than sizeof(long) will provoke a runtime assertion failure, however declaring a wxArray of floats will not (on the machines where sizeof(float) <= sizeof(long)), yet it will not work, please use wxObjArray for storing floats and doubles (NB: a more efficient wxArrayDouble class is scheduled for the next release of wxWidgets).
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, it is Index() function execution time is O(log(N)) instead of O(N) for the usual arrays but the Add() method is slower: it is 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 WX_DECLARE_OBJARRAY() macro and then you must include the file defining the implementation of template type: <wx/arrimpl.cpp> and define the array class with 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:
#include <wx/dynarray.h>
// 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 <wx/arrimpl.cpp> // this is a magic incantation which must be done!
WX_DEFINE_OBJARRAY(ArrayOfDirectories);
// that's all!
It is not as elegant as writing
typedef std::vector<MyDirectory> ArrayOfDirectories;
but is not that complicated and allows the code to be compiled with any, however dumb, C++ compiler in the world.
Things are much simpler for wxArray and wxSortedArray however: it is enough just to write
WX_DEFINE_ARRAY(int, ArrayOfDirectories); WX_DEFINE_SORTED_ARRAY(int, ArrayOfFiles);
i.e. there is only one DEFINE macro and no need for separate DECLARE one.
This macro defines a new array class named name and containing the elements of type T . The second form is used when compiling wxWidgets as a DLL under Windows and array needs to be visible outside the DLL. The third is needed for exporting an array from a user DLL.
Example:
WX_DEFINE_ARRAY_INT(wxArrayInt); class MyClass; WX_DEFINE_ARRAY(MyClass *, wxArrayOfMyClass);
Note that wxWidgets predefines the following standard array classes: wxArrayInt, wxArrayLong and wxArrayPtrVoid.
This macro defines a new sorted array class named name and containing the elements of type T . The second form is used when compiling wxWidgets as a DLL under Windows and array needs to be visible outside the DLL. The third is needed for exporting an array from a user DLL.
Example:
WX_DEFINE_SORTED_ARRAY_INT(wxSortedArrayInt); class MyClass; WX_DEFINE_SORTED_ARRAY(MyClass *, wxArrayOfMyClass);
You will have to initialize the objects of this class by passing a comparison function to the array object constructor like this:
int CompareInts(int n1, int n2)
{
return n1 - n2;
}
wxSortedArrayInt sorted(CompareInts);
int CompareMyClassObjects(MyClass *item1, MyClass *item2)
{
// sort the items by their address...
return Stricmp(item1->GetAddress(), item2->GetAddress());
}
wxArrayOfMyClass another(CompareMyClassObjects);
This macro declares a new object array class named name and containing the elements of type T . The second form is used when compiling wxWidgets as a DLL under Windows and array needs to be visible outside the DLL. The third is needed for exporting an array from a user DLL.
Example:
class MyClass; WX_DECLARE_OBJARRAY(MyClass, wxArrayOfMyClass); // note: not "MyClass *"!
You must use WX_DEFINE_OBJARRAY() macro to define the array class - otherwise you would get link errors.
This macro defines the methods of the array class name not defined by the WX_DECLARE_OBJARRAY() macro. You must include the file <wx/arrimpl.cpp> 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. The latter two forms are merely aliases of the first to satisfy some people's sense of symmetry when using the exported declarations.
Example of usage:
// first declare the class!
class MyClass
{
public:
MyClass(const MyClass&);
...
virtual ~MyClass();
};
#include <wx/arrimpl.cpp>
WX_DEFINE_OBJARRAY(wxArrayOfMyClass);
This macro may be used to append all elements of the other array to the array . The two arrays must be of the same type.
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 anyhow when you call Empty().
Default constructor initializes an empty array object.
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 T where 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.
The copy constructors and assignment operators perform a shallow array copy (i.e. they don't copy the objects pointed to even if the source array contains the items of pointer type) for wxArray and wxSortedArray and a deep copy (i.e. the array element are copied too) for wxObjArray.
The wxObjArray destructor deletes all the items owned by the array. This is not done by wxArray and wxSortedArray versions - you may use WX_CLEAR_ARRAY macro for this.
Appends the given number of copies of the item to the array consisting of the elements of type T .
The first version is used with wxArray and wxSortedArray. The second and the third are used with wxObjArray. There is an important difference between them: if you give a pointer to the array, it will take ownership of it, i.e. will delete it when the item is deleted from the array. If you give a reference to the array, however, the array will make a copy of the item and will not take ownership of the original item. Once again, it only makes sense for wxObjArrays because the other array types never take ownership of their elements. Also note that you cannot append more than one pointer as reusing it would lead to deleting it twice (or more) and hence to 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 copies parameter and modify the elements in place later if you plan to append a lot of items.
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.
This function does the same as Empty() and additionally frees the memory allocated to the array.
Same as GetCount() . This function is deprecated - it exists only for compatibility.
Removes the element from the array, but, unlike, Remove() doesn't delete it. The function returns the pointer to the removed element.
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.
Return the number of items in the array.
The first version of the function is for wxArray and wxObjArray, the second is for wxSortedArray only.
Searches the element in the array, starting from either beginning or the end depending on the value of searchFromEnd parameter. wxNOT_FOUND is returned if the element is not found, otherwise the index of the element is returned.
Linear search is used for the wxArray and wxObjArray classes but binary search in the sorted array is used for wxSortedArray (this is why searchFromEnd parameter doesn't make sense for it).
NB: even for wxObjArray classes, the operator==() of the elements in the array is 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.
Insert the given number of copies of the item into the array before the existing item n - thus, Insert(something, 0u) will insert an item in such way that it will become the first array element.
Please see Add() for explanation of the differences between the overloaded versions of this function.
Returns true if the array is empty, false otherwise.
Returns the item at the given position in the array. If 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.
Returns the last element in the array, i.e. is the same as 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.
Removes an element from the array by value: the first item of the array equal to 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:
T *item = array[n]; delete item; array.Remove(n)
See also WX_CLEAR_ARRAY macro which deletes all elements of a wxArray (supposed to contain pointers).
Removes count elements starting at 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:
T *item = array[n]; delete item; array.RemoveAt(n)
See also WX_CLEAR_ARRAY macro which deletes all elements of a wxArray (supposed to contain pointers).
This function ensures that the number of array elements is at least count . If the array has already count or more items, nothing is done. Otherwise, count - GetCount() elements are added and initialized to the value defval .
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.
The notation CMPFUNC<T> should be read as if we had the following declaration:
template int CMPFUNC(T *first, T *second);
where T is the type of the array elements. I.e. it is a function returning int which is passed two arguments of type 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.
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 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 char * 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 Item , Last or operator[] are not constant, so the array elements may be modified in place like this
array.Last().MakeUpper();
There is also a variant of wxArrayString called wxSortedArrayString which has exactly the same methods as wxArrayString, but which always keeps the string in it in (alphabetical) order. wxSortedArrayString uses binary search in its 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 which break the order of items) which is mentioned in their description.
Final word: none of the methods of wxArrayString is virtual including its destructor, so this class should not be used as a base class.
Default constructor.
Copy constructor. Note that when an array is assigned to a sorted array, its contents is automatically sorted during construction.
Constructor from a C string array. Pass a size sz and array arr .
Constructor from a wxString array. Pass a size sz and array arr .
Destructor frees memory occupied by the array strings. For the performance reasons it is not virtual, so this class should not be derived from.
Assignment operator.
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.
Compares 2 arrays respecting the case. Returns true if the arrays have different number of elements or if the elements don't match pairwise.
Return the array element at position 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 Item method.
Appends the given number of copies of the new item str to the array and returns the index of the first new item in the array.
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.
See also Insert
Preallocates enough memory to store nCount items. This function may be used to improve array class performance before adding a known number of items consecutively.
See also Dynamic array memory management
Clears the array contents and frees memory.
See also Empty
Returns the number of items in the array. This function is deprecated and is for backwards compatibility only, please use GetCount instead.
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.
Returns the number of items in the array.
Search the element in the array, starting from the beginning if bFromEnd is false or from end otherwise. If bCase , comparison is case sensitive (default), otherwise the case is ignored.
This function uses linear search for wxArrayString and binary search for wxSortedArrayString, but it ignores the bCase and bFromEnd parameters in the latter case.
Returns index of the first item matched or wxNOT_FOUND if there is no match.
Insert the given number of copies of the new element in the array before the position nIndex . Thus, for example, to insert the string in the beginning of the array you would write
Insert("foo", 0);
If nIndex is equal to GetCount() this function behaves as Add .
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!
Returns true if the array is empty, false otherwise. This function returns the same result as GetCount() == 0 but is probably easier to read.
Return the array element at position 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 also operator[] for the operator version.
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.
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 also Index
Removes count items starting at position nIndex from the array.
Releases the extra memory allocated by the array. This function is useful to minimize the array memory consumption.
See also Alloc , Dynamic array memory management
Sorts the array in alphabetical order or in reverse alphabetical order if reverseOrder is true. The sort is case-sensitive.
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!
The following example sorts strings by their length.
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);
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!
Sorts the array using the specified compareFunction for item comparison. CompareFunction is defined as a function taking two const wxString& parameters and returning an 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.
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 its CreateBitmap method and register the provider with wxArtProvider::PushProvider :
class MyProvider : public wxArtProvider
{
protected:
wxBitmap CreateBitmap(const wxArtID& id,
const wxArtClient& client,
const wxSize size)
{ ... }
};
...
wxArtProvider::PushProvider(new MyProvider);
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 (NB: this is not yet really possible as of wxWidgets 2.3.3, the set of wxArtProvider bitmaps is too small).
Every bitmap is known to wxArtProvider under an unique ID that is used by 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 artprov sample):
Additionally, any string recognized by custom art providers registered using PushProvider may be used.
When running under GTK+ 2, GTK+ stock item IDs (e.g. "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 http://freedesktop.org/Standards/icon-theme-spec . Note that themes are not guaranteed to contain all icons, so wxArtProvider may return wxNullBitmap or wxNullIcon . Default theme is typically installed in /usr/share/icons/hicolor .
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:
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).
Query registered providers for bitmap with given ID.
Same as wxArtProvider::GetBitmap , but return a wxIcon object (or wxNullIcon on failure).
Returns a suitable size hint for the given wxArtClient . If platform_default is true, return a size based on the current platform, otherwise return the size from the topmost wxArtProvider. wxDefaultSize may be returned if the client doesn't have a specified size, like wxART_OTHER for example.
Remove latest added provider and delete it.
Register new art provider (add it to the top of providers stack).
Remove a provider from the stack. The provider must have been added previously and is not deleted.
The 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.
wxAutomationObject excelObject;
if (excelObject.GetInstance("Excel.Application"))
excelObject.PutProperty("ActiveCell.Font.Bold", true);
Note that this class obviously works under Windows only.
Constructor, taking an optional IDispatch pointer which will be released when the object is deleted.
Destructor. If the internal IDispatch pointer is non-null, it will be released.
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:
wxVariant res = obj.CallMethod("Sum", wxVariant(1.2), wxVariant(3.4));
wxVariant res = obj.CallMethod("Sum", 1.2, 3.4);
Note that method can contain dot-separated property names, to save the application needing to call GetProperty several times using several temporary objects. For example:
object.CallMethod("ActiveCell.Font.ShowDialog", "My caption");
Creates a new object based on the class id, returning true if the object was successfully created, or false if not.
Gets the IDispatch pointer.
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.
Retrieves a property from this object, assumed to be a dispatch pointer, and initialises obj with it. To avoid having to deal with IDispatch pointers directly, use this function in preference to wxAutomationObject::GetProperty when retrieving objects from other objects.
Note that an IDispatch pointer is stored as a void* pointer in wxVariant objects.
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:
wxVariant res = obj.GetProperty("Range", wxVariant("A1"));
wxVariant res = obj.GetProperty("Range", "A1");
Note that property can contain dot-separated property names, to save the application needing to call GetProperty several times using several temporary objects.
Two types of argument array are provided, so that when possible pointers are used for efficiency.
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.
.
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:
obj.PutProperty("Value", wxVariant(23));
obj.PutProperty("Value", 23);
Note that property can contain dot-separated property names, to save the application needing to call GetProperty several times using several temporary objects.
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.
This class encapsulates the concept of a platform-dependent bitmap, either monochrome or colour or colour with alpha channel support.
Objects:
wxNullBitmap
Default constructor.
Copy constructor. Note that this does not take a fresh copy of the data, but instead makes the internal data point to bitmap 's data. So changing one bitmap will change the other. To make a real copy, you can use:
wxBitmap newBitmap = oldBitmap.GetSubBitmap(
wxRect(0, 0, oldBitmap.GetWidth(), oldBitmap.GetHeight()));
Creates a bitmap from the given data which is interpreted in platform-dependent manner.
Creates a bitmap from an array of 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.
Creates a new bitmap. A depth of -1 indicates the depth of the current screen or visual. Some platforms only support 1 for monochrome and -1 for the current colour setting. Beginning with version 2.5.4 of wxWidgets a depth of 32 including an alpha channel is supported under MSW, Mac and GTK+.
Creates a bitmap from XPM data.
Loads a bitmap from a file or resource.
The first form constructs a bitmap object with no data; an assignment or another member function such as Create or LoadFile must be called subsequently.
The second and third forms provide copy constructors. Note that these do not copy the bitmap data, but instead a pointer to the data, keeping a reference count. They are therefore very efficient operations.
The fourth form constructs a bitmap from data whose type and value depends on the value of the type argument.
The fifth form constructs a (usually monochrome) bitmap from an array of pixel values, under both X and Windows.
The sixth form constructs a new bitmap.
The seventh form constructs a bitmap from pixmap (XPM) data, if wxWidgets has been configured to incorporate this feature.
To use this constructor, you must first include an XPM file. For example, assuming that the file mybitmap.xpm contains an XPM array of character pointers called mybitmap:
#include "mybitmap.xpm" ... wxBitmap *bitmap = new wxBitmap(mybitmap);
The eighth form constructs a bitmap from a file or resource. name can refer to a resource name under MS Windows, or a filename under MS Windows and X.
Under Windows, type defaults to wxBITMAP_TYPE_BMP_RESOURCE. Under X, type defaults to wxBITMAP_TYPE_XPM.
Creates bitmap object from the 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 -1) which entails that a colour reduction has to 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.
Destroys the wxBitmap object and possibly the underlying bitmap data. Because reference counting is used, the bitmap may not actually be destroyed at this point - only when the reference count is zero will the data be deleted.
If the application omits to delete the bitmap explicitly, the bitmap will be destroyed automatically by wxWidgets when the application exits.
Do not delete a bitmap that is selected into a memory device context.
Adds a handler to the end of the static list of format handlers.
Deletes all bitmap handlers.
This function is called by wxWidgets on exit.
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.
Creates the bitmap from an icon.
Creates a fresh bitmap. If the final argument is omitted, the display depth of the screen is used.
The first form works on all platforms. The portability of the second form depends on the type of data.
Creates a bitmap from the given data, which can be of arbitrary type.
Finds the handler with the given name.
Finds the handler associated with the given extension and type.
Finds the handler associated with the given bitmap type.
Gets the colour depth of the bitmap. A value of 1 indicates a monochrome bitmap.
Returns the static list of bitmap format handlers.
Gets the height of the bitmap in pixels.
Gets the associated palette (if any) which may have been loaded from a file or set for the bitmap.
Gets the width of the bitmap in pixels.
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.
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.
Adds a handler at the start of the static list of format handlers.
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.
Loads a bitmap from a file or resource.
Returns true if bitmap data is present.
Finds the handler with the given name, and removes it. The handler is not deleted.
Depending on how wxWidgets has been configured, not all formats may be available.
Saves a bitmap in the named file.
Sets the depth member (does not affect the bitmap data).
Sets the height member (does not affect the bitmap data).
Sets the associated palette. (Not implemented under GTK+).
Sets the width member (does not affect the bitmap data).
Assignment operator. This operator does not copy any data, but instead passes a pointer to the data in bitmap and increments a reference counter. It is a fast operation.
Equality operator. This operator tests whether the internal data pointers are equal (a fast test).
Inequality operator. This operator tests whether the internal data pointers are unequal (a fast test).
A bitmap button is a control that contains a bitmap. It may be placed on a dialog box or panel , or indeed almost any other window.
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.
Default constructor.
Destructor, destroying the button.
Button creation function for two-step creation. For more details, see wxBitmapButton::wxBitmapButton .
Returns the bitmap for the disabled state.
Returns the bitmap for the focused state.
Returns the label bitmap (the one passed to the constructor).
Returns the bitmap for the selected state.
Sets the bitmap for the disabled button appearance.
Sets the bitmap for the button appearance when it has the keyboard focus.
This is the bitmap used for the unselected state, and for all other states if no other bitmaps are provided.
Sets the bitmap label for the button.
Sets the bitmap for the selected (depressed) button appearance.
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.
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 .
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.
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.
Default constructor. In your own default constructor, initialise the members m_name, m_extension and m_type.
Destroys the wxBitmapHandler object.
Creates a bitmap from the given data, which can be of arbitrary type. The wxBitmap object bitmap is manipulated by this function.
Gets the name of this handler.
Gets the file extension associated with this handler.
Gets the bitmap type associated with this handler.
Loads a bitmap from a file or resource, putting the resulting data into bitmap .
Saves a bitmap in the named file.
Sets the handler name.
Sets the handler extension.
Sets the handler type.
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 Programming with wxBoxSizer .
Constructor for a wxBoxSizer. orient may be either of wxVERTICAL or wxHORIZONTAL for creating either a column sizer or a row sizer.
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. Documented for information.
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.
Returns the orientation of the box sizer, either wxVERTICAL or wxHORIZONTAL.
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 FindOrCreateBrush .
wxBrush uses a reference counting system, so assignments between brushes are very cheap. You can therefore use actual wxBrush objects instead of pointers without efficiency problems. Once one wxBrush object changes its data it will create its own brush data internally so that other brushes, which previously shared the data using the reference counting, are not affected.
Objects:
wxNullBrush
Pointers:
wxBLUE_BRUSH
wxGREEN_BRUSH
wxWHITE_BRUSH
wxBLACK_BRUSH
wxGREY_BRUSH
wxMEDIUM_GREY_BRUSH
wxLIGHT_GREY_BRUSH
wxTRANSPARENT_BRUSH
wxCYAN_BRUSH
wxRED_BRUSH
Default constructor. The brush will be uninitialised, and wxBrush::Ok will return false.
Constructs a brush from a colour object and style.
Constructs a brush from a colour name and style.
Constructs a stippled brush using a bitmap.
The destructor may not delete the underlying brush object of the native windowing system, since wxBrush uses a reference counting system for efficiency.
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.
Destructor.
Returns a reference to the brush colour.
Gets a pointer to the stipple bitmap. If the brush does not have a wxSTIPPLE style, this bitmap may be non-NULL but uninitialised ( wxBitmap::Ok returns false).
Returns true if the style of the brush is any of hatched fills.
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).
Sets the brush colour using a reference to a colour object.
Sets the brush colour using a colour name from the colour database.
Sets the brush colour using red, green and blue values.
The style will be set to wxSTIPPLE, unless the bitmap has a mask associated to it, in which case the style will be set to wxSTIPPLE_MASK_OPAQUE.
If the wxSTIPPLE variant is used, the bitmap will be used to fill out the area to be drawn. If the wxSTIPPLE_MASK_OPAQUE is used, the current text foreground and text background determine what colours are used for displaying and the bits in the mask (which is a mono-bitmap actually) determine where to draw what.
Note that under Windows 95, only 8x8 pixel large stipple bitmaps are supported, Windows 98 and NT as well as GTK support arbitrary bitmaps.
Sets the stipple bitmap.
Sets the brush style.
Assignment operator, using reference counting. Returns a reference to `this'.
Equality operator. Two brushes are equal if they contain pointers to the same underlying brush data. It does not compare each attribute, so two independently-created brushes using the same parameters will fail the test.
Inequality operator. Two brushes are not equal if they contain pointers to different underlying brush data. It does not compare each attribute.
A brush list is a list containing all brushes which have been created.
There is only one instance of this class: wxTheBrushList . Use this object to search for a previously created brush of the desired type and create it if not already found. In some windowing systems, the brush may be a scarce resource, so it can pay to reuse old resources if possible. When an application finishes, all brushes 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 brush list less useful than it once was. Under Windows, scarce resources are cleaned up internally if they are not being used. Also, a reference 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 brush, because the reference counting does it for you. For example, you can set a brush in a device context, and then immediately delete the brush you passed, because the brush is `copied'.
So you may find it easier to ignore the brush list, and instead create and copy brushes 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 brush list is for wxWidgets to keep track of brushes in order to clean them up on exit. It is also kept for backward compatibility with earlier versions of wxWidgets.
Constructor. The application should not construct its own brush list: use the object pointer wxTheBrushList .
Used internally by wxWidgets to add a brush to the list.
Finds a brush with the specified attributes and returns it, else creates a new brush, adds it to the brush list, and returns it.
Used by wxWidgets to remove a brush from the list.
This simple 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 only once, when this object is destroyed.
It can be used in the same way as any other device context. wxBufferedDC itself typically replaces wxClientDC , if you want to use it in your OnPaint() handler, you should look at wxBufferedPaintDC .
If you use the first, default, constructor, you must call one of the Init methods later in order to use the object.
The other constructors initialize the object immediately and Init() must not be called after using them.
These functions initialize the object created using the default constructor. Please see constructors documentation for details.
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).
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).
Creates a buffered stream using a buffer of a default size of 1024 bytes for cashing the stream parent .
Destructor. Calls Sync() and destroys the internal buffer.
Calls Sync() and changes the stream position.
Flushes the buffer and calls Sync() on the parent stream.
This is a subclass of wxBufferedDC which can be used inside of an OnPaint() event handler. Just create an object of this class instead of wxPaintDC 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 wxScrolledWindow , you probably do not want to call PrepareDC on it as it already does this internally for the real underlying wxPaintDC.
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 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 (in which case PrepareDC is automatically called for the actual window device context).
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:
wxBusyCursor wait;
for (int i = 0; i < 100000; i++)
DoACalculation();
It works by calling wxBeginBusyCursor in the constructor, and wxEndBusyCursor in the destructor.
Constructs a busy cursor object, calling wxBeginBusyCursor .
Destroys the busy cursor object, calling wxEndBusyCursor .
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:
wxBusyInfo wait("Please wait, working...");
for (int i = 0; i < 100000; i++)
{
DoACalculation();
}
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:
wxWindowDisabler disableAll;
wxBusyInfo wait("Please wait, working...");
for (int i = 0; i < 100000; i++)
{
DoACalculation();
if ( !(i
wxTheApp->Yield();
}
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.
Constructs a busy info window as child of parent and displays msg in it.
NB: If parent is not NULL you must ensure that it is not closed while the busy info is shown.
Hides and closes the window containing the information text.
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 dialog box or panel , or indeed almost any other window.
Default constructor.
Destructor, destroying the button.
Button creation function for two-step creation. For more details, see wxButton::wxButton .
Returns the string label for the button.
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.
Under Windows, only dialog box buttons respond to this function. As normal under Windows and Motif, 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 wxPanel::SetDefaultItem .
Note that under Motif, calling this function immediately after creation of a button and before the creation of other buttons will cause misalignment of the row of buttons, since default buttons are larger. To get around this, call SetDefault after you have created a row of buttons: wxWidgets will then set the size of all buttons currently on the panel to the same size.
This sets the button to be the default item for the panel or dialog box.
Sets the string label for the button.
This class converts between any character sets and Unicode. It has one predefined instance, wxConvLocal , for the default user character set.
Constructor. You may specify either the name of the character set you want to convert from/to or an encoding constant. If the character set name is not recognized, ISO 8859-1 is used as fall back.
Destructor frees any resources needed to perform the conversion.
Converts from the selected character set to Unicode. Returns length of string written to destination buffer.
Converts from Unicode to the selected character set. Returns length of string written to destination buffer.
This event is sent by wxLayoutAlgorithm to calculate the amount of the remaining client area that the window should occupy.
Constructor.
Returns the flags associated with this event. Not currently used.
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.
Sets the flags associated with this event. Not currently used.
Call this to specify the new remaining parent client area, after the space occupied by the window has been subtracted.
The calendar control allows the user to pick a date. For this, it displays a window containing several parts: a control at the top to pick the month and the year (either or both of them may be disabled), and a month area below them which shows all the days in the month. The user can move the current selection using the keyboard and select the date (generating EVT_CALENDAR event) by pressing <Return> or double clicking it.
It has advanced possibilities for the customization of its display. 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 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 EVT_CALENDAR_MONTH event handler.
The following are the possible return values for HitTest method:
enum wxCalendarHitTestResult
{
wxCAL_HITTEST_NOWHERE, // outside of anything
wxCAL_HITTEST_HEADER, // on the header (weekdays)
wxCAL_HITTEST_DAY // on a day in the calendar
}
Default constructor, use Create after it.
Does the same as Create method.
Creates the control. See wxWindow for the meaning of the parameters and the control overview for the possible styles.
Destroys the control.
Sets the current date.
Gets the currently selected date.
This function should be used instead of changing wxCAL_NO_YEAR_CHANGE style bit directly. It allows or disallows the user to change the year interactively.
This function should be used instead of changing 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.
This function should be used instead of changing wxCAL_SHOW_HOLIDAYS style bit directly. It enables or disables the special highlighting of the holidays.
Set the colours used for painting the weekdays at the top of the control.
Gets the foreground colour of the header part of the calendar window.
Gets the background colour of the header part of the calendar window.
Set the colours to be used for highlighting the currently selected date.
Gets the foreground highlight colour.
Gets the background highlight colour.
Sets the colours to be used for the holidays highlighting (only used if the window style includes wxCAL_SHOW_HOLIDAYS flag).
Return the foreground colour currently used for holiday highlighting.
Return the background colour currently used for holiday highlighting.
Returns the attribute for the given date (should be in the range 1\ldots31).
The returned pointer may be NULL .
Associates the attribute with the specified date (in the range 1\ldots31).
If the pointer is NULL , the items attribute is cleared.
Marks the specified day as being a holiday in the current month.
Clears any attributes associated with the given day (in the range 1\ldots31).
Returns one of wxCAL_HITTEST_XXX constants and fills either date or wd pointer with the corresponding value depending on the hit test code.
wxCalendarDateAttr is a custom attributes for a calendar date. The objects of this class are used with wxCalendarCtrl .
Here are the possible kinds of borders which may be used to decorate a date:
enum wxCalendarDateBorder
{
wxCAL_BORDER_NONE, // no border (default)
wxCAL_BORDER_SQUARE, // a rectangular border
wxCAL_BORDER_ROUND // a round border
}
The constructors.
Sets the text (foreground) colour to use.
Sets the text background colour to use.
Sets the border colour to use.
Sets the font to use.
Sets the border kind
Display the date with this attribute as a holiday.
Returns true if this item has a non default text foreground colour.
Returns true if this attribute specifies a non default text background colour.
Returns true if this attribute specifies a non default border colour.
Returns true if this attribute specifies a non default font.
Returns true if this attribute specifies a non default (i.e. any) border.
Returns true if this attribute specifies that this item should be displayed as a holiday.
Returns the text colour to use for the item with this attribute.
Returns the background colour to use for the item with this attribute.
Returns the border colour to use for the item with this attribute.
Returns the font to use for the item with this attribute.
Returns the border to use for the item with this attribute.
The wxCalendarEvent class is used together with wxCalendarCtrl .
Returns the week day on which the user clicked in EVT_CALENDAR_WEEKDAY_CLICKED handler. It doesn't make sense to call this function in other handlers.
Sets the week day carried by the event, normally only used by the library internally.
A caret is a blinking cursor showing the position where the typed text will appear. The text controls usually have a caret but wxCaret class also allows 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.
Default constructor: you must use one of Create() functions later.
Create the caret of given (in pixels) width and height and associates it with the given window.
Create the caret of given (in pixels) width and height and associates it with the given window (same as constructor).
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).
Get the caret position (in pixels).
Get the caret size.
Get the window the caret is associated with.
Same as wxCaret::Show(false) .
Returns true if the caret was created successfully.
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).
Move the caret to given position (in logical coordinates).
Under Windows, this function will change the blink time for all carets permanently (until the next time it is called), even for the carets in other applications.
Sets the blink time for all the carets.
Changes the size of the caret.
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.
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.
Default constructor.
Destructor, destroying the checkbox.
Creates the checkbox for two-step construction. See wxCheckBox::wxCheckBox for details.
Gets the state of a 2-state checkbox.
Gets the state of a 3-state checkbox.
Returns whether or not the user can set the checkbox to the third state.
Returns whether or not the checkbox is a 3-state checkbox.
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.
Sets the checkbox to the given state. This does not cause a wxEVT_COMMAND_CHECKBOX_CLICKED event to get emitted.
Sets the checkbox to the given state. This does not cause a wxEVT_COMMAND_CHECKBOX_CLICKED event to get emitted.
A checklistbox is like a listbox, but allows items to be checked or unchecked.
When using this class under Windows wxWidgets must be compiled with USE_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.
Default constructor.
Constructor, creating and showing a list box.
Destructor, destroying the list box.
Checks the given item. Note that calling this method doesn't result in wxEVT_COMMAND_CHECKLISTBOX_TOGGLE being emitted.
Returns true if the given item is checked, false otherwise.
A choice item is used to select one of a list of strings. Unlike a listbox, only the selection is visible until the user pulls down the menu of choices.
Default constructor.
Destructor, destroying the choice item.
Creates the choice for two-step construction. See wxChoice::wxChoice .
Deletes the item with the given index from the control.
This is implemented for Motif only and always returns 1 for the other platforms.
Gets the number of columns in this choice item.
Unlike 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.
\newsince{2.6.2} (before this version GetSelection itself behaved like this).
This is implemented for Motif only and doesn't do anything under other platforms.
Sets the number of columns in this choice item.
wxChoicebook is a class similar to wxNotebook but which uses a wxChoice 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 notebook sample to see wxChoicebook in action.
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 .
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.
Creates an object of the appropriate kind. Returns NULL if the class has not been declared dynamically creatable (typically, it is an abstract class).
Finds the wxClassInfo object for a class of the given string name.
Returns the name of the first base class (NULL if none).
Returns the name of the second base class (NULL if none).
Returns the string form of the class name.
Returns the size of the class.
Initializes pointers in the wxClassInfo objects for fast execution of IsKindOf. Called in base wxWidgets library initialization.
Returns true if this class is a kind of (inherits from) the given class.
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 Interprocess communications overview for an example of how to do this.
Constructs a client object.
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 wxClient::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.
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!
Called by wxClient::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.
Returns true if this is a valid host name, false otherwise. This always returns true under MS Windows.
A wxClientDC must be constructed if an application wishes to paint on the client area of a window from outside an OnPaint event. This should normally be constructed as a temporary stack object; don't store a wxClientDC object.
To draw on a window from within OnPaint , construct a wxPaintDC object.
To draw on the whole window including decorations, construct a wxWindowDC object (Windows only).
Constructor. Pass a pointer to the window on which you wish to paint.
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 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 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 .
Constructor.
Virtual destructor.
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 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 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.
Get the untyped client data.
Get a pointer to the client data object.
Set the untyped client data.
Set the client data object. Any previous object will be deleted.
A class for manipulating the clipboard. Note that this is not compatible with the clipboard class from wxWidgets 1.xx, which has the same name but a different implementation.
To use the clipboard, you call member functions of the global wxTheClipboard object.
See also the wxDataObject overview 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:
// 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();
}
Constructor.
Destructor.
Call this function to add the data object to the clipboard. You may call this function repeatedly after having cleared the clipboard using wxClipboard::Clear .
After this function has been called, the clipboard owns the data, so do not delete the data explicitly.
Clears the global clipboard object and the system's clipboard if possible.
Call this function to close the clipboard, having opened it with wxClipboard::Open .
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. Returns false if the operation is unsuccessful for any reason.
Call this function to fill data with data on the clipboard, if available in the required format. Returns true on success.
Returns true if the clipboard has been opened.
Returns true if there is data which matches the data format of the given data object currently available (IsSupported sounds like a misnomer, FIXME: better deprecate this name?) on the clipboard.
Call this function to open the clipboard before calling wxClipboard::SetData and wxClipboard::GetData .
Call wxClipboard::Close when you have finished with the clipboard. You should keep the clipboard open for only a very short time.
Returns true on success. This should be tested (as in the sample shown above).
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.
On platforms supporting it (currently only GTK), selects the so called PRIMARY SELECTION as the clipboard as opposed to the normal clipboard, if primary is true.
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 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.
Constructor.
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.
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.
Returns true if the application wishes to force the window to close. This will shortly be obsolete, replaced by CanVeto.
Sets the 'can veto' flag.
Sets the 'force' flag.
Sets the 'logging off' flag.
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 wxCloseEvent::CanVeto returns true.
wxCmdLineParser is a class for parsing the command line.
It has the following features:
To use it you should follow these steps:
In the documentation below the following terminology is used:
| 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, -v might be a switch meaning "enable verbose mode". |
| option | Option for us here is something which comes with a value 0 unlike a switch. For example, -o:filename might be an option which allows to specify the name of the output file. |
| parameter | This is a required program argument. |
The structure wxCmdLineEntryDesc is used to describe the one command line switch, option or parameter. An array of such structures should be passed to SetDesc() . Also, the meanings of parameters of the AddXXX() functions are the same as of the corresponding fields in this structure:
struct wxCmdLineEntryDesc
{
wxCmdLineEntryType kind;
const wxChar *shortName;
const wxChar *longName;
const wxChar *description;
wxCmdLineParamType type;
int flags;
};
The type of a command line entity is in the kind field and may be one of the following constants:
enum wxCmdLineEntryType
{
wxCMD_LINE_SWITCH,
wxCMD_LINE_OPTION,
wxCMD_LINE_PARAM,
wxCMD_LINE_NONE // use this to terminate the list
}
The field shortName is the usual, short, name of the switch or the option. longName is the corresponding long name or NULL 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.
description is used by the Usage() method to construct a help message explaining the syntax of the program.
The possible values of type which specifies the type of the value accepted by an option or parameter are:
enum wxCmdLineParamType
{
wxCMD_LINE_VAL_STRING, // default
wxCMD_LINE_VAL_NUMBER,
wxCMD_LINE_VAL_DATE,
wxCMD_LINE_VAL_NONE
}
Finally, the flags field is a combination of the following bit masks:
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 sep before the value
}
Notice that by default (i.e. if flags are just 0), options are optional (sic) and each call to 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 GetParamCount to retrieve the number of parameters effectively specified after calling Parse .
The last flag 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.
Default constructor. You must use SetCmdLine later.
Constructor specifies the command line to parse. This is the traditional (Unix) command line format. The parameters argc and argv have the same meaning as for 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.
Constructor specifies the command line to parse in Windows format. The parameter cmdline has the same meaning as the corresponding parameter of WinMain() .
Same as wxCmdLineParser , but also specifies the command line description .
Same as wxCmdLineParser , but also specifies the command line description .
Same as wxCmdLineParser , but also specifies the command line description .
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.
Set command line to parse after using one of the constructors which don't do it. The second overload of this function is only available in Unicode build.
Set command line to parse after using one of the constructors which don't do it.
Frees resources allocated by the object.
NB: destructor is not virtual, don't use this class polymorphically.
switchChars contains all characters with which an option or switch may start. Default is "-" for Unix, "-/" for Windows.
Enable or disable support for the long options.
As long options are not (yet) POSIX-compliant, this option allows to disable them.
Identical to EnableLongOptions(false) .
Returns true if long options are enabled, otherwise false.
logo is some extra text which will be shown by Usage method.
Construct the command line description
Take the command line description from the wxCMD_LINE_NONE terminated table.
Example of usage:
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);
Add a switch name with an optional long name lng (no long name if it is empty, which is default), description desc and flags flags to the command line description.
Add an option name with an optional long name 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.
Add a parameter of the given type to the command line description.
Parse the command line, return 0 if ok, -1 if "-h" or "--help" option was encountered and the help message was given or a positive value if a syntax error occurred.
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.
Returns true if the given switch was found, false otherwise.
Returns true if an option taking a string value was found and stores the value in the provided pointer (which should not be NULL).
Returns true if an option taking an integer value was found and stores the value in the provided pointer (which should not be NULL).
Returns true if an option taking a date value was found and stores the value in the provided pointer (which should not be NULL).
Returns the number of parameters found. This function makes sense mostly if you had used wxCMD_LINE_PARAM_MULTIPLE flag.
Returns the value of Nth parameter (as string only for now).
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 .
Objects:
wxNullColour
Pointers:
wxBLACK
wxWHITE
wxRED
wxBLUE
wxGREEN
wxCYAN
wxLIGHT_GREY
Default constructor.
Constructs a colour from red, green and blue values.
Constructs a colour object using a colour name listed in wxTheColourDatabase .
Copy constructor.
Returns the blue intensity.
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).
Returns the green intensity.
Returns true if the colour object is valid (the colour has been initialised with RGB values).
Returns the red intensity.
Sets the RGB intensity values.
Assignment operator, taking another colour object.
Assignment operator, using a colour name to be found in the colour database.
Tests the equality of two colours by comparing individual red, green blue colours.
Tests the inequality of two colours by comparing individual red, green blue colours.
This class holds a variety of information related to colour dialogs.
Constructor. Initializes the custom colours to wxNullColour , the data colour setting to black, and the choose full setting to true.
Destructor.
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.
Gets the current colour associated with the colour dialog.
The default colour is black.
Gets the i th custom colour associated with the colour dialog. i should be an integer between 0 and 15.
The default custom colours are invalid colours.
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.
Sets the default colour for the colour dialog.
The default colour is black.
Sets the i th custom colour for the colour dialog. i should be an integer between 0 and 15.
The default custom colours are invalid colours.
Assignment operator for the colour data.
wxWidgets maintains a database of standard RGB colours for a predefined set of named colours (such as ``BLACK'', ``LIGHT GREY''). 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 suing FindName .
There is one predefined instance of this class called wxTheColourDatabase .
The standard database contains at least the following colours:
AQUAMARINE, BLACK, BLUE, BLUE VIOLET, BROWN, CADET BLUE, CORAL, CORNFLOWER BLUE, CYAN, DARK GREY, DARK GREEN, DARK OLIVE GREEN, DARK ORCHID, DARK SLATE BLUE, DARK SLATE GREY DARK TURQUOISE, DIM GREY, FIREBRICK, FOREST GREEN, GOLD, GOLDENROD, GREY, GREEN, GREEN YELLOW, INDIAN RED, KHAKI, LIGHT BLUE, LIGHT GREY, LIGHT STEEL BLUE, LIME GREEN, MAGENTA, MAROON, MEDIUM AQUAMARINE, MEDIUM BLUE, MEDIUM FOREST GREEN, MEDIUM GOLDENROD, MEDIUM ORCHID, MEDIUM SEA GREEN, MEDIUM SLATE BLUE, MEDIUM SPRING GREEN, MEDIUM TURQUOISE, MEDIUM VIOLET RED, MIDNIGHT BLUE, NAVY, ORANGE, ORANGE RED, ORCHID, PALE GREEN, PINK, PLUM, PURPLE, RED, SALMON, SEA GREEN, SIENNA, SKY BLUE, SLATE BLUE, SPRING GREEN, STEEL BLUE, TAN, THISTLE, TURQUOISE, VIOLET, VIOLET RED, WHEAT, WHITE, YELLOW, YELLOW GREEN.
Constructs the colour database. It will be initialized at the first use.
Adds a colour to the database. If a colour with the same name already exists, it is replaced.
Please note that the overload taking a pointer is deprecated and will be removed in the next wxWidgets version, please don't use it.
Finds a colour given the name. Returns an invalid colour object (that is, such that its Ok() method returns false) if the colour wasn't found in the database.
Finds a colour name given the colour. Returns an empty string if the colour is not found in the database.
This class represents the colour chooser dialog.
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 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).
Destructor.
Same as constructor .
Returns the colour data associated with the colour dialog.
Shows the dialog, returning wxID_OK if the user pressed OK, and wxID_CANCEL otherwise.
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.
Default constructor.
Destructor, destroying the combobox.
Creates the combobox for two-step construction. Derived classes should call or replace this function. See wxComboBox::wxComboBox for further details.
Returns true if the combobox is editable and there is a text selection to copy to the clipboard. Only available on Windows.
Returns true if the combobox is editable and there is a text selection to copy to the clipboard. Only available on Windows.
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.
Returns true if the combobox is editable and the last undo can be redone. Only available on Windows.
Returns true if the combobox is editable and the last edit can be undone. Only available on Windows.
Copies the selected text to the clipboard.
Copies the selected text to the clipboard and removes the selection.
Returns the insertion point for the combobox's text field.
Returns the last position in the combobox text field.
Returns the current value in the combobox text field.
Pastes text from the clipboard to the text field.
Redoes the last undo in the text field. Windows only.
Replaces the text between two positions with the given text, in the combobox text field.
Removes the text between the two positions in the combobox text field.
Sets the insertion point in the combobox text field.
Sets the insertion point at the end of the combobox text field.
Selects the text between the two positions, in the combobox text field.
Sets the text for the combobox text field.
NB: For a combobox with wxCB_READONLY style the string must be in the combobox choices list, otherwise the call to SetValue() is ignored.
Undoes the last edit in the text field. Windows only.
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.
Constructor. wxCommand is an abstract class, so you will need to derive a new class and call this constructor from your own constructor.
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).
name must be supplied for the command processor to display the command name in the application's edit menu.
Destructor.
Returns true if the command can be undone, false otherwise.
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.
Returns the command name.
Override this member function to un-execute a previous Do. 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.
How you implement this command is totally application dependent, but typical strategies include:
The docview sample uses the first method, to remove or restore segments in the drawing.
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.
Constructor.
Deprecated, use IsChecked instead.
Returns client data pointer for a listbox or choice selection event (not valid for a deselection).
Returns client object pointer for a listbox or choice selection event (not valid for a deselection).
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.
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.
Returns item index for a listbox or choice selection event (not valid for a deselection).
Returns item string for a listbox or choice selection event (not valid for a deselection).
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).
For a listbox or similar event, returns true if it is a selection, false if it is a deselection.
Sets the client data for this event.
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.
Sets the m_extraLong member.
Sets the m_commandInt member.
Sets the m_commandString member.
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.
Constructor.
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.
Destructor.
Returns true if the currently-active command can be undone, false otherwise.
Deletes all the commands in the list and sets the current command pointer to NULL.
Executes (redoes) the current command (the command that has just been undone if any).
Returns the list of commands.
Returns the maximum number of commands that the command processor stores.
Returns the edit menu associated with the command processor.
Returns the string that will be appended to the Redo menu item.
Returns the string that will be shown for the redo menu item.
Returns the string that will be appended to the Undo menu item.
Returns the string that will be shown for the undo menu item.
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).
Returns a boolean value that indicates if changes have been made since the last save operation. This only works if wxCommandProcessor::MarkAsSaved is called whenever the project is saved.
You must call this method whenever the project is saved if you plan to use wxCommandProcessor::IsDirty .
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.
Sets the menu labels according to the currently set menu and the current command state.
Sets the string that will be appended to the Redo menu item.
Sets the string that will be appended to the Undo menu item.
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.
storeIt indicates whether the successful command should be stored in the history list.
Undoes the command just executed.
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 Wait() for the worker thread, but if there are several worker threads it already makes much more sense).
Note that a call to Signal() may happen before the other thread calls 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 Signal() . Of course, this means that this call is going to block until Wait() is called by another thread.
This example shows how a main thread may launch a worker thread which starts running and then waits until the main thread signals it to continue:
class MySignallingThread : public wxThread
{
public:
MySignallingThread(wxMutex *mutex, wxCondition *condition)
{
m_mutex = mutex;
m_condition = condition;
Create();
}
virtual ExitCode Entry()
{
... do our job ...
// tell the other(s) thread(s) that we're about to terminate: we must
// lock the mutex first or we might signal the condition before the
// waiting threads start waiting on it!
wxMutexLocker lock(m_mutex);
m_condition.Broadcast(); // same as Signal() here -- one waiter only
return 0;
}
private:
wxCondition *m_condition;
wxMutex *m_mutex;
};
int main()
{
wxMutex mutex;
wxCondition condition(mutex);
// the mutex should be initially locked
mutex.Lock();
// create and run the thread but notice that it won't be able to
// exit (and signal its exit) before we unlock the mutex below
MySignallingThread *thread = new MySignallingThread(&mutex, &condition);
thread->Run();
// wait for the thread termination: Wait() atomically unlocks the mutex
// which allows the thread to continue and starts waiting
condition.Wait();
// now we can exit
return 0;
}
Of course, here it would be much better to simply use a joinable thread and call wxThread::Wait on it, but this example does illustrate the importance of properly locking the mutex when using wxCondition.
The following return codes are returned by wxCondition member functions:
enum wxCondError
{
wxCOND_NO_ERROR = 0, // successful completion
wxCOND_INVALID, // object hasn't been initialized successfully
wxCOND_TIMEOUT, // WaitTimeout() has timed out
wxCOND_MISC_ERROR // some other error
};
Default and only constructor. The mutex must be locked by the caller before calling Wait function.
Use IsOk to check if the object was successfully initialized.
Destroys the wxCondition object. The destructor is not virtual so this class should not be used polymorphically.
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.
Returns true if the object had been initialized successfully, false if an error occurred.
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.
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.
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.
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 wxCOND_TIMEOUT as soon as the given timeout expires.
wxConfigBase class 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 config overview for the descriptions 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.
Here is how you would typically use this class:
// 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->Read("/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;
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.
NB: 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.
By default, environment variable expansion is on and recording defaults is off.
This is the default and only constructor of the wxConfigBase class, and derived classes.
Empty but ensures that dtor of all derived classes is virtual.
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.
Calling this function will prevent 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.
Delete the whole underlying object (disk file, registry key, ...). Primarly for use by uninstallation routine.
Deletes the specified entry and the group it belongs to if it was the last key in it and the second parameter is true.
Delete the group (with all subgroups)
returns true if either a group or an entry with a given name exists
permanently writes all changes (otherwise, they're only written from object's destructor)
Get the current config object. If there is no current object and CreateOnDemand is true, creates one (using Create ) unless DontCreateOnDemand was called previously.
Returns the application name.
Returns the type of the given entry or 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.
The result is an element of enum EntryType:
enum EntryType
{
Type_Unknown,
Type_String,
Type_Boolean,
Type_Integer,
Type_Float
};
Gets the first group.
Gets the first entry.
Gets the next group.
Gets the next entry.
Get number of entries/subgroups in the current group, with or without its subgroups.
Retrieve the current path (always as absolute path).
Returns the vendor name.
returns true if the entry by this name exists
returns true if the group by this name exists
Returns true if we are expanding environment variables in key values.
Returns true if we are writing defaults back to the config file.
Read a string from the key, returning true if the value was read. If the key was not found, str is not changed.
Read a string from the key. The default value is returned if the key was not found.
Returns true if value was really read, false if the default was used.
Another version of Read() , returning the string value directly.
Reads a long value, returning true if the value was found. If the value was not found, l is not changed.
Reads a long value, returning true if the value was found. If the value was not found, defaultVal is used instead.
Reads a long value from the key and returns it. defaultVal is returned if the key is not found.
NB: writing
conf->Read("key", 0);
won't work because the call is ambiguous: compiler can not choose between two Read functions. Instead, write:
conf->Read("key", 0l);
Reads a double value, returning true if the value was found. If the value was not found, d is not changed.
Reads a double value, returning true if the value was found. If the value was not found, defaultVal is used instead.
Reads a bool value, returning true if the value was found. If the value was not found, b is not changed.
Reads a bool value, returning true if the value was found. If the value was not found, defaultVal is used instead.
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.
Returns false if oldName doesn't exist or if newName already exists.
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.
Returns false if oldName doesn't exist or if newName already exists.
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)
Determine whether we wish to expand environment variables in key values.
Set current path: if the first character is '/', it is the absolute path, otherwise it is a relative path. '..' is supported. If strPath doesn't exist it is created.
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.
These functions write the specified value to the config file and return true on success.
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 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.
wxIPCFormat is defined as follows:
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_UNICODETEXT = 13,
wxIPC_ENHMETAFILE = 14,
wxIPC_FILENAME = 15, /* CF_HDROP */
wxIPC_LOCALE = 16,
wxIPC_PRIVATE = 20
};
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.
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 wxConnection::OnAdvise member to be called. Returns true if successful.
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 wxConnection::Poke in that respect). Causes the server connection's wxConnection::OnExecute member to be called. Returns true if successful.
Called by the client or server application to disconnect from the other program; it causes the wxConnection::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 Disconnect must explicitly delete its side of the connection.
Message sent to the client application when the server notifies it of a change in the data associated with the given item, using Advise .
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 OnDisconnect (finally calling the inherited method as well) so that they know the connection object is no longer available.
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.
Message sent to the server application when the client notifies it to accept the given data.
Message sent to the server application when the client calls wxConnection::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.
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.
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.
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 wxConnection::OnPoke member to be called. If size is -1 the size is computed from the string length of data.
Returns true if successful.
Called by the client application to request data from the server. Causes the server connection's wxConnection::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.
Called by the client application to ask if an advise loop can be started with the server. Causes the server connection's wxConnection::OnStartAdvise member to be called. Returns true if the server okays it, false otherwise.
Called by the client application to ask if an advise loop can be stopped. Causes the server connection's wxConnection::OnStopAdvise member to be called. Returns true if the server okays it, false otherwise.
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:
wxContextHelp contextHelp(myWindow);
There are a couple of ways to invoke this behaviour implicitly:
Note that on Mac OS X, the cursor does not change when in context-sensitive help mode.
Constructs a context help object, calling BeginContextHelp if doNow is true (the default).
If window is NULL, the top window is used.
Destroys the context help object.
Puts the application into context-sensitive help mode. 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.
Ends context-sensitive help mode. Not normally called by the application.
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.
Default constructor.
Normally you need pass only the parent window to the constructor, and use the defaults for the remaining parameters.
Constructor, creating and showing a context help button.
This class is used for context menu events, sent to give the application a chance to show a context (popup) menu.
Constructor.
Returns the position at which the menu should be shown.
Sets the position at which the menu should be shown.
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.
Simulates the effect of the user issuing a command to the item. See wxCommandEvent .
Returns the control's text.
Sets the item's text.
This class is an abstract base class for some wxWidgets controls which contain several items, such as wxListBox and wxCheckListBox derived from it, wxChoice and wxComboBox .
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 wxControlWithItems have (non empty) string labels and, optionally, client data associated with them. Client data may be of two different kinds: either simple untyped ( 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 or the entire control is cleared (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 .
Adds the item to the end of the list box.
Adds the item to the end of the list box, associating the given, typed or untyped, client data pointer with the item.
Appends several items at once to the control. Notice that calling this method may be much faster than appending the items one by one if you need to add a lot of items.
Removes all items from the control.
Clear() also deletes the client data of the existing items if it is owned by the control.
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.
Finds an item whose label matches the given string.
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).
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).
Returns the number of items in the control.
This method can be used with single selection list boxes only, you should use wxListBox::GetSelections for the list boxes with wxLB_MULTIPLE style.
Returns the index of the selected item or wxNOT_FOUND if no item is selected.
Returns the label of the item with the given index.
Returns the label of the selected item or an empty string if no item is selected.
Inserts the item into the list before pos. Not valid for wxLB_SORT or wxCB_SORT styles, use Append instead.
Inserts the item into the list before pos, associating the given, typed or untyped, client data pointer with the item. Not valid for wxLB_SORT or wxCB_SORT styles, use Append instead.
Returns true if the control is empty or false if it has some items.
Obsolescence note: This method is obsolete and was replaced with GetCount , please use the new method in the new code. This method is only available if wxWidgets was compiled with WXWIN_COMPATIBILITY_2_2 defined and will disappear completely in future versions.
This is the same as SetSelection and exists only because it is slightly more natural for controls which support multiple selection.
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.
Associates the given typed client data pointer with the given item: the data object will be deleted when the item is deleted (either explicitly by using Deletes 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.
Sets the selection to the given item n or removes the selection entirely if n == 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.
Sets the label for the given item.
Selects the item with the specified string in the control. This doesn't cause any command events being emitted.
wxCountingOutputStream is a specialized output stream which does not write any data anyway, 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).
Creates a wxCountingOutputStream object.
Destructor.
Returns the current size of the stream.
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 between 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.
Default constructor initializes critical section object.
Destructor frees the resources.
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.
Leave the critical section allowing other threads use the global data protected by it. There is no error return for this function.
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:
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;
}
Without wxCriticalSectionLocker, you would need to remember to manually leave the critical section before each return .
Constructs a wxCriticalSectionLocker object associated with given criticalsection and enters it.
Destructor leaves the critical section.
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 is also available for MS Windows use.
Objects:
wxNullCursor
Pointers:
wxSTANDARD_CURSOR
wxHOURGLASS_CURSOR
wxCROSS_CURSOR
Default constructor.
Constructs a cursor by passing an array of bits (Motif and GTK+ only). maskBits is used only under Motif and GTK+. The parameters fg and bg are only present on GTK+, and force the cursor to use particular background and foreground colours.
If either hotSpotX or hotSpotY is -1, the hotspot will be the centre of the cursor image (Motif only).
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.
hotSpotX and 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.
Constructs a cursor using a cursor identifier.
Constructs a cursor from a wxImage. The cursor is monochrome, colors with the RGB elements all greater than 127 will be foreground, colors less than this background. The mask (if any) will be used as transparent.
In MSW the foreground will be white and the background black. If the cursor is larger than 32x32 it is resized. In GTK, the two most frequent colors will be used for foreground and background. The cursor will be displayed at the size of the image. On MacOS if the cursor is larger than 16x16 it is resized and currently only shown as black/white (mask respected).
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+.
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
Copy constructor. This uses reference counting so is a cheap operation.
Destroys the cursor. 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.
Returns true if cursor data is present.
Assignment operator, using reference counting. Returns a reference to `this'.
Equality operator. Two cursors are equal if they contain pointers to the same underlying cursor data. It does not compare each attribute, so two independently-created cursors using the same parameters will fail the test.
Inequality operator. Two cursors are not equal if they contain pointers to different underlying cursor data. It does not compare each attribute.
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 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.
If you already store the data in another place, it may be more convenient and efficient to provide the data on-demand which is possible too if you override the virtual functions mentioned below.
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)
The constructor accepts a format argument which specifies the (single) format supported by this object. If it isn't set here, SetFormat should be used.
The destructor will free the data hold by the object. Notice that although it calls a 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() ).
This function is called to allocate size bytes of memory from SetData(). The default version just uses the operator new.
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.
Returns the data size in bytes.
Returns a pointer to the data.
Set the data. The data object will make an internal copy.
Like SetData , but doesn't copy the data - instead the object takes ownership of the pointer.
A wxDC is a device context onto which graphics and text can be drawn. It is intended to represent a number of output devices in a generic way, so a window can have a device context associated with it, and a printer also has a device context. In this way, the same piece of code may write to a number of different devices, if the device context is used as a parameter.
Derived types of wxDC have documentation for specific features only, so refer to this section for most device context information.
Please note that in addition to the versions of the methods documented here, there are also versions which accept single wxPoint parameter instead of two wxCoord ones or wxPoint and wxSize instead of four of them.
Constructor.
Destructor.
Allows optimization of drawing code under MS Windows. Enclose drawing primitives between BeginDrawing and EndDrawing calls.
Drawing to a wxDialog panel device context outside of a system-generated OnPaint event requires this pair of calls to enclose drawing code. This is because a Windows dialog box does not have a retained device context associated with it, and selections such as pen and brush settings would be lost if the device context were obtained and released for each drawing operation.
Adds the specified point to the bounding box which can be retrieved with MinX , MaxX and MinY , MaxY functions.
Clears the device context using the current background brush.
\begin{comment}
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.
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.
Destroys the current clipping region so that none of the DC is clipped. See also wxDC::SetClippingRegion .
Convert device X coordinate to logical coordinate, using the current mapping mode.
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.
Converts device Y coordinate to logical coordinate, using the current mapping mode.
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.
Draws an arc of a circle, centred on ( xc, yc ), with starting point ( x1, y1 ) and ending at ( x2, y2 ). The current pen is used for the outline and the current brush for filling the shape.
The arc is drawn in an anticlockwise direction from the start point to the end point.
Draw a bitmap on the device context at the specified point. If 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 also SetTextForeground , SetTextBackground and wxMemoryDC .
Draws a check mark inside the given rectangle.
Draws a circle with the given centre and 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.
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.
x and y specify the x and y coordinates of the upper-left corner of the rectangle that contains the ellipse.
width and height specify the width and height of the rectangle that contains the ellipse.
start and 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 start is equal to end , a complete ellipse will be drawn.
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.
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.
Draws a line from the first point to the second. The current pen is used for drawing the line. Note that the point (x2, y2) is not part of the line and is not drawn by this function (this is consistent with the behaviour of many other toolkits).
Draws lines using an array of points of size 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.
Draws a filled polygon using an array of points of size n , or list of pointers to points, adding the optional offset coordinate.
The last argument specifies the fill rule: wxODDEVEN_RULE (the default) or 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.
Note that wxWidgets automatically closes the first and last points.
Draws two or more filled polygons using an array of 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.
n specifies the number of polygons to draw, the array count of size n specifies the number of points in each of the polygons in the points array.
The last argument specifies the fill rule: wxODDEVEN_RULE (the default) or 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 DrawPolyPolygon are not closed automatically.
Draws a point using the color of the current pen. Note that the other properties of the pen are not used, such as width etc..
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.
Draws the text rotated by angle degrees.
NB: Under Win9x only TrueType fonts can be drawn by this function. In particular, a font different from wxNORMAL_FONT should be used as the latter is not a TrueType font. wxSWISS_FONT is an example of a font which is.
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 radius is positive, the value is assumed to be the radius of the rounded corner. If radius is negative, the absolute value is assumed to be the 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.
Draws a spline between all given control points, using the current pen.
Draws a spline between all given control points, using the current pen. Doesn't delete the wxList and contents.
Draws a three-point spline using the current pen.
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.
NB: under wxGTK the current 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.
\begin{comment}
Ends a document (only relevant when outputting to a printer).
Allows optimization of drawing code under MS Windows. Enclose drawing primitives between BeginDrawing and EndDrawing calls.
Ends a document page (only relevant when outputting to a printer).
Flood fills the device context starting from the given point, using the current brush colour , and using a style:
Returns 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.
Gets the brush used for painting the background (see wxDC::SetBackground ).
Returns the current background mode: wxSOLID or wxTRANSPARENT .
Gets the current brush (see wxDC::SetBrush ).
Gets the character height of the currently set font.
Gets the average character width of the currently set font.
Gets the rectangle surrounding the current clipping region.
Gets the current font (see wxDC::SetFont ).
Gets the current logical function (see wxDC::SetLogicalFunction ).
Gets the mapping mode for the device context (see wxDC::SetMapMode ).
Fills the widths array with the widths from the beginning of text to the corresponding character of 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.
Gets the current pen (see wxDC::SetPen ).
Gets in colour the colour at the specified location. Not available for wxPostScriptDC or wxMetafileDC.
Note that setting a pixel can be done using DrawPoint .
Returns the resolution of the device in pixels per inch.
This gets the horizontal and vertical resolution in device units. It can be used to scale graphics to fit the page. For example, if maxX and 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:
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));
Returns the horizontal and vertical resolution in millimetres.
Gets the current text background colour (see wxDC::SetTextBackground ).
Gets the dimensions of the string using the currently selected font. string is the text string to measure, w and h are the total width and height respectively, descent is the dimension from the baseline of the font to the bottom of the descender, and externalLeading is any extra vertical space added to the font by the font designer (usually is zero).
The optional parameter 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 also wxFont , wxDC::SetFont .
Gets the current text foreground colour (see wxDC::SetTextForeground ).
Gets the current user scale factor (set by SetUserScale ).
Converts logical X coordinate to device coordinate, using the current mapping mode.
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.
Converts logical Y coordinate to device coordinate, using the current mapping mode.
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.
Gets the maximum horizontal extent used in drawing commands so far.
Gets the maximum vertical extent used in drawing commands so far.
Gets the minimum horizontal extent used in drawing commands so far.
Gets the minimum vertical extent used in drawing commands so far.
Returns true if the DC is ok to use.
Resets the bounding box: after a call to this function, the bounding box doesn't contain anything.
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.
Sets the current background brush for the DC.
mode may be one of wxSOLID and wxTRANSPARENT. This setting determines whether text will be drawn with a background colour or not.
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 also wxBrush .
See also wxMemoryDC for the interpretation of colours when drawing into a monochrome bitmap.
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.
Sets the current font for the DC. It must be a valid font, in particular you should not pass wxNullFont to this method.
See also wxFont .
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 wxDC::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:
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
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.
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 wxDC::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 pixel. |
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 for further details.
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 also wxMemoryDC for the interpretation of colours when drawing into a monochrome bitmap.
Sets the current text background colour for the DC.
Sets the current text foreground colour for the DC.
See also wxMemoryDC for the interpretation of colours when drawing into a monochrome bitmap.
Sets the user scaling factor, useful for applications which require `zooming'.
Starts a document (only relevant when outputting to a printer). Message is a message to show while printing.
Starts a document page (only relevant when outputting to a printer).
This is a small helper class which sets the specified DC to its constructor clipping region and then automatically destroys it in its destructor. Using it ensures that an unwanted clipping region is not left set on the DC.
Constructor: sets the clipping region for the given device context to the specified rectangle.
Destructor: destroys the clipping region set in the constructor.
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 wxDDEClient::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 .
Constructs a client object.
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 wxDDEClient::OnMakeConnection member to return your own derived connection object.
The type of wxDDEConnection returned from a wxDDEClient::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.
Returns true if this is a valid host name, false otherwise. This always returns true under MS Windows.
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 .
wxIPCFormat is defined as follows:
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_UNICODETEXT = 13,
wxIPC_ENHMETAFILE = 14,
wxIPC_FILENAME = 15, /* CF_HDROP */
wxIPC_LOCALE = 16,
wxIPC_PRIVATE = 20
};
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. If the arguments of the wxDDEConnection 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.
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 wxDDEConnection::OnAdvise member to be called. Returns true if successful.
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 wxDDEConnection::Poke in that respect). Causes the server connection's wxDDEConnection::OnExecute member to be called. Returns true if successful.
Called by the client or server application to disconnect from the other program; it causes the wxDDEConnection::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 . Returns true if successful.
Message sent to the client application when the server notifies it of a change in the data associated with the given item.
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.
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.
Message sent to the server application when the client notifies it to accept the given data.
Message sent to the server application when the client calls wxDDEConnection::Request . The server should respond by returning a character string from OnRequest , or NULL to indicate no data.
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.
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.
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 wxDDEConnection::OnPoke member to be called. Returns true if successful.
Called by the client application to request data from the server. Causes the server connection's wxDDEConnection::OnRequest member to be called. Returns a character string (actually a pointer to the connection's buffer) if successful, NULL otherwise.
Called by the client application to ask if an advise loop can be started with the server. Causes the server connection's wxDDEConnection::OnStartAdvise member to be called. Returns true if the server okays it, false otherwise.
Called by the client application to ask if an advise loop can be stopped. Causes the server connection's wxDDEConnection::OnStopAdvise member to be called. Returns true if the server okays it, false otherwise.
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 .
Constructs a server object.
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).
When a client calls 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 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.
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 ( CLIPFORMAT under Windows or Atom under X11, for example) and the standard formats are, indeed, just numbers which can be implicitly converted to wxDataFormat. The standard formats are:
| wxDF_INVALID | An invalid format - used as default argument for functions taking a wxDataFormat argument sometimes |
| wxDF_TEXT | Text format (wxString) |
| wxDF_BITMAP | A bitmap (wxBitmap) |
| wxDF_METAFILE | A metafile (wxMetafile, Windows only) |
| wxDF_FILENAME | A list of filenames |
| wxDF_HTML | An HTML string. This is only valid when passed to wxSetClipboardData when compiled with Visual C++ in non-Unicode mode |
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 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 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!
None
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)
Constructs a data format object for a custom format identified by its name format .
Returns true if the formats are equal.
Returns true if the formats are different.
Returns the name of a custom format (this function will fail for a standard format).
Returns the platform-specific number identifying the format.
Sets the format to be the custom format identified by the given name.
Sets the format to the given value, which should be one of wxDF_XXX constants.
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:
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
See also wxDataOutputStream .
Constructs a datastream object from an input stream. Only read methods will be available. The second form is only available in Unicode build of wxWidgets.
Destroys the wxDataInputStream object.
If 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).
Reads a single byte from the stream.
Reads bytes from the stream in a specified buffer. The amount of bytes to read is specified by the size variable.
Reads a 16 bit unsigned integer from the stream.
Reads 16 bit unsigned integers from the stream in a specified buffer. the amount of 16 bit unsigned integer to read is specified by the size variable.
Reads a 32 bit unsigned integer from the stream.
Reads 32 bit unsigned integers from the stream in a specified buffer. the amount of 32 bit unsigned integer to read is specified by the size variable.
Reads a 64 bit unsigned integer from the stream.
Reads 64 bit unsigned integers from the stream in a specified buffer. the amount of 64 bit unsigned integer to read is specified by the size variable.
Reads a double (IEEE encoded) from the stream.
Reads double data (IEEE encoded) from the stream in a specified buffer. the amount of double to read is specified by the size variable.
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 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 also wxDataOutputStream::WriteString .
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
enum Direction
{
Get = 0x01, // format is supported by GetDataHere()
Set = 0x02 // format is supported by SetData()
};
which distinguishes between them. 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):
| 1. 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. |
| 2. 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). |
| 3. 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). |
| 4. 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 and wxBitmapDataObject 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 .
Constructor.
Destructor.
Copy all supported formats in the given direction to the array pointed to by formats . There is enough space for GetFormatCount(dir) formats in it.
The method will write the data of the format format in the buffer buf and return true on success, false on failure.
Returns the data size of the given format format .
Returns the number of available formats for rendering or setting the data.
Returns the preferred format for either rendering the data (if dir is Get , its default value) or for setting it. Usually this will be the native format of the wxDataObject.
Set the data in the format format of the length len provided in the buffer buf .
Returns true on success, false on failure.
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 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.
None, this class should be used directly.
The default constructor.
Adds the dataObject to the list of supported objects and it becomes the preferred object if preferred is true.
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 but should be derived from.
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.
Constructor accepts the supported format (none by default) which may also be set later with SetFormat .
Returns the (one and only one) format supported by this object. It is supposed that the format is supported in both directions.
Sets the supported format.
Gets the size of our data. Must be implemented in the derived class if the object supports rendering its data.
Copy the data to the buffer, return true on success. Must be implemented in the derived class if the object supports rendering its data.
Copy the data from the buffer, return true on success. Must be implemented in the derived class if the object supports setting its data.
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.
See also wxDataInputStream .
Constructs a datastream object from an output stream. Only write methods will be available. The second form is only available in Unicode build of wxWidgets.
Destroys the wxDataOutputStream object.
If 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.
Writes the single byte i8 to the stream.
Writes an array of bytes to the stream. The amount of bytes to write is specified with the size variable.
Writes the 16 bit unsigned integer i16 to the stream.
Writes an array of 16 bit unsigned integer to the stream. The amount of 16 bit unsigned integer to write is specified with the size variable.
Writes the 32 bit unsigned integer i32 to the stream.
Writes an array of 32 bit unsigned integer to the stream. The amount of 32 bit unsigned integer to write is specified with the size variable.
Writes the 64 bit unsigned integer i64 to the stream.
Writes an array of 64 bit unsigned integer to the stream. The amount of 64 bit unsigned integer to write is specified with the size variable.
Writes the double f to the stream using the IEEE format.
Writes an array of double to the stream. The amount of double to write is specified with the size variable.
Writes string to the stream. Actually, this method writes the size of the string before writing 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 conv object passed to stream's constructor (consequently, ANSI application 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.
This event class holds information about a date change and is used together with wxDatePickerCtrl . It also serves as a base class for wxCalendarEvent .
Returns the date.
Sets the date carried by the event, normally only used by the library internally.
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 wxUSE_DATEPICKCTRL is set to 1.
Initializes the object and calls Create with all the parameters.
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), dt1 and/or dt2 are set to be invalid.
Returns the currently selected. If there is no selection or the selection is outside of the current range, an invalid object is returned.
If the current value of the control is outside of the newly set range bounds, the behaviour is undefined.
Sets the valid range for the date selection. If dt1 is valid, it becomes the earliest date (inclusive) accepted by the control. If dt2 is valid, it becomes the latest possible date.
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.
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 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 and with wxDateTime or wxTimeSpan , but the type of result is different for each case.
Beware about weeks: if you specify both weeks and days, the total number of days added will be 7*weeks + days! See also GetTotalDays() function.
Equality operators are defined for wxDateSpans. Two datespans are equal if and only if they both give the same target date when added to 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 1 Feb. 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).
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.
Returns the sum of two date spans. The first version returns a new object, the second and third ones modify this object in place.
Returns a date span object corresponding to one day.
Returns a date span object corresponding to the given number of days.
Returns the number of days (only, that it not counting the weeks component!) in this date span.
Returns the number of the months (not counting the years) in this date span.
Returns the number of weeks in this date span.
Returns the number of years in this date span.
Returns a date span object corresponding to one month.
Returns a date span object corresponding to the given number of months.
Returns the product of the date span by the specified factor . The product is computed by multiplying each of the components by the factor.
The first version returns a new object, the second and third ones modify this object in place.
Returns the date span with the opposite sign.
Changes the sign of this date span.
Sets the number of days (without modifying any other components) in this date span.
Sets the number of years (without modifying any other components) in this date span.
Sets the number of months (without modifying any other components) in this date span.
Sets the number of weeks (without modifying any other components) in this date span.
Returns the difference of two date spans. The first version returns a new object, the second and third ones modify this object in place.
Returns a date span object corresponding to one week.
Returns a date span object corresponding to the given number of weeks.
Returns a date span object corresponding to one year.
Returns a date span object corresponding to the given number of years.
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).
Returns true if this date span is different from the other one.
wxDateTime class represents an absolute moment in the time.
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:
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,
// 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 = GMT12 + 1, // Central Standard Time (+9.5)
A_EST = GMT10, // Eastern Standard Time
A_ESST = GMT11, // Eastern Summer Time
// Universal Coordinated Time = the new and politically correct name
// for GMT
UTC = GMT0
};
Month names: Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec and Inv_Month for an invalid.month value are the values of wxDateTime::Month enum.
Likewise, Sun, Mon, Tue, Wed, Thu, Fri, Sat, and Inv_WeekDay are the values in wxDateTime::WeekDay enum.
Finally, Inv_Year is defined to be an invalid value for year parameter.
GetMonthName() and GetWeekDayName functions use the following flags:
enum NameFlags
{
Name_Full = 0x01, // return full name
Name_Abbr = 0x02 // return abbreviated name
};
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:
enum Calendar
{
Gregorian, // calendar currently in use in Western countries
Julian // calendar in use since -45 until the 1582 (or later)
};
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:
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
};
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:
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
};
The type wxDateTime_t is typedefed as unsigned short and is used to contain the number of years, hours, minutes, seconds and milliseconds.
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:
wxDateTime dt(...);
int y = dt.GetYear();
printf("The year is
Returns the translations of the strings AM and PM used for time formatting for the current locale. Either of the pointers may be NULL if the corresponding value is not needed.
Get the beginning of DST for the given country in the given year (current one by default). This function suffers from limitations described in DST overview .
Returns the current default country. The default country is used for DST calculations, for example.
Get the current year in given calendar (only Gregorian is currently supported).
Get the current month in given calendar (only Gregorian is currently supported).
Get the current century, i.e. first two digits of the year, in given calendar (only Gregorian is currently supported).
Returns the end of DST for the given country in the given year (current one by default).
Gets the full (default) or abbreviated (specify Name_Abbr name of the given month.
Returns the number of days in the given year or in the given month of the year.
The only supported value for cal parameter is currently Gregorian .
Returns the current time.
Returns the current time broken down.
Gets the full (default) or abbreviated (specify Name_Abbr name of the given week day.
Returns true if the year is a leap one in the specified calendar.
This functions supports Gregorian and Julian calendars.
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.
Returns true if DST was used n the given year (the current one by default) in the given country.
Returns the object corresponding to the current time.
Example:
wxDateTime now = wxDateTime::Now();
printf("Current time in Paris:\t
Note that this function is accurate up to second: wxDateTime::UNow should be used for better precision (but it is less efficient and might not be available on all platforms).
Sets the country to use by default. This setting influences the DST calculations, date formatting and other things.
The possible values for country parameter are enumerated in wxDateTime constants section .
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).
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).
Default constructor. Use one of Set() functions to initialize the object later.
Same as Set .
Same as Set
Same as Set
Same as Set
Same as Set
Sets the date and time of to the current values. Same as assigning the result of Now() to this object.
Constructs the object from timet value holding the number of seconds since Jan 1, 1970.
Sets the date and time from the broken down representation in the standard tm structure.
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.
Sets the date to be equal to Today and the time from supplied parameters.
Sets the date and time from the parameters.
Reset time to midnight (00:00:00) without changing the date.
Sets the year without changing other date components.
Sets the month without changing other date components.
Sets the day without changing other date components.
Sets the hour without changing other date components.
Sets the minute without changing other date components.
Sets the second without changing other date components.
Sets the millisecond without changing other date components.
Same as Set .
Same as Set .
Returns true if the object represents a valid time moment.
Returns broken down representation of the date and time.
Returns the number of seconds since Jan 1, 1970. An assert failure will occur if the date is not in the range covered by time_t type.
Returns the year in the given timezone (local one by default).
Returns the month in the given timezone (local one by default).
Returns the day in the given timezone (local one by default).
Returns the week day in the given timezone (local one by default).
Returns the hour in the given timezone (local one by default).
Returns the minute in the given timezone (local one by default).
Returns the seconds in the given timezone (local one by default).
Returns the milliseconds in the given timezone (local one by default).
Returns the day of the year (in 1\ldots366 range) in the given timezone (local one by default).
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\ldots53 range (52 for non leap years).
The function depends on the week start convention specified by the flags argument but its results for Sunday_First are not well-defined as the ISO definition quoted above applies to the weeks starting on Monday only.
Returns the ordinal number of the week in the month (in 1\ldots5 range).
As GetWeekOfYear , this function supports both conventions for the week start. See the description of these week start conventions.
Returns true is this day is not a holiday in the given country.
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).
Sets the date from the date and time in http://developer.novell.com/ndk/doc/smscomp/index.html?page=/ndk/doc/smscomp/sms_docs/data/hc2vlu5i.html format.
Returns the date and time in http://developer.novell.com/ndk/doc/smscomp/index.html?page=/ndk/doc/smscomp/sms_docs/data/hc2vlu5i.html format.
Returns true if the two dates are strictly identical.
Returns true if this date precedes the given one.
Returns true if this date is later than the given one.
Returns true if this date lies strictly between the two others,
Returns true if IsStrictlyBetween is true or if the date is equal to one of the limit values.
Returns true if the date is the same without comparing the time parts.
Returns true if the time is the same (although dates may differ).
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.
Adds the given time span to this object.
Adds the given date span to this object.
Subtracts the given time span from this object.
Subtracts the given date span from this object.
Subtracts another date from this one and returns the difference between them as wxTimeSpan.
Parses the string 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 "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 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.
This function parses the string date according to the given format . The system 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" , "%x" or "%X" may not be perfect and GNU extensions such as "%z" and "%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 strftime(3) for the syntax of the format string.
The dateDef parameter is used to fill in the fields which could not be determined from the format string. For example, if the format is "%d" (the ay of the month), the month and the year are taken from dateDef . If it is not specified, Today is used as the default date.
Returns NULL if the conversion failed, otherwise return the pointer to the character which stopped the scan.
Parses the string 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.
Returns NULL if the conversion failed, otherwise return the pointer to the character which stopped the scan. This method is currently not implemented, so always returns 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.
Returns NULL if the conversion failed, otherwise return the pointer to the character which stopped the scan.
This functions is like ParseDateTime , but only allows the time to be specified in the input string.
Returns NULL if the conversion failed, otherwise return the pointer to the character which stopped the scan.
This function does the same as the standard ANSI C strftime(3) function. Please see its description for the meaning of format parameter.
It also accepts a few wxWidgets-specific extensions: you can optionally specify the width of the field to follow using printf(3) -like syntax and the format specification %l can be used to get the number of milliseconds.
Identical to calling Format() with "%x" argument (which means `preferred date representation for the current locale').
Identical to calling Format() with "%X" argument (which means `preferred time representation for the current locale').
This function returns the date representation in the ISO 8601 format (YYYY-MM-DD).
This function returns the time representation in the ISO 8601 format (HH:MM:SS).
Adjusts the date so that it will still lie in the same week as before, but its week day will be the given one.
Returns the reference to the modified object itself.
Returns the copy of this object to which SetToWeekDayInSameWeek was applied.
Sets the date so that it will be the first weekday following the current date.
Returns the reference to the modified object itself.
Returns the copy of this object to which SetToNextWeekDay was applied.
Sets the date so that it will be the last weekday before the current date.
Returns the reference to the modified object itself.
Returns the copy of this object to which SetToPrevWeekDay was applied.
Sets the date to the n -th weekday in the given month of the given year (the current month and year are used by default). The parameter 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) -- to the last Sunday in it.
Returns true if the date was modified successfully, false otherwise meaning that the specified date doesn't exist.
Returns the copy of this object to which SetToWeekDay was applied.
The effect of calling this function is the same as of calling SetToWeekDay(-1, weekday, month, year) . The date will be set to the last weekday in the given month and year (the current ones by default).
Always returns true .
Returns the copy of this object to which SetToLastWeekDay was applied.
Set the date to the given weekday in the week number numWeek of the given year . The number should be in range 1\ldots53.
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.
Sets the date to the last day in the specified month (the current one by default).
Returns the reference to the modified object itself.
Returns the copy of this object to which SetToLastMonthDay was applied.
Sets the date to the day number 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\ldots366 for the leap years and 1\ldots365 for the other ones.
Returns the reference to the modified object itself.
Returns the copy of this object to which SetToYearDay was applied.
Returns the JDN corresponding to this date. Beware of rounding errors!
Synonym for GetJulianDayNumber .
Returns the Modified Julian Day Number (MJD) which is, by definition, 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 th noons like JDN. The MJD 0 is Nov 17, 1858.
Synonym for GetModifiedJulianDayNumber .
Return the 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.
Transform the date from the given time zone to the local one. If noDST is true , no DST adjustments will be made.
Returns the date in the local time zone.
Transform the date to the given time zone. If noDST is true , no DST adjustments will be made.
Returns the date in the new time zone.
Modifies the object in place to represent the date in another time zone. If noDST is true , no DST adjustments will be made.
Same as FromTimezone but modifies the object in place.
This is the same as calling ToTimezone with the argument GMT0 .
This is the same as calling MakeTimezone with the argument GMT0 .
Returns true if the DST is applied for this date in the given country.
(TODO: description)
(TODO: description)
TODO convert other information from TeX to XML
Default constructor.
wxDbConnectInf ConnectInf;
....Set values for member variables of ConnectInf here
wxDb sampleDB(ConnectInf.GetHenv());
if (!sampleDB.Open(ConnectInf.GetDsn(), ConnectInf.GetUserID(),
ConnectInf.GetPassword()))
{
// Error opening datasource
}
\wxheading{See also}
This is the constructor for the wxDb class. The wxDb object must be created and opened before any database activity can occur.
Constructor, used to create an ODBC connection to a datasource.
============== ============== ================ ========= ======= TABLE NAME COLUMN NAME DATA TYPE PRECISION LENGTH ============== ============== ================ ========= ======= EMPLOYEE RECID (0008)NUMBER 15 8 EMPLOYEE USER_ID (0012)VARCHAR2 13 13 EMPLOYEE FULL_NAME (0012)VARCHAR2 26 26 EMPLOYEE PASSWORD (0012)VARCHAR2 26 26 EMPLOYEE START_DATE (0011)DATE 19 16
Allows a data "dictionary" of the datasource to be created, dumping pertinent information about all data tables to which the user specified in userID has access.
// Commit any open transactions on the datasource sampleDB.CommitTrans(); // Delete any remaining wxDbTable objects allocated with new delete parts; // Close the wxDb connection when finished with it sampleDB.Close();
At the end of your program, when you have finished all of your database work, you must close the ODBC connection to the datasource. There are actually four steps involved in doing this as illustrated in the example.
Any wxDbTable instances which use this connection must be deleted before closing the database connection.
Closes the database connection.
Transactions begin implicitly as soon as you make a change to the database with an insert/update/delete, or any other direct SQL command that performs one of these operations against the datasource. At any time thereafter, to save the changes to disk permanently, "commit" them by calling this function.
Calling this member function commits ALL open transactions on this ODBC connection. For example, if three different wxDbTable instances used the same connection to the datasource, committing changes made on one of those wxDbTable instances commits any pending transactions on all three wxDbTable instances.
Until a call to wxDb::CommitTrans() is made, no other user or cursor is able to see any changes made to the row(s) that have been inserted/modified/deleted.
\wxheading{Special Note : Cursors }
It is important to understand that different database/ODBC driver combinations handle transactions differently. One thing in particular that you must pay attention to is cursors, in regard to transactions. Cursors are what allow you to scroll through records forward and backward and to manipulate records as you scroll through them. When you issue a query, a cursor is created behind the scenes. The cursor keeps track of the query and keeps track of the current record pointer. After you commit or rollback a transaction, the cursor may be closed automatically. This is database dependent, and with some databases this behavior can be controlled through management functions. This means you would need to requery the datasource before you can perform any additional work using this cursor. This is only necessary however if the datasource closes the cursor after a commit or rollback. Use the wxDbTable::IsCursorClosedOnCommit{wxdbtableiscursorclosedoncommit member function to determine the datasource's transaction behavior. Note, in many situations it is very inefficient to assume the cursor is closed and always requery. This could put a significant, unnecessary load on datasources that leave the cursors open after a transaction.}
Permanently "commits" changes (insertions/deletions/updates) to the database.
// Incomplete code sample
db.CreateView("PARTS_SD1", "PN, PD, QTY",
"SELECT PART_NUM, PART_DESC, QTY_ON_HAND * 1.1 FROM PARTS \
WHERE STORAGE_DEVICE = 1");
// PARTS_SD1 can now be queried just as if it were a data table.
// e.g. SELECT PN, PD, QTY FROM PARTS_SD1
A 'view' is a logical table that derives columns from one or more other tables or views. Once the view is created, it can be queried exactly like any other table in the database.
NOTE: Views are not available with all datasources. Oracle is one example of a datasource which does support views.
Creates a SQL VIEW of one or more tables in a single datasource. Note that this function will only work against databases which support views (currently only Oracle as of November 21 2000).
The return value will be of the enumerated type wxDBMS. This enumerated type contains a list of all the currently tested and supported databases.
Additional databases may work with these classes, but the databases returned by this function have been tested and confirmed to work with these ODBC classes.
Possible values returned by this function can be viewed in the Enumerated types section of wxDb.
There are known issues with conformance to the ODBC standards with several datasources supported by the wxWidgets ODBC classes. Please see the overview for specific details on which datasource have which issues.
\wxheading{Return value}
The return value will indicate which of the supported datasources is currently connected to by this connection. In the event that the datasource is not recognized, a value of 'dbmsUNIDENTIFIED' is returned.
if (SQLExecDirect(hstmt, (UCHAR FAR *) pSqlStmt, SQL_NTS) != SQL_SUCCESS)
// Display all ODBC errors for this stmt
return(db.DispAllErrors(db.henv, db.hdbc, hstmt));
// Drop the table before attempting to create it
sprintf(sqlStmt, "DROP TABLE %s", tableName);
// Execute the drop table statement
if (SQLExecDirect(hstmt,(UCHAR FAR *)sqlStmt,SQL_NTS) != SQL_SUCCESS)
{
// Check for sqlState = S0002, "Table or view not found".
// Ignore this error, bomb out on any other error.
pDb->GetNextError(henv, hdbc, hstmt);
if (wxStrcmp(pDb->sqlState, "S0002"))
{
pDb->DispNextError(); // Displayed error retrieved
pDb->DispAllErrors(henv, hdbc, hstmt); // Display all other errors, if any
pDb->RollbackTrans(); // Rollback the transaction
CloseCursor(); // Close the cursor
return(false); // Return Failure
}
}
This function is normally used internally within the ODBC class library. It could be used programmatically after calling ODBC functions directly. This function works in conjunction with wxDb::GetNextError when errors (or sometimes informational messages) returned from ODBC need to be analyzed rather than simply displaying them as an error. GetNextError() retrieves the next ODBC error from the ODBC error queue. The wxDb member variables "sqlState", "nativeError" and "errorMsg" could then be evaluated. To display the error retrieved, DispNextError() could then be called. The combination of GetNextError() and DispNextError() can be used to iteratively step through the errors returned from ODBC evaluating each one in context and displaying the ones you choose.
If the view does not exist, this function will return true. Note that views are not supported with all datasources.
Drops the data table view named in 'viewName'.
Older form (pre-2.3/2.4 of wxWidgets) of the wxDb::IsFwdOnlyCursors . This method is provided for backward compatibility only. The method wxDb::IsFwdOnlyCursors should be used in place of this method.
The returned catalog will only contain catalog entries for tables to which the user specified in 'userID' has sufficient privileges. If no user is specified (NULL passed in), a catalog pertaining to all tables in the datasource accessible to the connected user (permissions apply) via this connection will be returned.
Returns a wxDbInf pointer that points to the catalog (datasource) name, schema, number of tables accessible to the current user, and a wxDbTableInf pointer to all data pertaining to all tables in the users catalog.
userID == NULL ... UserID is ignored (DEFAULT)
userID == "" ... UserID set equal to 'this->uid'
userID != "" ... UserID set equal to 'userID'
userID == NULL ... UserID is ignored (DEFAULT)
userID == "" ... UserID set equal to 'this->uid'
userID != "" ... UserID set equal to 'userID'
wxChar *tableList[] = {"PARTS", 0};
wxDbColInf *colInf = pDb->GetColumns(tableList);
if (colInf)
{
// Use the column inf
.......
// Destroy the memory
delete [] colInf;
}
userID == NULL ... UserID is ignored (DEFAULT)
userID == "" ... UserID set equal to 'this->uid'
userID != "" ... UserID set equal to 'userID'
SDWORD cb;
ULONG reqQty;
wxString sqlStmt;
sqlStmt = "SELECT SUM(REQUIRED_QTY - PICKED_QTY) FROM ORDER_TABLE WHERE \
PART_RECID = 1450 AND REQUIRED_QTY > PICKED_QTY";
// Perform the query
if (!pDb->ExecSql(sqlStmt.c_str()))
{
// ERROR
return(0);
}
// Request the first row of the result set
if (!pDb->GetNext())
{
// ERROR
return(0);
}
// Read column #1 of the row returned by the call to ::GetNext()
// and return the value in 'reqQty'
if (!pDb->GetData(1, SQL_C_ULONG, &reqQty, 0, &cb))
{
// ERROR
return(0);
}
// Check for a NULL result
if (cb == SQL_NULL_DATA)
return(0);
\wxheading{Remarks}
When requesting multiple columns to be returned from the result set (for example, the SQL query requested 3 columns be returned), the calls to this function must request the columns in ordinal sequence (1,2,3 or 1,3 or 2,3).
Returns the name of the database engine.
Returns the ODBC datasource name.
Returns the ODBC handle to the database connection.
Returns the ODBC environment handle.
Returns the ODBC statement handle associated with this database connection.
if (SQLExecDirect(hstmt, (UCHAR FAR *) pSqlStmt, SQL_NTS) != SQL_SUCCESS)
{
return(db.GetNextError(db.henv, db.hdbc, hstmt));
}
\wxheading{See also}
Returns the password used to establish this connection to the datasource.
Returns the number of wxDbTable() instances currently using this datasource connection.
Returns the user name (uid) used to establish this connection to the datasource.
db.Grant(DB_GRANT_SELECT | DB_GRANT_INSERT, "PARTS", "mary, sue");
Some databases require user names to be specified in all capital letters (i.e. Oracle). This function does not automatically capitalize the user names passed in the comma-separated list. This is the responsibility of the calling routine.
The currently logged in user must have sufficient grantor privileges for this function to be able to successfully grant the indicated privileges.
Use this member function to GRANT privileges to users for accessing tables in the datasource.
DB_GRANT_SELECT = 1
DB_GRANT_INSERT = 2
DB_GRANT_UPDATE = 4
DB_GRANT_DELETE = 8
DB_GRANT_ALL = DB_GRANT_SELECT | DB_GRANT_INSERT |
DB_GRANT_UPDATE | DB_GRANT_DELETE
This function may indicate that the database connection is open, even if the call to wxDb::Open may have failed to fully initialize the connection correctly. The connection to the database is open and can be used via the direct SQL commands, if this function returns true. Other functions which depend on the wxDb::Open to have completed correctly may not function as expected. The return result from wxDb::Open is the only way to know if complete initialization of this wxDb connection was successful or not. See wxDb::Open for more details on partial failures to open a connection instance.
Indicates whether the database connection to the datasource is currently opened.
Calling this function will enter a log message in the error list maintained for the database connection. This log message is free form and can be anything the programmer wants to enter in the error list.
If SQL logging is turned on, the call to this function will also log the text into the SQL log file.
ok = pDb->ModifyColumn("CONTACTS", "ADDRESS2",
DB_, colDefs[j].SzDataObj,
wxT("NOT NULL"));
Cannot be used to modify the precision of a numeric column, therefore 'columnLength' is ignored unless the dataType is DB\_DATA\_TYPE\_VARCHAR.
Some datasources do not allow certain properties of a column to be changed if any rows currently have data stored in that column. Those datasources that do allow columns to be changed with data in the rows many handle truncation and/or expansion in different ways. Please refer to the reference material for the datasource being used for behavioral descriptions.
Used to change certain properties of a column such as the length, or whether a column allows NULLs or not.
wxDb sampleDB(DbConnectInf.GetHenv());
if (!sampleDB.Open("Oracle 7.1 HP/UX", "gtasker", "myPassword"))
{
if (sampleDb.IsOpen())
{
// Connection is open, but the initialization of
// datatypes and parameter settings failed
}
else
{
// Error opening datasource
}
}
After a wxDb instance is created, it must then be opened. When opening a datasource, there must be three pieces of information passed. The data source name, user name (ID) and the password for the user. No database activity on the datasource can be performed until the connection is opened. This is normally done at program startup and the datasource remains open for the duration of the program/module run.
It is possible to have connections to multiple datasources open at the same time to support distributed database connections by having separate instances of wxDb objects that use either the same or different Dsn/Uid/AuthStr settings.
If this function returns a value of false, it does not necessarily mean that the connection to the datasource was not opened. It may mean that some portion of the initialization of the connection failed (such as a datatype not being able to be determined how the datasource represents it). To determine if the connection to the database failed, use the wxDb::IsOpen function after receiving a false result back from this function to determine if the connection was opened or not. If this function returns false, but wxDb::IsOpen returns true, then direct SQL commands may be passed to the database connection and can be successfully executed, but use of the datatypes (such as by a wxDbTable instance) that are normally determined during open will not be possible.
The Dsn , Uid , and AuthStr string pointers that are passed in are copied. NOT the strings themselves, only the pointers. The calling routine must maintain the memory for these three strings for the life of the wxDb instance.
Opens a connection to the datasource, sets certain behaviors of the datasource to confirm to the accepted behaviors (e.g. cursor position maintained on commits), and queries the datasource for its representations of the basic datatypes to determine the form in which the data going to/from columns in the data tables are to be handled.
The second form of this function, which accepts a "wxDb *" as a parameter, can be used to avoid the overhead (execution time, database load, network traffic) which are needed to determine the data types and representations of data that are necessary for cross-datasource support by these classes.
Normally the first form of the wxDb::Open() function will open the connection and then send a series of queries to the datasource asking it for its representation of data types, and all the features it supports. If one connection to the datasource has already been made previously, the information gathered when that connection was created can just be copied to any new connections to the same datasource by passing a pointer to the first connection in as a parameter to the wxDb::Open() function. Note that this new connection created from the first connections information will use the same Dsn/Uid/AuthStr as the first connection used.
Transactions begin implicitly as soon as you make a change to the database. The transaction continues until either a commit or rollback is executed. Calling wxDb::RollbackTrans() will result in ALL changes done using this database connection that have not already been committed to be "undone" back to the last commit/rollback that was successfully executed.
Calling this member function rolls back ALL open (uncommitted) transactions on this ODBC connection, including all wxDbTable instances that use this connection.
Function to "undo" changes made to the database. After an insert/update/delete, the operation may be "undone" by issuing this command any time before a wxDb::CommitTrans is called on the database connection.
Turns on/off debug error messages from the ODBC class library. When this function is passed true, errors are reported to the user/logged automatically in a text or pop-up dialog when an ODBC error occurs. When passed false, errors are silently handled.
When compiled in release mode (FINAL=1), this setting has no affect.
When called with sqlLogON , all commands sent to the datasource engine are logged to the file specified by filename . Logging is done by embedded wxDb::WriteSqlLog calls in the database member functions, or may be manually logged by adding calls to wxDb::WriteSqlLog in your own source code.
When called with sqlLogOFF , the logging file is closed, and any calls to wxDb::WriteSqlLog are ignored.
Returns the column name in a form ready for use in SQL statements. In most cases, the column name is returned verbatim. But some databases (e.g. MS Access, SQL Server, MSDE) allow for spaces in column names, which must be specially quoted. For example, if the datasource allows spaces in the column name, the returned string will have the correct enclosing marks around the name to allow it to be properly included in a SQL statement for the DBMS that is currently connected to with this connection.
Returns the table name in a form ready for use in SQL statements. In most cases, the table name is returned verbatim. But some databases (e.g. MS Access, SQL Server, MSDE) allow for spaces in table names, which must be specially quoted. For example, if the datasource allows spaces in the table name, the returned string will have the correct enclosing marks around the name to allow it to be properly included in a SQL statement for the data source that is currently connected to with this connection.
tableName may refer to a table, view, alias or synonym.
This function does not indicate whether or not the user has privileges to query or perform other functions on the table. Use the wxDb::TablePrivileges to determine if the user has sufficient privileges or not.
Checks the ODBC datasource for the existence of a table. If a userID is specified, then the table must be accessible by that user (user must have at least minimal privileges to the table).
userID == NULL ... UserID is ignored (DEFAULT)
userID == "" ... UserID set equal to 'this->uid'
userID != "" ... UserID set equal to 'userID'
The scope of privilege allowed to the connected user by a given table privilege is datasource dependent.
For example, the privilege UPDATE might allow the connected user to update all columns in a table on one datasource, but only those columns for which the grantor (the user that granted the connected user) has the UPDATE privilege on another datasource.
Looking up a user's privileges to a table can be time consuming depending on the datasource and ODBC driver. This time can be minimized by passing a schema as a parameter. With some datasources/drivers, the difference can be several seconds of time difference.
Checks the ODBC datasource for the existence of a table. If a userID is specified, then the table must be accessible by that user (user must have at least minimal privileges to the table).
SELECT : The connected user is permitted to retrieve data for
one or more columns of the table.
INSERT : The connected user is permitted to insert new rows
containing data for one or more columns into the
table.
UPDATE : The connected user is permitted to update the data in
one or more columns of the table.
DELETE : The connected user is permitted to delete rows of
data from the table.
REFERENCES : Is the connected user permitted to refer to one or
more columns of the table within a constraint (for
example, a unique, referential, or table check
constraint).
userID == NULL ... NOT ALLOWED!
userID == "" ... UserID set equal to 'this->uid'
userID != "" ... UserID set equal to 'userID'
schema == NULL ... Any owner (DEFAULT)
schema == "" ... Owned by 'this->uid'
schema != "" ... Owned by userID specified in 'schema'
Converts an ODBC sqlstate to an internal error code.
Very useful debugging tool that may be turned on/off during run time (see (see wxDb::SetSqlLogging for details on turning logging on/off). The passed in string logMsg will be written to a log file if SQL logging is turned on.
\wxheading{Return value}
If SQL logging is off when a call to WriteSqlLog() is made, or there is a failure to write the log message to the log file, the function returns false without performing the requested log, otherwise true is returned.
(TODO: description)
This class is used to hold information about the columns bound to an instance of a wxDbTable object.
Each instance of this class describes one column in the wxDbTable object. When calling the wxDb constructor , a parameter passed in indicates the number of columns that will be defined for the wxDbTable object. The constructor uses this information to allocate adequate memory for all of the column descriptions in your wxDbTable object. Private member wxDbTable::colDefs is a pointer to this chunk of memory maintained by the wxDbTable class (and can be retrieved using the wxDbTable::GetColDefs function). To access the nth column definition of your wxDbTable object, just reference wxDbColDefs element [n - 1].
Typically, wxDbTable::SetColDefs is used to populate an array of these data structures for the wxDbTable instance.
Currently there are no accessor functions for this class, so all members are public.
wxChar ColName[DB_MAX_COLUMN_NAME_LEN+1]; // Column Name
int DbDataType; - Logical Data Type;
e.g. DB_DATA_TYPE_INTEGER
SWORD SqlCtype; - C data type; e.g. SQL_C_LONG
void *PtrDataObj; - Address of the data object
int SzDataObj; - Size, in bytes, of the data object
bool KeyField; - Is column part of the PRIMARY KEY for the
table? -- Date fields should NOT be
KeyFields
bool Updateable; - Column is updateable?
bool InsertAllowed; - Column included in INSERT statements?
bool DerivedCol; - Column is a derived value?
SDWORD CbValue; - !!!Internal use only!!!
bool Null; - NOT FULLY IMPLEMENTED
Allows NULL values in Inserts and Updates
Beginning support for handling international formatting specifically on dates and floats.
wxString s_Field; // Formated String for Output
wxString s_Format[7]; // Formated Objects - TIMESTAMP has
the biggest (7)
wxString s_Amount[7]; // Formated Objects - amount of
things that can be formatted
int i_Amount[7]; // Formated Objects -
TT MM YYYY HH MM SS m
int i_Nation; // 0 = timestamp
1 = EU
2 = UK
3 = International
4 = US
int i_dbDataType; // conversion of the 'sqlDataType'
to the generic data type used by
these classes
SWORD i_sqlDataType;
The constructor for this class initializes all the values to zero or NULL.
The destructor does nothing at this time.
Only one function is provided with this class currently.
See the database classes overview for an introduction to using the ODBC classes.
Work in progress, and should be inter-related with wxLocale eventually.
Used with the wxDb::GetColumns functions for obtaining all retrievable information about a column's definition.
wxChar catalog[128+1];
wxChar schema[128+1];
wxChar tableName[DB_MAX_TABLE_NAME_LEN+1];
wxChar colName[DB_MAX_COLUMN_NAME_LEN+1];
SWORD sqlDataType;
wxChar typeName[128+1];
SWORD columnSize;
SWORD bufferLength;
short decimalDigits;
short numPrecRadix;
short nullable;
wxChar remarks[254+1];
int dbDataType; // conversion of the 'sqlDataType'
// to the generic data type used by
// these classes
int PkCol; // Primary key column
0 = No
1 = First Key
2 = Second Key, etc...
wxChar PkTableName[DB_MAX_TABLE_NAME_LEN+1];
// Tables that use this PKey as a FKey
int FkCol; // Foreign key column
0 = No
1 = First Key
2 = Second Key, etc...
wxChar FkTableName[DB_MAX_TABLE_NAME_LEN+1];
// Foreign key table name
wxDbColFor *pColFor; // How should this column be formatted
The constructor for this class initializes all the values to zero, "", or NULL.
The destructor for this class takes care of deleting the pColFor member if it is non-NULL.
See the database classes overview for an introduction to using the ODBC classes.
This class is used for holding the data necessary for connecting to the ODBC datasource. That information includes: SQL environment handle, datasource name, user ID, password and default directory path (used with dBase). Other optional fields held in this class are and file type, both for future functions planned to be added for creating/manipulating datasource definitions.
Default constructor.
wxDbConnectInf *DbConnectInf; DbConnectInf = new wxDbConnectInf(0,"MY_DSN", "MY_USER", "MY_PASSWORD"); ....the rest of the program delete DbConnectInf;
\wxheading{See also}
It is strongly recommended that programs use the longer form of the constructor and allow the constructor to create the SQL environment handle automatically, and manage the destruction of the handle.
Constructor which allows initial settings of all the classes member variables.
See the special note below on the henv parameter for forcing this constructor to create a SQL environment handle automatically, rather than needing to pass one in to the function.
Handles the default destruction of the instance of the class. If the long form of the wxDConnectInf was used, then this destructor also takes care of calling wxDConnectInf::FreeHenv to free the SQL environment handle.
This function can be automatically called by the long from of the wxDbConnectInf constructor.
Allocates a SQL environment handle that will be used to interface with an ODBC datasource.
If the SQL environment handle was created using the long form of the wxDbConnectInf constructor, then the flag indicating that the HENV should be destroyed when the classes destructor is called is reset to be false, so that any future handles created using the wxDbConnectInf::AllocHenv function must be manually released with a call to this function.
Frees the SQL environment handle being managed by the instance of this class.
Accessor function to return the password assigned for this class instance that will be used with the user ID.
Synonymous with wxDbConnectInf::GetPassword
Accessor function to return the default directory in which the datasource's data table is stored. This directory is only used for file based datasources like dBase. MS-Access does not require this to be set, as the path is set in the ODBC Administrator for MS-Access.
Accessor function to return the description assigned for this class instance.
NOTE: Description is a FUTURE USE item and is unused currently.
Accessor function to return the datasource name assigned for this class instance.
Accessor function to return the filetype of the ODBC datasource assigned for this class instance.
NOTE: FileType is a FUTURE USE item and is unused currently.
Accessor function to return the SQL environment handle being managed by this class instance.
Accessor function to return the password assigned for this class instance that will be used with the user ID.
Synonymous with wxDbConnectInf::GetAuthStr
Accessor function to return the user ID assigned for this class instance.
Accessor function to return the user ID assigned for this class instance.
Accessor function to assign the password for this class instance that will be used with the user ID.
Synonymous with wxDbConnectInf::SetPassword
Accessor function to assign the default directory in which the datasource's data table is stored. This directory is only used for file based datasources like dBase. MS-Access does not require this to be set, as the path is set in the ODBC Administrator for MS-Access.
Accessor function to assign the description assigned for this class instance.
NOTE: Description is a FUTURE USE item and is unused currently.
Accessor function to assign the datasource name for this class instance.
Accessor function to return the filetype of the ODBC datasource assigned for this class instance.
NOTE: FileType is a FUTURE USE item and is unused currently.
Accessor function to set the SQL environment handle for this class instance.
Accessor function to assign the password for this class instance that will be used with the user ID.
Synonymous with wxDbConnectInf::SetAuthStr
Accessor function to set the user ID for this class instance.
Accessor function to assign the user ID for this class instance.
This class is used to define columns to be shown, names of the columns, order and type of data, when using wxdbGridTableBase to display a Table or query in a wxGrid
See the database grid example in wxDbGridTableBase for an introduction to using the wxDbGrid classes.
Default constructor. See the database grid example in wxDbGridTableBase to see two different ways for adding columns.
See the database grid example in wxDbGridTableBase to see two different ways for adding columns.
Destructor.
As wxDbTable must be defined with to have columns which match those to by a wxDbGridColInfo info structure as this is the structure which informs the grid of how you want to display your wxDbTable . If no datatype conversion or the referenced column number does not exist the the behavior is undefined.
See the example at wxDbGridColInfo::wxDbGridColInfo .
Use this member function for adding columns. See the database grid example in wxDbGridTableBase to see two different ways for adding columns.
It is important to note that this class is merely a specifier to the wxDbGridTableBase constructor. Changes made to this datatype after the wxDbGridTableBase is called will not have any effect.
You can view a database table in a grid using this class.
If you are deriving your own wxDbTable subclass for your table , then you may consider overriding GetCol() and SetCol() to provide calculated fields. This does work but care should be taken when using wxDbGridTableBase in this way.
The constructor and AssignDbTable() call allows you to specify the ownership if the wxDbTable object pointer. If you tell wxGridTableBase to take ownership , it will delete the passed wxDbTable when an new on is assigned or wxGridTableBase's destructor is called. However no checks for aliasing are done so Assign(table,..,true); Assign(table,..,true); is an error. If you need to requery an table object the preferred way is that the client keeps ownership.
// First step, let's define wxDbTable
int numColumns = 2;
wxDbTable *table = new wxDbTable (db, tblName, numColumns);
int int_var;
wxChar string_name[255];
table->SetColDef (0, "column 0", DB_DATA_TYPE_INTEGER, &int_var,
SQL_C_LONG, sizeof(int_var), true);
table->SetColDef (1, "column 1", DB_DATA_TYPE_VARCHAR, &string_name,
SQL_C_LONG, sizeof(string_name), false);
// now let's define columns in the grid
// first way to do it
wxDbGridColInfo *columns;
columns = new wxDbGridColInfo(0, wxGRID_VALUE_LONG, "first column",
new wxDbGridColInfo(1, wxGRID_VALUE_STRING, "second column",
NULL);
// second way to do it
wxDbGridColInfo *columns;
// first column is special
columns = new wxDbGridColInfo(0, wxGRID_VALUE_LONG, "first column", NULL);
// all the rest
columns->AddColInfo (1, wxGRID_VALUE_STRING, "second column");
// second way may be better when columns are not known at compile time
// now, let's open the table and make a Query()
table->Open();
// this step is very important
table->SetRowMode (wxDbTable::WX_ROW_MODE_QUERY);
// in the grid we will see only the rows of the result query
m_dbTable->Query();
wxDbGridTableBase *dbgrid = new wxDbGridTableBase(table, columns, wxUSE_QUERY, true);
delete columns; // not needed anymore
wxGrid *grid = new wxGrid ( ... );
grid->SetTable(dbgrid, true);
grid->Fit();
Constructor.
It ensures that the row data is fetched from the database, and it the wxDbTable local buffer, the row number passed should be the grid row.
If row has changed it forces that row to be written back to the database, however support for detecting whether insert/update is required is currently not in wxDbTable, so this function is currently unsupported.
Resets the grid for using with a new database table, but using the same columns definition. This can be useful when re-querying the database and want to see the changes.
Used in creation of non-primary indexes. Currently there are no member functions for this class.
wxChar ColName[DB_MAX_COLUMN_NAME_LEN+1]
// Name of column
bool Ascending // Is index maintained in
ASCENDING sequence?
There are no constructors/destructors as of this time, and no member functions.
See the database classes overview for an introduction to using the ODBC classes.
Contains information regarding the database connection (datasource name, number of tables, etc). A pointer to a wxDbTableInf is included in this class so a program can create a wxDbTableInf array instance to maintain all information about all tables in the datasource to have all the datasource's information in one memory structure.
Primarily, this class is used internally by the wxWidgets ODBC classes.
wxChar catalog[128+1];
wxChar schema[128+1]; // typically means owner of table(s)
int numTables; // How many tables does this
datasource have
wxDbTableInf *pTableInf; // Equals a new
wxDbTableInf[numTables];
The constructor for this class initializes all the values to zero, "", or NULL.
The destructor for this class takes care of deleting the pTableInf member if it is non-NULL.
See the database classes overview for an introduction to using the ODBC classes.
A wxDbTable instance provides re-usable access to rows of data in a table contained within the associated ODBC datasource
See the database classes overview for an introduction to using the ODBC classes.
Default constructor.
Virtual default destructor.
This member function constructs a SQL DELETE statement. This can be used for debugging purposes if you are having problems executing your SQL statement.
WHERE and FROM clauses specified using wxDbTable::SetWhereClause and wxDbTable::SetFromClause are ignored by this function.
Constructs the full SQL statement that can be used to delete all rows matching the criteria in the pWhereClause.
This member function constructs a SQL SELECT statement. This can be used for debugging purposes if you are having problems executing your SQL statement.
WHERE and FROM clauses specified using wxDbTable::SetWhereClause and wxDbTable::SetFromClause are ignored by this function.
Constructs the full SQL statement that can be used to select all rows matching the criteria in the pWhereClause. This function is called internally in the wxDbTable class whenever the function wxDbTable::Query is called.
NOTE: Only the columns specified in wxDbTable::SetColDefs statements are included in the list of columns returned by the SQL statement created by a call to this function.
This member function allows you to see what the SQL UPDATE statement looks like that the ODBC class library builds. This can be used for debugging purposes if you are having problems executing your SQL statement.
WHERE and FROM clauses specified using wxDbTable::SetWhereClause and wxDbTable::SetFromClause are ignored by this function.
Constructs the full SQL statement that can be used to update all rows matching the criteria in the pWhereClause.
If typeOfUpdate is DB_UPD_KEYFIELDS, then the current values in the bound columns are used to determine which row(s) in the table are to be updated. The exception to this is when a datasource supports ROW IDs (Oracle). The ROW ID column is used for efficiency purposes when available.
NOTE: Only the columns specified in wxDbTable::SetColDefs statements are included in the list of columns updated by the SQL statement created by a call to this function. Any column definitions that were defined as being non-updateable will be excluded from the SQL UPDATE statement created by this function.
This member function allows you to see what the SQL WHERE clause looks like that the ODBC class library builds. This can be used for debugging purposes if you are having problems executing your own SQL statements.
If using 'typeOfWhere' set to DB_WHERE_MATCHING, any bound columns currently containing a NULL value are not included in the WHERE clause's list of columns to use in the comparison.
Constructs the portion of a SQL statement which would follow the word 'WHERE' in a SQL statement to be passed to the datasource. The returned string does NOT include the word 'WHERE'.
Not all datasources support the "FOR UPDATE" clause, so you must use this member function to determine if the datasource currently connected to supports this behavior or not before trying to select using "FOR UPDATE".
If the wxDbTable instance was created with the parameter wxDB_QUERY_ONLY, then this function will return false. For all known databases which do not support the FOR UPDATE clause, this function will return false also.
Use this function to determine if the datasource supports SELECT ... FOR UPDATE. When the keywords "FOR UPDATE" are included as part of your SQL SELECT statement, all records retrieved (not just queried, but actually retrieved using wxDbTable::GetNext , etc) from the result set are locked.
// Incomplete code sample
wxDbTable parts;
.....
if (parts.CanUpdateByROWID())
{
// Note that the ROWID column must always be the last column selected
sqlStmt = "SELECT PART_NUM, PART_DESC, ROWID" FROM PARTS";
}
else
sqlStmt = "SELECT PART_NUM, PART_DESC FROM PARTS";
The decision to include the ROWID in your SQL SELECT statement must be deferred until runtime since it depends on whether you are connected to an Oracle datasource or not.
CURRENTLY ONLY POSSIBLE IF USING ORACLE.
--- CURRENTLY DISABLED FOR *ALL* DATASOURCES --- NOV 1 2000 - gt
Every Oracle table has a hidden column named ROWID. This is a pointer to the physical location of the record in the datasource and allows for very fast updates and deletes. The key is to retrieve this ROWID during your query so it is available during an update or delete operation.
Use of the ROWID feature is always handled by the class library except in the case of wxDbTable::QueryBySqlStmt . Since you are passing in the SQL SELECT statement, it is up to you to include the ROWID column in your query. If you do not, the application will still work, but may not be as optimized. The ROWID is always the last column in the column list in your SQL SELECT statement. The ROWID is not a column in the normal sense and should not be considered part of the column definitions for the wxDbTable object.
Same as wxDbTable::ClearMemberVars except that this function clears only the specified column of its values, and optionally sets the column to be a NULL column.
This is useful before calling functions such as wxDbTable::QueryMatching or wxDbTable::DeleteMatching since these functions build their WHERE clauses from non-zero columns. To call either wxDbTable::QueryMatching or wxDbTable::DeleteMatching use this sequence:
1) ClearMemberVars() 2) Assign columns values you wish to match on 3) Call wxDbTable::QueryMatching() or wxDbTable::DeleteMatching()
Initializes all bound columns of the wxDbTable instance to zero. In the case of a string, zero is copied to the first byte of the string.
Typically handled internally by the ODBC class library, but may be used by the programmer if desired.
DO NOT CLOSE THE wxDB_DEFAULT_CURSOR!
Closes the specified cursor associated with the wxDbTable object.
USERS TABLE
FIRST_NAME LAST_NAME
----------- ----------
John Doe
Richard Smith
Michael Jones
John Carpenter
// Incomplete code sample
wxDbTable users;
.....
users.SetWhereClause("");
// This Count() will return 4, as there are four users listed above
// that match the query parameters
totalNumberOfUsers = users.Count();
// This Count() will return 3, as there are only 3 unique first names
// in the table above - John, Richard, Michael.
totalNumberOfUniqueFirstNames = users.Count("DISTINCT FIRST_NAME");
This function can be called before or after an actual query to obtain the count of records in the result set. Count() uses its own cursor, so result set cursor positioning is not affected by calls to Count().
WHERE and FROM clauses specified using wxDbTable::SetWhereClause and wxDbTable::SetFromClause ARE used by this function.
Returns the number of records which would be in the result set using the current query parameters specified in the WHERE and FROM clauses.
// Create a secondary index on the PARTS table
wxDbIdxDef IndexDef[2]; // 2 columns make up the index
wxStrcpy(IndexDef[0].ColName, "PART_DESC"); // Column 1
IndexDef[0].Ascending = true;
wxStrcpy(IndexDef[1].ColName, "SERIAL_NO"); // Column 2
IndexDef[1].Ascending = false;
// Create a name for the index based on the table's name
wxString indexName;
indexName.Printf("
parts->CreateIndex(indexName, true, 2, IndexDef);
The first parameter, index name, must be unique and should be given a meaningful name. Common practice is to include the table name as a prefix in the index name (e.g. For table PARTS, you might want to call your index PARTS_Index1). This will allow you to easily view all of the indexes defined for a given table grouped together alphabetically.
The second parameter indicates if the index is unique or not. Uniqueness is enforced at the RDBMS level preventing rows which would have duplicate indexes from being inserted into the table when violating a unique index's uniqueness.
In the third parameter, specify how many columns are in your index. This number must match the number of columns defined in the 'pIndexDefs' parameter.
The fourth parameter specifies which columns make up the index using the wxDbIdxDef structure. For each column in the index, you must specify two things, the column name and the sort order (ascending / descending). See the example below to see how to build and pass in the wxDbIdxDef structure.
The fifth parameter is provided to handle the differences in datasources as to whether they will automatically overwrite existing indexes with the same name or not. Some datasources require that the existing index must be dropped first, so this is the default behavior.
Some datasources (MySQL, and possibly others) require columns which are to be part of an index to be defined as NOT NULL. When this function is called, if a column is not defined to be NOT NULL, a call to this function will modify the column definition to change any columns included in the index to be NOT NULL. In this situation, if a NULL value already exists in one of the columns that is being modified, creation of the index will fail.
PostGres is unable to handle index definitions which specify whether the index is ascending or descending, and defaults to the system default when the index is created.
It is not necessary to call wxDb::CommitTrans after executing this function.
This member function allows you to create secondary (non primary) indexes on your tables. You first create your table, normally specifying a primary index, and then create any secondary indexes on the table. Indexes in relational model are not required. You do not need indexes to look up records in a table or to join two tables together. In the relational model, indexes, if available, provide a quicker means to look up data in a table. To enjoy the performance benefits of indexes, the indexes must be defined on the appropriate columns and your SQL code must be written in such a way as to take advantage of those indexes.
This function creates the table and primary index (if any) in the table space associated with the connected datasource. The owner of these objects will be the user id that was given when wxDb::Open was called. The objects will be created in the default schema/table space for that user.
In your derived wxDbTable object constructor, the columns and primary index of the table are described through the wxDbColDef structure. wxDbTable::CreateTable uses this information to create the table and to add the primary index. See wxDbTable ctor and wxDbColDef description for additional information on describing the columns of the table.
It is not necessary to call wxDb::CommitTrans after executing this function.
Creates a table based on the definitions previously defined for this wxDbTable instance.
Accessor function that returns the wxDb private member variable DB_STATUS for the database connection used by this instance of wxDbTable.
Use wxDbTable::GetFirst , wxDbTable::GetLast , wxDbTable::GetNext or wxDbTable::GetPrev to position the cursor to a valid record. Once positioned on a record, call this function to delete the row from the table.
A wxDb::CommitTrans or wxDb::RollbackTrans must be called after use of this function to commit or rollback the deletion.
NOTE: Most datasources have a limited size "rollback" segment. This means that it is only possible to insert/update/delete a finite number of rows without performing a wxDb::CommitTrans or wxDb::RollbackTrans . Size of the rollback segment varies from database to database, and is user configurable in most databases. Therefore it is usually best to try to perform a commit or rollback at relatively small intervals when processing a larger number of actions that insert/update/delete rows in a table.
Deletes the row from the table indicated by the current cursor.
For default cursors associated with the instance of wxDbTable, it is not necessary to specifically delete the cursors. This is automatically done in the wxDbTable destructor.
NOTE: If the cursor could not be deleted for some reason, an error is logged indicating the reason. Even if the cursor could not be deleted, the HSTMT that is passed in is deleted, and the pointer is set to NULL.
DO NOT DELETE THE wxDB_DEFAULT_CURSOR!
Allows a program to delete a cursor.
// Incomplete code sample to delete all users with a first name
// of "JOHN"
users.ClearMemberVars();
wxStrcpy(users.FirstName,"JOHN");
users.DeleteMatching();
To delete all users with a first name of "JOHN", do the following:
The WHERE clause is built by the ODBC class library based on all non-NULL columns. This allows deletion of records by matching on any column(s) in your wxDbTable instance, without having to write the SQL WHERE clause.
A wxDb::CommitTrans or wxDb::RollbackTrans must be called after use of this function to commit or rollback the deletion.
NOTE: Row(s) should be locked before deleting them to make sure they are not already in use. This can be achieved by calling wxDbTable::QueryMatching , and then retrieving the records, locking each as you go (assuming FOR UPDATE is allowed on the datasource). After the row(s) have been successfully locked, call this function.
NOTE: Most datasources have a limited "rollback" segment. This means that it is only possible to insert/update/delete a finite number of rows without performing a wxDb::CommitTrans or wxDb::RollbackTrans . Size of the rollback segment varies from database to database, and is user configurable in most databases. Therefore it is usually best to try to perform a commit or rollback at relatively small intervals when processing a larger number of actions that insert/update/delete rows in a table.
This member function allows you to delete records from your wxDbTable object by specifying the data in the columns to match on.
// Delete parts 1 thru 10 from containers 'X', 'Y' and 'Z' that
// are magenta in color
parts.DeleteWhere("(PART_NUMBER BETWEEN 1 AND 10) AND \
CONTAINER IN ('X', 'Y', 'Z') AND \
UPPER(COLOR) = 'MAGENTA'");
This is the most powerful form of the wxDbTable delete functions. This function gives access to the full power of SQL. This function can be used to delete records by passing a valid SQL WHERE clause. Sophisticated deletions can be performed based on multiple criteria using the full functionality of the SQL language.
A wxDb::CommitTrans must be called after use of this function to commit the deletions.
Note: This function is limited to deleting records from the table associated with this wxDbTable object only. Deletions on joined tables is not possible.
NOTE: Most datasources have a limited size "rollback" segment. This means that it is only possible to insert/update/delete a finite number of rows without performing a wxDb::CommitTrans or wxDb::RollbackTrans . Size of the rollback segment varies from database to database, and is user configurable in most databases. Therefore it is usually best to try to perform a commit or rollback at relatively small intervals when processing a larger number of actions that insert/update/delete rows in a table.
WHERE and FROM clauses specified using wxDbTable::SetWhereClause and wxDbTable::SetFromClause are ignored by this function.
Deletes all rows from the table which match the criteria specified in the WHERE clause that is passed in.
If the index specified in the 'IndexName' parameter does not exist, an error will be logged, and the function will return a result of false.
It is not necessary to call wxDb::CommitTrans after executing this function.
Allows an index on the associated table to be dropped (deleted) if the user login has sufficient privileges to do so.
This function returns true if the table does not exist, but only for supported databases (see wxDb::Dbms ). If a datasource is not specifically supported, and this function is called, the function will return false.
Most datasources/ODBC drivers will delete any indexes associated with the table automatically, and others may not. Check the documentation for your database to determine the behavior.
It is not necessary to call wxDb::CommitTrans after executing this function.
Deletes the associated table if the user has sufficient privileges to do so.
Accessor function for the private class member wxDbTable::from. Can be used as a synonym for wxDbTable::GetFromClause (the first form of this function) or wxDbTable::SetFromClause (the second form of this function).
These column definitions must not be manually redefined after they have been set.
Accessor function that returns a pointer to the array of column definitions that are bound to the columns that this wxDbTable instance is associated with.
To determine the number of elements pointed to by the returned wxDbColDef pointer, use the wxDbTable::GetNumberOfColumns function.
Accessor function for the private member variable pDb which is a pointer to the datasource connection that this wxDbTable instance uses.
This function can only be used if the datasource connection used by the wxDbTable instance was created with FwdOnlyCursors set to false. If the connection does not allow backward scrolling cursors, this function will return false, and the data contained in the bound columns will be undefined.
Retrieves the FIRST row in the record set as defined by the current query. Before retrieving records, a query must be performed using wxDbTable::Query , wxDbTable::QueryOnKeyFields , wxDbTable::QueryMatching or wxDbTable::QueryBySqlStmt .
Accessor function that returns the current FROM setting assigned with the wxDbTable::SetFromClause .
This function can only be used if the datasource connection used by the wxDbTable instance was created with FwdOnlyCursors set to false. If the connection does not allow backward scrolling cursors, this function will return false, and the data contained in the bound columns will be undefined.
Retrieves the LAST row in the record set as defined by the current query. Before retrieving records, a query must be performed using wxDbTable::Query , wxDbTable::QueryOnKeyFields , wxDbTable::QueryMatching or wxDbTable::QueryBySqlStmt .
This new cursor must be closed using wxDbTable::DeleteCursor by the calling program before the wxDbTable instance is deleted, or both memory and resource leaks will occur.
This function will create a new cursor that can be used to access the table being referenced by this wxDbTable instance, or to execute direct SQL commands on without affecting the cursors that are already defined and possibly positioned.
This function works with both forward and backward scrolling cursors.
Retrieves the NEXT row in the record set after the current cursor position as defined by the current query. Before retrieving records, a query must be performed using wxDbTable::Query , wxDbTable::QueryOnKeyFields , wxDbTable::QueryMatching or wxDbTable::QueryBySqlStmt .
Accessor function that returns the number of columns that are statically bound for access by the wxDbTable instance.
Accessor function that returns the current ORDER BY setting assigned with the wxDbTable::SetOrderByClause .
This function can only be used if the datasource connection used by the wxDbTable instance was created with FwdOnlyCursors set to false. If the connection does not allow backward scrolling cursors, this function will return false, and the data contained in the bound columns will be undefined.
Retrieves the PREVIOUS row in the record set before the current cursor position as defined by the current query. Before retrieving records, a query must be performed using wxDbTable::Query , wxDbTable::QueryOnKeyFields , wxDbTable::QueryMatching or wxDbTable::QueryBySqlStmt .
Accessor function that returns the name of the table/view that was indicated as being the table/view to query against when this wxDbTable instance was created.
This function is not being used within the ODBC class library and may be a candidate for removal if no use is found for it.
Row number with some datasources/ODBC drivers is the position in the result set, while in others it may be a physical position in the database. Check your database documentation to find out which behavior is supported.
Returns the ODBC row number for performing positioned updates and deletes.
Accessor function that returns the name of the table that was indicated as being the table that this wxDbTable instance was associated with.
Currently only applicable to dBase and MS-Access datasources.
Accessor function that returns the path to the data table that was indicated during creation of this wxDbTable instance.
Accessor function that returns the current WHERE setting assigned with the wxDbTable::SetWhereClause
// Incomplete code snippet
wxStrcpy(parts->PartName, "10");
wxStrcpy(parts->PartDesc, "Part #10");
parts->Qty = 1000;
RETCODE retcode = parts->Insert();
switch(retcode)
{
case DB_SUCCESS:
parts->GetDb()->CommitTrans();
return(true);
case DB_ERR_INTEGRITY_CONSTRAINT_VIOL:
// Current data would result in a duplicate key
// on one or more indexes that do not allow duplicates
parts->GetDb()->RollbackTrans();
return(false);
default:
// Insert failed for some unexpected reason
parts->GetDb()->RollbackTrans();
return(false);
}
A wxDb::CommitTrans or wxDb::RollbackTrans must be called after use of this function to commit or rollback the insertion.
DB_SUCCESS Record inserted successfully (value = 1)
DB_FAILURE Insert failed (value = 0)
DB_ERR_INTEGRITY_CONSTRAINT_VIOL
The insert failed due to an integrity
constraint violation (duplicate non-unique
index entry) is attempted.
Inserts a new record into the table being referenced by this wxDbTable instance. The values in the member variables of the wxDbTable instance are inserted into the columns of the new row in the database.
NULL column support is currently not fully implemented as of wxWidgets 2.4.
const
Used primarily in the ODBC class library to determine if a column value is set to "NULL". Works for all data types supported by the ODBC class library.
If more than one wxDbTable instance used the same database connection, all cursors which use the database connection are closed on the commit if this function indicates true.
Accessor function to return information collected during the opening of the datasource connection that is used by this wxDbTable instance. The result returned by this function indicates whether an implicit closing of the cursor is done after a commit on the database connection.
Accessor function that returns a value indicating if this wxDbTable instance was created to allow only queries to be performed on the bound columns. If this function returns true, then no actions may be performed using this wxDbTable instance that would modify (insert/delete/update) the table's data.
If the function returns a false value due to the table not existing, a log entry is recorded for the datasource connection indicating the problem that was detected when checking for table existence. Note that it is usually best for the calling routine to check for the existence of the table and for sufficient user privileges to access the table in the mode (wxDB_QUERY_ONLY or !wxDB_QUERY_ONLY) before trying to open the table for the best possible explanation as to why a table cannot be opened.
Checking the user's privileges on a table can be quite time consuming during the open phase. With most applications, the programmer already knows that the user has sufficient privileges to access the table, so this check is normally not required.
For best performance, open the table, and then use the wxDb::TablePrivileges function to check the users privileges. Passing a schema to the TablePrivileges() function can significantly speed up the privileges checks.
Every wxDbTable instance must be opened before it can be used. This function checks for the existence of the requested table, binds columns, creates required cursors, (insert/select and update if connection is not wxDB_QUERY_ONLY) and constructs the insert statement that is to be used for inserting data as a new row in the datasource.
NOTE: To retrieve data into an opened table, the of the table must be bound to the variables in the program via call(s) to wxDbTable::SetColDefs before calling Open().
See the database classes overview for an introduction to using the ODBC classes.
Accessor function for the private class member wxDbTable::orderBy. Can be used as a synonym for wxDbTable::GetOrderByClause (the first form of this function) or wxDbTable::SetOrderByClause (the second form of this function).
// Incomplete code sample
parts->SetWhereClause("DESCRIPTION = 'FOOD'");
parts->SetOrderByClause("EXPIRATION_DATE");
parts->SetFromClause("");
// Query the records based on the where, orderBy and from clauses
// specified above
parts->Query();
// Display all records queried
while(parts->GetNext())
dispPart(parts); // user defined function
This function queries records from the datasource based on the three wxDbTable members: "where", "orderBy", and "from". Use wxDbTable::SetWhereClause to filter on records to be retrieved (e.g. All users with a first name of "JOHN"). Use wxDbTable::SetOrderByClause to change the sequence in which records are returned in the result set from the datasource (e.g. Ordered by LAST_NAME). Use wxDbTable::SetFromClause to allow outer joining of the base table (the one being associated with this instance of wxDbTable) with other tables which share a related field.
After each of these clauses are set/cleared, call wxDbTable::Query() to fetch the result set from the datasource.
This scheme has an advantage if you have to requery your record set frequently in that you only have to set your WHERE, ORDER BY, and FROM clauses once. Then to refresh the record set, simply call wxDbTable::Query() as frequently as needed.
Note that repeated calls to wxDbTable::Query() may tax the database server and make your application sluggish if done too frequently or unnecessarily.
The base table name is automatically prepended to the base column names in the event that the FROM clause has been set (is non-null) using wxDbTable::SetFromClause .
The cursor for the result set is positioned before the first record in the result set after the query. To retrieve the first record, call either wxDbTable::GetFirst (only if backward scrolling cursors are available) or wxDbTable::GetNext . Typically, no data from the result set is returned to the client driver until a request such as wxDbTable::GetNext is performed, so network traffic and database load are not overwhelmed transmitting data until the data is actually requested by the client. This behavior is solely dependent on the ODBC driver though, so refer to the ODBC driver's reference material for information on its behaviors.
Values in the bound columns' memory variables are undefined after executing a call to this function and remain that way until a row in the result set is requested to be returned.
The wxDbTable::Query() function is defined as "virtual" so that it may be overridden for application specific purposes.
Be sure to set the wxDbTable's "where", "orderBy", and "from" member variables to "" if they are not to be used in the query. Otherwise, the results returned may have unexpected results (or no results) due to improper or incorrect query parameters constructed from the uninitialized clauses.
// Incomplete code samples
wxString sqlStmt;
sqlStmt = "SELECT * FROM PARTS WHERE STORAGE_DEVICE = 'SD98' \
AND CONTAINER = 12";
// Query the records using the SQL SELECT statement above
parts->QueryBySqlStmt(sqlStmt);
// Display all records queried
while(parts->GetNext())
dispPart(&parts);
Example SQL statements
----------------------
// Table Join returning 3 columns
SELECT PART_NUM, part_desc, sd_name
from parts, storage_devices
where parts.storage_device_id =
storage_devices.storage_device_id
// Aggregate function returning total number of
// parts in container 99
SELECT count(*) from PARTS where container = 99
// Order by clause; ROWID, scalar function
SELECT PART_NUM, substring(part_desc, 1, 10), qty_on_hand + 1, ROWID
from parts
where warehouse = 10
order by PART_NUM desc // descending order
// Subquery
SELECT * from parts
where container in (select container
from storage_devices
where device_id = 12)
This is the most powerful form of the query functions available. This member function allows a programmer to write their own custom SQL SELECT statement for requesting data from the datasource. This gives the programmer access to the full power of SQL for performing operations such as scalar functions, aggregate functions, table joins, and sub-queries, as well as datasource specific function calls.
The requirements of the SELECT statement are the following:
Even though data can be selected from multiple tables (joins) in your select statement, only the base table associated with this wxDbTable object is automatically updated through the ODBC class library. Data from multiple tables can be selected for display purposes however. Include columns in the wxDbTable object and mark them as non-updateable (See wxDbColDef for details). This way columns can be selected and displayed from other tables, but only the base table will be updated automatically when performed through the wxDbTable::Update function after using this type of query. To update tables other than the base table, use the wxDbTable::Update function passing a SQL statement.
After this function has been called, the cursor is positioned before the first record in the record set. To retrieve the first record, call either wxDbTable::GetFirst or wxDbTable::GetNext .
Performs a query against the datasource by accepting and passing verbatim the SQL SELECT statement passed to the function.
// Incomplete code sample
parts->ClearMemberVars(); // Set all columns to zero
wxStrcpy(parts->PartNumber,"32"); // Set columns to query on
parts->OnHold = true;
parts->QueryMatching(); // Query
// Display all records queried
while(parts->GetNext())
dispPart(parts); // Some application defined function
The SQL WHERE clause is built by the ODBC class library based on all non-zero/non-NULL columns in your wxDbTable object. Matches can be on one, many or all of the wxDbTable's columns. The base table name is prepended to the column names in the event that the wxDbTable's FROM clause is non-null.
This function cannot be used to perform queries which will check for columns that are 0 or NULL, as the automatically constructed WHERE clause only will contain comparisons on column member variables that are non-zero/non-NULL.
The primary difference between this function and wxDbTable::QueryOnKeyFields is that this function can query on any column(s) in the wxDbTable object. Note however that this may not always be very efficient. Searching on non-indexed columns will always require a full table scan.
The cursor is positioned before the first record in the record set after the query is performed. To retrieve the first record, the program must call either wxDbTable::GetFirst or wxDbTable::GetNext .
WHERE and FROM clauses specified using wxDbTable::SetWhereClause and wxDbTable::SetFromClause are ignored by this function.
QueryMatching allows querying of records from the table associated with the wxDbTable object by matching "columns" to values.
For example: To query the datasource for the row with a PART_NUMBER column value of "32", clear all column variables of the wxDbTable object, set the PartNumber variable that is bound to the PART_NUMBER column in the wxDbTable object to "32", and then call wxDbTable::QueryMatching().
// Incomplete code sample
wxStrcpy(parts->PartNumber, "32");
parts->QueryOnKeyFields();
// Display all records queried
while(parts->GetNext())
dispPart(parts); // Some application defined function
The cursor is positioned before the first record in the record set after the query is performed. To retrieve the first record, the program must call either wxDbTable::GetFirst or wxDbTable::GetNext .
WHERE and FROM clauses specified using wxDbTable::SetWhereClause and wxDbTable::SetFromClause are ignored by this function.
QueryOnKeyFields provides an easy mechanism to query records in the table associated with the wxDbTable object by the primary index column(s). Simply assign the primary index column(s) values and then call this member function to retrieve the record.
Note that since primary indexes are always unique, this function implicitly always returns a single record from the database. The base table name is prepended to the column names in the event that the wxDbTable's FROM clause is non-null.
This routine is only guaranteed to work if the table has a unique primary index defined for it. Otherwise, more than one record may be fetched and there is no guarantee that the correct record will be refreshed. The table's columns are refreshed to reflect the current data in the database.
This function re-reads the bound columns into the memory variables, setting them to the current values stored on the disk.
The cursor position and result set are unaffected by calls to this function. (The one exception is in the case where the record to be refreshed has been deleted by some other user or transaction since it was originally retrieved as part of the result set. For most datasources, the default behavior in this situation is to return the value that was originally queried for the result set, even though it has been deleted from the database. But this is datasource dependent, and should be tested before relying on this behavior.)
// Long way not using this function
wxStrcpy(colDefs[0].ColName, "PART_NUM");
colDefs[0].DbDataType = DB_DATA_TYPE_VARCHAR;
colDefs[0].PtrDataObj = PartNumber;
colDefs[0].SqlCtype = SQL_C_WXCHAR;
colDefs[0].SzDataObj = PART_NUMBER_LEN;
colDefs[0].KeyField = true;
colDefs[0].Updateable = false;
colDefs[0].InsertAllowed= true;
colDefs[0].DerivedCol = false;
// Shortcut using this function
SetColDefs(0, "PART_NUM", DB_DATA_TYPE_VARCHAR, PartNumber,
SQL_C_WXCHAR, PART_NUMBER_LEN, true, false, true, false);
If pData is to hold a string of characters, be sure to include enough space for the NULL terminator in pData and in the byte count of size .
Using the first form of this function, if the column definition is not able to be created, a value of false is returned. If the specified index of the column exceeds the number of columns defined in the wxDbTable instance, an assert is thrown and logged (in debug builds) and a false is returned.
A failure to create the column definition in the second form results in a value of NULL being returned.
Both forms of this function provide a shortcut for defining the columns in your wxDbTable object. Use this function in any derived wxDbTable constructor when describing the column/columns in the wxDbTable object.
The second form of this function is primarily used when the wxDb::GetColumns function was used to query the datasource for the column definitions, so that the column definitions are already stored in wxDbColInf form. One example use of using wxDb::GetColumns then using this function is if a data table existed in one datasource, and the table's column definitions were to be copied over to another datasource or table.
DB_DATA_TYPE_VARCHAR : strings
DB_DATA_TYPE_INTEGER : non-floating point numbers
DB_DATA_TYPE_FLOAT : floating point numbers
DB_DATA_TYPE_DATE : dates
SQL_C_CHAR // string - deprecated: use SQL_C_WXCHAR
SQL_C_WXCHAR // string - Used transparently in unicode or non-unicode builds
SQL_C_LONG
SQL_C_ULONG
SQL_C_SHORT
SQL_C_USHORT
SQL_C_FLOAT
SQL_C_DOUBLE
SQL_C_NUMERIC
SQL_C_TIMESTAMP
SQL_C_BOOLEAN // defined in db.h
SQL_C_ENUM // defined in db.h
When swapping between cursors, the member variables of the wxDbTable object are automatically refreshed with the column values of the row that the current cursor is positioned at (if any). If the cursor is not positioned, then the data in member variables is undefined.
The only way to return back to the cursor that was in use before this function was called is to programmatically determine the current cursor's HSTMT BEFORE calling this function using wxDbTable::GetCursor and saving a pointer to that cursor.
...
// Base table is the "LOCATION" table, and it is being
// outer joined to the "PART" table via the field "PART_NUMBER"
// that can be related between the two tables.
location->SetWhereClause("LOCATION.PART_NUMBER = PART.PART_NUMBER")
location->SetFromClause("PART");
...
\wxheading{See also}
Used by the wxDbTable::Query and wxDbTable::Count member functions to allow outer joining of records from multiple tables.
Do not include the keyword "FROM" when setting the FROM clause.
If using the FROM clause when performing a query, be certain to include in the corresponding WHERE clause a comparison of a column from either the base table or one of the other joined tables to each other joined table to ensure the datasource knows on which column values the tables should be joined on.
Accessor function for setting the private class member wxDbTable::from that indicates what other tables should be outer joined with the wxDbTable's base table for access to the columns in those other tables.
Synonym to this function is one form of wxDbTable::From
No database updates are done by this function. It only operates on the member variables in memory. Use and insert or update function to store this value to disk.
Both forms of this function allow a member variable representing a column in the table associated with this wxDbTable object to be set to NULL.
The first form allows the column to be set by the index into the column definitions used to create the wxDbTable instance, while the second allows the actual column name to be specified.
...
parts->SetOrderByClause("PART_DESCRIP, QUANTITY");
...
...
location->SetOrderByClause("LOCATION.POSITION, PART.PART_NUMBER);
...
\wxheading{See also}
Do not include the keywords "ORDER BY" when setting the ORDER BY clause.
Accessor function for setting the private class member wxDbTable::orderBy which determines sequence/ordering of the rows returned in the result set of a query.
A synonym to this function is one form of the function wxDbTable::OrderBy
Neither Oracle or Access support this function as of yet. Other databases should be evaluated for support before depending on this function working correctly.
Allows a time period to be set as the timeout period for queries.
...
// Simple where clause
parts->SetWhereClause("PART_NUMBER = '32'");
...
// Any comparison operators
parts->SetWhereClause("PART_DESCRIP LIKE 'HAMMER
...
// Multiple comparisons, including a function call
parts->Where("QTY > 0 AND {fn UCASE(PART_DESCRIP)} LIKE '
...
// Using parameters and multiple logical combinations
parts->Where("((QTY > 10) OR (ON_ORDER > 0)) AND ON_HOLD = 0");
...
// This query uses an outer join (requiring a FROM clause also)
// that joins the PART and LOCATION table on he common field
// PART_NUMBER.
parts->Where("PART.ON_HOLD = 0 AND \
PART.PART_NUMBER = LOCATION.PART_NUMBER AND \
LOCATION.PART_NUMBER > 0");
\wxheading{See also}
Do not include the keywords "WHERE" when setting the WHERE clause.
Accessor function for setting the private class member wxDbTable::where that determines which rows are returned in the result set by the datasource.
A synonym to this function is one form of the function wxDbTable::Where
wxString sqlStmt;
sqlStmt = "update PART set QTY = 0 where PART_NUMBER = '32'";
A wxDb::CommitTrans or wxDb::RollbackTrans must be called after use of this function to commit or rollback the update.
The first form of this function will update the row that the current cursor is currently positioned at with the values in the memory variables that are bound to the columns. The actual SQL statement to perform the update is automatically created by the ODBC class, and then executed.
The second form of the function allows full access through SQL statements for updating records in the database. Write any valid SQL UPDATE statement and submit it to this function for execution. Sophisticated updates can be performed using the full power of the SQL dialect. The full SQL statement must have the exact syntax required by the driver/datasource for performing the update. This usually is in the form of:
UPDATE tablename SET col1=X, col2=Y, ... where ...
Care should be used when updating columns that are part of indexes with this function so as not to violate an unique key constraints.
A wxDb::CommitTrans or wxDb::RollbackTrans must be called after use of this function to commit or rollback the update(s).
Performs updates to the base table of the wxDbTable object, updating only the rows which match the criteria specified in the pWhereClause .
All columns that are bound to member variables for this wxDbTable instance that were defined with the "updateable" parameter set to true will be updated with the information currently held in the memory variable.
Accessor function for the private class member wxDbTable::where. Can be used as a synonym for wxDbTable::GetWhereClause (the first form of this function) to return the current where clause or wxDbTable::SetWhereClause (the second form of this function) to set the where clause for this table instance.
Synonym for wxDbTable::GetNext
Synonym for wxDbTable::GetPrev
tableName[0] = 0;
tableType[0] = 0;
tableRemarks[0] = 0;
numCols = 0;
pColInf = NULL;
Currently only used by wxDb::GetCatalog internally and wxDbInf class, but may be used in future releases for user functions. Contains information describing the table (Name, type, etc). A pointer to a wxDbColInf array instance is included so a program can create a wxDbColInf array instance (using wxDb::GetColumns ) to maintain all information about the columns of a table in one memory structure.
Eventually, accessor functions will be added for this class
See the database classes overview for an introduction to using the ODBC classes.
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
Checks the memory blocks for errors, starting from the currently set checkpoint.
Performs a memory dump from the currently set checkpoint, writing to the current debug stream. Calls the Dump member function for each wxObject derived instance.
Returns true if the memory allocator checks all previous memory blocks for errors. By default, this is false since it slows down execution considerably.
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.
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.
Returns the output stream associated with the debug context.
This is obsolete, replaced by wxLog functionality.
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.
Prints a list of the classes declared in this application, giving derivation and whether instances of this class can be dynamically created.
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.
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.
Tells the memory allocator to check all previous memory blocks for errors. By default, this is false since it slows down execution considerably.
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.
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).
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.
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.
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 sample .
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.
wxDebugReport report;
wxDebugReportPreviewStd preview;
report.AddCurrentContext(); // could also use AddAll()
report.AddCurrentDump(); // to do both at once
if ( preview.Show(report) )
report.Process();
This enum is used for functions that report either the current state or the state during the last (fatal) exception:
enum wxDebugReport::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.
The destructor normally destroys the temporary directory created in the constructor with all the files it contains. Call Reset() to prevent this from happening.
Adds all available information to the report. Currently this includes a text (XML) file describing the process context and, under Win32, a minidump file.
Add an XML file containing the current or exception context and the stack trace.
The same as AddContext(Context_Current) .
The same as AddDump(Context_Current) .
Adds the minidump file to the debug report.
Minidumps are only available under recent Win32 versions ( dbghlp32.dll can be installed under older systems to make minidumps available).
The same as AddContext(Context_Exception) .
The same as AddDump(Context_Exception) .
Add another file to the report. If 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
description only exists to be displayed to the user in the report summary shown by wxDebugReportPreview .
\wxheading{See also }
This is a convenient wrapper around AddFile . It creates the file with the given name and writes text to it, then adds the file to the report. The filename shouldn't contain the path.
Returns true if file could be added successfully, false if an IO error occurred.
This function may be overridden to add arbitrary custom context to the XML context file created by AddContext . By default, it does nothing.
This function may be overridden to modify the contents of the exception tag in the XML context file.
This function may be overridden to modify the contents of the modules tag in the XML context file.
This function may be overridden to modify the contents of the system tag in the XML context file.
Returns the name of the temporary directory used for the files in this report.
This method should be used to construct the full name of the files which you wish to add to the report using AddFile .
Retrieves the name (relative to GetDirectory() ) and the description of the file with the given index. If n is greater than or equal to the number of filse, false is returned.
Gets the current number files in this report.
Gets the name used as a base name for various files, by default wxApp::GetAppName() is used.
Returns true if the object was successfully initialized. If this method returns false the report can't be used.
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.
Removes the file from report: this is used by wxDebugReportPreview to allow the user to remove files potentially containing private information from the report.
Resets the directory name we use. The object can't be used any more after this as it becomes uninitialized and invalid.
wxDebugReportCompress is a wxDebugReport which compresses all the files in this debug report into a single .ZIP file in its Process() function.
Default constructor does nothing special.
Returns the full path of the compressed file (empty if creation failed).
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 .
Trivial default constructor.
dtor is trivial as well but should be virtual for a base class
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.
wxDebugReportPreviewStd is a standard debug report preview window. It displays a GUIdialog allowing the user to examine the contents of a debug report, remove files from and add notes to it.
Trivial default constructor.
Show the dialog, see wxDebugReportPreview::Show() for more information.
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.
This class will upload the compressed file created by its base class to an HTML multipart/form-data form at the specified address. The url is the upload page address, input is the name of the "type=file" control on the form used for the file name and action is the value of the form action field. The report is uploaded using curl program which should be available, the curl parameter may be used to specify the full path to it.
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() .
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.
wxDebugStreamBuf streamBuf; ostream stream(&streamBuf); stream << "Hello world!" << endl;
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.
The default constructor does the same thing as the other one except that it uses the generic renderer instead of the user-specified rendererNative .
In any case, this sets up the delegate renderer object to follow all calls to the specified real renderer.
Note that this object does not take ownership of (i.e. won't delete) rendererNative .
This class also provides all the virtual methods of wxRendererNative , please refer to that class documentation for the details.
This is the event class for the dialup events sent by wxDialUpManager .
Constructor is only used by wxDialUpManager .
Is this a CONNECTED or DISCONNECTED event? In other words, does it notify about transition from offline to online state or vice versa?
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)?
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 wxDialUpManager::Create() and you can't create the objects of this class directly.
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.
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
Destructor.
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).
Dial the given ISP, use username and password to authenticate.
The parameters are only used under Windows currently, for Unix you should use SetConnectCommand to customize this functions behaviour.
If no 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 async parameter is false , the function waits until the end of dialing and returns true upon successful completion.
If 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).
Returns true if (async) dialing is in progress.
Cancel dialing the number initiated with Dial with async parameter equal to true .
Note that this won't result in DISCONNECTED event being sent.
Hang up the currently active dial up connection.
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.
NB: this functions 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.
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.
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.
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.
Returns false if couldn't set up automatic check for online status.
Disable automatic check for connection status change - notice that the wxEVT_DIALUP_XXX events won't be sent any more neither.
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 www.yahoo.com:80 .
This method is for Unix only.
Sets the commands to start up the network and to hang up again.
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 usually used to allow the user to make some choice or to answer a question.
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, although this code snippet:
void AskUser()
{
MyAskDialog *dlg = new MyAskDialog(...);
if ( dlg->ShowModal() == wxID_OK )
...
//else: dialog was cancelled or some another button pressed
dlg->Destroy();
}
works, you can also achieve the same result by using a simpler code fragment below:
void AskUser()
{
MyAskDialog dlg(...);
if ( dlg.ShowModal() == wxID_OK )
...
// no need to call Destroy() here
}
An application can define a wxCloseEvent handler for the dialog to respond to system close events.
Default constructor.
Constructor.
Destructor. Deletes any child windows before deleting the physical window.
Centres the dialog box on the display.
Used for two-step dialog box construction. See wxDialog::wxDialog for details.
Creates a sizer with standard buttons. flags is a bit list of the following flags: wxOK, wxCANCEL, wxYES, wxNO, wxHELP, wxNO_DEFAULT.
The sizer lays out the buttons in a manner appropriate to the platform.
This function simply calls CreateStdDialogButtonSizer .
Creates a wxStdDialogButtonSizer with standard buttons. flags is a bit list of the following flags: wxOK, wxCANCEL, wxYES, wxNO, wxHELP, wxNO_DEFAULT.
The sizer lays out the buttons in a manner appropriate to the platform.
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.
Ends a modal dialog, passing a value to be returned from the wxDialog::ShowModal invocation.
Gets the identifier to be used when the user presses an OK button in a PocketPC titlebar.
Gets the identifier of the button to map presses of \textsc{ESC button to.
Returns the title of the dialog box.
On PocketPC, a dialog is automatically provided with an empty toolbar. GetToolBar 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.
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) .
Iconizes or restores the dialog. Windows only.
Always returns false under Windows since dialogs cannot be iconized.
Returns true if the dialog box is iconized. Windows only.
Returns true if the dialog box is modal, false otherwise.
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.
The default handler for wxEVT_SYS_COLOUR_CHANGED.
Sets the identifier to be used when the user presses an OK button in a PocketPC titlebar. By default, this is wxID_OK.
Sets the identifier to be used when the user presses \textsc{ESC button in the dialog. By default, this is wxID_ANY meaning that the first suitable button is used: if there a wxID_CANCEL button, it is activated, otherwise wxID_OK button is activated if present. Another possible special value for id is wxID_NONE meaning that \textsc{ESC presses should be ignored. If another value is given, it is interpreted as the id of the button to map the escape key to.
Sets the icon for this dialog.
See also wxIcon .
Sets the icons for this dialog.
See also wxIconBundle .
NB: This function is deprecated and 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 (wxDialog::Show blocks control until the dialog is hidden) or modeless (control returns immediately).
Sets the title of the dialog box.
The preferred way of dismissing a modal dialog is to use wxDialog::EndModal .
Hides or shows the dialog.
Shows a modal dialog. Program flow does not return until the dialog has been dismissed with wxDialog::EndModal .
wxDir is a portable equivalent of Unix {open/read/close}dir functions which allow enumerating of the files in a directory. wxDir allows 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:
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("
cont = dir.GetNext(&filename);
}
These flags define what kind of filename is included in the list of files enumerated by GetFirst/GetNext.
enum
{
wxDIR_FILES = 0x0001, // include files
wxDIR_DIRS = 0x0002, // include directories
wxDIR_HIDDEN = 0x0004, // include hidden files
wxDIR_DOTDOT = 0x0008, // include '.' and '..'
// by default, enumerate everything except '.' and '..'
wxDIR_DEFAULT = wxDIR_FILES | wxDIR_DIRS | wxDIR_HIDDEN
}
Default constructor, use Open() afterwards.
Opens the directory for enumeration, use IsOpened() to test for errors.
Destructor cleans up the associated resources. It is not virtual and so this class is not meant to be used polymorphically.
Test for existence of a directory with the given name
The function appends the names of all the files under directory dirname to the array files (note that its old content is preserved). Only files matching the filespec are taken, with empty spec matching all the files.
The 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 also Traverse
Start enumerating all files matching filespec (or all files if it is empty) and flags, return true on success.
Returns the name of the directory itself. The returned string does not have the trailing path separator (slash or backslash).
Continue enumerating files satisfying the criteria specified by the last call to GetFirst .
Returns true if the directory contains any files matching the given filespec . If filespec is empty, look for any files at all. In any case, even hidden files are taken into account.
Returns true if the directory contains any subdirectories (if a non empty filespec is given, only check for directories matching it). The hidden subdirectories are taken into account as well.
Returns true if the directory was successfully opened by a previous call to Open .
Open the directory for enumerating, returns true on success or false if an error occurred.
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 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, sink.OnDir() is called and 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 (size_t)-1 on error.
See also GetAllFiles
This class represents the directory chooser dialog.
Constructor. Use wxDirDialog::ShowModal to show the dialog.
Destructor.
Returns the default or user-selected path.
Returns the message that will be displayed on the dialog.
Returns the dialog style.
Sets the message that will be displayed on the dialog.
Sets the default path.
Sets the dialog style. This is currently unused.
Shows the dialog, returning wxID_OK if the user pressed OK, and wxID_CANCEL otherwise.
wxDirTraverser is an abstract interface which must be implemented by objects passed to Traverse function.
Example of use (this works almost like GetAllFiles ):
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);
The elements of wxDirTraverseResult are the possible return values of the callback functions:
enum wxDirTraverseResult
{
wxDIR_IGNORE = -1, // ignore this directory but continue with others
wxDIR_STOP, // stop traversing
wxDIR_CONTINUE // continue into this directory
};
This function is called for each directory. It may return wxSIR_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.
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.
This function is called for each directory which we failed to open for enumerating. It may return wxSIR_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 .
Determines the sizes and locations of displays connected to the system.
Constructor, setting up a wxDisplay instance with the specified display.
Destructor.
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 DMUseScreenPrefs, an undocumented function that changed the video mode to the system default by using the system's 'scrn' resource.
Returns the number of connected displays.
Returns the current video mode that this display is in.
Returns the bit depth of the display whose index was passed to the constructor.
Returns the index of the display on which the given point lies. Returns -1 if the point is not on any connected display.
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 -1 if the window is not on any connected display.
Currently wxMSW only.
Returns the bounding rectangle of the display whose index was passed to the constructor.
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).
Returns the display's name. A name is not available on all platforms.
Returns true if the display is the primary display. The primary display is the one whose index is 0.
Deprecation note: This class is deprecated since version 2.4 and is not compiled in by default in version 2.6 and will be removed in 2.8. Please use wxDynamicLibrary instead.
wxDllLoader is a class providing an interface similar to Unix's dlopen() . It is used by the wxLibrary framework and manages the actual loading of shared libraries and the resolving of symbols in them. There are no instances of this class, it simply serves as a namespace for its static member functions.
Please note that class wxDynamicLibrary provides alternative, friendlier interface to wxDllLoader.
The terms DLL and shared library/object will both be used in the documentation to refer to the same thing: a .dll file under Windows or .so or .sl one under Unix.
Example of using this class to dynamically load the strlen() function:
#if defined(__WXMSW__)
static const wxChar *LIB_NAME = _T("kernel32");
static const wxChar *FUNC_NAME = _T("lstrlenA");
#elif defined(__UNIX__)
static const wxChar *LIB_NAME = _T("/lib/libc-2.0.7.so");
static const wxChar *FUNC_NAME = _T("strlen");
#endif
wxDllType dllHandle = wxDllLoader::LoadLibrary(LIB_NAME);
if ( !dllHandle )
{
... error ...
}
else
{
typedef int (*strlenType)(char *);
strlenType pfnStrlen = (strlenType)wxDllLoader::GetSymbol(dllHandle, FUNC_NAME);
if ( !pfnStrlen )
{
... error ...
}
else
{
if ( pfnStrlen("foo") != 3 )
{
... error ...
}
else
{
... ok! ...
}
}
wxDllLoader::UnloadLibrary(dllHandle);
}
This header defines a platform-dependent wxDllType typedef which stores a handle to a loaded DLLs on the given platform.
Returns the string containing the usual extension for shared libraries for the given systems (including the leading dot if not empty).
For example, this function will return ".dll" under Windows or (usually) ".so" under Unix.
This function returns a valid handle for the main program itself. Notice that the NULL return value is valid for some systems (i.e. doesn't mean that the function failed).
NB: This function is Unix specific. It will always fail under Windows or OS/2.
This function resolves a symbol in a loaded DLL, such as a variable or function name.
Returned value will be NULL if the symbol was not found in the DLL or if an error occurred.
This function loads a shared library into memory, with libname being the name of the library: it may be either the full name including path and (platform-dependent) extension, just the basename (no path and no extension) or a basename with extension. In the last two cases, the library will be searched in all standard locations.
Returns a handle to the loaded DLL. Use success parameter to test if it is valid. If the handle is valid, the library must be unloaded later with UnloadLibrary .
This function unloads the shared library. The handle dllhandle must have been returned by LoadLibrary previously.
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.
See the example application in samples/docview .
Constructor.
Destructor.
Returns the document associated with this frame.
Returns the view associated with this frame.
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.
Closes and deletes the current view and document.
Sets the document for this frame.
Sets the view for this frame.
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.
See the example application in samples/docview .
Constructor.
Destructor.
Returns the document associated with this frame.
Returns the view associated with this frame.
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.
Closes and deletes the current view and document.
Sets the document for this frame.
Sets the view for this frame.
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 wxDocTemplates classes.
See the example application in samples/docview .
Constructor.
Destructor.
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.
void wxDocParentFrame::OnCloseWindow(wxCloseEvent& event)
{
if (m_docManager->Clear(!event.CanVeto()))
{
this->Destroy();
}
else
event.Veto();
}
The wxDocManager class is part of the document/view framework supported by wxWidgets, and cooperates with the wxView , wxDocument and wxDocTemplate classes.
Constructor. Create a document manager instance dynamically near the start of your application before doing any document or view operations.
flags is currently unused.
If 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.
Destructor.
Sets the current view.
Adds the document to the list of documents.
Adds a file to the file history list, if we have a pointer to an appropriate file menu.
Adds the template to the document manager's template list.
Closes all currently opened documents.
Creates a new document in a manner determined by the flags parameter, which can be:
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.
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.
Removes the template from the list of templates.
Appends the files in the history list, to all menus managed by the file history object.
Appends the files in the history list, to the given menu only.
Loads the file history from a config object.
Removes the given menu from the list of menus managed by the file history object.
Saves the file history into a config object. This must be called explicitly by the application.
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 that you can add multiple menus using this function, to be managed by the file history object.
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.
Returns the document associated with the currently active view (if any).
Returns the currently active view
Returns a reference to the list of documents.
Returns a pointer to file history.
Returns the directory last selected by the user when opening a file. Initially empty.
Returns the number of documents that can be open simultaneously.
Returns the number of files currently stored in the file history.
Returns a reference to the list of associated templates.
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 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.
Copies a suitable default name into buf . This is implemented by appending an integer counter to the string unnamed and incrementing the counter.
A hook to allow a derived class to create a different type of file history. Called from Initialize .
Closes and deletes the currently active document.
Closes and deletes all the currently opened documents.
Creates a document from a list of templates (if more than one template).
Creates a new document and reads in the selected file.
Reverts the current document by calling wxDocument::Revert for the current document.
Saves the current document by calling wxDocument::Save for the current document.
Calls wxDocument::SaveAs for the current document.
Removes the document from the list of documents.
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 wxDocManager::CreateDocument.
Returns a document template by asking the user (if there is more than one template). This function is used in wxDocManager::CreateDocument.
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 wxDocManager::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.
Sets the directory to be displayed to the user when opening a file. Initially this is empty.
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.
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 wxDocTemplates classes.
See the example application in samples/docview .
Constructor.
Destructor.
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.
void wxDocParentFrame::OnCloseWindow(wxCloseEvent& event)
{
if (m_docManager->Clear(!event.CanVeto()))
{
this->Destroy();
}
else
event.Veto();
}
The wxDocTemplate class is used to model the relationship between a document class and a view class.
Constructor. Create instances dynamically near the start of your application after creating a wxDocManager instance, and before doing any document or view operations.
manager is the document manager object which manages this template.
descr is a short description of what the template is for. This string will be displayed in the file filter list of Windows file selectors.
filter is an appropriate file filter such as *.txt .
dir is the default directory to use for file selectors.
ext is the default file extension (such as txt).
docTypeName is a name that should be unique for a given type of document, used for gathering a list of views relevant to a particular document.
viewTypeName is a name that should be unique for a given view.
docClassInfo is 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.
viewClassInfo is 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.
flags is a bit list of the following:
Destructor.
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 wxDocTemplate::InitDocument which in turns calls wxDocument::OnCreate.
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.
Returns the default file extension for the document data, as passed to the document template constructor.
Returns the text description of this template, as passed to the document template constructor.
Returns the default directory, as passed to the document template constructor.
Returns a pointer to the document manager instance for which this template was created.
Returns the document type name, as passed to the document template constructor.
Returns the file filter, as passed to the document template constructor.
Returns the flags, as passed to the document template constructor.
Returns the view type name, as passed to the document template constructor.
Initialises the document, calling wxDocument::OnCreate. This is called from wxDocTemplate::CreateDocument.
Returns true if the document template can be shown in user dialogs, false otherwise.
Sets the default file extension.
Sets the template description.
Sets the default directory.
Sets the pointer to the document manager instance for which this template was created. Should not be called by the application.
Sets the file filter.
Sets the internal document template flags (see the constructor description for more details).
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.
Constructor. Define your own default constructor to initialize application-specific data.
Destructor. Removes itself from the document manager.
If the view is not already in the list of views, adds the view and calls OnChangedViewList.
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.
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 wxDocument::OnChangedViewList, whose default implemention is to save and delete the document if no views exist.
Returns a pointer to the command processor associated with this document.
See wxCommandProcessor .
Gets a pointer to the template that created the document.
Gets a pointer to the associated document manager.
Gets the document type name for this document. See the comment for documentTypeName .
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.
Gets the filename associated with this document, or "" if none is associated.
A convenience function to get the first view for a document, because in many cases a document will only have a single view.
See also GetViews
Copies a suitable document name into the supplied name buffer. The default function uses the title, or if there is no title, uses the filename; or if no filename, the string unnamed .
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.
Returns the list whose elements are the views on the document.
See also GetFirstView
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 (for example if using wxTextWindow to view and edit the document).
See also Modify .
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 that only one of these forms exists, depending on how wxWidgets was configured.
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 (for example if using wxTextWindow to view and edit the document).
See also IsModified .
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).
The default implementation calls DeleteContents (an empty implementation) sets the modified flag to false. Override this to supply additional behaviour when the document is closed with Close.
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.
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 .
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.
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.
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.
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.
Removes the view from the document's list of views, and calls OnChangedViewList.
Saves the document by calling OnSaveDocument if there is an associated filename, or SaveAs if there is no filename.
Prompts the user for a file to save to, and then calls OnSaveDocument.
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 that only one of these forms exists, depending on how wxWidgets was configured.
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 .
Sets the document type name for this document. See the comment for documentTypeName .
Sets the pointer to the template that created the document. Should only be called by the framework.
Sets the filename for this document. Usually called by the framework.
If notifyViews is true, wxView::OnChangeFilename is called for all views.
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.
Updates all views. If sender is non-NULL, does not update this view.
hint represents optional information to allow a view to optimize its update.
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 do achieve smooth dragging. On other platforms, wxGenericDragImage is used. Applications may also prefer to use wxGenericDragImage on Windows, too.
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 wxDragImage::DoDrawImage and wxDragImage::GetImageRect .
Please see samples/dragimag for an example.
Default constructor.
Constructs a drag image from a bitmap and optional cursor.
Constructs a drag image from an icon and optional cursor.
Constructs a drag image from a text string and optional cursor.
Constructs a drag image from the text in the given tree control item, and optional cursor.
Constructs a drag image from the text in the given tree control item, and optional cursor.
Constructs a drag image an optional cursor. This constructor is only available for wxGenericDragImage, and can be used when the application supplies wxDragImage::DoDrawImage and wxDragImage::GetImageRect .
Start dragging the image, in a window or full screen.
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 wxDragImage::Show and wxDragImage::Move to show the image on the screen.
Call wxDragImage::EndDrag when the drag has finished.
Note that this call automatically calls CaptureMouse.
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 wxDragImage::GetImageRect .
Call this when the drag has finished.
Note that this call automatically calls ReleaseMouse.
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 wxDragImage::DoDrawImage ) to provide a virtual drawing capability.
Hides the image. You may wish to call this before updating the window contents (perhaps highlighting an item). Then call wxDragImage::Move and wxDragImage::Show .
Call this to move the image to a new position. The image will only be shown if wxDragImage::Show has been called previously (for example at the start of the drag).
pt is 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.
Shows the image. Call this at least once when dragging.
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 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.
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 here . It uses the older, Windows message-based approach of dropping files.
Constructor.
Returns an array of filenames.
Returns the number of files dropped.
Returns the position at which the files were dropped.
Returns an array of filenames.
This class represents a source for a drag and drop operation.
See Drag and drop overview and wxDataObject overview for more information.
wxDragResult is defined as follows:
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)
};
The constructors for wxDataObject.
If you use the constructor without data parameter you must call SetData later.
Note that the exact type of 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.
win is the window which initiates the drag and drop operation.
Sets the data wxDataObject associated with the drop source. This will not delete any previously associated data.
Do it (call this in response to a mouse button press, for example). This starts the drag-and-drop operation which will terminate when the user releases the mouse.
.
Returns the wxDataObject object that has been assigned previously.
Overridable: you may give some custom UI feedback during the drag and drop operation in this function. It is called on each mouse move, so your implementation must not be too slow.
Set the icon to use for a certain drag result.
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 , possibly many times OnDragOver , OnDrop and finally OnData .
See Drag and drop overview and wxDataObject overview for more information.
wxDragResult is defined as follows:
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)
};
Constructor. data is the data to be associated with the drop target.
Destructor. Deletes the associated data object, if any.
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.
Called after OnDrop returns true. By default this will usually GetData and will return the suggested default value def .
Called when the user drops a data object on the target. Return false to veto the operation.
Called when the mouse enters the drop target. By default, this calls OnDragOver .
Called when the mouse is being dragged over the drop target. By default, this calls functions return the suggested return value def .
Called when the mouse leaves the drop target.
Sets the data wxDataObject associated with the drop target and deletes any previously associated data object.
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.
Constructor. Second form calls Load .
Returns the platform-specific full name for the library called name . E.g. it adds a ".dll" extension under Windows and "lib" prefix and ".so" , ".sl" or maybe ".dylib" extension under Unix.
The possible values for cat are:
| wxDL_LIBRARY | normal library |
| wxDL_MODULE | a loadable module or plugin |
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.
The possible values for cat are:
| wxDL_PLUGIN_GUI | plugin which uses GUI classes (default) |
| wxDL_PLUGIN_BASE | plugin which only uses wxBase |
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 .
Returns pointer to symbol name in the library or NULL if the library contains no such symbol.
This function is available only under Windows as it is only useful when dynamically loading symbols from standard Windows DLLs. Such functions have either 'A' (in ANSI build) or '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 appende automatically depending on the current build. Otherwise, this method is identical to GetSymbol .
Return a valid handle for the main program itself or NULL if symbols from the main program can't be loaded on this platform.
Returns true if the symbol with the given 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.
\newsince{2.5.4}
Returns true if the library was successfully loaded, false otherwise.
This static method returns an array containing the details of all modules loaded into the address space of the current project, the array elements are object of wxDynamicLibraryDetails class. 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.
Loads DLL with the given name into memory. The flags argument can be a combination of the following bits:
| wxDL_LAZY | equivalent of RTLD_LAZY under Unix, ignored elsewhere |
| wxDL_NOW | equivalent of RTLD_NOW under Unix, ignored elsewhere |
| wxDL_GLOBAL | equivalent of RTLD_GLOBAL under Unix, ignored elsewhere |
| wxDL_VERBATIM | don't try to append the appropriate extension to the library name (this is done by default). |
| wxDL_DEFAULT | default flags, same as wxDL_NOW currently |
Returns true if the library was successfully loaded, false otherwise.
Unloads the library from memory. wxDynamicLibrary object automatically calls this method from its destructor if it had been successfully loaded.
The second version 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.
This class is used for the objects returned by 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.
Returns the base name of this module, e.g. kernel32.dll or libc-2.3.2.so .
Returns the full path of this module if available, e.g. c:\backslashwindows\backslashsystem32\backslashkernel32.dll or /lib/libc-2.3.2.so .
Retrieves the load address and the size of this module.
Returns the version of this module, e.g. 5.2.3790.0 or 2.3.2 . The returned string is empty if the version information is not available.
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 limited subset of encodings in supported by wxEncodingConverter: wxFONTENCODING_ISO8859_1..15 , wxFONTENCODING_CP1250..1257 and wxFONTENCODING_KOI8 .
Constructor.
Initialize 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 input_enc encoding and will output string in 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. Method affects behaviour of Convert() in case input character cannot be converted because it does not exist in output encoding:
| 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) |
| 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 true if (any text in) multibyte encoding encIn can be converted to another one ( encOut ) losslessly.
Do not call this method with 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).
Convert input string according to settings passed to Init and writes the result to output .
Convert input string according to settings passed to Init in-place, i.e. write the result to the same memory area.
All of the versions above return true if the conversion was lossless and false if at least one of the characters couldn't be converted and was replaced with '?' in the output. Note that if wxCONVERT_SUBSTITUTE was passed to Init , substitution is considered lossless operation.
Convert wxString and return new wxString object.
Return equivalents for given font that are used under given platform. Supported platforms:
wxPLATFORM_CURRENT means the platform this binary was compiled for.
Examples:
current platform enc returned value
----------------------------------------------
unix CP1250 {ISO8859_2}
unix ISO8859_2 {ISO8859_2}
windows ISO8859_2 {CP1250}
unix CP1252 {ISO8859_1,ISO8859_15}
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 NOT check for presence of fonts in system. It only tells you what are most suitable encodings. (It usually returns only one encoding.)
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 enc is in the array, it is the very first item in it.
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.
Use the device context returned by GetDC to draw on, don't create a wxPaintDC in the event handler.
Constructor.
Returns the device context associated with the erase event to draw on.
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 Event handling overview .
Constructor. Should not need to be used directly by an application.
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:
wxEvent *Clone(void) const { return new MyEvent(*this); }
Returns the object (usually a window) associated with the event, if any.
Returns the identifier of the given event type, such as wxEVENT_TYPE_BUTTON_COMMAND.
Returns the identifier associated with this event, such as a button command id.
Returns true if the event handler should be skipped, false otherwise.
Gets the timestamp for the event.
Returns true if the event is or is derived from wxCommandEvent else it returns false. Note: Exists only for optimization purposes.
Sets the propagation level to the given value (for example returned from an earlier call to StopPropagation ).
Sets the originating object.
Sets the event type.
Sets the identifier associated with this event, such as a button command id.
Sets the timestamp for the event.
Test if this event should be propagated or not, i.e. if the propagation level is currently greater than 0.
Called by an event handler, it controls whether additional event handlers bound to this event will be called after the current event handler returns. Skip(false) (the default behavior) will prevent additional event handlers from being called and control will be returned to the sender of the event immediately after the current handler has finished. Skip(true) will cause the event processing system to continue searching for a handler function for this event.
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.
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.
Constructor.
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.
The difference between sending an event (using the ProcessEvent method) and posting it is that in the first case the event is processed before the function returns, while in the second case, the function returns immediately and the event will be processed sometime later (usually during the next event loop iteration).
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.
This is also the method to call for inter-thread communication---it will post events safely between different threads which means that this method is thread-safe by using critical sections where needed. In a multi-threaded program, you often need to inform the main GUI thread about the status of other working threads and such notification should be done using this method.
This method automatically wakes up idle handling if the underlying window system is currently idle and thus would not send any idle events. (Waking up idle handling is done calling ::wxWakeUpIdle .)
This function posts an event to be processed later.
frame->Connect( wxID_EXIT,
wxEVT_COMMAND_MENU_SELECTED,
wxCommandEventHandler(MyFrame::OnQuit) );
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 'event' or the old 'dynamic' sample for usage.
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 wxEvtHandler::Connect method. There is no way to disconnect functions connected using the (static) event tables.
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.
Gets user-supplied client data.
Get a pointer to the user-supplied client data object.
Returns true if the event handler is enabled, false otherwise.
Gets the pointer to the next handler in the chain.
Gets the pointer to the previous handler in the chain.
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:
Processes an event, searching event tables and calling zero or more suitable event handler function(s).
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:
If a suitable function is called but calls wxEvent::Skip , this function will fail, and searching will continue.
Searches the event table, executing an event handler function if an appropriate one is found.
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.
Sets user-supplied client data.
Set the client data object. Any previous object will be deleted.
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.
Enables or disables the event handler.
Sets the pointer to the next handler.
Sets the pointer to the previous handler.
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 FILE * handle used by standard C IO library (also known as stdio ).
| wxFromStart | Count offset from the start of the file |
| wxFromCurrent | Count offset from the current position of the file pointer |
| wxFromEnd | Count offset from the end of the file (backwards) |
Default constructor.
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.
Opens a file with the given file pointer, which has already been opened.
Destructor will close the file.
NB: it is not virtual so you should not derive from wxFFile!
Attaches an existing file pointer to the wxFFile object.
The descriptor should be already opened and it will be closed by wxFFile object.
Closes the file and returns true on success.
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().
Returns the file pointer associated with the file.
Returns true if the an attempt has been made to read 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.
Flushes the file and returns true on success.
Returns the type of the file. Possible return values are:
enum wxFileKind
{
wxFILE_KIND_UNKNOWN,
wxFILE_KIND_DISK, // a file supporting seeking to arbitrary offsets
wxFILE_KIND_TERMINAL, // a tty
wxFILE_KIND_PIPE // a pipe
};
Returns true if the file is opened. Most of the methods of this class may only be used for an opened file.
Returns the length of the file.
Opens the file, returning true if successful.
Reads the specified number of bytes into a buffer, returning the actual number read.
Reads the entire contents of the file into a string.
Seeks to the specified position and returns true on success.
Moves the file pointer to the specified number of bytes before the end of the file and returns true on success.
Returns the current position.
Writes the specified number of bytes from a buffer.
Writes the contents of the string to the file
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 wxFile and wxFFile differ in one aspect, namely when to report that the end of the file has been reached. This is documented in wxFile::Eof and wxFFile::Eof and the behaviour of the stream classes reflects this difference, i.e. wxFileInputStream will report wxSTREAM_EOF after having read the last byte whereas wxFFileInputStream will report wxSTREAM_EOF after trying to read past the last byte. Related to EOF behavior, note that SeekI() can seek beyond the end of the stream (file) and will thus not return wxInvalidOffset for that.
Opens the specified file using its filename name using the specified mode.
Initializes a file stream in read-only mode using the file I/O object file .
Initializes a file stream in read-only mode using the specified file pointer fp .
Destructor.
Returns true if the stream is initialized and ready.
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 wxFile and wxFFile differ in one aspect, namely when to report that the end of the file has been reached. This is documented in wxFile::Eof and wxFFile::Eof and the behaviour of the stream classes reflects this difference, i.e. wxFileInputStream will report wxSTREAM_EOF after having read the last byte whereas wxFFileInputStream will report wxSTREAM_EOF after trying to read past the last byte. Related to EOF behavior, note that SeekO() can seek beyond the end of the stream (file) and will thus not return wxInvalidOffset for that.
Opens the file with the given filename name in the specified mode.
Initializes a file stream in write-only mode using the file I/O object file .
Initializes a file stream in write-only mode using the file descriptor fp .
Destructor.
Returns true if the stream is initialized and ready.
Initializes a new file stream in read-write mode using the specified iofilename name.
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 create the stream but only returns the pointer to it. In other words after 10 calls to GetStream() you will obtain ten identical pointers.
class wxMyFSFile : public wxFSFile
{
private:
void *m_Mem;
public:
wxMyFSFile(.....)
~wxMyFSFile() {free(m_Mem);}
// of course dtor is virtual ;-)
};
Constructor. You probably won't use it. See Notes for details.
If you are not sure of the meaning of these params, see the description of the GetXXXX() functions.
Returns anchor (if present). The term of anchor can be easily explained using few examples:
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! */
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.
Returns full location of the file, including path and protocol. Examples :
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
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.
Returns time when this file was modified.
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).
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 commands which doesn't involve file transfer (i.e. directory oriented commands) you just need to call a corresponding member function or use the generic 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.
using wxFTP for file downloading:
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;
}
To upload a file you would do (assuming the connection to the server was opened successfully):
wxOutputStream *out = ftp.GetOutputStream("filename");
if ( out )
{
out->Write(...); // your data
delete out;
}
wxFTP defines constants corresponding to the two supported transfer modes:
enum TransferMode
{
ASCII,
BINARY
};
Default constructor.
Destructor will close the connection if connected.
Aborts the download currently in process, returns true if ok, false if an error occurred.
Send the specified command to the FTP server. ret specifies the expected result.
Send the specified command to the FTP server and return the first character of the return code.
Returns the last command result, i.e. the full server reply for the last command.
Change the current FTP working directory. Returns true if successful.
Create the specified directory in the current FTP working directory. Returns true if successful.
Remove the specified directory from the current FTP working directory. Returns true if successful.
Returns the current FTP working directory.
Rename the specified src element to dst . Returns true if successful.
Delete the file specified by path . Returns true if successful.
Sets the transfer mode to ASCII. It will be used for the next transfer.
Sets the transfer mode to binary (IMAGE). It will be used for the next transfer.
If 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.
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.
This parameter can be included in a URL if you want to use the URL manager. For example, you can use: "ftp://a_user:a_password@a.host:service/a_directory/a_file" to specify a user and a password.
Sets the user name to be sent to the FTP server to be allowed to log in.
This parameter can be included in a URL if you want to use the URL manager. For example, you can use: "ftp://a_user:a_password@a.host:service/a_directory/a_file" to specify a user and a password.
Sets the password to be sent to the FTP server to be allowed to log in.
Returns true if the given remote file exists, false otherwise.
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.
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 wildcard string. If 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:
-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
But on Windows system, it will look like this:
winamp~1 exe 520196 02-25-1999 19:28 winamp204.exe
1 file(s) 520 196 bytes
Return value: true if the file list was successfully retrieved, false otherwise.
This function returns the computer-parsable list of the files in the current directory (optionally only of the files matching the 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 value: true if the file list was successfully retrieved, false otherwise.
Initializes an output stream to the specified 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.
a standalone connection (without wxURL)}
wxFTP ftp;
wxInputStream *in_stream;
char *data;
ftp.Connect("a.host.domain");
ftp.ChDir("a_directory");
in_stream = ftp.GetInputStream("a_file_to_get");
data = new char[in_stream->GetSize()];
in_stream->Read(data, in_stream->GetSize());
if (in_stream->LastError() != wxStream_NOERROR) {
// Do something.
}
delete in_stream; /* Close the DATA connection */
ftp.Close(); /* Close the COMMAND connection */
Creates a new input stream on the specified path. You can use all but the seek functionality of wxStream. Seek isn't available on all streams. For example, HTTP or FTP streams do not deal with it. Other functions like Tell are not available for this sort of stream, at present. You will be notified when the EOF is reached by an error.
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 file descriptor. - see also wxFFile for a wrapper around FILE structure.
wxFileOffset is used by the wxFile functions which require offsets as parameter or return them. If the platform supports it, wxFileOffset if a typedef for a native 64 bit integer, else a 32 bit integer is used for wxFileOffset.
wx/file.h defines the following constants:
#define wxS_IRUSR 00400 #define wxS_IWUSR 00200 #define wxS_IXUSR 00100 #define wxS_IRGRP 00040 #define wxS_IWGRP 00020 #define wxS_IXGRP 00010 #define wxS_IROTH 00004 #define wxS_IWOTH 00002 #define wxS_IXOTH 00001 // default mode for the new files: corresponds to umask 022 #define wxS_DEFAULT (wxS_IRUSR | wxS_IWUSR | wxS_IRGRP | wxS_IWGRP | wxS_IROTH | wxS_IWOTH)
These constants define the file access rights and are used with wxFile::Create and wxFile::Open .
The OpenMode enumeration defines the different modes for opening a file, it is defined inside wxFile class so its members should be specified with wxFile:: scope resolution prefix. It is also used with wxFile::Access function.
| wxFile::read | Open file for reading or test if it can be opened for reading with Access() |
| wxFile::write | Open file for writing deleting the contents of the file if it already exists or test if it can be opened for writing with Access() |
| wxFile::read_write | Open file for reading and writing; can not be used with Access() |
| wxFile::write_append | Open file for appending: the file is opened for writing, but the old contents of the file is not erased and the file pointer is initially placed at the end of the file; can not be used with Access(). This is the same as wxFile::write if the file doesn't exist. |
| wxFile::write_excl | Open the file securely for writing (Uses O_EXCL | O_CREAT). Will fail if the file already exists, else create and open it atomically. Useful for opening temporary files without being vulnerable to race exploits. |
Other constants defined elsewhere but used by wxFile functions are wxInvalidOffset which represents an invalid value of type wxFileOffset and is returned by functions returning wxFileOffset on error and the seek mode constants used with Seek() :
| wxFromStart | Count offset from the start of the file |
| wxFromCurrent | Count offset from the current position of the file pointer |
| wxFromEnd | Count offset from the end of the file (backwards) |
Default constructor.
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.
Associates the file with the given file descriptor, which has already been opened.
Destructor will close the file.
NB: it is not virtual so you should not use wxFile polymorphically.
This function verifies if we may access the given file in specified mode. Only values of wxFile::read or wxFile::write really make sense here.
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 wxFile::fd_stdin , wxFile::fd_stdout and wxFile::fd_stderr ).
The descriptor should be already opened and it will be closed by wxFile object.
Closes the file.
Creates a file for writing. If the file already exists, setting overwrite to true will ensure it is overwritten.
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().
Returns the file descriptor associated with the file.
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 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.
Returns true if the given name specifies an existing regular file (not a directory or a link)
Flushes the file descriptor.
Note that wxFile::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).
Returns the type of the file. Possible return values are:
enum wxFileKind
{
wxFILE_KIND_UNKNOWN,
wxFILE_KIND_DISK, // a file supporting seeking to arbitrary offsets
wxFILE_KIND_TERMINAL, // a tty
wxFILE_KIND_PIPE // a pipe
};
Returns true if the file has been opened.
Returns the length of the file.
Opens the file, returning true if successful.
Reads the specified number of bytes into a buffer, returning the actual number read.
Seeks to the specified position.
Moves the file pointer to the specified number of bytes before the end of the file.
Returns the current position or wxInvalidOffset if file is not opened or if another error occurred.
Writes the specified number of bytes from a buffer.
Writes the contents of the string to the file.
Note that this method only works with NUL -terminated strings, if you want to write data with embedded NUL s to the file you should use the other Write() overload .
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 key = value defining the keys and lines of special form [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.
Read the config data from the specified stream instead of the associated file, as usual.
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.
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 SetUmask(0077) .
This function doesn't do anything on non-Unix platforms.
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.
None.
Constructor.
MSW only: adds a file to the file list represented by this data object.
Returns the array of file names.
This class represents the file chooser dialog.
Pops up a file selector box. In Windows and GTK2.4+, this is the common file selector dialog. In X, this is a file selector box with somewhat less functionality. 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. Flags may be a combination of wxOPEN, wxSAVE, wxOVERWRITE_PROMPT, wxHIDE_READONLY, wxFILE_MUST_EXIST, wxMULTIPLE, wxCHANGE_DIR or 0.
Both the X 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:
"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.
Constructor. Use wxFileDialog::ShowModal to show the dialog.
NB: Previous versions of wxWidgets used wxCHANGE_DIR by default under MS Windows which allowed the program to simply remember the last directory where user selected the files to open/save. This (desired) functionality must be implemented in the program itself now (manually remember the last path used and pass it to the dialog the next time it is called) or by using this flag.
Destructor.
Returns the default directory.
Returns the default filename.
Fills the array filenames with the names of the files chosen. This function should only be used with the dialogs which have wxMULTIPLE 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.
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.
Returns the message that will be displayed on the dialog.
Returns the full path (directory and filename) of the selected file.
Fills the array paths with the full paths of the files chosen. This function should only be used with the dialogs which have wxMULTIPLE style, use GetPath for the others.
Returns the dialog style.
Returns the file dialog wildcard.
Sets the default directory.
Sets the default filename.
Sets the default filter index, starting from zero.
Sets the message that will be displayed on the dialog.
Sets the path (the combined directory and filename that will be returned when the dialog is dismissed).
Sets the dialog style. See wxFileDialog::wxFileDialog for details.
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.
Shows the dialog, returning wxID_OK if the user pressed OK, and wxID_CANCEL otherwise.
This is a drop target which accepts files (dragged from File Manager or Explorer).
Constructor.
See wxDropTarget::OnDrop . This function is implemented appropriately for files, and calls wxFileDropTarget::OnDropFiles .
Override this function to receive dropped files.
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.
Constructor. Pass the maximum number of files that should be stored and displayed.
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 idBase (To one of your own defined IDs) when using more than one wxFileHistory in your application.
Destructor.
Adds a file to the file history list, if the object has a pointer to an appropriate file menu.
Appends the files in the history list, to all menus managed by the file history object.
Appends the files in the history list, to the given menu only.
Returns the file at this index (zero-based).
Returns the maximum number of files that can be stored.
Returns the number of files currently stored in the file history.
Loads the file history from the given config object. This function should be called explicitly by the application.
Removes the specified file from the history.
Removes this menu from the list of those managed by this object.
Saves the file history into the given config object. This must be called explicitly by the application.
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.
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 wxFile and wxFFile differ in one aspect, namely when to report that the end of the file has been reached. This is documented in wxFile::Eof and wxFFile::Eof and the behaviour of the stream classes reflects this difference, i.e. wxFileInputStream will report wxSTREAM_EOF after having read the last byte whereas wxFFileInputStream will report wxSTREAM_EOF after trying to read past the last byte. Related to EOF behavior, note that SeekI() can seek beyond the end of the stream (file) and will thus not return wxInvalidOffset for that.
Opens the specified file using its ifilename name in read-only mode.
Initializes a file stream in read-only mode using the file I/O object file .
Initializes a file stream in read-only mode using the specified file descriptor.
Destructor.
Returns true if the stream is initialized and ready.
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 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.
Many wxFileName methods accept the path format argument which is by wxPATH_NATIVE by default meaning to use the path format native for the current platform.
The path format affects the operation of wxFileName functions in several ways: first and foremost, it defines the path separator character to use, but it also affects other things such as whether the path has the drive part or not.
enum wxPathFormat
{
wxPATH_NATIVE = 0, // the path format for the current platform
wxPATH_UNIX,
wxPATH_BEOS = wxPATH_UNIX,
wxPATH_MAC,
wxPATH_DOS,
wxPATH_WIN = wxPATH_DOS,
wxPATH_OS2 = wxPATH_DOS,
wxPATH_VMS,
wxPATH_MAX // Not a valid value for specifying path format
}
Default constructor.
Copy constructor.
Constructor taking a full filename. If it terminates with a '/', a directory path is constructed (the name will be empty), otherwise a file name and extension are extracted from it.
Constructor from a directory name and a file name.
Constructor from a directory name, base file name and extension.
Constructor from a volume name, a directory name, base file name and extension.
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).
Creates the file name from various combinations of data.
Makes this object refer to the current working directory on the specified volume (or current volume if volume is empty).
Sets this file name object to the given directory name. The name and extension will be empty.
Sets this file name object to the home directory.
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 invalid state.
Reset all components to default, uninitialized state.
Removes the extension from the file name resulting in a file name with no trailing dot.
Returns a temporary file name starting with the given prefix . If the 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 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 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.
Returns true if the directory with this name exists.
Returns the object corresponding to the directory with the given name. The dir parameter may have trailing path separator or not.
Returns true if the file with this name exists.
Returns the file name object corresponding to the given file . This function exists mainly for symmetry with DirName .
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.
Returns the number of directories in the file name.
Returns the directories in string array form.
Returns the file name extension.
Returns the characters that can't be used in filenames and directory names for the specified format.
Returns the canonical path format for this platform.
Returns the full name (including extension but excluding directories).
Returns the full path with name and extension.
Returns the home directory.
Return the long form of the path (returns identity on non-Windows platforms)
Returns the last time the file was last modified.
Returns the name part of the filename.
Returns the path part of the filename (without the name or extension). The possible flags values are:
| 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. |
| 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. |
Returns the usually used path separator for this format. For all formats but 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.
Returns the string containing all the path separators for this format. For all formats but wxPATH_DOS this string contains only one character but for DOS and Windows both '/' and '\' may be used as separators.
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.
Return the short form of the path (returns identity on non-Windows platforms).
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.
Any of the pointers may be NULL if the corresponding time is not needed.
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).
Returns the string separating the volume from the path for this format.
Returns true if an extension is present.
Returns true if a name is present.
Returns true if a volume specifier is present.
Inserts a directory component before the zero-based position in the directory list. Please see AppendDir for important notes.
Returns true if this filename is absolute.
Returns true if the file names of this type are case-sensitive.
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).
Returns true if the char is a path separator for this format.
Returns true if this filename is not absolute.
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.
On Mac OS, gets the common type and creator for the given extension.
On Mac OS, registers application defined extensions and their default type and creator.
On Mac OS, looks up the appropriate type and creator from the registration and then sets it.
Make the file name absolute. This is a shortcut for Normalize(wxPATH_NORM_DOTS | wxPATH_NORM_ABSOLUTE | wxPATH_NORM_TILDE, cwd, format) .
This function tries to put this file name in a form relative to pathBase . In other words, it returns the file name which should be used to access this file if the current directory were pathBase .
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.
Prepends a directory to the file path. Please see AppendDir for important notes.
Removes the specified directory component from the path.
Removes last directory component from the path.
Deletes the specified directory from the file system.
Compares the filename using the rules of this platform.
Changes the current working directory.
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 .
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.
The full name is the file name and extension (but without the path).
Sets the name.
Sets the file creation and last access/modification times (any of the pointers may be NULL).
Sets the volume specifier.
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 ( volume , path , name or ext ) may be NULL if you are not interested in the value of a particular component. Also, fullpath may be empty on entry.
On return, path contains the file path (without the trailing separator), name contains the file name and 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 hasExt instead of relying on testing whether ext is empty or not.
Splits the given fullpath into the volume part (which may be empty) and the pure path part, not containing any volume.
Sets the access and modification times to the current moment.
Assigns the new value to this filename object.
Returns true if the filenames are equal. The string filenames is interpreted as a path in the native filename format.
Returns true if the filenames are different. The string filenames is interpreted as a path in the native filename format.
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 wxFile and wxFFile differ in one aspect, namely when to report that the end of the file has been reached. This is documented in wxFile::Eof and wxFFile::Eof and the behaviour of the stream classes reflects this difference, i.e. wxFileInputStream will report wxSTREAM_EOF after having read the last byte whereas wxFFileInputStream will report wxSTREAM_EOF after trying to read past the last byte. Related to EOF behavior, note that SeekO() can seek beyond the end of the stream (file) and will thus not return wxInvalidOffset for that.
Creates a new file with ofilename name and initializes the stream in write-only mode.
Initializes a file stream in write-only mode using the file I/O object file .
Initializes a file stream in write-only mode using the file descriptor fd .
Destructor.
Returns true if the stream is initialized and ready.
Initializes a new file stream in read-write mode using the specified iofilename name.
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 to provide access to user-defined virtual file systems.
Constructor.
wxFileSystem::AddHandler(new My_FS_Handler);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.
This static function adds new handler into the list of handlers. The handlers provide access to virtual FS.
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' !!
Sets the current location. location parameter passed to OpenFile is relative to this path.
Caution! Unless is_dir is true the 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/":
ChangePathTo("dir/subdir/xh.htm");
ChangePathTo("dir/subdir", true);
ChangePathTo("dir/subdir/", true);
Returns actual path (set by ChangePathTo ).
Converts filename into URL.
Works like wxFindFirstFile . Returns name of the first filename (within filesystem's current path) that matches wildcard . flags may be one of wxFILE (only files), wxDIR (only directories) or 0 (both).
Returns the next filename that matches parameters passed to FindFirst .
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.
Classes derived from wxFileSystemHandler are used to access virtual file systems. Its public interface consists of two methods: CanOpen and 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 if you don't know how locations are constructed.
Also consult list of available handlers .
Constructor.
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:
bool MyHand::CanOpen(const wxString& location)
{
return (GetProtocol(location) == "http");
}
Must be overridden in derived handlers.
Returns the anchor if present in the location. See wxFSFile for details.
Example: GetAnchor("index.htm#chapter2") == "chapter2"
Note: the anchor is NOT part of the left location.
Returns the left location string extracted from location .
Example: GetLeftLocation("file:myzipfile.zip#zip:index.htm") == "file:myzipfile.zip"
Returns the MIME type based on extension of location . (While wxFSFile::GetMimeType returns real MIME type - either extension-based or queried from HTTP.)
Example : GetMimeTypeFromExt("index.htm") == "text/html"
Returns the protocol string extracted from location .
Example: GetProtocol("file:myzipfile.zip#zip:index.htm") == "zip"
Returns the right location string extracted from location .
Example : GetRightLocation("file:myzipfile.zip#zip:index.htm") == "index.htm"
Works like wxFindFirstFile . Returns name of the first filename (within filesystem's current path) that matches wildcard . flags may be one of wxFILE (only files), wxDIR (only directories) or 0 (both).
This method is only called if CanOpen returns true.
Returns next filename that matches parameters passed to FindFirst .
This method is only called if CanOpen returns true and FindFirst returned a non-empty string.
Opens the file and returns wxFSFile pointer or NULL if failed.
Must be overridden in derived handlers.
This class holds information about a given 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 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".
\descsection{MessageParameters class}
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 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:
// provide the message parameters for the MIME type manager
class MailMessageParameters : public wxFileType::MessageParameters
{
public:
MailMessageParameters(const wxString& filename,
const wxString& mimetype)
: wxFileType::MessageParameters(filename, mimetype)
{
}
virtual wxString GetParamValue(const wxString& name) const
{
// parameter names are not case-sensitive
if ( name.CmpNoCase("charset") == 0 )
return "US-ASCII";
else
return wxFileType::MessageParameters::GetParamValue(name);
}
};
Now you only need to create an object of this class and pass it to, for example, GetOpenCommand like this:
wxString command;
if ( filetype->GetOpenCommand(&command,
MailMessageParameters("foo.txt", "text/plain")) )
{
// the full command for opening the text documents is in 'command'
// (it might be "notepad foo.txt" under Windows or "cat foo.txt" under Unix)
}
else
{
// we don't know how to handle such files...
}
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.
The default constructor is private because you should never create objects of this type: they are only returned by wxMimeTypesManager methods.
The destructor of this class is not virtual, so it should not be derived from.
If the function returns true , the string pointed to by mimeType is filled with full MIME type specification for this file type: for example, "text/plain".
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.
If the function returns true , the array 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".
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 GetFileTypeFromExtension function in the first place.
If the function returns true , the iconLoc is filled with the location of the icon for this MIME type. A wxIcon may be created from iconLoc later.
Windows: The function returns the icon shown by Explorer for the files of the specified type.
Mac: This function is not implemented and always returns false .
Unix: MIME manager gathers information about icons from GNOME and KDE settings and thus GetIcon's success depends on availability of these desktop environments.
If the function returns true , the string pointed to by desc is filled with a brief description for this file type: for example, "text document" for the "text/plain" MIME type.
With the first version of this method, if the true is returned, the string pointed to by 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).
If the function returns true , the string pointed to by 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.
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 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.
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.
Initializes a "filter" stream.
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.
Initializes a "filter" stream.
wxFindReplaceDialog events
Constuctor used by wxWidgets only.
Get the currently selected flags: this is the combination of wxFR_DOWN , wxFR_WHOLEWORD and wxFR_MATCHCASE flags.
Return the string to find (never empty).
Return the string to replace the search string with (only for replace and replace all events).
Return the pointer to the dialog which generated this event.
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 SetXXX() methods may only be called before showing the dialog and calling them has no effect later.
Flags used by wxFindReplaceData::GetFlags() and 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
}
Constuctor initializes the flags to default value (0).
Get the string to find.
Get the replacement string.
Get the combination of wxFindReplaceFlags values.
Set the flags to use to initialize the controls of the dialog.
Set the string to find (used as initial value by the dialog).
Set the replacement string (used as initial value by the dialog).
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 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 dialogs sample for an example of using it.
After using default constructor Create() must be called.
The parent and data parameters must be non- NULL .
Destructor.
Creates the dialog; use Show to show it on screen.
The parent and data parameters must be non- NULL .
Get the wxFindReplaceData object used by this dialog.
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 SetFlexibleDrection ), it needs to be decided how the sizer should grow in the other ("non flexible") direction in order to fill the available space. The SetNonFlexibleGrowMode method serves this purpose.
Constructor for a wxGridSizer. rows and 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. vgap and hgap define extra space between all children.
Specifies that column idx (starting from zero) should be grown if there is extra space available to the sizer.
The 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).
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 proportion parameter.
| wxVERTICAL | Rows are flexibly sized. |
| wxHORIZONTAL | Columns are flexibly sized. |
| wxBOTH | Both rows and columns are flexibly sized (this is the default value). |
Returns a wxOrientation value that specifies whether the sizer flexibly resizes its columns, rows, or both (default).
Specifies that column idx is no longer growable.
Specifies that row idx is no longer growable.
Specifies whether the sizer should flexibly resize its columns, rows, or both. Argument direction can be wxVERTICAL , wxHORIZONTAL or wxBOTH (which is the default value). Any other value is ignored. See GetFlexibleDirection() for the explanation of these values.
Note that this method does not trigger relayout.
Specifies how the sizer should grow in the non flexible direction if there is one (so SetFlexibleDirections() must have been called previously). Argument mode can be one of those documented in GetNonFlexibleGrowMode , please see there for their explanation.
Note that this method does not trigger relayout.
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 SetFocus .
Constructor.
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.
You can retrieve the current system font settings with wxSystemSettings .
The possible values for the family parameter of wxFont constructor are (the old names are for compatibility only):
enum wxFontFamily
{
wxFONTFAMILY_DEFAULT = wxDEFAULT,
wxFONTFAMILY_DECORATIVE = wxDECORATIVE,
wxFONTFAMILY_ROMAN = wxROMAN,
wxFONTFAMILY_SCRIPT = wxSCRIPT,
wxFONTFAMILY_SWISS = wxSWISS,
wxFONTFAMILY_MODERN = wxMODERN,
wxFONTFAMILY_TELETYPE = wxTELETYPE,
wxFONTFAMILY_MAX
};
The possible values for the weight parameter are (the old names are for compatibility only):
enum wxFontWeight
{
wxFONTWEIGHT_NORMAL = wxNORMAL,
wxFONTWEIGHT_LIGHT = wxLIGHT,
wxFONTWEIGHT_BOLD = wxBOLD,
wxFONTWEIGHT_MAX
};
The font flags which can be used during the font creation are:
enum
{
// no special flags: font with default weight/slant/anti-aliasing
wxFONTFLAG_DEFAULT = 0,
// slant flags (default: no slant)
wxFONTFLAG_ITALIC = 1 << 0,
wxFONTFLAG_SLANT = 1 << 1,
// weight flags (default: medium)
wxFONTFLAG_LIGHT = 1 << 2,
wxFONTFLAG_BOLD = 1 << 3,
// anti-aliasing flag: force on or off (default: the current system default)
wxFONTFLAG_ANTIALIASED = 1 << 4,
wxFONTFLAG_NOT_ANTIALIASED = 1 << 5,
// underlined/strikethrough flags (default: no lines)
wxFONTFLAG_UNDERLINED = 1 << 6,
wxFONTFLAG_STRIKETHROUGH = 1 << 7,
};
The known font encodings are:
enum wxFontEncoding
{
wxFONTENCODING_SYSTEM = -1, // system default
wxFONTENCODING_DEFAULT, // current default encoding
// ISO8859 standard defines a number of single-byte charsets
wxFONTENCODING_ISO8859_1, // West European (Latin1)
wxFONTENCODING_ISO8859_2, // Central and East European (Latin2)
wxFONTENCODING_ISO8859_3, // Esperanto (Latin3)
wxFONTENCODING_ISO8859_4, // Baltic (old) (Latin4)
wxFONTENCODING_ISO8859_5, // Cyrillic
wxFONTENCODING_ISO8859_6, // Arabic
wxFONTENCODING_ISO8859_7, // Greek
wxFONTENCODING_ISO8859_8, // Hebrew
wxFONTENCODING_ISO8859_9, // Turkish (Latin5)
wxFONTENCODING_ISO8859_10, // Variation of Latin4 (Latin6)
wxFONTENCODING_ISO8859_11, // Thai
wxFONTENCODING_ISO8859_12, // doesn't exist currently, but put it
// here anyhow to make all ISO8859
// consecutive numbers
wxFONTENCODING_ISO8859_13, // Baltic (Latin7)
wxFONTENCODING_ISO8859_14, // Latin8
wxFONTENCODING_ISO8859_15, // Latin9 (a.k.a. Latin0, includes euro)
wxFONTENCODING_ISO8859_MAX,
// Cyrillic charset soup (see http://czyborra.com/charsets/cyrillic.html)
wxFONTENCODING_KOI8, // we don't support any of KOI8 variants
wxFONTENCODING_ALTERNATIVE, // same as MS-DOS CP866
wxFONTENCODING_BULGARIAN, // used under Linux in Bulgaria
// what would we do without Microsoft? They have their own encodings
// for DOS
wxFONTENCODING_CP437, // original MS-DOS codepage
wxFONTENCODING_CP850, // CP437 merged with Latin1
wxFONTENCODING_CP852, // CP437 merged with Latin2
wxFONTENCODING_CP855, // another cyrillic encoding
wxFONTENCODING_CP866, // and another one
// and for Windows
wxFONTENCODING_CP874, // WinThai
wxFONTENCODING_CP1250, // WinLatin2
wxFONTENCODING_CP1251, // WinCyrillic
wxFONTENCODING_CP1252, // WinLatin1
wxFONTENCODING_CP1253, // WinGreek (8859-7)
wxFONTENCODING_CP1254, // WinTurkish
wxFONTENCODING_CP1255, // WinHebrew
wxFONTENCODING_CP1256, // WinArabic
wxFONTENCODING_CP1257, // WinBaltic (same as Latin 7)
wxFONTENCODING_CP12_MAX,
wxFONTENCODING_UTF7, // UTF-7 Unicode encoding
wxFONTENCODING_UTF8, // UTF-8 Unicode encoding
wxFONTENCODING_UNICODE, // Unicode - currently used only by
// wxEncodingConverter class
wxFONTENCODING_MAX
};
Objects:
wxNullFont
Pointers:
wxNORMAL_FONT
wxSMALL_FONT
wxITALIC_FONT
wxSWISS_FONT
Default constructor.
If the desired font does not exist, the closest match will be chosen. Under Windows, only scalable TrueType fonts are used.
See also wxDC::SetFont , wxDC::DrawText and wxDC::GetTextExtent .
Creates a font object with the specified attributes.
The destructor may not delete the underlying font object of the native windowing system, since wxFont uses a reference counting system for efficiency.
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.
Destructor.
Returns true if the font is a fixed width (or monospaced) font, false if it is a proportional one or font is invalid.
Returns the current application's default encoding.
Returns the typeface name associated with the font, or the empty string if there is no typeface information.
Gets the font family. See wxFont::SetFamily for a list of valid family identifiers.
Returns the platform-dependent string completely describing this font or an empty string if the font wasn't constructed using the native font description.
Gets the point size.
Gets the font style. See wxFont::wxFont for a list of valid styles.
Returns true if the font is underlined, false otherwise.
Gets the font weight. See wxFont::wxFont for a list of valid weight identifiers.
These functions take the same parameters as wxFont constructor and return a new font object allocated on the heap.
Using New() is currently the only way to directly create a font with the given size in pixels on platforms other than wxMSW.
Returns true if this object is a valid font, false otherwise.
Sets the default font encoding.
Creates the font corresponding to the given native font description string which must have been previously returned by GetNativeFontInfoDesc . If the string is invalid, font is unchanged.
Sets the point size.
Sets the font style.
Sets underlining.
Sets the font weight.
Assignment operator, using reference counting. Returns a reference to `this'.
Equality operator. Two fonts are equal if they contain pointers to the same underlying font data. It does not compare each attribute, so two independently-created fonts using the same parameters will fail the test.
Inequality operator. Two fonts are not equal if they contain pointers to different underlying font data. It does not compare each attribute.
This class holds a variety of information related to font dialogs.
Constructor. Initializes fontColour to black, showHelp to black, allowSymbols to true, enableEffects to true, minSize to 0 and maxSize to 0.
Enables or disables `effects' under MS Windows or generic only. This refers to the controls for manipulating colour, strikeout and underline properties.
The default value is true.
Under MS Windows, returns a flag determining whether symbol fonts can be selected. Has no effect on other platforms.
The default value is true.
Gets the colour associated with the font dialog.
The default value is black.
Gets the font chosen by the user if the user pressed OK (wxFontDialog::ShowModal returned wxID_OK).
Determines whether `effects' are enabled under Windows. This refers to the controls for manipulating colour, strikeout and underline properties.
The default value is true.
Gets the font that will be initially used by the font dialog. This should have previously been set by the application.
Returns true if the Help button will be shown (Windows only).
The default value is false.
Under MS Windows, determines whether symbol fonts can be selected. Has no effect on other platforms.
The default value is true.
Sets the font that will be returned to the user (for internal use only).
Sets the colour that will be used for the font foreground colour.
The default colour is black.
Sets the font that will be initially used by the font dialog.
Sets the valid range for the font point size (Windows only).
The default is 0, 0 (unrestricted range).
Determines whether the Help button will be displayed in the font dialog (Windows only).
The default value is false.
Assignment operator for the font data.
This class represents the font chooser dialog.
Constructor. Pass a parent window, and optionally the 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.
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.
Returns the font data associated with the font dialog.
Shows the dialog, returning wxID_OK if the user pressed Ok, and wxID_CANCEL otherwise.
If the user cancels the dialog (ShowModal returns 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.
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 EnumerateFacenames or EnumerateEncodings and the corresponding callback ( OnFacename or OnFontEncoding ) will be called repeatedly until either all fonts satisfying the specified criteria are exhausted or the callback returns false.
Either OnFacename or OnFontEncoding should be overridden depending on whether you plan to call EnumerateFacenames or EnumerateEncodings . Of course, if you call both of them, you should override both functions.
Call OnFacename for each font which supports given encoding (only if it is not wxFONTENCODING_SYSTEM) and is of fixed width (if fixedWidthOnly is true).
Calling this function with default arguments will result in enumerating all fonts available on the system.
Call OnFontEncoding for each encoding supported by the given font - or for each encoding supported by at least some font if font is not specified.
Return array of strings containing all encodings found by EnumerateEncodings . This is convenience function. It is based on default implementation of OnFontEncoding so don't expect it to work if you overwrite that method.
Return array of strings containing all facenames found by EnumerateFacenames . This is convenience function. It is based on default implementation of OnFacename so don't expect it to work if you overwrite that method.
Called by EnumerateFacenames for each match. Return true to continue enumeration or false to stop it.
Called by EnumerateEncodings for each match. Return true to continue enumeration or false to stop it.
A font list is a list containing all fonts which have been created. There is only one instance of this class: 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'.
Constructor. The application should not construct its own font list: use the object pointer wxTheFontList .
Used by wxWidgets to add a font to the list, called in the font constructor.
Finds a font of the given specification, or creates one and adds it to the list. See the wxFont constructor for details of the arguments.
Used by wxWidgets to remove a font from the list.
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.
If you need to display text in encoding which is not available at host system (see IsEncodingAvailable ), you may use these two classes to find font in some similar encoding (see GetAltForEncoding ) and convert the text to this encoding ( wxMBConv classes ).
Following code snippet demonstrates it:
if (!wxFontMapper::Get()->IsEncodingAvailable(enc, facename))
{
wxFontEncoding alternative;
if (wxFontMapper::Get()->GetAltForEncoding(enc, &alternative,
facename, false))
{
wxCSConv convFrom(wxFontMapper::Get()->GetEncodingName(enc));
wxCSConv convTo(wxFontMapper::Get()->GetEncodingName(alternative));
text = wxString(text.mb_str(convFrom), convTo);
}
else
...failure (or we may try iso8859-1/7bit ASCII)...
}
...display text...
Default ctor.
Virtual dtor for a base class.
Returns the encoding for the given charset (in the form of RFC 2046) or wxFONTENCODING_SYSTEM if couldn't decode it.
Be careful when using this function with 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 EVT_PAINT .
Get the current font mapper object. If there is no current object, creates one.
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() .
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.
Returns the n -th supported encoding. Together with GetSupportedEncodingsCount() this method may be used to get all supported encodings.
Return user-readable string describing the given encoding.
Return the encoding corresponding to the given internal name. This function is the inverse of GetEncodingName and is intentionally less general than CharsetToEncoding , i.e. it doesn't try to make any guesses nor ever asks the user. It is meant just as a way of restoring objects previously serialized using GetEncodingName .
Return internal string identifier for the encoding (see also GetEncodingDescription() )
Returns the number of the font encodings supported by this class. Together with GetEncoding this method may be used to get all supported encodings.
Check whether given encoding is available in given face or not. If no facename is given, find any font in this encoding.
The parent window for modal dialogs.
The title for the dialogs (note that default is quite reasonable).
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.
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().
Set the root config path to use (should be an absolute path).
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/CreateToolBar functions manages these windows, and adjusts the value returned by GetClientSize to reflect the remaining size available to application windows.
wxFrame processes the following events:
| 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 |
| 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. |
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.
Default constructor.
For Motif, MWM (the Motif Window Manager) should be running for any window styles to work (otherwise all styles take effect).
Constructor, creating the window.
Destructor. Destroys all child windows and menu bar if present.
Centres the frame on the display.
Used in two-step frame construction. See wxFrame::wxFrame for further details.
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.
By default, the status bar is an instance of wxStatusBar. To use a different class, override wxFrame::OnCreateStatusBar .
Note that you can put controls and other windows on the status bar if you wish.
Creates a status bar at the bottom of the frame.
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 wxFrame::OnCreateToolBar .
When a toolbar has been created with this function, or made known to the frame with wxFrame::SetToolBar , the frame will manage the toolbar position and adjust the return value from wxWindow::GetClientSize to reflect the available space for application windows.
Under Pocket PC, you should always use this function for creating the toolbar to be managed by the frame, so that wxWidgets can use a combined menubar and toolbar. Where you manage your own toolbars, create a wxToolBar as usual.
Creates a toolbar at the top or left of the frame.
Returns the origin of the frame client area (in client coordinates). It may be different from (0, 0) if the frame has a toolbar.
Returns the status bar pane used to display menu and toolbar help.
Simulate a menu command.
This function sends a dummy 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 Layout() directly and this function should not be used in this case.
Set the status bar pane used to display menu and toolbar help. Using -1 disables help display.
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.
Sets the widths of the fields in the status bar.
This class represents the position of an item in a virtual grid of rows and columns managed by a wxGridBagSizer .
Construct a new wxGBPosition, optionally setting the row and column. The default is (0,0).
Get the current column value.
Get the current row value.
Set a new column value.
Set a new row value.
Is the wxGBPosition valid? (An invalid wxGBPosition is (-1,-1). )
Compare equality of two wxGBPositions.
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.
Construct a sizer item for tracking a spacer.
Construct a sizer item for tracking a window.
Construct a sizer item for tracking a subsizer.
Get the row and column of the endpoint of this item
Get the grid position of the item.
Get the row and column spanning of the item.
Returns true if this item and the other item instersect
Returns true if the given pos/span would intersect with this item.
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.
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.
This class is used to hold the row and column spanning attributes of items in a wxGridBagSizer .
Construct a new wxGBSpan, optionally setting the rowspan and colspan. The default is (1,1). (Meaning that the item occupies one cell in each direction.
Get the current colspan value.
Get the current rowspan value.
Set a new colspan value.
Set a new rowspan value.
Is the wxGBSpan valid? (An invalid wxGBSpan is (-1,-1). )
Compare equality of two wxGBSpans.
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.
Default constructor.
wxGLCanvas is a class for displaying OpenGL graphics. There are wrappers for OpenGL on Windows, and GTK+ and Motif.
To use this class, create a wxGLCanvas window, call wxGLCanvas::SetCurrent to direct normal OpenGL commands to the window, and then call wxGLCanvas::SwapBuffers to show the OpenGL buffer on the window.
To set up the attributes for the rendering context (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 attribList parameter. The values that should be set up and their meanings will be described below.
To switch wxGLCanvas support on under Windows, edit setup.h and set wxUSE_GLCANVAS to 1. You may also need to have to add opengl32.lib to the list of libraries your program is linked with. On Unix, pass --with-opengl to configure to compile using OpenGL or Mesa.
The generic GL implementation doesn't support many of these options, such as stereo, auxiliary buffers, alpha channel, and accum buffer. Other implementations may support them.
| WX_GL_RGBA | Use true colour |
| WX_GL_BUFFER_SIZE | Bits for buffer if not WX_GL_RGBA |
| WX_GL_LEVEL | 0 for main buffer, >0 for overlay, <0 for underlay |
| WX_GL_DOUBLEBUFFER | Use doublebuffer |
| WX_GL_STEREO | Use stereoscopic display |
| WX_GL_AUX_BUFFERS | Number of auxiliary buffers (not all implementation support this option) |
| WX_GL_MIN_RED | Use red buffer with most bits (> MIN_RED bits) |
| WX_GL_MIN_GREEN | Use green buffer with most bits (> MIN_GREEN bits) |
| WX_GL_MIN_BLUE | Use blue buffer with most bits (> MIN_BLUE bits) |
| WX_GL_MIN_ALPHA | Use alpha buffer with most bits (> MIN_ALPHA bits) |
| WX_GL_DEPTH_SIZE | Bits for Z-buffer (0,16,32) |
| WX_GL_STENCIL_SIZE | Bits for stencil buffer |
| WX_GL_MIN_ACCUM_RED | Use red accum buffer with most bits (> MIN_ACCUM_RED bits) |
| WX_GL_MIN_ACCUM_GREEN | Use green buffer with most bits (> MIN_ACCUM_GREEN bits) |
| WX_GL_MIN_ACCUM_BLUE | Use blue buffer with most bits (> MIN_ACCUM_BLUE bits) |
| WX_GL_MIN_ACCUM_ALPHA | Use blue buffer with most bits (> MIN_ACCUM_ALPHA bits) |
Constructor.
attribList[index]= WX_GL_DEPTH_SIZE; attribList[index+1]=32; and so on.
Obtains the context that is associated with this canvas.
Sets this canvas as the current recipient of OpenGL calls. Each canvas contains an OpenGL device context that has been created during the creation of this window. So this call sets the current device context as the target device context for OpenGL operations.
Note that this function may only be called after the window has been shown.
Sets the current colour for this window, using the wxWidgets colour database to find a named colour.
Displays the previous OpenGL commands on the window.
wxGLContext is a class for sharing OpenGL data resources, such as display lists, with another wxGLCanvas .
By sharing data resources, you can prevent code duplication, save memory, and ultimately help optimize your application.
As an example, let's say you want to draw a ball on two different windows that is identical on each one, but the dimensions of one is slightly different than the other one. What you would do is create your display lists in the shared context, and then translate each ball on the individual canvas's context. This way the actual data for the ball is only created once (in the shared context), and you won't have to duplicate your development efforts on the second ball.
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.
Obtains the window that is associated with this context.
Sets this context as the current recipient of OpenGL calls. Each context contains an OpenGL device context that has been created during the creation of this window. So this call sets the current device context as the target device context for OpenGL operations.
Sets the current colour for this context, using the wxWidgets colour database to find a named colour.
Displays the previous OpenGL commands on the associated window.
A gauge is a horizontal or vertical bar which shows a quantity (often time). There are no user commands for the gauge.
Default constructor.
Constructor, creating and showing a gauge.
Destructor, destroying the gauge.
Creates the gauge for two-step construction. See wxGauge::wxGauge for further details.
This method is not implemented (returns 0) for most platforms.
Returns the width of the 3D bezel face.
This method is not implemented (doesn't do anything) for most platforms.
Returns the maximum position of the gauge.
This method is not implemented (returns 0) for most platforms.
Returns the 3D shadow margin width.
Returns the current position of the gauge.
Returns true if the gauge is vertical (has wxGA_VERTICAL style) and false otherwise.
This method is not implemented (doesn't do anything) for most platforms.
Sets the 3D bezel face width.
Sets the range (maximum value) of the gauge.
This method is not implemented (doesn't do anything) for most platforms.
Sets the 3D shadow width.
Sets the position of the gauge.
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.
Default constructor.
Main constructor.
Destructor.
Create function for two-step construction. See wxGenericDirCtrl::wxGenericDirCtrl for details.
Initializes variables.
Collapses the entire tree.
Tries to expand as much of the given path as possible, so that the filename or directory is visible in the tree control.
Gets the default path.
Gets the currently-selected directory or filename.
Gets selected filename path only (else empty string).
This function doesn't count a directory as a selection.
Returns the filter string.
Returns the current filter index (zero-based).
Returns a pointer to the filter list control (if present).
Returns the root id for the tree control.
Returns a pointer to the tree control.
Collapse and expand the tree, thus re-creating it from scratch. May be used to update the displayed directory content.
Sets the default path.
Sets the filter string.
Sets the current filter index (zero-based).
Sets the current path.
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 Validator overview .
Copy constructor.
Constructor taking a bool pointer. This will be used for wxCheckBox and wxRadioButton.
Constructor taking a wxString pointer. This will be used for wxButton, wxComboBox, wxStaticText, wxTextCtrl.
Constructor taking an integer pointer. This will be used for wxGauge, wxScrollBar, wxRadioBox, wxSpinButton, wxChoice.
Constructor taking a wxArrayInt pointer. This will be used for wxListBox, wxCheckListBox.
Destructor.
Clones the generic validator using the copy constructor.
Transfers the value from the window to the appropriate data type.
Transfers the value to the window.
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 wxGrid classes overview 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. If you have been using the old wxGrid class you will probably want to have a look at the wxGrid classes overview to see how things have changed. 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.
Default constructor
Constructor to create a grid object. Call either wxGrid::CreateGrid or wxGrid::SetTable directly after this to initialize the grid before using it.
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 ).
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 wxGrid::InsertCols for further information.
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 wxGrid::InsertRows for further information.
Automatically sets the height and width of all rows and columns to fit their contents.
Common part of AutoSizeColumn/Row() or row?
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.
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.
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.
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.
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 wxGrid::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.
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.
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 ).
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 ).
Return true if the dragging of grid lines to resize rows and columns is enabled or false otherwise.
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).
Do we have some place to store attributes in?
Return the rectangle corresponding to the grid cell's size and position in logical coordinates.
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.
Deselects all cells that are currently selected.
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 wxGrid::SetTable .
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 wxGrid::InsertCols for further information.
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 wxGrid::InsertRows for further information.
Disables in-place editing of grid cells. Equivalent to calling EnableCellEditControl(false).
Disables column sizing by dragging with the mouse. Equivalent to passing false to wxGrid::EnableDragColSize .
Disable mouse dragging of grid lines to resize rows and columns. Equivalent to passing false to wxGrid::EnableDragGridSize
Disables row sizing by dragging with the mouse. Equivalent to passing false to wxGrid::EnableDragRowSize .
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.
Enables or disables column sizing by dragging with the mouse.
Enables or disables row and column resizing by dragging gridlines with the mouse.
Enables or disables row sizing by dragging with the mouse.
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 wxGrid::SetReadOnly .
For more information about controlling grid cell attributes see the wxGridCellAttr cell attribute class and the wxGrid classes overview .
Turns the drawing of grid lines on or off.
Decrements the grid's batch count. When the count is greater than zero repainting of the grid is suppressed. Each previous call to wxGrid::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.
Overridden wxWindow method.
Causes immediate repainting of the grid. Use this instead of the usual wxWindow::Refresh.
Returns the number of times that wxGrid::BeginBatch has been called without (yet) matching calls to wxGrid::EndBatch . While the grid's batch count is greater than zero the display will not be updated.
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.
Returns the background colour of the cell at the specified location.
Returns a pointer to the editor for the cell at the specified location.
See wxGridCellEditor and the wxGrid overview for more information about cell editors and renderers.
Returns the font for text in the grid cell at the specified location.
Returns a pointer to the renderer for the grid cell at the specified location.
See wxGridCellRenderer and the wxGrid overview for more information about cell editors and renderers.
Returns the text colour for the grid cell at the specified location.
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 wxGrid::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 wxGrid overview for more information.
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.
Returns the current height of the column labels.
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.
This returns the value of the lowest column width that can be handled correctly. See member SetColMinimalAcceptableWidth for details.
Get the minimal width of the given column/row.
Returns the width of the specified column.
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.
Returns the current default background colour for grid cells.
Returns the current default font for grid cell text.
Returns the current default colour for grid cell text.
Returns the default height for column labels.
Returns the current default width for grid columns.
Returns a pointer to the current default grid cell editor.
See wxGridCellEditor and the wxGrid overview for more information about cell editors and renderers.
Returns a pointer to the current default grid cell renderer.
See wxGridCellRenderer and the wxGrid overview for more information about cell editors and renderers.
Returns the default width for the row labels.
Returns the current default height for grid rows.
Returns the current grid cell column position.
Returns the current grid cell row position.
Returns the colour used for grid lines.
Returns true if drawing of grid lines is turned on, false otherwise.
Returns the colour used for the background of row and column labels.
Returns the font used for row and column labels.
Returns the colour used for row and column label text.
Returns the total number of grid columns (actually the number of columns in the underlying grid table).
Returns the total number of grid rows (actually the number of rows in the underlying grid table).
This returns the value of the lowest row width that can be handled correctly. See member SetRowMinimalAcceptableHeight for details.
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.
Returns the current width of the row labels.
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.
Returns the height of the specified row.
Returns the number of pixels per horizontal scroll increment. The default is 15.
Returns the number of pixels per vertical scroll increment. The default is 15.
Returns the current selection mode, see wxGrid::SetSelectionMode .
Returns an array of singly selected cells.
Returns an array of selected cols.
Returns an array of selected rows.
Access or update the selection fore/back colours
Returns an array of the top left corners of blocks of selected cells, see wxGrid::GetSelectionBlockBottomRight .
Returns an array of the bottom right corners of blocks of selected cells, see wxGrid::GetSelectionBlockTopLeft .
Returns a base pointer to the current table object.
Returned number of whole cols visible.
Hides the in-place cell edit control.
Init the m_colWidths/Rights arrays
NB: never access m_row/col arrays directly because they are created on demand, always use accessor functions instead!
Init the m_rowHeights/Bottoms arrays with default values.
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.
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.
Returns true if the in-place edit control is currently enabled.
Returns true if the current cell has been set to read-only (see wxGrid::SetReadOnly ).
Returns false if the whole grid has been set as read-only or true otherwise. See wxGrid::EnableEditing for more information about controlling the editing status of grid cells.
Is this cell currently selected.
Returns true if the cell at the specified location can't be edited. See also wxGrid::IsReadOnly .
Returns true if there are currently rows, columns or blocks of cells selected.
Returns true if a cell is either wholly visible (the default) or at least partially visible in the grid window.
Brings the specified cell into the visible grid cell area with minimal scrolling. Does nothing if the cell is already visible.
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.
\wxheading{Keyboard}
This function is called for Down cursor key presses or Shift+Down to
expand a selection.
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.
\wxheading{Keyboard}
This function is called for Left cursor key presses or Shift+Left to
expand a selection.
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.
\wxheading{Keyboard}
This function is called for Right cursor key presses or Shift+Right to
expand a selection.
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.
\wxheading{Keyboard}
This function is called for Up cursor key presses or Shift+Up to expand a
selection.
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.
\wxheading{Keyboard}
This function is called for the Ctrl+Down key combination. Shift+Ctrl+Down
expands a selection.
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.
\wxheading{Keyboard}
This function is called for the Ctrl+Left key combination. Shift+Ctrl+left
expands a selection.
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.
\wxheading{Keyboard}
This function is called for the Ctrl+Right key combination.
Shift+Ctrl+Right expands a selection.
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.
\wxheading{Keyboard}
This function is called for the Ctrl+Up key combination. Shift+Ctrl+Up
expands a selection.
Moves the grid cursor down by some number of rows so that the previous bottom visible row becomes the top visible row.
\wxheading{Keyboard}
This function is called for PgDn keypresses.
Moves the grid cursor up by some number of rows so that the previous top visible row becomes the bottom visible row.
\wxheading{Keyboard}
This function is called for PgUp keypresses.
Methods for a registry for mapping data types to Renderers/Editors
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.
Selects all cells in the grid.
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.
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.
This function returns the rectangle that encloses the selected cells in device coords and clipped to the client size of the grid window.
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.
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.
Sets the editor for the grid cell at the specified location. The grid will take ownership of the pointer.
See wxGridCellEditor and the wxGrid overview for more information about cell editors and renderers.
Sets the font for text in the grid cell at the specified location.
Sets the renderer for the grid cell at the specified location. The grid will take ownership of the pointer.
See wxGridCellRenderer and the wxGrid overview for more information about cell editors and renderers.
Sets the text colour for the grid cell at the specified location.
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 wxGrid::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 wxGrid overview for more information.
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 wxGrid classes overview .
Sets the specified column to display boolean values. wxGrid displays boolean values with a checkbox.
Sets the specified column to display integer values.
Sets the specified column to display floating point values with the given width and precision.
Sets the specified column to display data in a custom format. See the wxGrid overview for more information on working with custom data types.
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.
Sets the height of the column labels.
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.
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 wxGrid::GetColMinimalAcceptableWidth .
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.
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 wxGrid::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.
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.
Sets the default background colour for grid cells.
Sets the default font to be used for grid cell text.
Sets the current default colour for grid cell text.
Sets the default editor for grid cells. The grid will take ownership of the pointer.
See wxGridCellEditor and the wxGrid overview for more information about cell editors and renderers.
Sets the default renderer for grid cells. The grid will take ownership of the pointer.
See wxGridCellRenderer and the wxGrid overview for more information about cell editors and renderers.
Sets the default width for columns in the grid. This will only affect columns subsequently added to the grid unless resizeExistingCols is true.
Sets the default height for rows in the grid. This will only affect rows subsequently added to the grid unless resizeExistingRows is true.
Set the grid cursor to the specified cell. This function calls wxGrid::MakeCellVisible .
Sets the colour used to draw grid lines.
Sets the background colour for row and column labels.
Sets the font for row and column labels.
Sets the colour for row and column label text.
A grid may occupy more space than needed for its rows/columns. This function allows to set how big this extra space is
Common part of AutoSizeColumn/Row() and GetBestSize()
Makes the cell at the specified location read-only or editable. See also wxGrid::IsReadOnly .
Sets the cell attributes for all cells in the specified row. See the wxGridCellAttr class for more information about controlling cell attributes.
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.
Sets the width of the row labels.
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.
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 wxGrid::GetRowMinimalAcceptableHeight .
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.
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 wxGrid::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.
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.
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.
Set the selection behaviour of the grid.
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 wxGrid::CreateGrid when your application involves complex or non-string data or data sets that are too large to fit wholly in memory.
Displays the in-place cell edit control for the current cell.
Returns the grid column that corresponds to the logical x coordinate. Returns wxNOT_FOUND if there is no column at the x position.
Returns the column whose right hand edge is close to the given logical x position. If no column edge is near to this position wxNOT_FOUND is returned.
Returns the row whose bottom edge is close to the given logical y position. If no row edge is near to this position wxNOT_FOUND is returned.
Returns the grid row that corresponds to the logical y coordinate. Returns wxNOT_FOUND if there is no row at the y position.
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 .
Constructor, with optional parameters to specify the gap between the rows and columns.
The Add methods return a valid pointer if the item was successfully placed at the given position, NULL if something was already there.
Called when the managed size of the sizer is needed or when layout needs done.
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 excludeItem is given then it will not be checked for intersection, for example it may be the item we are checking the position of.
Find the sizer item for the given window or subsizer, returns NULL if not found. (non-recursive)
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 pt correspond to the client coordinates of the window using the sizer for layout. (non-recursive)
Return the sizer item for the given grid cell, or NULL if there is no item at that position. (non-recursive)
Return the sizer item that has a matching user data (it only compares pointer values) or NULL if not found. (non-recursive)
Get the size of the specified cell, including hgap and vgap. Only valid after a Layout.
Get the size used for cells in the grid with no item.
Get the grid position of the specified item.
Get the row/col spanning of the specified item
Called when the managed size of the sizer is needed or when layout needs done.
Set the size used for cells in the grid with no item.
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.
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.
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 wxGridTable::GetAttr().
Default constructor.
VZ: considering the number of members wxGridCellAttr has now, this ctor seems to be pretty useless... may be we should just remove it?
Creates a new copy of this object.
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
Sets the text colour.
Sets the background colour.
Sets the font.
Sets the alignment.
takes ownership of the pointer
accessors
The editor for boolean data.
Default constructor.
This class may be used to format boolean data in a cell. for string cells.
Default constructor
The editor for string data allowing to choose from a list of strings.
Parameters string format is "item1[,item2[...,itemN]]"
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.
Creates the actual edit control.
Size and position the edit control.
Show or hide the edit control, use the specified attributes to set colours/fonts for it.
Draws the part of the cell not occupied by the control: the base class version just fills it with background colour from the attribute.
Fetch the value from the table and prepare the edit control to begin editing. Set the focus to the edit control.
Complete the editing of the current cell. Returns true if the value has changed. If necessary, the control may be destroyed.
Reset the value in the control back to its starting value.
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.
If the editor is enabled by clicking on the cell, this method will be called.
Some types of controls on some platforms may need some help with the Return key.
Final cleanup.
Create a new object which is the copy of this one.
The dtor is private because only DecRef() can delete us.
The editor for floating point numbers data.
Parameters string format is "width,precision"
This class may be used to format floating point data in a cell.
Returns the precision ( see wxGridCellFloatRenderer ).
Returns the width ( see wxGridCellFloatRenderer ).
Parameters string format is "width[,precision]".
Sets the precision ( see wxGridCellFloatRenderer ).
Sets the width ( see wxGridCellFloatRenderer )
The editor for numeric integer data.
Allows to specify the range for acceptable data; if min == max == -1, no range checking is done
String representation of the value.
If the return value is true, the editor uses a wxSpinCtrl to get user input, otherwise it uses a wxTextCtrl.
Parameters string format is "min,max".
This class may be used to format integer data in a cell.
Default constructor
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.
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.
Get the preferred size of the cell for its contents.
This class may be used to format string data in a cell; it is the default for string cells.
Default constructor
The editor for string/text data.
Default constructor.
The parameters string format is "n" where n is a number representing the maximum width.
Default constructor.
Returns the column at which the event occurred.
Returns the edit control.
Returns the row at which the event occurred.
Sets the column at which the event occurred.
Sets the edit control.
Sets the row at which the event occurred.
This event class contains information about various grid events.
Default constructor.
Returns true if the Alt key was down at the time of the event.
Returns true if the Control key was down at the time of the event.
Column at which the event occurred.
Position in pixels at which the event occurred.
Row at which the event occurred.
Returns true if the Meta key was down at the time of the event.
Returns true if the user deselected a cell, false if the user deselected a cell.
Returns true if the Shift key was down at the time of the event.
Default constructor.
Returns true if the Alt key was down at the time of the event.
Returns true if the Control key was down at the time of the event.
Top left corner of the rectangular area that was (de)selected.
Bottom row of the rectangular area that was (de)selected.
Left column of the rectangular area that was (de)selected.
Right column of the rectangular area that was (de)selected.
Top left corner of the rectangular area that was (de)selected.
Top row of the rectangular area that was (de)selected.
Returns true if the Meta key was down at the time of the event.
Returns true if the area was selected, false otherwise.
Returns true if the Shift key was down at the time of the event.
This event class contains information about a row/column resize event.
Default constructor.
Returns true if the Alt key was down at the time of the event.
Returns true if the Control key was down at the time of the event.
Position in pixels at which the event occurred.
Row or column at that was resized.
Returns true if the Meta key was down at the time of the event.
Returns true if the Shift key was down at the time of the event.
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.
Constructor for a wxGridSizer. rows and 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. vgap and hgap define extra space between all children.
Returns the number of columns in the sizer.
Returns the horizontal gap (in pixels) between cells in the sizer.
Returns the number of rows in the sizer.
Returns the vertical gap (in pixels) between the cells in the sizer.
Sets the number of columns in the sizer.
Sets the horizontal gap (in pixels) between cells in the sizer.
Sets the number of rows in the sizer.
Sets the vertical gap (in pixels) between the cells in the sizer.
Grid table classes.
You must override these functions in a derived table class.
Data type determination and value access.
For user defined types
Overriding these is optional
Attribute handling give us the attr provider to use - we take ownership of the pointer
get the currently used attr provider (may be NULL)
Does this table allow attributes? Default implementation creates a wxGridCellAttrProvider if necessary.
change row/col number in attribute if needed
by default forwarded to wxGridCellAttrProvider if any. May be overridden to handle attributes directly in the table.
these functions take ownership of the pointer
Returns the HTTP response code returned by the server. Please refer to the RFC 2616 for the list of the responses.
Creates a new input stream on the specified path. You can use all except the seek functionality of wxStream. Seek isn't available on all streams. For example, http or ftp streams doesn't deal with it. Other functions like Tell and SeekI for this sort of stream. You will be notified when the EOF is reached by an error.
It sets data of a field to be sent during the next request to the HTTP server. The field name is specified by header and the content by h_data . This is a low level function and it assumes that you know what you are doing.
Returns the data attached with a field whose name is specified by header . If the field doesn't exist, it will return an empty string and not a NULL string.
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.
WX_DECLARE_STRING_HASH_MAP( VALUE_T, // type of the values
CLASSNAME ); // name of the class
Declares a hash map class named CLASSNAME, with wxString keys and VALUE_T values.
WX_DECLARE_VOIDPTR_HASH_MAP( VALUE_T, // type of the values
CLASSNAME ); // name of the class
Declares a hash map class named CLASSNAME, with void* keys and VALUE_T values.
WX_DECLARE_HASH_MAP( KEY_T, // type of the keys
VALUE_T, // type of the values
HASH_T, // hasher
KEY_EQ_T, // key equality predicate
CLASSNAME); // name of the class
The HASH_T and KEY_EQ_T are the types used for the hashing function and key comparison. wxWidgets provides three predefined hashing functions: wxIntegerHash for integer types ( int , long , short , and their unsigned counterparts ), wxStringHash for strings ( wxString , wxChar* , char* ), and wxPointerHash for any kind of pointer. Similarly three equality predicates: wxIntegerEqual , wxStringEqual , wxPointerEqual are provided.
Using this you could declare a hash map mapping int values to wxString like this:
WX_DECLARE_HASH_MAP( int,
wxString,
wxIntegerHash,
wxIntegerEqual,
MyHash );
// using an user-defined class for keys
class MyKey { /* ... */ };
// hashing function
class MyKeyHash
{
public:
MyKeyHash() { }
unsigned long operator()( const MyKey& k ) const
{ /* compute the hash */ }
MyKeyHash& operator=(const MyKeyHash&) { return *this; }
};
// comparison operator
class MyKeyEqual
{
public:
MyKeyEqual() { }
bool operator()( const MyKey& a, const MyKey& b ) const
{ /* compare for equality */ }
MyKeyEqual& operator=(const MyKeyEqual&) { return *this; }
};
WX_DECLARE_HASH_MAP( MyKey, // type of the keys
SOME_TYPE, // any type you like
MyKeyHash, // hasher
MyKeyEqual, // key equality predicate
CLASSNAME); // name of the class
An iterator is similar to a pointer, and so you can use the usual pointer operations: ++it ( and it++ ) to move to the next element, *it to access the element pointed to, it->first ( it->second ) to access the key ( value ) of the element pointed to. Hash maps provide forward only iterators, this means that you can't use --it , it + 3 , it1 - it2 .
class MyClass { /* ... */ };
// declare a hash map with string keys and int values
WX_DECLARE_STRING_HASH_MAP( int, MyHash5 );
// same, with int keys and MyClass* values
WX_DECLARE_HASH_MAP( int, MyClass*, wxIntegerHash, wxIntegerEqual, MyHash1 );
// same, with wxString keys and int values
WX_DECLARE_STRING_HASH_MAP( int, MyHash3 );
// same, with wxString keys and values
WX_DECLARE_STRING_HASH_MAP( wxString, MyHash2 );
MyHash1 h1;
MyHash2 h2;
// store and retrieve values
h1[1] = new MyClass( 1 );
h1[10000000] = NULL;
h1[50000] = new MyClass( 2 );
h2["Bill"] = "ABC";
wxString tmp = h2["Bill"];
// since element with key "Joe" is not present, this will return
// the default value, which is an empty string in the case of wxString
MyClass tmp2 = h2["Joe"];
// iterate over all the elements in the class
MyHash2::iterator it;
for( it = h2.begin(); it != h2.end(); ++it )
{
wxString key = it->first, value = it->second;
// do something useful with key and value
}
In the documentation below you should replace wxHashMap with the name you used in the class declaration.
| wxHashMap::key_type | Type of the hash keys |
| wxHashMap::mapped_type | Type of the values stored in the hash map |
| wxHashMap::value_type | Equivalent to struct { key_type first; mapped_type second }; |
| wxHashMap::iterator | Used to enumerate all the elements in a hash map; it is similar to a value_type* |
| wxHashMap::const_iterator | Used to enumerate all the elements in a constant hash map; it is similar to a const value_type* |
| wxHashMap::size_type | Used for sizes |
| wxHashMap::Insert_Result | The return value for insert() |
The size parameter is just a hint, the table will resize automatically to preserve performance.
Copy constructor.
Returns an iterator pointing at the first element of the hash map. Please remember that hash maps do not guarantee ordering.
Removes all elements from the hash map.
Counts the number of elements with the given key present in the map. This function returns only 0 or 1.
Returns true if the hash map does not contain any elements, false otherwise.
Returns an iterator pointing at the one-after-the-last element of the hash map. Please remember that hash maps do not guarantee ordering.
Erases the element with the given key, and returns the number of elements erased (either 0 or 1).
Erases the element pointed to by the iterator. After the deletion the iterator is no longer valid and must not be used.
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()).
Inserts the given value in the hash map. The return value is equivalent to a std::pair<wxHashMap::iterator, bool> ; the iterator points to the inserted element, the boolean value is true if v was actually inserted.
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 value_type() is inserted in the table.
Returns the number of elements in the map.
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.
class MyClass { /* ... */ };
// same, with MyClass* keys (only uses pointer equality!)
WX_DECLARE_HASH_SET( MyClass*, wxPointerHash, wxPointerEqual, MySet1 );
// same, with int keys
WX_DECLARE_HASH_SET( int, wxIntegerHash, wxIntegerEqual, MySet2 );
// declare a hash set with string keys
WX_DECLARE_HASH_SET( wxString, wxStringHash, wxStringEqual, MySet3 );
MySet1 h1;
MySet2 h1;
MySet3 h3;
// store and retrieve values
h1.insert( new MyClass( 1 ) );
h3.insert( "foo" );
h3.insert( "bar" );
h3.insert( "baz" );
int size = h3.size(); // now is three
bool has_foo = h3.find( "foo" ) != h3.end();
h3.insert( "bar" ); // still has size three
// iterate over all the elements in the class
MySet3::iterator it;
for( it = h3.begin(); it != h3.end(); ++it )
{
wxString key = *it;
// do something useful with key
}
WX_DECLARE_HASH_SET( KEY_T, // type of the keys
HASH_T, // hasher
KEY_EQ_T, // key equality predicate
CLASSNAME); // name of the class
The HASH_T and KEY_EQ_T are the types used for the hashing function and key comparison. wxWidgets provides three predefined hashing functions: wxIntegerHash for integer types ( int , long , short , and their unsigned counterparts ), wxStringHash for strings ( wxString , wxChar* , char* ), and wxPointerHash for any kind of pointer. Similarly three equality predicates: wxIntegerEqual , wxStringEqual , wxPointerEqual are provided.
Using this you could declare a hash set using int values like this:
WX_DECLARE_HASH_SET( int,
wxIntegerHash,
wxIntegerEqual,
MySet );
// using an user-defined class for keys
class MyKey { /* ... */ };
// hashing function
class MyKeyHash
{
public:
MyKeyHash() { }
unsigned long operator()( const MyKey& k ) const
{ /* compute the hash */ }
MyKeyHash& operator=(const MyKeyHash&) { return *this; }
};
// comparison operator
class MyKeyEqual
{
public:
MyKeyEqual() { }
bool operator()( const MyKey& a, const MyKey& b ) const
{ /* compare for equality */ }
MyKeyEqual& operator=(const MyKeyEqual&) { return *this; }
};
WX_DECLARE_HASH_SET( MyKey, // type of the keys
MyKeyHash, // hasher
MyKeyEqual, // key equality predicate
CLASSNAME); // name of the class
In the documentation below you should replace wxHashSet with the name you used in the class declaration.
| wxHashSet::key_type | Type of the hash keys |
| wxHashSet::mapped_type | Type of hash keys |
| wxHashSet::value_type | Type of hash keys |
| wxHashSet::iterator | Used to enumerate all the elements in a hash set; it is similar to a value_type* |
| wxHashSet::const_iterator | Used to enumerate all the elements in a constant hash set; it is similar to a const value_type* |
| wxHashSet::size_type | Used for sizes |
| wxHashSet::Insert_Result | The return value for insert() |
An iterator is similar to a pointer, and so you can use the usual pointer operations: ++it ( and it++ ) to move to the next element, *it to access the element pointed to, *it to access the value of the element pointed to. Hash sets provide forward only iterators, this means that you can't use --it , it + 3 , it1 - it2 .
The size parameter is just a hint, the table will resize automatically to preserve performance.
Copy constructor.
Returns an iterator pointing at the first element of the hash set. Please remember that hash sets do not guarantee ordering.
Removes all elements from the hash set.
Counts the number of elements with the given key present in the set. This function returns only 0 or 1.
Returns true if the hash set does not contain any elements, false otherwise.
Returns an iterator pointing at the one-after-the-last element of the hash set. Please remember that hash sets do not guarantee ordering.
Erases the element with the given key, and returns the number of elements erased (either 0 or 1).
Erases the element pointed to by the iterator. After the deletion the iterator is no longer valid and must not be used.
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()).
Inserts the given value in the hash set. The return value is equivalent to a std::pair<wxHashMap::iterator, bool> ; the iterator points to the inserted element, the boolean value is true if v was actually inserted.
Returns the number of elements in the set.
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.
Below is an example of using a hash table.
wxHashTable table(wxKEY_STRING);
wxPoint *point = new wxPoint(100, 200);
table.Put("point 1", point);
....
wxPoint *found_point = (wxPoint *)table.Get("point 1");
A hash table is implemented as an array of pointers to lists. When no data has been stored, the hash table takes only a little more space than this array (default size is 1000). When a data item is added, an integer is constructed from the integer or string key that is within the bounds of the array. If the array element is NULL, a new (keyed) list is created for the element. Then the data object is appended to the list, storing the key in case other data objects need to be stored in the list also (when a `collision' occurs).
Retrieval involves recalculating the array index from the key, and searching along the keyed list for the data object whose stored key matches the passed key. Obviously this is quicker when there are fewer collisions, so hashing will become inefficient if the number of items to be stored greatly exceeds the size of the hash table.
Constructor. key_type is one of wxKEY_INTEGER, or wxKEY_STRING, and indicates what sort of keying is required. size is optional.
Destroys the hash table.
The counterpart of Next . If the application wishes to iterate through all the data in the hash table, it can call BeginFind and then loop on Next .
Clears the hash table of all nodes (but as usual, doesn't delete user data).
Deletes entry in hash table and returns the user's data (if found).
If set to true data stored in hash table will be deleted when hash table object is destroyed.
Gets data from the hash table, using an integer or string key (depending on which has table constructor was used).
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).
If the application wishes to iterate through all the data in the hash table, it can call BeginFind and then loop on Next . This function returns a wxHashTable::Node pointer (or NULL if there are no more nodes). The return value is functionally equivalent to wxNode but might not be implemented as a wxNode . The user will probably only wish to use the GetData method to retrieve the data; the node may also be deleted.
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.
Returns the number of elements in the hash table.
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 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:
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:
Constructs a help instance object, but does not invoke the help viewer.
Destroys the help instance, closing down the viewer if it is running.
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.
If the help viewer is not running, runs it and displays the file at the given block number.
WinHelp: Refers to the context number.
MS HTML Help: Refers to the context number.
External HTML help: the same as for wxHelpController::DisplaySection .
wxHtmlHelpController: sectionNo is an identifier as specified in the .hhc file. See Help files format .
This function is for backward compatibility only, and applications should use wxHelpController instead.
If the help viewer is not running, runs it and displays the contents.
Displays the section as a popup window using a context id.
Returns false if unsuccessful or not implemented.
If the help viewer is not running, runs it and displays the given section.
The interpretation of section differs between help viewers. For most viewers, this call is equivalent to KeywordSearch. For MS HTML Help, wxHTML help and external HTML help, if section has a .htm or .html extension, that HTML file will be displayed; otherwise a keyword search is done.
If the help viewer is not running, runs it and displays the given section.
WinHelp, MS HTML Help sectionNo is a context id.
External HTML help: wxExtHelpController implements sectionNo as an id in a map file, which is of the form:
0 wx.html ; Index 1 wx34.html#classref ; Class reference 2 wx204.html ; Function reference
wxHtmlHelpController: sectionNo is an identifier as specified in the .hhc file. See Help files format .
See also the help sample for notes on how to specify section numbers for various help file formats.
Displays the text in a popup window, if possible.
Returns false if unsuccessful or not implemented.
wxHtmlHelpController returns the frame, size and position.
For all other help controllers, this function does nothing and just returns NULL.
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.
WinHelp, MS HTML Help: If more than one match is found, the first topic is displayed.
External HTML help, simple wxHTML help: If more than one match is found, a choice of topics is displayed.
wxHtmlHelpController: see wxHtmlHelpController::KeywordSearch .
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 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.
Overridable member called when this application's viewer is quit by the user.
This does not work for all help controllers.
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. newFrameEachTime is ignored.
For all other help controllers this function has no effect.
Sets detailed viewer information. So far this is only relevant to wxExtHelpController.
Some examples of usage:
m_help.SetViewer("kdehelp");
m_help.SetViewer("gnome-help-browser");
m_help.SetViewer("netscape", wxHELP_NETSCAPE);
If the viewer is running, quits it by disconnecting.
For Windows Help, the viewer will only close if no other application is using it.
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 .
Note that the instance doesn't own the help controller. The help controller should be deleted separately.
Sets the help controller associated with this help provider.
Returns the help controller associated with this help provider.
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.
Constructor.
Returns the left-click position of the mouse, in screen coordinates. This allows the application to position the help appropriately.
Sets the left-click position of the mouse, in screen coordinates.
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 wxHelpProvider::Set().
Virtual destructor for any base class.
Associates the text with the given window or id. Although all help providers have these functions to allow making wxWindow::SetHelpText work, not all of them implement the functions.
Unlike some other classes, the help provider is not created on demand. This must be explicitly done by the application.
Gets the help string for this window. Its interpretation is dependent on the help provider except that empty string always means that no help is associated with the window.
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.
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.
Get/set the current, application-wide help provider. Returns the previous one.
Shows help for the given window. Uses GetHelp internally if applicable.
Returns true if it was done, or false if no help was available for this window.
Internal data structure. It represents fragments of parsed HTML page, the so-called 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 : visible cells with non-zero width and height and helper cells (usually with zero width and height) that perform special actions such as color or font change.
Constructor.
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:
while (container->AdjustPagebreak(&p)) {}
Renders the cell.
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!
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)
| wxHTML_COND_ISANCHOR | Finds particular anchor. param is pointer to wxString with name of the anchor. |
| wxHTML_COND_USER | User-defined conditions start from this number. |
Returns descent value of the cell (m_Descent member). \helponly{See explanation:
\image{}{descent.bmp} }
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.
Returns height of the cell (m_Height member).
Returns unique cell identifier if there is any, empty string otherwise.
Returns hypertext link if associated with this cell or NULL otherwise. See wxHtmlLinkInfo . (Note: this makes sense only for visible tags).
Returns pointer to the next cell in list (see htmlcell.h if you're interested in details).
Returns pointer to parent container.
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!
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!
Returns width of the cell (m_Width member).
This method performs two actions:
It must be called before displaying cells structure because m_PosX and m_PosY are undefined (or invalid) before calling Layout.
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 that it calls wxHtmlWindow::LoadPage .
Sets unique cell identifier. Default value is no identifier, i.e. empty string.
Sets the hypertext link associated with this cell. (Default value is wxHtmlLinkInfo ("", "") (no link))
Sets the next cell in the list. This shouldn't be called by user - it is to be used only by wxHtmlContainerCell::InsertCell .
Sets parent container of this cell. This is called from wxHtmlContainerCell::InsertCell .
Sets the cell's position within parent container.
This cell changes the colour of either the background or the foreground.
Constructor.
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.
Constructor. parent is pointer to parent container or NULL.
Returns container's horizontal alignment.
Returns container's vertical alignment.
Returns the background colour of the container or wxNullColour if no background colour is set.
Returns the indentation. ind is one of the wxHTML_INDENT_* constants.
Note: You must call GetIndentUnits with same ind parameter in order to correctly interpret the returned integer value. It is NOT always in pixels!
Returns the units of indentation for ind where ind is one of the wxHTML_INDENT_* constants.
Inserts new cell into the container.
Sets the container's alignment (both horizontal and vertical) according to the values stored in tag . (Tags ALIGN parameter is extracted.) In fact it is only a front-end to SetAlignHor and SetAlignVer .
Sets the container's horizontal alignment . During Layout each line is aligned according to al value.
Sets the container's vertical alignment . This is per-line alignment!
Sets the background colour for this container.
Sets the border (frame) colours. A border is a rectangle around the container.
Sets the indentation (free space between borders of container and subcells).
Sets minimal height of the container.
When container's 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 h - even if the subcells cover much smaller area.
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.
pixel_scale is number of real pixels that equals to 1 HTML pixel.
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.
Constructor.
Assign DC instance to the renderer.
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.)
Sets fonts. See wxHtmlWindow::SetFonts for detailed description.
See also SetSize .
Set size of output rectangle, in pixels. Note that you can't change width of the rectangle between calls to Render ! (You can freely change height.)
Assign text to the renderer. Render then draws the text onto DC.
Renders HTML text to the DC.
Returned value is y coordinate of first cell than didn't fit onto page. Use this value as from in next call to Render in order to print multipages document.
Returns the height of the HTML text. This is important if area height (see 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.
This class provides very simple interface to printing architecture. It allows you to print HTML documents using only a few commands.
Constructor.
Preview HTML file.
Returns false in case of error -- call wxPrinter::GetLastError to get detailed information about the kind of the error.
Preview HTML text (not file!).
Returns false in case of error -- call wxPrinter::GetLastError to get detailed information about the kind of the error.
Print HTML file.
Returns false in case of error -- call wxPrinter::GetLastError to get detailed information about the kind of the error.
Print HTML text (not file!).
Returns false in case of error -- call wxPrinter::GetLastError to get detailed information about the kind of the error.
Display page setup dialog and allows the user to modify settings.
Sets fonts. See wxHtmlWindow::SetFonts for detailed description.
Set page header.
Set page footer.
Returns pointer to wxPrintData instance used by this class. You can set its parameters (via SetXXXX methods).
Returns a pointer to wxPageSetupDialogData instance used by this class. You can set its parameters (via SetXXXX methods).
This class is the parent class of input filters for wxHtmlWindow . It allows you to read and display files of different file formats.
Constructor.
Returns true if this filter is capable of reading file file .
Example:
bool MyFilter::CanRead(const wxFSFile& file)
{
return (file.GetMimeType() == "application/x-ugh");
}
Reads the file and returns string with HTML document.
Example:
wxString MyImgFilter::ReadFile(const wxFSFile& file)
{
return "<html><body><img src=\"" +
file.GetLocation() +
"\"></body></html>";
}
WARNING! 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.
This help controller provides an easy way of displaying HTML help in your application (see test sample). The help system is based on books (see 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.
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 htmlWorkshopFiles to true in your tex2rtf.ini file.
Constructor.
style is combination of these flags:
| wxHF_TOOLBAR | Help frame has toolbar. |
| wxHF_FLAT_TOOLBAR | Help frame has toolbar with flat buttons (aka coolbar). |
| wxHF_CONTENTS | Help frame has contents panel. |
| wxHF_INDEX | Help frame has index panel. |
| wxHF_SEARCH | Help frame has search panel. |
| wxHF_BOOKMARKS | Help frame has bookmarks controls. |
| wxHF_OPEN_FILES | Allow user to open arbitrary HTML document. |
| wxHF_PRINT | Toolbar contains "print" button. |
| wxHF_MERGE_BOOKS | Contents pane does not show book nodes. All books are merged together and appear as single book to the user. |
| wxHF_ICONS_BOOK | All nodes in contents pane have a book icon. This is how Microsoft's HTML help viewer behaves. |
| wxHF_ICONS_FOLDER | Book nodes in contents pane have a book icon, book's sections have a folder icon. This is the default. |
| wxHF_ICONS_BOOK_CHAPTER | Both book nodes and nodes of top-level sections of a book (i.e. chapters) have a book icon, all other sections (sections, subsections, ...) have a folder icon. |
| wxHF_DEFAULT_STYLE | wxHF_TOOLBAR | wxHF_CONTENTS | wxHF_INDEX | wxHF_SEARCH | wxHF_BOOKMARKS | wxHF_PRINT |
Adds book ( .hhp file - HTML Help Workshop project file) into the list of loaded books. This must be called at least once before displaying any help.
book_file or book_url 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, AddBook(wxFileName("help.zip")) is possible and, in fact, recommended way.
This protected virtual method may be overridden so that the controller uses slightly different frame. See samples/html/helpview sample for an example.
Displays page x . This is THE important function - it is used to display the help in application.
You can specify the page in many ways:
Looking for the page runs in these steps:
This alternative form is used to search help contents by numeric IDs.
Displays help window and focuses contents panel.
Displays help window and focuses index panel.
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).
Important: KeywordSearch searches only pages listed in .hhc file(s). You should list all pages in the contents file.
Reads the controller's setting (position of window, etc.)
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 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.
Sets format of title of the frame. Must contain exactly one "%s" (for title of displayed HTML page).
Associates 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 UseConfig , wxHtmlHelpController will use default wxConfig object if available (for details see wxConfigBase::Get and wxConfigBase::Set ).
Stores controllers setting (position of window etc.)
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.
Constructor.
Adds new book. 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.
Returns page's URL based on integer ID stored in project.
Returns page's URL based on its (file)name.
Returns array with help books info.
Returns reference to array with contents entries.
Returns reference to array with index entries.
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.)
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.
Constructor.
style is combination of these flags:
| wxHF_TOOLBAR | Help frame has toolbar. |
| wxHF_FLAT_TOOLBAR | Help frame has toolbar with flat buttons (aka coolbar). |
| wxHF_CONTENTS | Help frame has contents panel. |
| wxHF_INDEX | Help frame has index panel. |
| wxHF_SEARCH | Help frame has search panel. |
| wxHF_BOOKMARKS | Help frame has bookmarks controls. |
| wxHF_OPEN_FILES | Allow user to open arbitrary HTML document. |
| wxHF_PRINT | Toolbar contains "print" button. |
| wxHF_MERGE_BOOKS | Contents pane does not show book nodes. All books are merged together and appear as single book to the user. |
| wxHF_ICONS_BOOK | All nodes in contents pane have a book icon. This is how Microsoft's HTML help viewer behaves. |
| wxHF_ICONS_FOLDER | Book nodes in contents pane have a book icon, book's sections have a folder icon. This is the default. |
| wxHF_ICONS_BOOK_CHAPTER | Both book nodes and nodes of top-level sections of a book (i.e. chapters) have a book icon, all other sections (sections, subsections, ...) have a folder icon. |
| wxHF_DEFAULT_STYLE | wxHF_TOOLBAR | wxHF_CONTENTS | wxHF_INDEX | wxHF_SEARCH | wxHF_BOOKMARKS | wxHF_PRINT |
Creates the frame. See the constructor for parameters description.
Creates contents panel. (May take some time.)
Protected.
Creates index panel. (May take some time.)
Protected.
Creates search panel.
Displays page x. If not found it will give the user the choice of searching books. Looking for the page runs in these steps:
The second form takes numeric ID as the parameter. (uses extension to MS format, <param name="ID" value=id>)
Displays contents panel.
Displays index panel.
Return wxHtmlHelpData object.
Search for given keyword. Optionally it searches through the index (mode = wxHELP_SEARCH_INDEX), default the content (mode = wxHELP_SEARCH_ALL).
Reads user's settings for this frame (see wxHtmlHelpController::ReadCustomization )
Refresh all panels. This is necessary if a new book was added.
Protected.
Sets the frame's title format. format must contain exactly one "%s" (it will be replaced by the page title).
Add books to search choice panel.
Saves user's settings for this frame (see wxHtmlHelpController::WriteCustomization ).
You may override this virtual method to add more buttons into help frame's toolbar. toolBar is a pointer to the toolbar and style is the style flag as passed to Create method.
wxToolBar::Realize is called immediately after returning from this function.
See samples/html/helpview for an example.
This class stores all necessary information about hypertext links (as represented by <A> tag in HTML documents). In current implementation it stores URL and target frame name. Note that frames are not currently supported by wxHTML!
Default ctor.
Construct hypertext link from HREF (aka URL) and TARGET (name of target frame).
Return pointer to event that generated OnLinkClicked event. Valid only within wxHtmlWindow::OnLinkClicked , NULL otherwise.
Return pointer to the cell that was clicked. Valid only within wxHtmlWindow::OnLinkClicked , NULL otherwise.
Return HREF value of the <A> tag.
Return TARGET value of the <A> tag (this value is used to specify in which frame should be the page pointed by Href opened).
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 OnGetItem() function.
Normal constructor which calls Create() internally.
Default constructor, you must call Create() later.
Destructor cleans up whatever resources we use.
Creates the control and optionally sets the initial number of items in it (it may also be set or changed later with SetItemCount() ).
There are no special styles defined for wxHtmlListBox, in particular the wxListBox styles can not be used here.
Returns true on success or false if the control couldn't be created
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.
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 SetSelectionBackground allows to change the selection background for all cells at once and doing anything more fancy is probably going to look strangely.
This virtual function may be overridden to customize the appearance of the selected cells. It is used to determine how the colour 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.
This method must be implemented in the derived class and should return the body (i.e. without <html> nor <body> tags) of the HTML fragment for the given item.
This function may be overridden to decorate HTML returned by OnGetItem() .
Classes derived from this handle the 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 Parse method.
Constructor.
This may (and may not) be overwritten in derived class.
This method is called each time new tag is about to be added. 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.
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 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.
Must be overwritten in derived class.
This method is called by DoParsing each time a part of text is parsed. txt is NOT only one word, it is substring of input. It is not formatted or preprocessed (so white spaces are unmodified).
Parses the m_Source from begin_pos to end_pos-1. (in noparams version it parses whole m_Source)
This must be called after DoParsing().
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
wxFSFile *f = m_Parser -> GetFS() -> OpenFile("image.jpg");
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.
Returns pointer to the source being parsed.
Setups the parser for parsing the source string. (Should be overridden in derived class)
Opens given URL and returns 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 OpenURL in derived class.
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:
You shouldn't use InitParser, DoParsing, GetProduct or DoneParser directly.
Imagine you want to parse following pseudo-html structure:
<myitems>
<param name="one" value="1">
<param name="two" value="2">
</myitems>
<execute>
<param program="text.exe">
</execute>
It is obvious that you cannot use only one tag handler for <param> tag. Instead you must use context-sensitive handlers for <param> inside <myitems> and <param> inside <execute>.
This is the preferred solution:
TAG_HANDLER_BEGIN(MYITEM, "MYITEMS")
TAG_HANDLER_PROC(tag)
{
// ...something...
m_Parser -> PushTagHandler(this, "PARAM");
ParseInner(tag);
m_Parser -> PopTagHandler();
// ...something...
}
TAG_HANDLER_END(MYITEM)
Forces the handler to handle additional tags (not returned by GetSupportedTags ). The handler should already be added to this parser.
Restores parser's state before last call to PushTagHandler .
Sets the virtual file system that will be used to request additional files. (For example <IMG> tag handler requests wxFSFile with the image data.)
Call this function to interrupt parsing from a tag handler. No more tags will be parsed afterward. This function may only be called from wxHtmlParser::Parse or any function called by it (i.e. from tag handlers).
This class serves as printout class for HTML documents.
Constructor.
Adds a filter to the static list of filters for wxHtmlPrintout. See wxHtmlFilter for further information.
Sets fonts. See wxHtmlWindow::SetFonts for detailed description.
Sets page footer.
Sets page header.
Prepare the class for printing this HTML file . The file may be located on any virtual file system or it may be normal file.
Prepare the class for printing this HTML text.
Sets margins in millimeters. Defaults to 1 inch for margins and 0.5cm for space between text and header and/or footer
This class represents a single HTML tag. It is used by tag handlers .
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.
Returns a string containing all parameters.
Example : tag contains <FONT SIZE=+2 COLOR="#000000"> . Call to tag.GetAllParams() would return SIZE=+2 COLOR="#000000" .
Returns beginning position of the text between this tag and paired ending tag. See explanation (returned position is marked with `|'):
bla bla bla <MYTAG> bla bla internal text</MYTAG> bla bla
|
Returns ending position of the text between this tag and paired ending tag. See explanation (returned position is marked with `|'):
bla bla bla <MYTAG> bla bla internal text</MYTAG> bla bla
|
Returns ending position 2 of the text between this tag and paired ending tag. See explanation (returned position is marked with `|'):
bla bla bla <MYTAG> bla bla internal text</MYTAG> bla bla
|
Returns tag's name. The name is always in uppercase and it doesn't contain '<' or '/' characters. (So the name of <FONT SIZE=+2> tag is "FONT" and name of </table> is "TABLE")
...
/* you have wxHtmlTag variable tag which is equal to
HTML tag <FONT SIZE=+2 COLOR="#0000FF"> */
dummy = tag.GetParam("SIZE");
// dummy == "+2"
dummy = tag.GetParam("COLOR");
// dummy == "#0000FF"
dummy = tag.GetParam("COLOR", true);
// dummy == "\"#0000FF\"" -- see the difference!!
Returns the value of the parameter. You should check whether the parameter exists or not (use HasParam ) first.
Interprets tag parameter par as colour specification and saves its value into wxColour variable pointed by clr .
Returns true on success and false if par is not colour specification or if the tag has no such parameter.
Interprets tag parameter par as an integer and saves its value into int variable pointed by value .
Returns true on success and false if par is not an integer or if the tag has no such parameter.
Returns true if this tag is paired with ending tag, false otherwise.
See the example of HTML document:
<html><body> Hello<p> How are you? <p align=center>This is centered...</p> Oops<br>Oooops! </body></html>
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.
Returns true if the tag has a parameter of the given name. Example : <FONT SIZE=+2 COLOR="#FF00FF"> has two parameters named "SIZE" and "COLOR".
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 format ).
Constructor.
Returns list of supported tags. The list is in uppercase and tags are delimited by ','. Example : "I,B,FONT,P"
bool MyHandler::HandleTag(const wxHtmlTag& tag)
{
...
// change state of parser (e.g. set bold face)
ParseInner(tag);
...
// restore original state of parser
}
You shouldn't call ParseInner if the tag is not paired with an ending one.
This is the core method of each handler. It is called each time one of supported tags is detected. tag contains all necessary info (see wxHtmlTag for details).
This method calls parser's DoParsing method for the string between this tag and the paired ending tag:
...<A HREF="x.htm">Hello, world!</A>...
In this example, a call to ParseInner (with tag pointing to A tag) will parse 'Hello, world!'.
Assigns parser to this handler. Each instance of handler is guaranteed to be called only from the parser.
This class provides easy way of filling wxHtmlWinParser's table of tag handlers. It is used almost exclusively together with the set of TAGS_MODULE_* macros
You must override this method. In most common case its body consists only of lines of the following type:
parser -> AddTagHandler(new MyHandler);
I recommend using the TAGS_MODULE_* macros.
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.
Constructor.
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 .
Constructor. Don't use the default one, use constructor with wnd parameter ( wnd is pointer to associated wxHtmlWindow )
Adds module to the list of wxHtmlWinParser tag handler.
Closes the container, sets actual container to the parent one and returns pointer to it (see Overview ).
Creates font based on current setting (see SetFontSize , SetFontBold , SetFontItalic , SetFontFixed , SetFontUnderlined ) and returns pointer to it. If the font was already created only a pointer is returned.
Returns actual text colour.
Returns default horizontal alignment.
Returns (average) char height in standard font. It is used as DC-independent metrics.
Note: This function doesn't return the actual height. If you want to know the height of the current font, call GetDC -> GetCharHeight() .
Returns average char width in standard font. It is used as DC-independent metrics.
Note: This function doesn't return the actual width. If you want to know the height of the current font, call GetDC -> GetCharWidth()
Returns pointer to the currently opened container (see Overview ). Common use:
m_WParser -> GetContainer() -> InsertCell(new ...);
Returns pointer to the DC used during parsing.
Returns wxEncodingConverter class used to do conversion between input encoding and output encoding .
Returns true if actual font is bold, false otherwise.
Returns actual font face name.
Returns true if actual font is fixed face, false otherwise.
Returns true if actual font is italic, false otherwise.
Returns actual font size (HTML size varies from -2 to +4)
Returns true if actual font is underlined, false otherwise.
Returns input encoding.
Returns actual hypertext link. (This value has a non-empty Href string if the parser is between <A> and </A> tags, wxEmptyString otherwise.)
Returns the colour of hypertext link text.
Returns output encoding, i.e. closest match to document's input encoding that is supported by operating system.
Returns associated window (wxHtmlWindow). This may be NULL! (You should always test if it is non-NULL. For example TITLE handler sets window title only if some window is associated, otherwise it does nothing)
Opens new container and returns pointer to it (see Overview ).
Sets actual text colour. Note: this DOESN'T change the colour! You must create wxHtmlColourCell yourself.
Sets default horizontal alignment (see wxHtmlContainerCell::SetAlignHor .) Alignment of newly opened container is set to this value.
Allows you to directly set opened container. This is not recommended - you should use OpenContainer wherever possible.
Sets the DC. This must be called before Parse ! 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.)
Sets bold flag of actualfont. x is either true of false.
Sets current font face to face . This affects either fixed size font or proportional, depending on context (whether the parser is inside <TT> tag or not).
Sets fixed face flag of actualfont. x is either true of false.
Sets italic flag of actualfont. x is either true of false.
Sets actual font size (HTML size varies from 1 to 7)
Sets underlined flag of actualfont. x is either true of false.
Sets fonts. See wxHtmlWindow::SetFonts for detailed description.
Sets input encoding. The parser uses this information to build conversion tables from document's encoding to some encoding supported by operating system.
Sets actual hypertext link. Empty link is represented by wxHtmlLinkInfo with Href equal to wxEmptyString.
Sets colour of hypertext link.
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).
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 SetPage(text) , LoadPage(filename) or LoadFile .
Default constructor.
Constructor. The parameters are the same as for the wxScrolledWindow constructor.
Adds input filter to the static list of available filters. These filters are present by default:
Appends HTML fragment to currently displayed text and refreshes the window.
Returns pointer to the top-level container.
See also Cells Overview , Printing Overview
Returns anchor within currently opened page (see GetOpenedPage ). If no page is opened or if the displayed page wasn't produced by call to LoadPage, empty string is returned.
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.
Returns title of the opened page or wxEmptyString if current page does not contain <TITLE> tag.
Returns the related frame.
Moves back to the previous page. (each page displayed using LoadPage is stored in history list.)
Returns true if it is possible to go back in the history (i.e. HistoryBack() won't fail).
Returns true if it is possible to go forward in the history (i.e. HistoryBack() won't fail).
Clears history.
Moves to next page in history.
Loads HTML page from file and displays it.
Unlike SetPage this function first loads HTML page from location and then displays it. See example:
htmlwin->LoadPage("help/myproject/index.htm");
This method is called when a mouse button is clicked inside wxHtmlWindow. The default behaviour is to call OnLinkClicked if the cell contains a hypertext link.
This method is called when a mouse moves over an HTML cell.
Called when user clicks on hypertext link. Default behaviour is to call LoadPage and do nothing else.
Also see wxHtmlLinkInfo .
| wxHTML_OPEN | Open the URL. |
| wxHTML_BLOCK | Deny access to the URL, wxHtmlParser::OpenURL will return NULL. |
| wxHTML_REDIRECT | Don't open url , redirect to another URL. OnOpeningURL must fill *redirect with the new URL. OnOpeningURL will be called again on returned URL. |
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 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 wxHTML_OPEN .
Called on parsing <TITLE> tag.
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 wxHtmlWindow
Read values: all things set by SetFonts, SetBorders.
Selects all text in the window.
Returns current selection as plain text. Returns empty string if no text is currently selected.
Selects the line of text that pos points at. Note that pos is relative to the top of displayed page, not to window's origin, use CalcUnscrolledPosition to convert physical coordinate.
Selects the word at position pos . Note that pos is relative to the top of displayed page, not to window's origin, use CalcUnscrolledPosition to convert physical coordinate.
This function sets the space between border of window and HTML contents. See image:
\helponly{\image{}{border.bmp}}
This function sets font sizes and faces.
\wxheading{Defaults}
Default font sizes are defined by constants wxHTML_FONT_SIZE_1, wxHTML_FONT_SIZE_2, ..., wxHTML_FONT_SIZE_7. Note that they differ among platforms. Default face names are empty strings.
Sets HTML page and display it. This won't load the page!! It will display the source . See example:
htmlwin -> SetPage("<html><body>Hello, world!</body></html>");
If you want to load a document from some location use LoadPage instead.
Sets the frame in which page title will be displayed. format is format of frame title, e.g. "HtmlHelp : %s". It must contain exactly one %s. This %s is substituted with HTML page title.
After calling SetRelatedFrame , this sets statusbar slot where messages will be displayed. (Default is -1 = no messages.)
Returns content of currently displayed page as plain text.
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 wxHtmlWindow .
Saved values: all things set by SetFonts, SetBorders.
Set the address to hostname , which can be a host name or an IP-style address in dot notation (a.b.c.d)
Returns the hostname which matches the IP address.
Returns a wxString containing the IP address in dot quad (127.0.0.1) format.
Set the port to that corresponding to the specified service .
Set the port to that corresponding to the specified service .
Returns the current service.
Set address to any of the addresses of the current machine. Whenever possible, use this function instead of wxIPV4address::LocalHost , as this correctly handles multi-homed hosts and avoids other small problems. Internally, this is the same as setting the IP address to INADDR_ANY .
Set address to localhost (127.0.0.1). Whenever possible, use the wxIPV4address::AnyAddress , function instead of this one, as this will correctly handle multi-homed hosts and avoid other small problems.
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.
Set the address to hostname , which can be a host name or an IP-style address in a format dependent on implementation.
Returns the hostname which matches the IP address.
Returns a wxString containing the IP address.
Set the port to that corresponding to the specified service .
Set the port to that corresponding to the specified service .
Returns the current service.
Internally, this is the same as setting the IP address to INADDR_ANY .
On IPV4 implementations, 0.0.0.0
On IPV6 implementations, ::
Set address to localhost.
On IPV4 implementations, 127.0.0.1
On IPV6 implementations, ::1
Determines if current address is set to localhost.
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.
It is usually desirable to associate a pertinent icon with a frame. Icons can also be used for other purposes, for example with wxTreeCtrl and wxListCtrl .
Icons have different formats on different platforms. Therefore, separate icons will usually be created for the different environments. Platform-specific methods for creating a wxIcon structure are catered for, and this is an occasion where conditional compilation will probably be required.
Note that a new icon must be created for every time the icon is to be used for a new window. In Windows, the icon will not be reloaded if it has already been used. An icon allocated to a frame will be deleted when the frame is deleted.
For more information please see Bitmap and icon overview .
Objects:
wxNullIcon
Default constructor.
Copy constructor.
Creates an icon from the given data, which can be of arbitrary type.
Creates an icon from an array of bits.
Creates a new icon.
Creates an icon from XPM data.
Loads an icon from a file or resource.
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.
The second and third forms provide copy constructors. Note that these do not copy the icon data, but instead a pointer to the data, keeping a reference count. They are therefore very efficient operations.
The fourth form constructs an icon from data whose type and value depends on the value of the type argument.
The fifth form constructs a (usually monochrome) icon from an array of pixel values, under both X and Windows.
The sixth form constructs a new icon.
The seventh form constructs an icon from pixmap (XPM) data, if wxWidgets has been configured to incorporate this feature.
To use this constructor, you must first include an XPM file. For example, assuming that the file mybitmap.xpm contains an XPM array of character pointers called mybitmap:
#include "mybitmap.xpm" ... wxIcon *icon = new wxIcon(mybitmap);
A macro, wxICON, is available which creates an icon using an XPM on the appropriate platform, or an icon resource on Windows.
wxIcon icon(wxICON(mondrian));
// Equivalent to:
#if defined(__WXGTK__) || defined(__WXMOTIF__)
wxIcon icon(mondrian_xpm);
#endif
#if defined(__WXMSW__)
wxIcon icon("mondrian");
#endif
The eighth form constructs an icon from a file or resource. name can refer to a resource name under MS Windows, or a filename under MS Windows and X.
Under Windows, type defaults to wxBITMAP_TYPE_ICO_RESOURCE. Under X, type defaults to wxBITMAP_TYPE_XPM.
Loads an icon from the specified location .
Copies bmp bitmap to this icon. Under MS Windows the bitmap must have mask colour set.
Destroys the wxIcon object and possibly the underlying icon data. Because reference counting is used, the icon may not actually be destroyed at this point - only when the reference count is zero will the data be deleted.
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.
Gets the colour depth of the icon. A value of 1 indicates a monochrome icon.
Gets the height of the icon in pixels.
Gets the width of the icon in pixels.
Loads an icon from a file or resource.
Returns true if icon data is present.
\begin{comment}
Depending on how wxWidgets has been configured, not all formats may be available.
Saves an icon in the named file.
Sets the depth member (does not affect the icon data).
Sets the height member (does not affect the icon data).
Sets the width member (does not affect the icon data).
Assignment operator. This operator does not copy any data, but instead passes a pointer to the data in icon and increments a reference counter. It is a fast operation.
Equality operator. This operator tests whether the internal data pointers are equal (a fast test).
Inequality operator. This operator tests whether the internal data pointers are unequal (a fast test).
This class contains multiple copies of an icon in different sizes, see also wxDialog::SetIcons and wxTopLevelWindow::SetIcons .
Default constructor.
Initializes the bundle with the icon(s) found in the file.
Initializes the bundle with a single icon.
Copy constructor.
Destructor.
Adds all the icons contained in the file to the bundle; if the collection already contains icons with the same width and height, they are replaced by the new ones.
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.
Returns the icon with the given size; if no such icon exists, returns the icon with size wxSYS_ICON_X/wxSYS_ICON_Y; if no such icon exists, returns the first icon in the bundle. If size = wxSize( -1, -1 ), returns the icon with size wxSYS_ICON_X/wxSYS_ICON_Y.
Same as GetIcon( wxSize( size, size ) ).
Assignment operator.
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.
Returns true if the object is valid, i.e. was properly initialized, and false otherwise.
An event being sent when the frame is iconized (minimized) or restored.
Currently only wxMSW and wxGTK generate such events.
Constructor.
Returns true if the frame has been iconized, false if it has been restored.
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 RequestMore method in your handler or call wxWakeUpIdle periodically (for example from timer event), 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.
Constructor.
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 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.
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 wxIdleEvent::SetMode .
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.
Returns true if the OnIdle function processing this event requested more processing time.
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.
mode can be one of the following values. The default is wxIDLE_PROCESS_ALL.
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
};
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.
Starting from wxWidgets 2.5.0 wxImage supports alpha channel data, that is in addition to a byte for the red, green and blue colour components for each pixel it also stores a byte representing the pixel opacity. An alpha value of 0 corresponds to a transparent pixel (null opacity) while a value of 255 means that the pixel is 100% opaque.
Unlike RGB data, not all images have an alpha channel and before using GetAlpha you should check if this image contains an alpha channel with HasAlpha . Note that currently only images loaded from PNG files with transparency information will have an alpha channel but alpha support will be added to the other formats as well (as well as support for saving images with alpha channel which also isn't implemented).
The following image handlers are available. wxBMPHandler is always installed by default. To use other image formats, install the appropriate handler with wxImage::AddHandler or wxInitAllImageHandlers .
When saving in PCX format, wxPCXHandler will count the number of different colours in the image; if there are 256 or less colours, it will save as 8 bit, else it will save as 24 bit.
Loading PNMs only works for ASCII or raw RGB images. When saving in PNM format, wxPNMHandler will always save as raw RGB.
Default constructor.
Copy constructor.
(Deprecated form, use wxBitmap::ConvertToImage instead.) Constructs 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.
Creates an image with the given width and height. If clear is true, the new image will be initialized to black. Otherwise, the image data will be uninitialized.
Creates an image from given data with the given width and height. If static_data is true, then wxImage will not delete the actual image data in its destructor, otherwise it will free it by calling free() .
Loads an image from a file.
Loads an image from an input stream.
Depending on how wxWidgets has been configured, not all formats may be available.
Note: any handler other than BMP must be previously initialized with wxImage::AddHandler or wxInitAllImageHandlers .
Note: you can use GetOptionInt to get the hotspot for loaded cursor file:
int hotspot_x = image.GetOptionInt(wxIMAGE_OPTION_CUR_HOTSPOT_X);
int hotspot_y = image.GetOptionInt(wxIMAGE_OPTION_CUR_HOTSPOT_Y);
Creates an image from XPM data.
Destructor.
Adds a handler to the end of the static list of format handlers.
returns true if the current image handlers can read this file
Deletes all image handlers.
This function is called by wxWidgets on exit.
Computes the histogram of the image. histogram is a reference to wxImageHistogram object. wxImageHistogram is a specialization of wxHashMap "template" and is defined as follows:
class WXDLLEXPORT wxImageHistogramEntry
{
public:
wxImageHistogramEntry() : index(0), value(0) {}
unsigned long index;
unsigned long value;
};
WX_DECLARE_EXPORTED_HASH_MAP(unsigned long, wxImageHistogramEntry,
wxIntegerHash, wxIntegerEqual,
wxImageHistogram);
If the image has alpha channel, this method converts it to mask. All pixels with alpha value less than 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.
Deprecated, use equivalent wxBitmap constructor (which takes wxImage and depth as its arguments) instead.
Returns monochromatic version of the image. The returned image has white colour where the original has (r,g,b) colour and black colour everywhere else.
Returns an identical copy of the image.
Creates a fresh image. If clear is true, the new image will be initialized to black. Otherwise, the image data will be uninitialized.
Destroys the image data.
Finds the first colour that is never used in the image. The search begins at given initial colour and continues by increasing R, G and B components (in this order) by 1 until an unused colour is found or the colour space exhausted.
Finds the handler with the given name.
Finds the handler associated with the given extension and type.
Finds the handler associated with the given image type.
Finds the handler associated with the given MIME type.
wxFileDialog FileDlg( this, "Choose Image", ::wxGetWorkingDirectory(), "", _("Image Files ") + wxImage::GetImageExtWildcard(), wxOPEN );
Iterates all registered wxImageHandler objects, and returns a string containing file extension masks suitable for passing to file open/save dialog boxes.
Returns the alpha value for the given pixel. This function may only be called for the images with alpha channel, use HasAlpha to check for this.
The returned value is the opacity of the image, i.e. the value of 0 corresponds to the transparent pixels while the value of 255 -- to the opaque ones.
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.
Returns the blue intensity at the given coordinate.
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\ldots 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 wxImage::SetData .
Returns the green intensity at the given coordinate.
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.
Returns the static list of image format handlers.
Gets the height of the image in pixels.
Gets the blue value of the mask colour.
Gets the green value of the mask colour.
Gets the red value of the mask colour.
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.
Returns the palette associated with the image. Currently the palette is only used when converting to wxBitmap under Windows.
Eventually wxImage handlers will set the palette if one exists in the image file.
Returns the red intensity at the given coordinate.
Returns a sub image of the current one as long as the rect belongs entirely to the image.
Gets the width of the image in pixels.
Constructor for HSVValue, an object that contains values for hue, saturation and value which represent the value of a color. It is used by wxImage::HSVtoRGB and wxImage::RGBtoHSV , which converts between HSV color space and RGB color space.
Converts a color in HSV color space to RGB color space.
Returns true if there is a mask active, false otherwise.
Gets a user-defined option. The function is case-insensitive to name .
For example, when saving as a JPEG file, the option quality is used, which is a number between 0 and 100 (0 is terrible, 100 is very good).
Gets a user-defined option as an integer. The function is case-insensitive to name .
If the given option is not present, the function returns 0. Use wxImage::HasOption is 0 is a possibly valid value for the option.
Options for wxPNGHandler
| wxIMAGE_OPTION_PNG_FORMAT | Format for saving a PNG file. |
| wxIMAGE_OPTION_PNG_BITDEPTH | Bit depth for every channel (R/G/B/A). |
Supported values for wxIMAGE_OPTION_PNG_FORMAT:
| wxPNG_TYPE_COLOUR | Stores RGB image. |
| wxPNG_TYPE_GREY | Stores grey image, converts from RGB. |
| wxPNG_TYPE_GREY_RED | Stores grey image, uses red value as grey. |
Returns true if the given option is present. The function is case-insensitive to name .
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.
Adds a handler at the start of the static list of format handlers.
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 threshold .
Loads an image from a file. If no handler type is provided, the library will try to autodetect the format.
Depending on how wxWidgets has been configured, not all formats may be available.
Note: you can use GetOptionInt to get the hotspot for loaded cursor file:
int hotspot_x = image.GetOptionInt(wxIMAGE_OPTION_CUR_HOTSPOT_X);
int hotspot_y = image.GetOptionInt(wxIMAGE_OPTION_CUR_HOTSPOT_Y);
\wxheading{Return value}
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.
Loads an image from an input stream.
Returns true if image data is present.
Constructor for RGBValue, an object that contains values for red, green and blud which represent the value of a color. It is used by wxImage::HSVtoRGB and wxImage::RGBtoHSV , which converts between HSV color space and RGB color space.
Converts a color in RGB color space to HSV color space.
Finds the handler with the given name, and removes it. The handler is not deleted.
Returns a mirrored copy of the image. The parameter horizontally indicates the orientation.
Replaces the colour specified by r1,g1,b1 by the colour r2,g2,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.
Returns the (modified) image itself.
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 size and background colour at the position pos relative to the upper left of the new image. If 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.
Rotates the image about the given point, by angle radians. Passing true to 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.
Rotates the hue of each pixel in the image by 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.
Returns a copy of the image rotated 90 degrees in the direction indicated by clockwise .
Saves an image in the named file.
Saves an image in the named file. File type is determined from the extension of the file name. Note that this function may fail if the extension is not recognized! You can use one of the forms above to save images to files with non-standard extensions.
Depending on how wxWidgets has been configured, not all formats may be available.
Note: you can use GetOptionInt to set the hotspot before saving an image into a cursor file (default hotspot is in the centre of the image):
image.SetOption(wxIMAGE_OPTION_CUR_HOTSPOT_X, hotspotX);
image.SetOption(wxIMAGE_OPTION_CUR_HOTSPOT_Y, hotspotY);
Saves an image in the given stream.
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 may be mentioned that the GTK port uses this function internally to scale bitmaps when using mapping modes in wxDC.
Example:
// get the bitmap from somewhere
wxBitmap bmp = ...;
// rescale it to have size of 32*32
if ( bmp.GetWidth() != 32 || bmp.GetHeight() != 32 )
{
wxImage image = bmp.ConvertToImage();
bmp = wxBitmap(image.Scale(32, 32));
// another possibility:
image.Rescale(32, 32);
bmp = image;
}
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 size and background colour at the position pos relative to the upper left of the new image. If 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.
This function is similar to SetData and has similar restrictions. The pointer passed to it may however be NULL in which case the function will allocate the alpha array internally -- this is useful to add alpha channel data to an image which doesn't have any. If the pointer is not NULL , it must have one byte for each image pixel and be allocated with malloc() . wxImage takes ownership of the pointer and will free it unless static_data parameter is set.to true -- in this case the caller should do it.
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.
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 malloc() , NOT with 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 wxImage::GetData .
Specifies whether there is a mask or not. The area of the mask is determined by the current mask colour.
Sets the mask colour for this image (and tells the image to use the mask).
Sets image's mask so that the pixels that have RGB value of mr,mg,mb in mask will be masked in the image. This is done by first finding an unused colour in the image, setting this colour as the mask colour and then using this colour to draw all pixels in the image who corresponding pixel in mask has given RGB value.
Sets a user-defined option. The function is case-insensitive to name .
For example, when saving as a JPEG file, the option quality is used, which is a number between 0 and 100 (0 is terrible, 100 is very good).
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).
Sets the pixel at the given coordinate. This routine performs bounds-checks for the coordinate so it can be considered a safe way to manipulate the data, but in some cases this might be too slow so that the data will have to be set directly. In that case you will have to get access to the image data using the GetData method.
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.
Assignment operator. This operator does not copy any data, but instead passes a pointer to the data in image and increments a reference counter. It is a fast operation.
Equality operator. This operator tests whether the internal data pointers are equal (a fast test).
Inequality operator. This operator tests whether the internal data pointers are unequal (a fast test).
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.
Default constructor. In your own default constructor, initialise the members m_name, m_extension and m_type.
Destroys the wxImageHandler object.
Gets the name of this handler.
Gets the file extension associated with this handler.
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.
Gets the image type associated with this handler.
Gets the MIME type associated with this handler.
Sets the handler name.
Sets the handler extension.
Sets the handler MIME type.
Sets the handler type.
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.
Default constructor.
Constructor specifying the image size, whether image masks should be created, and the initial size of the list.
Adds a new image using a bitmap and optional mask bitmap.
Adds a new image using a bitmap and mask colour.
The original bitmap or icon is not affected by the Add operation, and can be deleted afterwards.
Adds a new image using an icon.
Initializes the list. See wxImageList::wxImageList for details.
Draws a specified image onto a device context.
Returns the bitmap corresponding to the given index.
Returns the icon corresponding to the given index.
Returns the number of images in the list.
Retrieves the size of the images in the list. Currently, the index parameter is ignored as all images in the list have the same size.
Removes the image at the given position.
Removes all the images in the list.
Replaces the existing image with the new image.
Windows only.
The original bitmap or icon is not affected by the Replace operation, and can be deleted afterwards.
Replaces the existing image with the new image.
Objects of this class are stored in the wxLayoutConstraint class as one of eight possible constraints that a window can be involved in.
Constraints are initially set to have the relationship wxUnconstrained, which means that their values should be calculated by looking at known constraints.
Constructor. Not used by the end-user.
Constrains this edge to be above the given window, with an optional margin. Implicitly, this is relative to the top edge of the other window.
Constrains this edge or dimension to be the given absolute value.
Sets this edge or constraint to be whatever the window's value is at the moment. If either of the width and height constraints are as is , the window will not be resized, but moved instead. This is important when considering panel items which are intended to have a default size, such as a button, which may take its size from the size of the button label.
Constrains this edge to be below the given window, with an optional margin. Implicitly, this is relative to the bottom edge of the other window.
Sets this edge or dimension to be unconstrained, that is, dependent on other edges and dimensions from which this value can be deduced.
Constrains this edge to be to the left of the given window, with an optional margin. Implicitly, this is relative to the left edge of the other window.
Constrains this edge or dimension to be to a percentage of the given window, with an optional margin.
Constrains this edge to be to the right of the given window, with an optional margin. Implicitly, this is relative to the right edge of the other window.
Constrains this edge or dimension to be to the same as the edge of the given window, with an optional margin.
Sets the properties of the constraint. Normally called by one of the convenience functions such as Above, RightOf, SameAs.
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 .
Constructor.
wxInputStream is an abstract base class which may not be used directly.
Creates a dummy input stream.
Destructor.
Returns true if some data is available in the stream right now, so that calling Read() wouldn't block.
Returns the first character in the input queue and removes it, blocking until it appears if necessary.
Returns true if the end of stream has been reached.
Returns the last number of bytes read.
Returns the first character in the input queue without removing it.
Reads the specified amount of bytes and stores the data in buffer .
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.
Changes the stream current position.
Returns the current stream position.
This function is only useful in read mode. It is the manager of the "Write-Back" buffer. This buffer acts like a temporary buffer where data which has to be read during the next read IO call are put. This is useful when you get a big block of data which you didn't want to read: you can replace them at the top of the input queue by this way.
Be very careful about this call in connection with calling SeekI() on the same stream. Any call to SeekI() will invalidate any previous call to this method (otherwise you could SeekI() to one position, "unread" a few bytes there, SeekI() to another position and data would be either lost or corrupted).
This function acts like the previous one except that it takes only one character: it is sometimes shorter to use than the generic function.
wxJoystick allows an application to control one or more joysticks.
Constructor. joystick may be one of wxJOYSTICK1, wxJOYSTICK2, indicating the joystick controller of interest.
Destroys the wxJoystick object.
Returns the state of the joystick buttons. Every button is mapped to a single bit in the returned integer, with the first button being mapped to the least significant bit, and so on. A bitlist of wxJOY_BUTTONn identifiers, where n is 1, 2, 3 or 4 is available for historical reasons.
Returns the manufacturer id.
Returns the movement threshold, the number of steps outside which the joystick is deemed to have moved.
Returns the number of axes for this joystick.
Returns the number of buttons for this joystick.
Returns the number of joysticks currently attached to the computer.
Returns the maximum polling frequency.
Returns the minimum polling frequency.
Returns the product id for the joystick.
Returns the product name for the joystick.
Returns the x, y position of the joystick.
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.
Returns the point-of-view position, expressed in continuous, one-hundredth of a degree units. Returns -1 on error.
Returns the maximum rudder position.
Returns the minimum rudder position.
Returns the rudder position.
Returns the maximum U position.
Returns the minimum U position.
Gets the position of the fifth axis of the joystick, if it exists.
Returns the maximum V position.
Returns the minimum V position.
Gets the position of the sixth axis of the joystick, if it exists.
Returns the maximum x position.
Returns the minimum x position.
Returns the maximum y position.
Returns the minimum y position.
Returns the maximum z position.
Returns the minimum z position.
Returns the z position of the joystick.
Returns true if the joystick has a point of view control.
Returns true if the joystick point-of-view supports discrete values (centered, forward, backward, left, and right).
Returns true if the joystick point-of-view supports continuous degree bearings.
Returns true if there is a rudder attached to the computer.
Returns true if the joystick has a U axis.
Returns true if the joystick has a V axis.
Returns true if the joystick has a Z axis.
Returns true if the joystick is functioning.
Sets the movement threshold, the number of steps outside which the joystick is deemed to have moved.
This event class contains information about mouse events, particularly events received by windows.
Constructor.
Returns true if the event was a down event from the specified button (or any button).
Returns true if the specified button (or any button) was in a down state.
Returns true if the event was an up event from the specified button (or any button).
Returns the identifier of the button changing state. This is a wxJOY_BUTTONn identifier, where n is one of 1, 2, 3, 4.
Returns the down state of the buttons. This is a bitlist of wxJOY_BUTTONn identifiers, where n is one of 1, 2, 3, 4.
Returns the identifier of the joystick generating the event - one of wxJOYSTICK1 and wxJOYSTICK2.
Returns the x, y position of the joystick event.
Returns the z position of the joystick event.
Returns true if this was a button up or down event ( not 'is any button down?').
Returns true if this was an x, y move event.
Returns true if this was a z move event.
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 WXK_XXX values from the keycodes table . 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 'A' key is pressed, the key down event key code is equal to ASCII A == 65. But the char event key code is ASCII a == 97. On the other hand, if you press both Shift and 'A' keys simultaneously , the key code in key down event will still be just 'A' while the char event key code parameter will now be '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 ShiftDown() , in general you should use 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 '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 text wxWidgets sample and pressing some keys in any of the text controls shown in it.
Note: If a key down ( EVT_KEY_DOWN ) event is caught and the event handler does not call event.Skip() then the corresponding char event ( 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 WM_KEYDOWN and WM_CHAR events. In particular, Alt-x combination will generate a char event in wxWidgets (unless it is used as an accelerator).
Tip: be sure to call event.Skip() for events that you don't process in key event function, otherwise menu shortcuts may cease to work under Windows.
Constructor. Currently, the only valid event types are wxEVT_CHAR and wxEVT_CHAR_HOOK.
Returns true if the Alt key was down at the time of the key event.
"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() .
Returns true if the control key was down at the time of the key event.
Returns the virtual key code. ASCII events return normal ASCII values, while non-ASCII events return values such as WXK_LEFT for the left cursor key. See 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 .
Obtains the position (in client coordinates) at which the key was pressed.
Returns the raw key code for this event. This is a platform-dependent scan code which should only be used in advanced applications.
NB: Currently the raw key codes are not supported by all ports, use #ifdef wxHAS_RAW_KEY_CODES to determine if this feature is available.
Returns the low level key flags for this event. The flags are platform-dependent and should only be used in advanced applications.
NB: Currently the raw key flags are not supported by all ports, use #ifdef wxHAS_RAW_KEY_CODES to determine if this feature is available.
Returns the Unicode character corresponding to this key event.
This function is only available in Unicode build, i.e. when wxUSE_UNICODE is 1.
Returns the X position (in client coordinates) of the event.
Returns the Y (in client coordinates) position of the event.
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).
Returns true if the Meta key was down at the time of the key event.
Returns true if the shift key was down at the time of the key event.
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).
Note: wxLayoutAlgorithm has nothing to do with wxLayoutConstraints. It is an alternative way of specifying layouts for which the normal constraint system is unsuitable.
enum wxLayoutOrientation {
wxLAYOUT_HORIZONTAL,
wxLAYOUT_VERTICAL
};
enum wxLayoutAlignment {
wxLAYOUT_NONE,
wxLAYOUT_TOP,
wxLAYOUT_LEFT,
wxLAYOUT_RIGHT,
wxLAYOUT_BOTTOM,
};
Default constructor.
Destructor.
Lays out the children of a normal frame. mainWindow is set to occupy the remaining space.
This function simply calls wxLayoutAlgorithm::LayoutWindow .
Lays out the children of an MDI parent frame. If 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.
Lays out the children of a normal frame or other window.
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).
Note: constraints are now deprecated and you should use sizers instead.
Objects of this class can be associated with a window to define its layout constraints, with respect to siblings or its parent.
The class consists of the following eight constraints of class wxIndividualLayoutConstraint, some or all of which should be accessed directly to set the appropriate constraints.
Most constraints are initially set to have the relationship wxUnconstrained, which means that their values should be calculated by looking at known constraints. The exceptions are width and height , which are set to wxAsIs to ensure that if the user does not specify a constraint, the existing width and height will be used, to be compatible with panel items which often have take a default size. If the constraint is wxAsIs, the dimension will not be changed.
Constructor.
wxList classes provide linked list functionality for wxWidgets, and for an application if it wishes. Depending on the form of constructor used, a list can be keyed on integer or string keys to provide a primitive look-up ability, but please note that this feature is deprecated . See wxHashMap for a faster method of storage when random access is required.
While wxList class in the previous versions of wxWidgets only could contain elements of type wxObject and had essentially untyped interface (thus allowing you to put apples in the list and read back oranges from it), the new wxList classes family may contain elements of any type and has much more strict type checking. Unfortunately, it also requires an additional line to be inserted in your program for each list class you use (which is the only solution short of using templates which is not done in wxWidgets because of portability issues).
The general idea is to have the base class wxListBase working with void * data but make all of its dangerous (because untyped) functions protected, so that they can only be used from derived classes which, in turn, expose a type safe interface. With this approach a new wxList-like class must be defined for each list type (i.e. list of ints, of wxStrings or of MyObjects). This is done with WX_DECLARE_LIST and WX_DEFINE_LIST macros like this (notice the similarity with WX_DECLARE_OBJARRAY and WX_IMPLEMENT_OBJARRAY macros):
// this part might be in a header or source (.cpp) file
class MyListElement
{
... // whatever
};
// declare our list class: this macro declares and partly implements MyList
// class (which derives from wxListBase)
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/listimpl.cpp>
WX_DEFINE_LIST(MyList);
// now MyList class may be used as a usual wxList, but all of its methods
// will take/return the objects of the right (i.e. MyListElement) type. You
// also have MyList::Node type which is the type-safe version of wxNode.
MyList list;
MyListElement element;
list.Append(element); // ok
list.Append(17); // error: incorrect type
// let's iterate over the list
for ( MyList::Node *node = list.GetFirst(); node; node = node->GetNext() )
{
MyListElement *current = node->GetData();
...process the current element...
}
For compatibility with previous versions wxList and wxStringList classes are still defined, but their usage is deprecated and they will disappear in the future versions completely. The use of the latter is especially discouraged as it is not only unsafe but is also much less efficient than wxArrayString class.
In the documentation of the list classes below, the template notations are used even though these classes are not really templates at all -- but it helps to think about them as if they were. You should replace wxNode<T> with wxListName::Node and T itself with the list element type (i.e. the first parameter of WX_DECLARE_LIST).
It is very common to iterate on a list as follows:
...
wxWindow *win1 = new wxWindow(...);
wxWindow *win2 = new wxWindow(...);
wxList SomeList;
SomeList.Append(win1);
SomeList.Append(win2);
...
wxNode *node = SomeList.GetFirst();
while (node)
{
wxWindow *win = node->GetData();
...
node = node->GetNext();
}
To delete nodes in a list as the list is being traversed, replace
...
node = node->GetNext();
...
with
...
delete win;
delete node;
node = SomeList.GetFirst();
...
See wxNode for members that retrieve the data associated with a node, and members for getting to the next or previous node.
Note : keyed lists are deprecated and should not be used in new code.
Constructors. key_type is one of wxKEY_NONE, wxKEY_INTEGER, or wxKEY_STRING, and indicates what sort of keying is required (if any).
objects is an array of n objects with which to initialize the list.
The variable-length argument list constructor must be supplied with a terminating NULL.
Destroys the list. Also destroys any remaining nodes, but does not destroy client data held in the nodes.
Note : keyed lists are deprecated and should not be used in new code.
Appends a new wxNode to the end of the list and puts a pointer to the object in the node. The last two forms store a key with the object for later retrieval using the key. The new node is returned in each case.
The key string is copied and stored by the list implementation.
Clears the list (but does not delete the client data stored with each node unless you called DeleteContents( true ), in which case it deletes data).
If destroy is true , instructs the list to call delete on the client contents of a node whenever the node is destroyed. The default is false .
Deletes the given node from the list, returning true if successful.
Finds the given client object and deletes the appropriate node from the list, returning true if successful. The application must delete the actual object separately.
Removes element at given position.
Returns the node whose client data is object or NULL if none found.
Note : keyed lists are deprecated and should not be used in new code.
Returns the node whose stored key matches key . Use on a keyed list only.
Returns the number of elements in the list.
Returns the first node in the list (NULL if the list is empty).
Returns the last node in the list (NULL if the list is empty).
Returns the index of obj within the list or wxNOT_FOUND if obj is not found in the list.
Insert object at front of list.
Insert object before position , i.e. the index of the new item in the list will be equal to position . position should be less than or equal to GetCount ; if it is equal to it, this is the same as calling Append .
Inserts the object before the given node .
Returns true if the list is empty, false otherwise.
Returns the node at given position in the list.
NB: This function is deprecated, use Find instead.
Returns the node associated with object if it is in the list, NULL otherwise.