An object used by an application wishing to create an accelerator table.
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);
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.
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 0x02000000Event 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
An activate event is sent when a window or application is being activated or deactivated.
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.
while (app.Pending())
Dispatch();
// Provide wxWidgets message loop compatibility
BOOL CTheApp::PreTranslateMessage(MSG *msg)
{
if (wxTheApp && wxTheApp->ProcessMessage((WXMSW *)msg))
return true;
else
return CWinApp::PreTranslateMessage(msg);
}
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.
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.
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
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
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.
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.
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.
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).
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).
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.
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!
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!
wxArtProvider class is used to customize the look of wxWidgets application. When wxWidgets need to display an icon or a bitmap (e.g. in the standard file dialog), it does not use hard-coded resource but asks wxArtProvider for it instead. This way the users can plug in own wxArtProvider class and easily replace standard art with his/her own version. It is easy thing to do: all that is needed is to derive a class from wxArtProvider, override it's 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.
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.
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");
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.
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.
This class encapsulates the concept of a platform-dependent bitmap, either monochrome or colour.
wxBitmap newBitmap = oldBitmap.GetSubBitmap(
wxRect(0, 0, oldBitmap.GetWidth(), oldBitmap.GetHeight()));
#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.
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.
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 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.
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.
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.
A brush list is a list containing all brushes which have been created.
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.
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).
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.
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.
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.
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.
This class converts between any character sets and Unicode. It has one predefined instance, { wxConvLocal}, for the default user character set.
This event is sent by wxLayoutAlgorithm to calculate the amount of the remaining client area that the window should occupy.
The calendar control allows the user to pick a date interactively. For this, it displays a window containing several parts: the control to pick the month and the year at the top (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.
enum wxCalendarHitTestResult
{
wxCAL_HITTEST_NOWHERE, // outside of anything
wxCAL_HITTEST_HEADER, // on the header (weekdays)
wxCAL_HITTEST_DAY // on a day in the calendar
}
wxCalendarDateAttr is a custom attributes for a calendar date. The objects of this class are used with wxCalendarCtrl.
enum wxCalendarDateBorder
{
wxCAL_BORDER_NONE, // no border (default)
wxCAL_BORDER_SQUARE, // a rectangular border
wxCAL_BORDER_ROUND // a round border
}
The wxCalendarEvent class is used together with wxCalendarCtrl.
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.
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.
A checklistbox is like a listbox, but allows items to be checked or unchecked.
This class is currently implemented under Windows and GTK. 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.
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.
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}.
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.
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).
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.
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.
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();
}
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.
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.
This class holds a variety of information related to colour dialogs.
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}.
This class represents the colour chooser dialog.
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.
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.
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.
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.
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.
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.
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
};
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.
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
};
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:
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.
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.
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.
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).
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.
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.
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.
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
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.
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.
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));
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 dstThe 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.
| 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. |
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.
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.
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.
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
};
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.
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!
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.
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.
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.
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.
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.
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).
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
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.
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.
// 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";
1) ClearMemberVars() 2) Assign columns values you wish to match on 3) Call wxDbTable::QueryMatching() or wxDbTable::DeleteMatching()
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");
// Create a secondary index on the PARTS table
wxDbIndexDef 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);